Merge pull request #230 from srobo/dgt/sr2022-ruggeduino-update

SR2022 Update Ruggeduino docs

Author: trickeydan

programming/sr/ruggeduinos/custom_firmware.md

@@ -12,31 +12,15 @@ This documentation refers to a feature which is only available on the physical r
 
 The Ruggeduino that came as part of your kit was shipped with a firmware that provides the functionality outlined in the [Ruggeduino](/docs/programming/sr/ruggeduinos) page.
 You may wish to extend the functionality of this firmware, or completely replace it.
-The `sr.robot` library provides support for three Ruggeduino firmware scenarios:
+The `sr.robot3` library provides support for three Ruggeduino firmware scenarios:
 
  1. Default SR firmware
  2. [Extended SR firmware](#extension): Firmwares that add commands to the default SR firmware.
  3. [Completely custom](#completely): Any firmware not derived from the SR firmware.
 
-By default, the [`sr.robot`](/docs/programming/sr/) library assumes that all connected Ruggeduinos are running the SR firmware.
-If you wish to use an extended SR firmware, or completely custom firmware,
- then you need to tell the `Robot` object what to do with your Ruggeduino(s).
-To do this, you will need to expand the initialisation of your `Robot` object as detailed [here](/docs/programming/sr/#CustomRobotInit).
-Your code will then look something like this:
-
-~~~~~ python
-from sr.robot import *
-
-R = Robot.setup()
-
-R.init()
-
-R.wait_start()
-
-# The rest of your code
-~~~~~
-
-The next step depends on whether you are running an extended SR firmware, or a completely custom firmware.
+By default, the [`sr.robot3`](/docs/programming/sr/) library assumes that all connected Ruggeduinos are running the SR firmware
+or firmware which is compatible with the SR Ruggeduino firmware.
+If you're using completely custom firmware, you'll need to tell the kit to ignore the ruggeduino so that you're able to define your own setup logic.
 
 [Extension of the SR firmware](#extension) {#extension}
 ------------------------------
@@ -95,149 +79,20 @@ Your command can read additional data from the serial port if it requires additi
 It can also write a response back to the host (your Python code).
 Have a look at the `command_read()` function to see how to do this.
 
-### Step 2: Extend the `Ruggeduino` class
-
-Your robot's python code will, by default, use a `Ruggeduino` object to communicate with the Ruggeduino.
-The object returned to you when you type `R.ruggeduinos[0]` is a `Ruggeduino` instance.
-This object knows how to talk to the default command handlers in the SR firmware.
-
-<div class="info" markdown="1">
-Don't worry if you don't know what "object" means -- you can probably blag this without knowing!
-If you do want to know about them, you'll find introductions to them all over the web.
-You could try [this one](http://www.jesshamrick.com/2011/05/18/an-introduction-to-classes-and-inheritance-in-python/), for example.
-</div>
-
-You'll need to extend the `Ruggeduino` class, giving it at least one extra method to perform your command.
-Start by adding this to your code:
-
-~~~~~ python
-from sr.robot import *
-
-class CustomisedRuggeduino(Ruggeduino):
-    pass
-~~~~~
-
-You've just declared a class called `CustomisedRuggeduino` (you will probably want to call it something else that makes more sense in your application).
-At the moment, it behaves in exactly the same way as the `Ruggeduino` class.
-You now need to add your custom method to it:
-
-~~~~~ python
-from sr.robot import *
-
-class CustomisedRuggeduino(Ruggeduino):
-
-    # Your function for instructing a Ruggeduino to bake a cake
-    def bake_cake(self):
-        with self.lock:
-            self.command("c")
-~~~~~
-
-Skipping ahead for a moment: Once we've told your `Robot` object about this `CustomisedRuggeduino`
- class (which we do in the next step), you will be able to do this:
-
-~~~~~ python
-R.ruggeduinos[0].bake_cake()
-# and you'll still be able to do this:
-R.ruggeduinos[0].digital_read(3)
-~~~~~
-
-<div class="warning" markdown="1">
-The IDE will unfortunately error about the lack of a `bake_cake` method (or your equivalent) in the above code.
-This is an expected restriction of the way the IDE checks the syntax of your code.
-
-You can therefore ignore these errors (though you should be careful that the error is one of these and not something else).
-</div>
-
-#### `with self.lock:`
-
-You'll notice that the code above contains a line that reads:
-
-~~~~~ python
-with self.lock:
-~~~~~
-
-Whenever you call `self.command`, you need to ensure that it is called within a block of code headed by this `with` statement.
-This is a tool that makes your code "thread-safe".
-If you're not using threads, then you will still need to use it, but it won't affect the behaviour of your program.
+### Step 2: Use your new command from Python
 
-#### Responses
-
-The response from your command is returned by the `self.command` function.
-Remember that it will be a string, so you will need to convert it as necessary.
-
-If, for example, our cake-baking function on our Ruggeduino responds with the number of cakes that were baked, then we could do this:
+You can send a custom command from your Python code to the Ruggeduino to control your cake-baking.
 
 ~~~~~ python
-class CustomisedRuggeduino(Ruggeduino):
-
-    def bake_cake(self):
-        with self.lock:
-            resp = self.command("c")
-        return int(resp)
+cake_result = R.ruggeduino.command("c")
 ~~~~~
 
-
-### Step 3: Tell the `Robot` to use your extended class
-
-Now that you've extended the `Ruggeduino` class to create your `CustomisedRuggeduino` class,
- it's time to tell the `Robot` object about it using the `ruggeduino_set_handler_by_fwver` function:
-
-~~~~~ python
-from sr.robot import *
-
-# The class that you wrote in step 2
-class CustomisedRuggeduino(Ruggeduino):
-    def bake_cake(self):
-        with self.lock:
-            self.command("c")
-
-R = Robot.setup()
-
-# Register the custom class with the Robot object
-R.ruggeduino_set_handler_by_fwver("SRcustom", CustomisedRuggeduino)
-
-R.init()
-
-R.wait_start()
-
-# Now you can call your custom function!
-R.ruggeduinos[0].bake_cake()
-~~~~~
+The `cake_result` variable will contain any response from your firmware, if you sent one.
 
 You're done!  You can now use your custom cake-baking firmware!
 
-
-#### Multiple Ruggeduinos with Extended SR Firmwares
-
-You may wish to use multiple Ruggeduinos with your robot, each supporting a different set of commands.
-There are two ways to go about this.
-
-You can change the string "SRCustom" in your firmwares to be something different
- (but make sure you keep the colon that follows it!),
- and then change the string you pass to `ruggeduino_set_handler_by_fwver` to suit.
-For example, if you change it to be "CakeBaker" in one of your ruggeduinos,
- but leave it as "SRCustom" in the other, then your enumeration code would become:
-
-~~~~~ python
-R.ruggeduino_set_handler_by_fwver("SRcustom", CustomisedRuggeduino)
-R.ruggeduino_set_handler_by_fwver("CakeBaker", CakeBakerRuggeduino)
-~~~~~
-
-Alternatively, you can set the handling class using the ID of the Ruggeduino.
-The Ruggeduino IDs are written to the robot log when you run a program on your robot with your Ruggeduino connected.
-Instead of using `ruggeduino_set_handler_by_fwver`, you use `ruggeduino_set_handler_by_id`:
-
-~~~~~ python
-R.ruggeduino_set_handler_by_id("752303138333517171B1", CustomisedRuggeduino)
-R.ruggeduino_set_handler_by_id("10231028301928310283", CakeBakerRuggeduino)
-~~~~~
-
-You will then be able to access your ruggeduino using its ID like so:
-
-~~~~~ python
-R.ruggeduinos["752303138333517171B1"]
-~~~~~
-
+If you have multiple Ruggeduino running custom firmware, you can keep track of which one is which
+by using the serial numner.
 
 [Completely custom firmware](#completely) {#completely}
 ----------------------------
@@ -249,43 +104,30 @@ To configure a `Robot` object to ignore a Ruggeduino with custom firmware, you w
 The Ruggeduino ID is a 20 character string of mostly numbers, and is output in the robot log when you run a program on your robot with your
 Ruggeduino connected.
 
-After calling `Robot.setup()`, you should call the `ruggeduino_ignore_id`
- method of the robot object, with the ID as an argument.
 You'll need the ID later, so it's best to save it into a variable:
 
 ~~~~~ python
 from sr.robot import *
 
 RUGGEDUINO_ID = "752303138333517171B1" # Replace this with the actual ID
 
-R = Robot.setup()
-
-R.ruggeduino_ignore_id( RUGGEDUINO_ID )
-
-R.init()
-
-R.wait_start()
+R = Robot(ignored_ruggeduinos=["752303138333517171B1"])
 
 # The rest of your code
 ~~~~~
 
 If you need to communicate with the Ruggeduino firmware, you will need its serial device path.
-This is accessible after the `R.init()` call through the list of Ruggeduinos:
-
-~~~~~ python
-# ... Robot.setup() ... etc.
 
-R.init()
+This is accessible from the `ignored_ruggeduinos` dictionary.
 
-ruggeduino_device = R.ruggeduinos[RUGGEDUINO_ID].path
-
-# Do your Ruggeduino initialisation here if you wish
-
-R.wait_start()
+~~~~~ python
+ruggeduino_device = R.ignored_ruggeduinos[RUGGEDUINO_ID]
 
 # The rest of your code
 ~~~~~
 
+The device path will look something like `/dev/ttyACM1`.
+
 You may wish to use pyserial to communicate with the Ruggeduino, in which case you could open it like so:
 
 ~~~~~ python
@@ -294,12 +136,9 @@ from sr.robot import *
 
 RUGGEDUINO_ID = "752303138333517171B1"
 
-R = Robot.setup()
-R.ruggeduino_ignore_id( RUGGEDUINO_ID )
-R.init()
-R.wait_start()
+R = Robot(ignored_ruggeduinos=[RUGGEDUINO_ID])
 
-ser = serial.Serial( R.ruggeduinos[RUGGEDUINO_ID].path )
+ser = serial.Serial(R.ignored_ruggeduinos[RUGGEDUINO_ID])
 
 ~~~~~
 

programming/sr/ruggeduinos/index.md

@@ -10,45 +10,45 @@ The [Ruggeduino](http://ruggedcircuits.com/html/ruggeduino.html)
 provides a total of 18 pins for either digital input or output (labelled 2 to 13 and A0 to A5),
 including 6 for analogue input (labelled A0 to A5).
 
-The `ruggeduinos` object is used to control a collection of Ruggeduinos.
-Similar to `motors` and `servos`, `ruggeduinos` can be used like a list.
-To do something with the **first Ruggeduino**, you would use:
+When a single Ruggeduino is connected to your robot, you can control it
+using the `ruggeduino` object.
 
 ~~~~~ python
-R.ruggeduinos[0].something...
+R.ruggeduinos.something...
 ~~~~~
 
-...because indexes are 0-based (counting starts from 0, not 1).
-
-When you have more than one Ruggeduino board connected to your kit
-they will be ordered based upon their serial number.
-
 The serial number of each detected Ruggeduino is printed to the log when your robot starts.
 It will look something like this:
 
 ~~~~~ not-code
-Found the following devices:
- - Ruggeduinos:
-    0: Ruggeduino( serialnum = "752303138333517171B1" )
+sr.robot3.robot INFO - Found Ruggeduino - 752303138333517171B1
 ~~~~~
 
-In addition, like `motors`, `ruggeduinos` is actually a dictionary.
-As a result, in `ruggeduinos` you can also use the Ruggeduino serial number as a key.
+If you have more than one Ruggeduino attached, the `ruggeduinos` object 
+can be used to control a collection of Ruggeduinos. Similar to `motors` 
+and `servos`, `ruggeduinos` is a dictionary accessed by serial number.
 For example, if you had a board whose serial number was "752303138333517171B1",
 you could do this instead:
 
 ~~~~~ python
 R.ruggeduinos["752303138333517171B1"].something...
 ~~~~~
 
+<div class="warning">
+    When you have more than one Ruggeduino board connected to your kit,
+    you must use `R.ruggeduinos` and index by serial number. This is so
+    that the kit knows which Ruggeduino you want to control.
+</div>
+
+
 [Setting pin modes](#pinmodes) {#pinmodes}
 --------------------------------------------------------------------------
 
 To use one of the pins on the Ruggeduino, you must first set whether you want it to behave as an input or as an output.
 You can do this with the following code:
 
 ~~~~~ python
-R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].pin_mode(PIN_NO, MODE)
+R.ruggeduino.pins[10].mode = MODE
 ~~~~~
 
 The possible values for `MODE` are:
@@ -65,12 +65,12 @@ The possible values for `MODE` are:
 An example of how to use this is below:
 
 ~~~~~ python
-# set Ruggeduino board 0's pin 2 to output
-R.ruggeduinos[0].pin_mode(2, OUTPUT)
-# set Ruggeduino board 0's pin 3 to input
-R.ruggeduinos[0].pin_mode(3, INPUT)
-# set Ruggeduino board 0's pin 4 to input and enable pull-up resistor
-R.ruggeduinos[0].pin_mode(4, INPUT_PULLUP)
+# set Ruggeduino pin 2 to output
+R.ruggeduino.pins[2].mode = OUTPUT
+# set Ruggeduino pin 3 to input
+R.ruggeduinos[0].pins[3].mode = INPUT
+# set Ruggeduino git commit -m "pin 4 to input and enable pull-up resistor
+R.ruggeduinos[0].pins[4].mode = INPUT_PULLUP
 ~~~~~
 
 <div class="warning">You cannot use pins 0 and 1, as using these would disrupt communications between the Ruggeduino and the Power Board.</div>
@@ -81,37 +81,39 @@ R.ruggeduinos[0].pin_mode(4, INPUT_PULLUP)
 You can read a **digital** input pin with the following code:
 
 ~~~~~ python
-# R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].digital_read(PIN_NO)
+# R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].pins[PIN_NO].digital_read()
 
-# to read Ruggeduino board 0's digital pin 3...
-pin0 = R.ruggeduinos[0].digital_read(3)
+# to read Ruggeduino's digital pin 3...
+pin0 = R.ruggeduino.pins[3].digital_read()
 ~~~~~
 
 `pin0` will now contain `True` or `False` depending on whether the pin was high (3.3v) or low (0v), respectively.
 
 You can read an **analogue** input pin with the following code:
 
 ~~~~~ python
-# R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].analogue_read(PIN_NO)
+# R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].pins[PIN_NO].analogue_read()
 
-# to read Ruggeduino board 0's analogue pin A0...
-pin0 = R.ruggeduinos[0].analogue_read(0)
+# to read Ruggeduino's analogue pin A0...
+pin0 = R.ruggeduino.pins[A0].analogue_read()
 ~~~~~
 
+The analogue pin numbers are available as `A0`, `A1`, `A2`, `A3`, `A4`, and `A5` respectively.
+
 
 [Output](#output) {#output}
 --------
 
 You can only set digital outputs (there's no analogue output, although you may feel free to modify the Ruggeduino's firmware to add the ability to output [PWM](https://wikipedia.org/wiki/Pulse-width_modulation "Pulse-width modulation") if you desire). To set a digital output pin, you would use the following:
 
 ~~~~~ python
-# R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].digital_write(PIN_NO, VALUE)
+# R.ruggeduinos[RUGGEDUINO_BOARD_NUMBER].pins[PIN_NO].digital_write(VALUE)
 
-# to set Ruggeduino board 0's pin 2 high:
-R.ruggeduinos[0].digital_write(2, True)
+# to set Ruggeduinos pin 2 high:
+R.ruggeduino.pins[2].digital_write(True)
 
-# to set Ruggeduino board 0's pin 2 low:
-R.ruggeduinos[0].digital_write(2, False)
+# to set Ruggeduino's pin 2 low:
+R.ruggeduino.pins[2].digital_write(False)
 ~~~~~
 
 [Pull-up resistors](#pullup) {#pullup}