Merge pull request #252 from srobo/dgt/sr2022-servo-board

Update the servo board docs for SR2022

Author: trickeydan

programming/sr/servos/index.md

@@ -10,69 +10,72 @@ Servos
 This documentation refers to a feature which is only available on the physical robot kits.
 </div>
 
-The `servos` object is used to control a collection of Servo Boards.
-Similar to `motors` and `ruggeduinos`, `servos` can be used like a list.
-To do something with the **first Servo Board**, you would use:
+The `servo_board` object is used to control a collection of Servo Boards.
+
+When a single Servo Board is connected to your robot, you can control it
+using the `servo_board` object.
 
 ~~~~~ python
-R.servos[0].something...
+R.servo_board.something...
 ~~~~~
 
-...because indexes are 0-based (counting starts from 0, not 1).
-
-When you have more than one Servo Board connected to your kit
-they will be ordered based upon their serial number.
-
-The SR Part Code of each detected motor board is also printed to the log when your robot starts.
+The serial number of each detected Servo Board is printed to the log when your robot starts.
 It will look something like this:
 
 ~~~~~ not-code
-Found the following devices:
- - Servos:
-    0: Servo( serialnum = "SR0LG31" )
+sr.robot3.robot INFO - Found Student Robotics Servo Board v4 - srABC1
 ~~~~~
 
-
-However, like `motors` and `ruggeduinos`, `servos` is actually a dictionary.
-As a result, in `servos` you can also use the SR Part Code of the Servo Board as a key.
-For example, if you had a board that was labelled "SR0LG31",
-you could do this instead:
+If you have more than one Servo Board attached, you need to specify which one you want to control. This is done using the serial number of the board. For example: if you had a board that was labelled "srABC1",
 
 ~~~~~ python
-R.servos["SR0LG31"].something...
+R.servo_boards["srABC1"].something...
 ~~~~~
 
+<div class="warning">
+    When you have more than one servo board connected to your kit,
+    you must use `R.servo_boards` and index by serial number. This is so
+    that the kit knows which servo board you want to control.
+</div>
+
 Setting servo positions
 -----------------------
 
-The position of servos can range from `-100` to `100` inclusive:
+The position of servos can range from `-1` to `1` inclusive:
 
 ~~~~~ python
-# R.servos[SERVO_BOARD_ID][SERVO_NUMBER] = POS
+# R.servo_board.servos[SERVO_NUMBER].position = POS
 
-# set servo 1's position (on the first Servo Board connected, board 0) to 20
-R.servos[0][1] = 20
-# Set servo 2's position (on the Servo Board with part code SRABC) to -55
-R.servos["SRABC"][2] = -55
-~~~~~
+# set servo 1's position to 0.2
+R.servo_board.servos[1].position = 0.2
 
-<div class="warning" markdown="1">
-It is important that you use integers (whole numbers, such as `10` instead of
-`10.0`) when specifying servo positions.
-</div>
+# Set servo 2's position (on the Servo Board with serial number srABC) to -0.55
+R.servo_boards["srABC"].servos[2].position = -0.55
+~~~~~
 
 You can read the last value a servo was set to using similar code:
 
 ~~~~~ python
 # get the last setting of the second servo on the first Servo Board
-lastSetting = R.servos[0][1]
+last_setting = R.servo_board.servos[1].position
 ~~~~~
 
 <div class="info" markdown="1">
 While it is possible to retrieve the last position a servo was set to,
 this does not guarantee that the servo is currently in that position.
 </div>
 
+Turning off a servo
+-------------------
+
+You can also set a servo output to be unpowered, so that there is no longer a PWM signal from the output on the servo board.
+
+You can unpower the servo output by setting the position to `None`.
+
+~~~~~ python
+r.servo_board.servos[11].position = None
+~~~~~
+
 [How the set position relates to the servo angle](#ServoAngle) {#ServoAngle}
 -----------------------------------------------
 
@@ -84,4 +87,4 @@ Some servos are very strong and it could damage the internal gears.
 The angle of an RC servo is controlled by the width of a pulse supplied to it periodically.
 There is no standard for the width of this pulse and there are differences between manufacturers as to what angle the servo will turn to for a given pulse width.
 To be able to handle the widest range of all servos our hardware outputs a very wide range of pulse widths which in some cases will force the servo to try and turn past its internal end-stops.
-You should experiment and find what the actual limit of your servos are (it almost certainly won't be -100 and 100) and not drive them past that.
+You should experiment and find what the actual limit of your servos are (it almost certainly won't be -1 and 1) and not drive them past that.