runtime.api

Student API for controlling the robot.

The student provides a single Python file containing a minimum of four functions:

>>> def autonomous_setup():
...     ...
>>> def autonomous_main():
...     ...
>>> def teleop_setup():
...     ...
>>> def teleop_main():
...     ...

The *_setup functions—autonomous_setup and teleop_setup—run once at the start of the autonomous and teleop phases, respectively. After the setup function runs, the corresponding *_main functions run periodically until the end of the phase. The frequency of main calls is configurable, but the default interval is 0.1s.

These interfaces are largely thin wrappers around runtime.buffer.BufferStore.

class runtime.api.Actions[source]

Bases: runtime.api.StudentAPI

API for performing asynchronous execution.

An “action” is a special function defined with the async def keywords, like so:

>>> async def wave_hand():
...     Robot.set(SERVO_UID, 'servo0', -0.5)
...     await Actions.sleep(1)
...     Robot.set(SERVO_UID, 'servo0', 0.5)

In this example, the robot’s servo rotates 45 degrees counterclockwise from the motor’s center, waits one second, and then rotates 90 degrees clockwise. Actions are useful for triggering time-sensitive events outside the autonomous_main or teleop_main functions, which fire at a fixed frequency.

To schedule an action to run, call Actions.run() on the action’s name from one of the regular *_setup or *_main functions, like so:

>>> def autonomous_setup():
...     Actions.run(wave_hand)  # Correct
...     wave_hand()             # Incorrect: will not run

Do not call an action like you would call a regular function.

abstract is_running(action, /)[source]

Check whether an action is already running.

Parameters

action (Callable[[...], Awaitable[None]]) – An action (coroutine function).

abstract run(action, /, *args, timeout=30, periodic=False)[source]

Schedule an action to run outside of the *_main functions.

Parameters

  • action (Callable[[...], Awaitable[None]]) – An action (coroutine function).

  • args (Any) – Positional arguments to pass to the action.

  • timeout (float) – Maximum number of seconds the action should be allowed to run for. Must be a nonnegative number.

  • periodic (bool) – Whether to run the action repeatedly or not. A periodic action that completes before the timeout has elapsed is not rescheduled early.

async static sleep(duration, /)[source]

Pause the current action for some amount of time.

Parameters

duration (float) – The number of seconds to wait for. Must be a nonnegative number.

Note

Remember to use the await keyword before Actions.sleep().

class runtime.api.Alliance(value)[source]

Bases: enum.IntEnum

The alliances that compete in a match.

BLUE

The blue alliance.

GOLD

The gold alliance.

class runtime.api.BufferAPI(buffers, logger)[source]

Bases: runtime.api.StudentAPI

Base type for all APIs that access shared memory buffers.

Parameters
class runtime.api.Field(buffers, logger, start=<factory>)[source]

Bases: runtime.api.BufferAPI

API for interacting with the field and other robots.

Parameters

start (float) – The UNIX timestamp (in seconds) of the start of the current autonomous/teleop phase.

clock()[source]

The number of seconds since autonomus or teleop started.

recv()[source]

Receive a message from an allied robot.

send(obj, /)[source]

Send a message to an allied robot.

property alliance: runtime.api.Alliance

The alliance this robot is a member of in this match.

class runtime.api.Gamepad(buffers, logger, enabled=True)[source]

Bases: runtime.api.BufferAPI

API for reading game controller inputs.

Parameters

enabled (bool) – Whether gamepads are enabled. In autonomous mode, this parameter should be set to False.

get(param, index=0, /)[source]

Get a gamepad parameter.

Attempting to access a gamepad while it is disabled will emit a warning but will still return a type-safe default value.

Parameters

  • param (str) – Parameter name.

  • index (int) – Gamepad identifier (a nonnegative integer).

class runtime.api.Robot(buffers, logger, names=<factory>)[source]

Bases: runtime.api.BufferAPI

API for accessing Smart Devices.

Parameters

names (Mapping[str, int]) – A mapping from human-readable device names (aliases) to UIDs that students can configure.

get(uid, param, /)[source]

Get a Smart Device parameter.

Parameters

  • uid (Union[str, int]) – Either a UID as an integer or a device name to be resolved into a UID.

  • param (str) – Parameter name.

Returns

The current parameter value. Because written parameters take time to propogate to the device and the device must send an acknowledgement, the current value may not immediately reflect a written value.

write(uid, param, value, /)[source]

Write a Smart Device parameter.

Parameters

  • uid (Union[str, int]) – Either a UID as an integer or a device name to be resolved into a UID.

  • param (str) – Parameter name.

  • value (Any) – New parameter value.

class runtime.api.StudentAPI[source]

Bases: abc.ABC

Base type for all student-callable interfaces.

runtime.api.safe(method)[source]

A decorator that wraps API methods to catch and log any exceptions.

Parameters

method (Callable[[...], runtime.api.RT]) – API method to be wrapped.

Returns

The method wrapper. If the wrapped method raises an Exception, the wrapper’s return value will be None. BaseException is too broad to catch.