SR2024 - Update Section - Power board API

Author: 8BitJosh

programming/power.md

@@ -1,4 +1,6 @@
 ---
+redirect_from:
+  - /programming/sr/power
 layout: page
 title: Power Board API
 ---
@@ -7,121 +9,124 @@ Power Board API
 ===============
 
 There are a few things that can be done with the power board, namely current and voltage sensing, and beeping.
-As there is only one power board, it is not accessed like a list like `motors` and is instead accessed directly, for example:
+See the [Power Board](/docs/kit/power_board) hardware page for more details.
+
+
+Accessing the Power Board
+-------------------------
+
+The power board can be accessed using the `power_board` property of the `Robot` object.
 
 ~~~~~ python
-R.power_board.something...
+from sr.robot3 import *
+robot = Robot()
+
+my_power_board = robot.power_board
 ~~~~~
 
-[Power Outputs](#outputs) {#outputs}
--------
 
-Each of the power board's controllable outputs has a constant whose name closely
- matches the name of the output:
+Power Outputs
+-------------
+
+Each of the power board's controllable outputs has a constant whose name closely matches the name of the output:
 
 * H0 : `OUT_H0`
 * H1 : `OUT_H1`
 * L0 : `OUT_L0`
 * L1 : `OUT_L1`
-* L2 : N/A (Not Controllable)
+* L2 : N/A (Not Controllable - This port is used to power the Brain Board)
 * L3 : `OUT_L3`
 * 5V : `OUT_FIVE_VOLT`
 
-Both of the 5V outputs are controlled simultaneously.
+Both of the 5V outputs are controlled together.
 
-While they are all turned on when your code starts running,
- you can control whether each output is turned on or off like so:
+All the ports are turned on when your code starts running, you can then control whether each output is turned on or off like so:
 
 ~~~~~ python
-from sr.robot3 import *
-
 # Turn output H0 off
-R.power_board.outputs[OUT_H0].is_enabled = False
+robot.power_board.outputs[OUT_H0].is_enabled = False
 
 # Turn output L0 on
-R.power_board.outputs[OUT_L0].is_enabled = True
+robot.power_board.outputs[OUT_L0].is_enabled = True
 
 # Find out whether L3 is enabled
-print(R.power_board.outputs[OUT_L3].is_enabled)
+print(robot.power_board.outputs[OUT_L3].is_enabled)
 
 # Find the current (in Amps) being used by L3
-print(R.power_board.outputs[OUT_L3].current)
+print(robot.power_board.outputs[OUT_L3].current)
 ~~~~~
 
-An exception is raised if you try to set an output index which doesn't exist.
-
 You can also control all the outputs together:
 
 ~~~~~ python
-R.power_board.outputs.power_off()
-R.power_board.outputs.power_on()
+robot.power_board.outputs.power_off()
+robot.power_board.outputs.power_on()
 ~~~~~
 
 <div class="warning">
-  If you turn off the power output which is powering another of your boards,
-  then they will appear to be missing and your code will break if you try to
-  control them.
+If you turn off the power output which is powering another one of your boards,
+they will appear to be missing and your code will break if you try to control them.
 </div>
 
 
-[Battery Status](#battery) {#battery}
--------
+Battery Status
+--------------
 
 The power board can report both the battery voltage, in Volts, and the current being drawn from it, in Amps.
 You can access these values like so:
 
 ~~~~~ python
-# Print the battery voltage and current to the log
-print(
-  R.power_board.battery_sensor.voltage,
-  R.power_board.battery_sensor.current,
-)
+# Print the battery voltage in volts
+print(robot.power_board.battery_sensor.voltage)
+
+# Print the battery current in amps
+print(robot.power_board.battery_sensor.current)
 ~~~~~
 
-A fully charged battery will measure 12.6V.
-The power board will turn off and signal a low battery at 10.2V.
-The discharge curve is roughly linear between 11.4V and 10.4V.
+- A fully charged battery will measure 12.6V.
+- The power board will turn off and signal a low battery at 10.2V.
+- The discharge curve is roughly linear between 11.4V and 10.4V.
 
 
-[Beeping](#beeping) {#beeping}
+Beeping
 -------
 
 The power board has a piezo buzzer which can beep.
 
-The `buzz` function accepts multiple parameters, depending on what you
-want to play. The first argument is the duration of the beep, in
-seconds. The later arguments are either the note you want to play, or
-the frequency of the buzzer (in Hertz). You have to specify which of
-note or frequency you're passing using a keyword argument, your code
-will fail otherwise.
+The `buzz` function accepts multiple parameters, depending on what you want to play.
+- The first argument is either the note you want to play, or the frequency of the buzzer in Hertz.
+- The second argument is the duration of the beep, in seconds.
 
-Theoretically, the piezo buzzer will buzz at any provided frequency, however
-humans can only hear between [20Hz and 20000Hz][pitch-range].
+The `Note` enum provides notes in [scientific pitch notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation) between `C6` and `C8`.
+You can play other tones by providing a frequency.
 
-The `Note` enum provides notes in [scientific pitch notation][pitch-notation]
-between `C6` and `C8`. You can play other tones by providing a frequency.
+The frequency on the buzzer is limited from 8Hz to 10,000Hz
 
 <div class="info" markdown="1">
-  Calling `buzz` is non-blocking, which means it doesn't actually wait
-  for the piezo to stop buzzing before continuing with your code. If you
-  want to wait for the buzzing to stop, use the <code>blocking</code> argument!
+  Calling `buzz` is non-blocking, which means it doesn't actually wait for the piezo to stop buzzing before continuing with your code.
+  If you want to wait for the buzzing to stop, use the `blocking` argument.
 </div>
 
 ~~~~~ python
-from sr.robot3 import Note
-
 # Beep for 0.5s in D.
-R.power_board.piezo.buzz(0.5, Note.D6)
+R.power_board.piezo.buzz(Note.D6, 0.5)
 
 # Beep for 2s at 400Hz
-R.power_board.piezo.buzz(2, 400)
+R.power_board.piezo.buzz(400, 2)
 
 # Beep for 3s at 250Hz and wait for it to finish
-R.power_board.piezo.buzz(3, 250, blocking=True)
+R.power_board.piezo.buzz(250, 3, blocking=True)
 ~~~~~
 
-`ValueError` is raised if the note is not recognised or the frequency is not an integer.
 
+Start Button
+------------
+
+You can manually wait for the start button to be pressed, not only at the start.
+
+~~~~~ python
+robot.wait_start()
+~~~~~
 
-[pitch-range]: https://en.wikipedia.org/wiki/Hearing_range#Humans
-[pitch-notation]: https://en.wikipedia.org/wiki/Scientific_pitch_notation
+This method will block until the start button is pressed.
+This may be useful for testing, but be sure to remove it in the competition, as you won't be allowed to touch the start button after a match has begun!