Merge branch 'update-power-board' into sr2022

Author: PeterJCLaw

programming/sr/power/index.md

@@ -7,28 +7,12 @@ Power
 =====
 
 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` for example:
+As there is only one power board, it is not accessed like a list like `motors` and is instead accessed directly, for example:
 
 ~~~~~ python
-R.power.something...
+r.power_board.something...
 ~~~~~
 
-[Battery Status](#battery) {#battery}
--------
-
-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.battery.voltage, R.power.battery.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.
-
-
 [Power Outputs](#outputs) {#outputs}
 -------
 
@@ -46,29 +30,93 @@ While they are all turned on when your code starts running,
  you can control whether each output is turned on or off like so:
 
 ~~~~~ python
+from sr.robot3 import *
+
 # Turn output H0 off
-R.power.output[OUT_H0] = False
+r.power_board.outputs[OUT_H0].is_enabled = False
 
 # Turn output L0 on
-R.power.output[OUT_L0] = True
+r.power_board.outputs[OUT_L0].is_enabled = True
+
+# Find out whether L3 is enabled
+print(r.power_board.outputs[OUT_L3].is_enabled)
+
+# Find the current (in Amps) being used by L3
+print(r.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()
+~~~~~
+
+<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.
+</div>
+
+
+[Battery Status](#battery) {#battery}
+-------
+
+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,
+)
+~~~~~
+
+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}
 -------
 
 The power board has a piezo buzzer which can beep.
 
-The beep function accepts 1 or 2 parameters, `duration` is compulsory and is measured in milliseconds. `note` is optional, but must be one string of `a-g` or `uc`. `frequency` is also optional, and should be an integer. One of `note` and `frequency`, must be given. If both are given, `note` is used.
+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.
+
+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][pitch-notation]
+between `C6` and `C8`. You can play other tones by providing a frequency.
+
+<div class="info">
+  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, add a `sleep` afterwards!
+  If you send more than 32 beeps to the robot too quickly, your power board will crash!
+</div>
 
 ~~~~~ python
+from sr.robot3 import Note
+
 # Beep for 0.5s in D.
-R.power.beep(500, note='d')
+r.power_board.piezo.buzz(0.5, Note.D6)
 
 # Beep for 2s at 400Hz
-R.power.beep(2000, frequency=400)
+r.power_board.piezo.buzz(2, 400)
 ~~~~~
 
 `ValueError` is raised if the note is not recognised or the frequency is not an integer.
+
+
+[pitch-range]: https://en.wikipedia.org/wiki/Hearing_range#Humans
+[pitch-notation]: https://en.wikipedia.org/wiki/Scientific_pitch_notation