diff --git a/.spelling b/.spelling
index 82743b35..3be7f7ff 100644
--- a/.spelling
+++ b/.spelling
@@ -9,6 +9,7 @@ DTSE9H
Ebuyer
esque
finessing
+GPIO
iMAX
IntelliJ
Nikitin
diff --git a/programming/arduino/custom_firmware.md b/programming/arduino/custom_firmware.md
index 686290be..7ffffdbe 100644
--- a/programming/arduino/custom_firmware.md
+++ b/programming/arduino/custom_firmware.md
@@ -23,7 +23,7 @@ The Arduino serial number is a string of numbers and letters, and is output in t
You'll need the serial number later, so it's best to save it into a variable:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
# Replace this with the actual serial number of your board
ARDUINO_SN = "752303138333517171B1"
@@ -40,7 +40,7 @@ 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
-from sr.robot3 import *
+from sr.robot3 import Robot
# Replace this with the actual serial number of your board
ARDUINO_SN = "752303138333517171B1"
diff --git a/programming/arduino/sr_firmware.md b/programming/arduino/sr_firmware.md
index 51a3b593..76c15a1b 100644
--- a/programming/arduino/sr_firmware.md
+++ b/programming/arduino/sr_firmware.md
@@ -15,7 +15,7 @@ The kit can control multiple Arduinos at once, however we only provide one in th
If there is exactly one Arduino connected to your robot, it can be accessed using the `arduino` property of the `Robot` object.
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
my_arduino = robot.arduino
@@ -57,10 +57,13 @@ The possible modes for a pin are:
`INPUT_PULLUP`
: set the pin to input mode with a [pull-up resistor](#pull-up-resistors)
+These are available from `sr.robot3`, or the `GPIOPinMode` enum.
An example of how to use this is below:
~~~~~ python
+from sr.robot3 import INPUT, INPUT_PULLUP, OUTPUT
+
# set Arduino pin 2 to output
robot.arduino.pins[2].mode = OUTPUT
@@ -96,8 +99,11 @@ value = robot.arduino.pins[A0].analog_read()
value = robot.arduino.pins[A4].analog_read()
~~~~~
-The analog pin numbers are available as `A0`, `A1`, `A2`, `A3`, `A4`, and `A5` respectively.
+The analog pin numbers are available as `A0`, `A1`, `A2`, `A3`, `A4`, and `A5` respectively, either imported directly or using the `AnalogPins` enum.
+~~~~ python
+from sr.robot3 import A0, A1, A2, A3, A4, A5, AnalogPins
+~~~~
## Output
@@ -145,6 +151,6 @@ distance_mm = robot.arduino.ultrasound_measure(4, 5)
The ultrasound sensor can measure distances up to around 4 metres.
-If the ultrasound signal has to travel further, the echo may not be detected.
+If the ultrasound signal has to travel further, the echo may not be detected.
This will cause the sensor to timeout and return 0.
diff --git a/programming/cheat_sheet.md b/programming/cheat_sheet.md
index f9657bae..3bd5f435 100644
--- a/programming/cheat_sheet.md
+++ b/programming/cheat_sheet.md
@@ -16,7 +16,7 @@ For more information, make sure you check the rest of the documentation.
In order to use the `sr.robot3` API you first need to import it into your code:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
~~~~~
## Initialising your robot
diff --git a/programming/leds.md b/programming/leds.md
index eeb699e9..f7b533be 100644
--- a/programming/leds.md
+++ b/programming/leds.md
@@ -38,7 +38,7 @@ robot.kch.leds[LED_B].colour = Colour.CYAN
robot.kch.leds[LED_C].colour = Colour.OFF
~~~~~
-The available colours are:
+The available colours are defined on the `Colour` enum:
~~~~~ python
Colour.OFF
@@ -63,3 +63,9 @@ robot.kch.leds[LED_B].r = False
# Turn on the green segment of LED B
robot.kch.leds[LED_B].g = True
~~~~~
+
+These values are all available from the `sr.robot3` module:
+
+~~~~ python
+from sr.robot3 import Colour, LED_A, LED_B, LED_C
+~~~~
diff --git a/programming/motors.md b/programming/motors.md
index d2af0eed..a8aeb2af 100644
--- a/programming/motors.md
+++ b/programming/motors.md
@@ -19,7 +19,7 @@ Accessing the Motor Board
If there is exactly one Motor Board connected to your robot, it can be accessed using the `motor_board` property of the `Robot` object.
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
my_motor_board = robot.motor_board
@@ -39,7 +39,7 @@ sr.robot3.robot - INFO - Found MotorBoard, serial: srXYZ1
You can then access the boards like this:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
my_motor_board = robot.motor_boards["srABC1"]
@@ -125,6 +125,7 @@ Special Values
--------------
In addition to the numeric values, there are two special constants that can be used:
+
- `BRAKE`
- `COAST`
@@ -135,6 +136,8 @@ In addition to the numeric values, there are two special constants that can be u
~~~~~ python
+from sr.robot3 import BRAKE, COAST
+
# Stop the motor as quick as possible
robot.motor_boards["srABC1"].motors[0].power = BRAKE
~~~~~
diff --git a/programming/power.md b/programming/power.md
index f13f4520..02f4c031 100644
--- a/programming/power.md
+++ b/programming/power.md
@@ -18,7 +18,7 @@ Accessing the Power Board
The power board can be accessed using the `power_board` property of the `Robot` object.
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
my_power_board = robot.power_board
@@ -28,7 +28,7 @@ my_power_board = robot.power_board
Power Outputs
-------------
-Each of the power board's controllable outputs has a constant whose name closely matches the name of the output:
+Each of the power board's controllable outputs has a constant whose name closely matches the name of the output, which can be imported from `sr.robot3`:
* H0 : `OUT_H0`
* H1 : `OUT_H1`
@@ -38,6 +38,8 @@ Each of the power board's controllable outputs has a constant whose name closely
* L3 : `OUT_L3`
* 5V : `OUT_FIVE_VOLT`
+These are also available on the `PowerOutputPosition` enum.
+
Both of the 5V outputs are controlled together.
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:
@@ -108,6 +110,8 @@ The frequency on the buzzer is limited from 8Hz to 10,000Hz
~~~~~ python
+from sr.robot3 import Note
+
# Beep for 0.5s in D.
robot.power_board.piezo.buzz(Note.D6, 0.5)
diff --git a/programming/robot_api/comp_mode.md b/programming/robot_api/comp_mode.md
index 9278f3b7..97c45ad0 100644
--- a/programming/robot_api/comp_mode.md
+++ b/programming/robot_api/comp_mode.md
@@ -28,14 +28,7 @@ This will instruct your robot that it is in competition mode and will have a num
Certain robot attributes will change when in comp mode, these can be used to change your robot's behaviour.
The affected attributes are:
- mode
- : Whether the robot is running in competition mode.
- When in a competition match, this will be `COMP`, and at all other times this will be `DEV`.
+ - `robot.mode`
+ - `robot.zone`
- zone
- : The number of the scoring zone that the robot is associated with.
- Between `0` and `3`.
-
- The zone you are in defines which arena markers are near your scoring zone.
- You can use the knowledge of your zone to compensate for this, so your robot behaves correctly in all starting positions.
- See the [rules]({{ site.baseurl }}/rules) for where the scoring zones and arena markers are positioned.
+ See [other robot attributes]({{ site.baseurl }}/programming/robot_api/#other-robot-attributes) for further details of these attributes.
diff --git a/programming/robot_api/index.md b/programming/robot_api/index.md
index b11f32b4..91dc2764 100644
--- a/programming/robot_api/index.md
+++ b/programming/robot_api/index.md
@@ -23,13 +23,21 @@ See the [Motor Board]({{ site.baseurl }}/programming/motors) page for more detai
To gain access to all of this functionality, all you need to do at the top of your code is the following:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
~~~~~
This imports the Student Robotics module that we've written to interface with our hardware.
We then use the `Robot` class from within the `sr.robot3` module, to create a `robot` object that sets up and gives you access to your robot's hardware.
+Alongside `Robot`, other values are importable from `sr.robot3` which may be useful, such as `OUT_H0` or `A3`. It's best practice to only import the values you need, rather than `import *`. Most of these are available directly, or can be retrieved from the enums they're defined on (`PowerOutputPosition` and `AnalogPins` in these cases). If you need multiple values, you can import them all on one line:
+
+~~~~ python
+from sr.robot3 import Robot, OUT_H0, AnalogPins
+~~~~
+
+If you don't need a value, it's best not to import it, to avoid accidentally overriding it.
+
Most examples in the documentation will assume you have created a `robot` object from the `Robot` class.
If you see `robot` in a code example, it is assumed you have run the two lines above.
@@ -46,7 +54,6 @@ Then, within your `robot` you can use the following attributes to access to the
The functions of each board are described on their respective pages.
-
## Other Robot Attributes
As well as the attributes listed above, the `Robot` class also has the following attributes, which you may find useful:
@@ -56,6 +63,8 @@ zone
Between `0` and `3`.
This attribute is only available after the start button is pressed and will throw an error if accessed before.
+ The zone you are in defines which arena markers are near your scoring zone.
+ You can use the knowledge of your zone to compensate for this, so your robot behaves correctly in all starting positions.
See the [competition mode](./comp_mode) page for more information about this attribute.
mode
@@ -66,7 +75,7 @@ mode
See the [competition mode](./comp_mode) page for more information about this attribute.
~~~~~ python
- from sr.robot3 import *
+ from sr.robot3 import Robot, COMP, DEV
robot = Robot()
@@ -76,6 +85,8 @@ mode
print("This is development")
~~~~~
+ `COMP` and `DEV` are aliases for `RobotMode.COMP` and `RobotMode.DEV`, which can also be imported from `sr.robot3`.
+
usbkey
: A [`Path`](https://docs.python.org/3/library/pathlib.html#basic-use) object containing the path to the USB stick.
You can use this to easily read and write files on the USB stick itself.
@@ -83,7 +94,7 @@ usbkey
An example of how the `usbkey` attribute might be used to read a file called `my-file.txt` which is stored on the USB stick:
~~~~~ python
- from sr.robot3 import *
+ from sr.robot3 import Robot
import os
robot = Robot()
@@ -103,7 +114,7 @@ is_simulated
Normally the Robot object is initialised with the following:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
~~~~~
@@ -111,7 +122,7 @@ By default your robot will pause on this line waiting for the start button to be
However if you want to initialise some hardware or software before the start button is pressed then Robot initialisation can be broken up as follows.
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot(wait_for_start=False)
# Initialisation phase.
@@ -121,3 +132,30 @@ robot.wait_start()
~~~~~
This will not pause on the line which creates the `robot` but will instead pause on the `robot.wait_start()` line, until the start button is pressed.
+
+## Enums
+
+Many values from the robot API are "enums". Enums are sets of values with names.
+
+Enums compare equal to each other:
+
+~~~~~ python
+from sr.robot3 import Colour
+
+pump_output = PowerOutputPosition.H0
+
+pump_output == PowerOutputPosition.H0 # True
+pump_output == PowerOutputPosition.H1 # False
+~~~~~
+
+Enums are special values. They may look like strings or numbers, but they're not. An enum is a name for a special value. For example, the value for `PowerOutputPosition.H0` is `0`, whilst `RobotMode.COMP` is `"COMP"`. The inner value can be retrieved using `.value`.
+
+
+~~~~~ python
+from sr.robot3 import RobotMode
+
+RobotMode.COMP == "COMP" # False
+RobotMode.COMP.value == "COMP" # True
+~~~~~
+
+In general, the enum should be used and compared directly, rather than using its inner value.
diff --git a/programming/servos.md b/programming/servos.md
index 7b1249aa..8744be82 100644
--- a/programming/servos.md
+++ b/programming/servos.md
@@ -18,7 +18,7 @@ Accessing the Servo Board
The servo board can be accessed using the `servo_board` property of the `Robot` object.
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
my_servo_board = robot.servo_board
diff --git a/programming/vision/index.md b/programming/vision/index.md
index ec15b5a7..1817c647 100644
--- a/programming/vision/index.md
+++ b/programming/vision/index.md
@@ -28,7 +28,7 @@ see
Here's an example that will repeatedly print out the distance, in meters, to each marker that the robot can see:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
while True:
@@ -52,7 +52,7 @@ capture
~~~~~ python
import cv2
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
frame = robot.camera.capture()
@@ -68,7 +68,7 @@ You can use the output of the `capture` method with the other vision commands to
This may be useful if you wish to use both your own vision algorithms and our marker detection on the same frames.
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
# Capture an OpenCV frame
@@ -101,7 +101,7 @@ Snapshots are saved to your USB drive, and can be viewed on another computer.
```python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
diff --git a/tutorials/basic_motor_control.md b/tutorials/basic_motor_control.md
index 1b06871d..0c8c3dbe 100644
--- a/tutorials/basic_motor_control.md
+++ b/tutorials/basic_motor_control.md
@@ -80,7 +80,7 @@ If the motor appears to be going in the wrong direction, just swap the motor's p
As a first example:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()
@@ -131,7 +131,7 @@ Our aim is to do the forwards and backwards bit (as above), but, instead of sett
Here's the code:
~~~~~ python
-from sr.robot3 import *
+from sr.robot3 import Robot
robot = Robot()