API Reference¶

Every function you can call from a BugBot program. The same names and units work on the robot, from the laptop and in the simulator, unless a row says otherwise.

Every program starts with from bugbot import * connect(). That connects to the robot (or the simulator) and makes every function below available by name.

Units¶

Speed: 0 to 100, percent of full power.
Distance: centimetres. Velocity: centimetres per second.
Angles: degrees, clockwise positive. heading() is 0 to 360, and reset_heading() makes the way the robot faces now 0.
Position: (x, y) in centimetres from where the robot started or was last reset. x is to the right, y is forward. In a game the position is measured from the bottom-left corner of the shared mat instead.
A call marked waits finishes before the next line of your program runs. Every other call returns straight away.
Safety: if your program stops, or no driving command arrives for half a second, the robot stops.

Motion¶

Function	What it does
`forward(speed=50, distance=None)`	Drive forward. With `distance` (cm) it waits until the robot has gone that far, then stops.
`backward(speed=50, distance=None)`	The same, backward.
`left(speed=50, distance=None)`	Slide left without turning. Same `distance` option.
`right(speed=50, distance=None)`	Slide right without turning.
`turn_left(speed=50)`	Spin anticlockwise on the spot until told otherwise.
`turn_right(speed=50)`	Spin clockwise on the spot.
`turn_right(30, angle=degrees)`	Turn by an angle, clockwise positive. Waits until done.
`drive(fwd, lat, rot=0)`	Forward, sideways and rotation together, each -100 to 100. Keeps going until the next command.
`stop()`	All motors off.
`wait(seconds)`	Pause the program, keeping the current motion going.
`clock()`	Seconds since the program started.

Lights, gripper and servos¶

Function	What it does
`led(colour)` or `led(r, g, b)`	The RGB LED. Colour names: red, green, blue, yellow, cyan, magenta, white, orange, purple, pink, off. Or a hex code such as `led("#FF8000")`.
`gripper(state)`	`gripper("open")` or `gripper(1)` opens the jaws, `gripper("close")` or `gripper(0)` closes them on a ball in reach. Waits while they move (about 0.4 s).
`kick()`	One kick: the kicker turns once and the spring sends the ball in front about 45 cm.
`servo(index, angle)`	Servo 0 is the gripper: 90 closes it, 0 opens it. Servo 1 is the kicker: 91 turns it (one turn is one kick), 90 stops it.

Sound¶

The simulated robot has a passive piezo, the small disc that beeps in alarms and toys. A later BugBot board adds one; on today's robot these two raise "this robot has no piezo".

Function	What it does
`tone(freq)` or `tone(freq, seconds)`	Play one note at `freq` hertz, 100 to 10000. With `seconds` the program waits until the note ends; without, the note carries on until the next `tone()` or `no_tone()`. `tone(0)` is silence.
`no_tone()`	Stop the note.

A piezo plays one note at a time, with no volume control. It is loudest at a few thousand hertz and thin at low notes. Middle C is 262 Hz; each octave up doubles the frequency.

Sensors¶

Function	Returns
`distance()`	Centimetres to the nearest thing straight ahead.
`tof_grid()`	64 distances in cm, 8 rows of 8. Rows 2 and 3 look level, straight out.
`scan()`	The depth sensor as a fan: eight `(angle, distance)` pairs across its view, left to right. The angle is degrees from straight ahead, negative to the left.
`heading()`	Which way the robot faces, 0 to 360 degrees.
`position()`	`(x, y)` in cm.
`velocity()`	`(vx, vy)` in cm/s.
`battery()`	0 to 100 percent.
`bumped()`	`True` just after the robot touches something.
`holding()`	The colour of the ball in the gripper, or `None`.
`reset_heading()`	The way the robot faces now becomes 0.
`reset_position()`	Where the robot is now becomes (0, 0).

What the robot knows about itself¶

