SR2024 - Update Section - Arduino API

Author: 8BitJosh

.spelling

@@ -16,6 +16,8 @@ Plazma
 PULLUP
 Quarternion
 rtui
+Arduino
+Arduinos
 Ruggeduino
 Ruggeduinos
 Scarzy

_data/sidebar_tree.yaml

@@ -60,6 +60,10 @@ tree:
     - url: /programming/arduino/
       title: Arduino API
       tree:
+      - url: /programming/arduino/sr_firmware
+        title: SR Firmware
+      - url: /programming/arduino/extended_sr_firmware
+        title: Extended SR Firmware
       - url: /programming/arduino/custom_firmware
         title: Custom Firmware
     - url: /programming/cheat_sheet

programming/arduino/custom_firmware.md

@@ -3,148 +3,140 @@ layout: page
 title: Arduino custom firmware
 ---
 
-Arduino custom firmware
-=======================
+# Arduino with custom firmware
 
-<div class="info">
-This documentation refers to a feature which is only available on the physical robot kits.
+<div class="info" markdown="1">
+On this page we talk specifically about Arduinos.
+However this page is applicable to opening any device that shows up as a serial port.
 </div>
 
-The Ruggeduino that came as part of your kit was shipped with a firmware that provides the functionality outlined in the [Ruggeduino](/docs/programming/arduino) page.
-You may wish to extend the functionality of this firmware, or completely replace it.
-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.
+## Ignoring a device
 
-By default, the [`sr.robot3`](/docs/programming/robot_api/) 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.
+By default when the `robot` object is created it will try to communicate with all Arduinos and will expect them to respond in the way the SR firmware does.
+If you want the API to not try connecting to a device we need to *ignore* the Arduino.
 
