Robot API

Student Robotics has written a module — sr.robot3 — which is used to interface with the hardware. It handles all the low-level interactions so you don’t have to.

For example, to set the power of output 0 on a Motor Board to 30%, you would write:

robot.motor_board.motors[0].power = 0.3

To gain access to all of this functionality, all you need to do at the top of your code is the following:

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:

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.

Then, within your robot you can use the following attributes to access to the robot’s hardware:

• kch
• motor_board
• power_board
• servo_board
• arduino
• camera

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:

zone

The number of the scoring zone that the robot is associated with. 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 page for more information about this attribute.

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.

This attribute is only available after the start button is pressed and will throw an error if accessed before. See the competition mode page for more information about this attribute.

from sr.robot3 import Robot, COMP, DEV

robot = Robot()

if robot.mode == COMP:
    print("This is the competition!")
elif robot.mode == DEV:
    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 object containing the path to the USB stick. You can use this to easily read and write files on the USB stick itself.

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:

from sr.robot3 import Robot
import os

robot = Robot()
print("The path to the USB stick is:", robot.usbkey)
print("My file on the USB contains:")
with open(os.path.join(robot.usbkey, 'my-file.txt')) as file:
    print(file.read())

is_simulated

A boolean value indicating whether or not the code is running in the simulator. This value is True when in the simulator and False when on the robot.

Custom Robot Object Initialisation

Normally the Robot object is initialised with the following:

from sr.robot3 import Robot
robot = Robot()

By default your robot will pause on this line waiting for the start button to be pressed. 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.

from sr.robot3 import Robot
robot = Robot(wait_for_start=False)

# Initialisation phase.
# Here you can perform hardware/software initialisation before start

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:

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.

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.