Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SR2024 - Update Section - API Quick Reference #511

Merged
merged 2 commits into from
Sep 17, 2023
Merged

SR2024 - Update Section - API Quick Reference #511

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5b4b72e
Update cheat sheet
8BitJosh Sep 13, 2023
b0b73fa
Review tweaks
8BitJosh Sep 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 86 additions & 75 deletions programming/cheat_sheet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,75 +22,74 @@ from sr.robot3 import *
### Standard Initialisation

~~~~~ python
R = Robot()
robot = Robot()
~~~~~

### Initialisation without waiting for the start button

~~~~~ python
R = Robot(auto_start=True)
robot = Robot(wait_for_start=False)

# Code here runs before the start button is pressed

R.wait_start()
robot.wait_start() # wait for the start button
~~~~~

### Initialisation with extra logging

You can also tell the robot to print extra logging information, although this is quite noisy.
You can also tell the robot to print extra logging information, although this will create a lot of logs.

~~~~~ python
R = Robot(verbose=True)
robot = Robot(debug=True)
~~~~~

## Selecting which board to control

If you only have one board of a given type plugged into your robot, then you can use its singular name:

~~~~~ python
R.power_board.something
R.motor_board.something
R.servo_board.something
R.ruggeduino.something
robot.power_board
robot.motor_board
robot.servo_board
robot.arduino
~~~~~

If you have multiple boards of a given type plugged into your robot, you must index them by serial number:

~~~~~ python
R.motor_boards["srABC1"].something
R.servo_boards["srXYZ2"].something
R.ruggeduinos["1234567890"].something
robot.motor_boards["srABC1"]
robot.arduinos["1234567890"]
~~~~~

## Power Board

The outputs on the power board will turn on when you initialise your robot.
The outputs on the power board will turn on when you initialise your robot and turn off when your code ends.

### Turn on and off the power outputs

~~~~~ python
# Turn all of the outputs on
R.power_board.outputs.power_on()
robot.power_board.outputs.power_on()

# Turn all of the outputs off
R.power_board.outputs.power_off()
robot.power_board.outputs.power_off()

# Turn a single output on
R.power_board.outputs[OUT_H0].is_enabled = True
robot.power_board.outputs[OUT_H0].is_enabled = True

# Turn a single output off
R.power_board.outputs[OUT_H0].is_enabled = False
robot.power_board.outputs[OUT_H0].is_enabled = False
~~~~~

### Reading voltage and current

~~~~~ python
# Read the current of an individual output
current = R.power_board.outputs[OUT_H0].current
current = robot.power_board.outputs[OUT_H0].current

# Read the current and voltage from the LiPo battery
voltage = R.power_board.battery_sensor.voltage
current = R.power_board.battery_sensor.current
voltage = robot.power_board.battery_sensor.voltage
current = robot.power_board.battery_sensor.current
~~~~~

### Buzzer
Expand All @@ -99,10 +98,13 @@ The power board has an on-board piezoelectric buzzer.

~~~~~ python
# Play a standard note C6 -> C8 included for 0.5s
R.power_board.piezo.buzz(0.5, Note.C6)
robot.power_board.piezo.buzz(Note.C6, 0.5)

# Play a tone at 1047Hz for 1 second
R.power_board.piezo.buzz(1, 1047)
robot.power_board.piezo.buzz(1047, 1)

# Play a tone at 500Hz tone for 2 seconds and wait for it to finish
robot.power_board.piezo.buzz(500, 2, blocking=True)
~~~~~

## Motors
Expand All @@ -114,34 +116,33 @@ You can set the power of each motor on the board between -1 and 1.
If you change the power of your motor too rapidly, the overcurrent protection may be triggered.

~~~~~ python
R.motor_board.motors[0].power = 1
R.motor_board.motors[1].power = -1
robot.motor_board.motors[0].power = 1
robot.motor_board.motors[1].power = -1
~~~~~

Setting a motor to `COAST` is equivalent to power level `0`.
### Special motor values

Setting a motor to `BRAKE` is equivalent to power level `0`.

~~~~~ python
# This is the same operation
R.motor_board.motors[0].power = COAST
R.motor_board.motors[0].power = 0
robot.motor_board.motors[0].power = BRAKE
robot.motor_board.motors[0].power = 0
~~~~~

### Braking Motors

You can also brake a motor, which will quickly slow the motor.
`COAST` will stop applying power to the motors. This will mean they continue moving under the momentum they had before and slowly come to a stop.

~~~~~ python
R.motor_board.motors[0].power = BRAKE
R.motor_board.motors[1].power = -1
robot.motor_board.motors[0].power = COAST
~~~~~

## Servos

You can set the position of each servo output on the board between -1 and 1.