-[Extension of the SR firmware](#extension) {#extension}
-------------------------------
+To configure a `Robot` object to ignore a Arduino with custom firmware, you will need to provide it with the Arduino's serial number.
+The Arduino serial number is a string of numbers and letters, and is output in the robot log when you run a program on your robot with your Arduino connected.
 
-<div class="warning" markdown="1">
-Because the API sets all pins to inputs when the robot is initialised, you cannot set pin modes in the setup function as these will be overridden.
-In order to setup pins you can either create a function on the ruggeduino that you call after your robot is initialised or use the [Python functions](/docs/programming/arduino/#pin-modes) to setup the pins.
-</div>
-
-You may wish to extend the SR firmware with additional functionality.
-This will allow you to continue using the commands already provided by the SR firmware (e.g. `digital_read()`),
- which means any existing robot code you have won't need modifying very much.
-When you extend the SR firmware, you'll be adding at least one new command to the firmware.
-There are almost limitless possibilities of what your commands may do, but here are some examples to give you an idea:
-
- * Talk to an SPI or I2C sensor.
- * Read N input pins at the same instant in time.
- * Time pulses received from an ultrasound sensor.
-
-There are three steps that you will need to go through to implement and use your custom commands:
-
-### Step 1: Add your command to the Ruggeduino firmware
-
-To extend the SR firmware, you will need to first download its [source code]({{ site.baseurl }}/resources/kit/ruggeduino-fw.ino), and edit it in the Arduino IDE.
-When the SR ruggeduino python library wants the ruggeduino to run a command, it sends it a single character to tell it which command to run.
-You'll find a `switch` statement in the `loop()` function that processes this command character:
-
-~~~~~ cpp
-switch (selected_command) {
-      case 'a':
-        command_analogue_read();
-        break;
-      case 'r':
-        command_read();
-        break;
-      case 'l':
-        command_write(LOW);
-        break;
-
- // ... and so on ...
-~~~~~
+You'll need the serial number later, so it's best to save it into a variable:
 
-For example, you can see in the above that when it receives an "a" character, it calls the `command_analogue_read()` function.
-This function does pretty much what it says on the tin: it reads an analogue pin.
+~~~~~ python
+from sr.robot3 import *
 
-You will need to add your own entry into this `switch` statement for your new command.
-This will need to be represented by a character that doesn't already appear in the switch statement.
-Let's say you chose "c"; your entry would look like this:
+# Replace this with the actual serial number of your board
+ARDUINO_SN = "752303138333517171B1"
 
-~~~~~ cpp
-switch (selected_command) {
-      case 'c':
-        command_bake_cake();
-        break;
+robot = Robot(ignored_arduinos=[ARDUINO_SN])
 
- // ... all the original entries ...
+# The rest of your code
 ~~~~~
 
-You would then write your `command_bake_cake()` function.
-Your command can read additional data from the serial port if it requires additional information to operate.
-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: Use your new command from Python
+## Opening a serial port
 
-You can send a custom command from your Python code to the Ruggeduino to control your cake-baking.
+If you need to communicate with a device, you will need to open its serial port.
+If you want the `robot` object to do this and provide a serial port for your use, you will need to do the following.
 
 ~~~~~ python
-cake_result = R.ruggeduino.command("c")
-~~~~~
+from sr.robot3 import *
 
-The `cake_result` variable will contain any response from your firmware, if you sent one.
+# Replace this with the actual serial number of your board
+ARDUINO_SN = "752303138333517171B1"
 
-You're done!  You can now use your custom cake-baking firmware!
+# Set this to the baud rate that the device communicates with
+SERIAL_BAUD_RATE = 115200
 
-If you have multiple Ruggeduino running custom firmware, you can keep track of which one is which
-by using the serial number.
+robot = Robot(
+    ignored_arduinos=[ARDUINO_SN],
+    raw_ports=[(ARDUINO_SN, SERIAL_BAUD_RATE)]
+)
+
+# The rest of your code
+~~~~~
 
-[Completely custom firmware](#completely) {#completely}
-----------------------------
+This opens the serial connection to the device and the serial port is now available under:
 
-When configured correctly, the `Robot` object will perform absolutely no serial communications with a completely custom firmware.
-We refer to this as *ignoring* a Ruggeduino.
-To configure a `Robot` object to ignore a Ruggeduino with custom firmware, you will need to provide it with the Ruggeduino's ID.
+~~~~~ python
+robot.raw_serial_devices[ARDUINO_SN]
+~~~~~
 
-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.
+<div class="info" markdown="1">
+Note that all communications with the serial port is done with `bytes` rather than strings that you will be more familiar with.
 
-You'll need the ID later, so it's best to save it into a variable:
+You may need to convert from a string to bytes:
 
 ~~~~~ python
-from sr.robot3 import *
-
-RUGGEDUINO_ID = "752303138333517171B1" # Replace this with the actual ID
+bytes_object = string_object.encode()
+~~~~~
 
-R = Robot(ignored_ruggeduinos=["752303138333517171B1"])
+or bytes to a string:
 
-# The rest of your code
+~~~~~ python
+string_object = bytes_object.decode()
 ~~~~~
+</div>
+
 
-If you need to communicate with the Ruggeduino firmware, you will need its serial device path.
+### write
 
-This is accessible from the `ignored_ruggeduinos` dictionary.
+`write` is used to send data to the serial port, the function will send whatever you provide.
+Putting a `b` in front of a string is a short hand way of creating a bytes object.
 
 ~~~~~ python
-ruggeduino_device = R.ignored_ruggeduinos[RUGGEDUINO_ID]
+# This will send the message "data" over the serial port
+# The b in front of the string is not a typo, this is a byte string
+robot.raw_serial_devices[ARDUINO_SN].write(b"data")
+~~~~~
 
-# The rest of your code
+
+### read
+
+`read` is used to get some data from the serial port, the function will read the number of bytes specified.
+If the port times out waiting for data, it may return less bytes that specified.
+
+~~~~~ python
+# This will read 5 bytes from the serial port
+received_data = robot.raw_serial_devices[ARDUINO_SN].read(5)
 ~~~~~
 
-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:
+### read until
+
+`read_until` is used to get some data from the serial port, it will read data until it reads the specified terminator.
+If the port times out waiting for the terminator, it may return less data without the terminator on the end.
+
+For example this can be used to read in a single line of data, terminated with a newline character `\n`.
 
 ~~~~~ python
-import serial
-from sr.robot3 import *
+# This will read in data until we get to a new line character
+received_data = robot.raw_serial_devices[ARDUINO_SN].read_until(b"\n")
+~~~~~
 
-RUGGEDUINO_ID = "752303138333517171B1"
 
-R = Robot(ignored_ruggeduinos=[RUGGEDUINO_ID])
+### pyserial port
 
-ser = serial.Serial(R.ignored_ruggeduinos[RUGGEDUINO_ID])
+The `Robot` uses pyserial to open the serial connection to the board.
+If you would prefer you can access the pyserial object directly, like so:
 
+~~~~~ python
+serial_port = robot.raw_serial_devices[ARDUINO_SN].port
 ~~~~~
 
 Refer to the [pyserial documentation](https://pyserial.readthedocs.org/en/latest/) for more information on how to use pyserial.
+
+
+## Finding other serial devices
+
+If you are using your own serial device that you want to access via a [raw serial port](#opening-a-serial-port), you will need to know its serial number.
+To do this we provide a helper function.
+Running the below code example will print a list of all the devices connected to the system.
+
+Once you have found your device, and copied the serial number, you can follow the guidance in the [opening a serial port](#opening-a-serial-port) section.
+If you need help finding which device is yours contact us on Discord for help.
+
+~~~~~ python
+from sr.robot3 import list_ports
+
+list_ports()
+~~~~~

programming/arduino/extended_sr_firmware.md

@@ -0,0 +1,77 @@
+---
+layout: page
+title: Arduino extended firmware
+---
+
+# Arduino with extended SR firmware
+
+You may wish to extend the SR firmware with additional functionality.
+This will allow you to continue using the commands already provided by the SR firmware (e.g. `digital_read()`),
+which means any existing robot code you have won't need modifying very much.
+When you extend the SR firmware, you'll be adding new commands to the firmware.
+There are almost limitless possibilities of what your commands may do, but here are some examples to give you an idea:
+
+* Talk to an SPI or I2C sensor.
+* Read N input pins at the same instant in time.
+* Time pulses received from an ultrasound sensor.
+
+There are two steps that you will need to go through to implement and use your custom commands:
+
+
+## Step 1: Add your command to the Arduino firmware
+
+To extend the SR firmware, you will need to first download its [source code]({{ site.baseurl }}/resources/kit/arduino-fw.ino), and edit it in the Arduino IDE.
+When the SR Arduino python library wants the Arduino to run a command, it sends it a single character to tell it which command to run.
+You'll find a `switch` statement in the `loop()` function that processes this command character:
+
+~~~~~ cpp
+switch (selected_command) {
+      case 'a':
+        command_analog_read();
+        break;
+      case 'r':
+        command_read();
+        break;
+      case 'l':
+        command_write(LOW);
+        break;
+
+ // ... and so on ...
+~~~~~
+
+For example, you can see in the above code that when it receives an "a" character, it calls the `command_analog_read()` function.
+This function does pretty much what it says on the tin: it reads an analog pin.
+
+You will need to add your own entry into this `switch` statement for your new command.
+This will need to be represented by a character that doesn't already appear in the switch statement.
+Let's say you chose "s"; your entry would look like this:
+
+~~~~~ cpp
+switch (selected_command) {
+      case 's':
+        command_read_sensor();
+        break;
+
+ // ... all the original entries ...
+~~~~~
+
+You would then write your `command_read_sensor()` function, which would implement reading the sensor.
+Your function can read additional data from the serial port if it requires additional information to operate.
+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: Use your new command from Python
+
+You can send a custom command from your Python code to the Arduino to read the sensor.
+
+~~~~~ python
+sensor_data = robot.arduino.command("s")
+~~~~~
+
+The `sensor_data` variable will contain any response from your firmware, if you sent one.
+
+You're done!
+You can now use your custom firmware that can read from a sensor.
+
+If you have multiple Arduinos running custom firmware, you can keep track of which one is which by using the serial number.