position() and heading() are the simulator's own truth, the equivalent of an overhead camera in a lab. A real robot does not have them. What it does have is the odometry board: an optical flow sensor looking down at the mat and an IMU. Those are measured, so they are wrong in the ways real sensors are wrong, and a program that needs to know where it is has to work it out.

Function	Returns
`imu()`	`(heading, turn_rate, ax, ay)`: degrees, degrees per second (clockwise positive), and the acceleration along the robot's own right and forward axes in cm/s/s. Noisy, and the heading carries a small offset that wanders.
`flow()`	`(vx, vy)` in cm/s, right and forward: how fast the mat is sliding past underneath. It measures what actually moved, so a robot pushing against a wall reads near zero.
`odometry()`	`(x, y, heading)`: where the robot thinks it is, from adding up `flow()` and the turn rate. It drifts.
`reset_odometry(x=0, y=0, heading=0)`	Tell the robot where it is. Dead reckoning starts again from there.
`set_noise(level=1, depth=None)`	How rough the sensors are: 0 is perfect, 1 is the robot as built, 3 is a bad day. `depth` sets the depth sensor's noise in cm.
`plot(name, value)`	Add one point to a chart drawn under the console, so a signal can be looked at rather than read. Up to eight named lines. On the real robot the points come back to the laptop: the dashboard charts them and saves them as `<script>_plot.csv`.
`trace(name, ..., every="change")`	Print a trace table while the program runs: a column for each variable named (as text, in quotes), and a new row every time one of them changes, headed by the line that changed it. `every="row"` writes every value on every row instead of only the ones that changed. Up to eight variables. On the real robot the table is printed back on the laptop.
`draw(name, points, colour="yellow", style="dots", size=None)`	Draw on the mat in the simulator's overhead view: `points` is a list of `(x, y)` in cm. `style` is `"dots"`, `"line"` (joined in order) or `"squares"` (filled, `size` cm across, 10 unless given). Each name is one layer, and drawing it again replaces it, so draw it every time round a loop to show something that changes: the cells a search has looked at, a planned route, a cloud of guesses. `draw(name, [])` clears it. Up to eight layers, 2000 points each. On the real robot the picture is sent back to the laptop, where the dashboard draws it.

Vision¶

The camera is 320 pixels wide with a 120 degree view, so cx 160 is straight ahead. The camera runs one detector at a time: pick it with set_cv.

Function	Returns
`set_cv(mode, colour=None)`	Choose the detector: `"apriltag"`, `"blob"` (with a colour: red, green, blue or yellow), `"line"` or `"none"`.
`apriltags()`	Every tag in view: `[id, cx, cy, distance_cm]`.
`marker_tags()`	The markers in view. Only the mat carries tags, so this is the same list as `apriltags()`.
`robots()`	Every other robot in view, nearest first: `[colour, cx, cy, distance_cm]`, found by the colour of its lit dome. Needs no `set_cv()`.
`blobs()`	`[cx, cy, area, x0, y0, x1, y1, aspect]` for each patch of the chosen colour.
`line()`	`[cx, angle]` for the line ahead, or `[]` when there is none.
`camera_image(width=32, height=24)`	The picture itself, scaled down: a list of rows, each a list of `(red, green, blue)` pixels from 0 to 255. At most 64 by 48. Works whichever detector is chosen.

On the real robot only (not in the simulator): the "contour" and "face" detectors, with edges() and faces(), and camera_suspend() / camera_resume() to save power.

Radio¶

Function	What it does
`send(text)`	Send a message that every other robot hears.
`messages()`	Everything that arrived since you last asked: a list of `(sender, text)`, oldest first.

Games¶

Function	Returns
`info()`	Facts the game gives your robot, looked up by name, for example `info()['lane_x']` in the lane games.
`others()`	The other robots in the arena, each with a `name`, an `x` and a `y`.

Lists and tuples¶

On the robot, functions that return several values give a list; on the laptop and in the simulator they give a tuple. Unpacking works the same everywhere, so x, y = position() is fine on all three.