~~~~~ python
R.servo_board.servos[0].position = -1
R.servo_board.servos[1].position = 1
robot.servo_board.servos[0].position = -1
robot.servo_board.servos[1].position = 1
~~~~~

You can also set the position to `0`, which is the approximate centre.
Expand All @@ -153,15 +154,23 @@ You can also set the position to `0`, which is the approximate centre.
It can sometimes be useful to save a photo of what markers the robot can see:

~~~~~ python
R.camera.save("my-photo.png") # Save my-photo.png to the USB drive
robot.camera.save("my-photo.jpg") # Save my-photo.jpg to the USB drive
~~~~~

### Capturing an openCV array

Take a photo using the webcam, and return the image data as an OpenCV array:

~~~~~ python
frame = robot.camera.capture()
~~~~~

### Looking for markers

You can take a photo with the camera and search for markers:

~~~~~ python
markers = R.camera.see()
markers = robot.camera.see()
~~~~~

There are various bits of information available about visible markers:
Expand All @@ -172,94 +181,96 @@ for marker in markers:
marker.id # The ID of the marker
marker.size # Physical size of the marker in mm.

marker.distance # Distance away from the camera in mm

# Cartesian coords of the marker
marker.cartesian.x
marker.cartesian.y
marker.cartesian.z
marker.pixel_centre # The co-ordinates of the centre of the marker
marker.pixel_corners # A list of corners of the marker

# Spherical coords of the marker
marker.spherical.rot_x
marker.spherical.rot_y
marker.spherical.dist
# Position of the marker
marker.position.distance # Distance away from the camera in mm
marker.position.horizontal_angle # angle to the marker in radians
marker.position.vertical_angle # angle to the marker in radians

# Orientation of the marker
marker.orientation.rot_x
marker.orientation.rot_y
marker.orientation.rot_z
marker.orientation.rotation_matrix
marker.orientation.yaw
marker.orientation.pitch
marker.orientation.roll
~~~~~

## Ruggeduino
## Arduino

### Setting the mode of a pin

~~~~~ python
R.ruggeduino.pins[4].mode = OUTPUT
R.ruggeduino.pins[4].mode = INPUT
R.ruggeduino.pins[4].mode = INPUT_PULLUP
robot.ruggeduino.pins[4].mode = OUTPUT
robot.ruggeduino.pins[4].mode = INPUT
robot.ruggeduino.pins[4].mode = INPUT_PULLUP
~~~~~

### Digital Write

You can set the output for a pin of the Ruggeduino:
You can set the output for a pin of the Arduino:

~~~~~ python
R.ruggeduino.pins[4].mode = OUTPUT
robot.ruggeduino.pins[2].mode = OUTPUT

R.ruggeduino.pins[2].digital_write(True)
R.ruggeduino.pins[2].digital_write(False)
robot.ruggeduino.pins[2].digital_write(True)
robot.ruggeduino.pins[2].digital_write(False)
~~~~~

### Digital Read

You can read a digital value from the pins of the Ruggeduino:
You can read a digital value from the pins of the Arduino:

~~~~~ python
R.ruggeduino.pins[3].mode = INPUT
robot.ruggeduino.pins[3].mode = INPUT
robot.ruggeduino.pins[5].mode = INPUT_PULLUP

value = R.ruggeduino.pins[3].digital_read()
value = robot.ruggeduino.pins[3].digital_read()
value = robot.ruggeduino.pins[5].digital_read()
~~~~~

### Analogue Read

You can read an analogue value from the analogue pins of the Ruggeduino:
You can read an analogue value from the analogue pins of the Arduino:

~~~~~ python
value = R.ruggeduino.pins[A0].analogue_read()
robot.ruggeduino.pins[A0].mode = INPUT

value = robot.ruggeduino.pins[A0].analogue_read()
~~~~~

## Metadata

The API also makes some information about where your code is running

### Starting Zone for a match
### Starting zone for a match

~~~~~ python
zone = R.zone # -> 0, 1, 2, or 3
zone = robot.zone # -> 0, 1, 2, or 3
~~~~~

### Arena Information
### Robot mode

This is set to `COMP` when your robot is in a match.

~~~~~ python
arena = R.arena # -> 'A'
robot_mode = robot.mode # -> DEV or COMP
~~~~~

### Robot Mode
### USB stick path

This is set to `COMP` when your robot is in a match.
This is the path to where your USB stick is mounted.

You can use this to save files and information to the drive.

~~~~~ python
robot_mode = R.mode # -> DEV or COMP
usb_key_path = robot.usbkey
~~~~~

### USB Key Path
### Is simulated

This is the path to where your USB key is mounted.

You can use this to save files and information to the drive.
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.

~~~~~ python
usb_key_path = R.usbkey # -> pathlib.Path
value = robot.is_simulated
~~~~~