MARLIN API​

To use the MARLIN API, import the marlin library in your Python code.

from marlin import Robot, IMU, RadioBeacon, Thruster, Servo, Phase

The API has four parts:

1. Robot (configuration, match state)
2. Controller (joysticks and buttons)
3. Effectors (thrusters and servos)
4. Sensors (IMU and radio beacon)

Robot​

Robot()​

Robot is a class. Import it from MARLIN and create one object robot at the start of your code.

Robot(endpoint: str | None = None)

from marlin import Robot

robot = Robot()

configure()​

configure() declares the type of hardware connected to each port to the Robot Brain. Only list the ports you use. A wrong declaration will throw an error.

robot.configure(
    *,
    sensors: dict[str, type[Sensor]],
    effectors: dict[str, type[Effector]],
) -> None

from marlin import Robot, IMU, Thruster, Servo

robot = Robot()
robot.configure(
    sensors={"S1": IMU},
    effectors={"M1": Thruster, "M8": Thruster, "M2": Servo},
)

run()​

run() watches robot.phase and calls the respective match phase function once.

You write one function per phase and pass them in here — each is optional, keyword-only, and receives the robot. Each function is called once, the moment its phase starts, so it must keep looping until the phase ends — that is what while robot.running: is for. run() blocks until the match is over or an E-Stop fires.

Whenever a phase ends — or your function returns early — MARLIN idles every effector. A function that returns early is not called again that phase; one that loops past the end is stopped and its commands ignored. An exception in your function stops the robot, then comes out of run() with the usual Python traceback.

robot.run(
    *,
    initialize: Callable[[Robot], None] | None = None,
    autonomous: Callable[[Robot], None] | None = None,
    driver: Callable[[Robot], None] | None = None,
) -> None

def autonomous(robot):
    while robot.running:
        ...

def driver(robot):
    while robot.running:
        ...

robot.run(autonomous=autonomous, driver=driver)

Match State​

Seven read-only properties describing the robot and the match. The Pool Server dictates the match phase. In its absence, MARLIN can specify the match phase from the control station.

robot.running​

True while the phase your function was called for is still going. False when the phase ends, causing a while robot.running: loop to exit at the end of a match phase.

robot.running runs at a rate of 50 Hz, the same rate MARLIN sends commands. Adding time.sleep() decreases the frequency.

Example

def driver(robot):
    while robot.running:
        ...            # runs 50 times a second without time.sleep()

robot.phase​

Reads which part of the match the robot is in.

Example

from marlin import Phase

if robot.phase == Phase.AUTON:
    ...

Controller​

The Controller has four joystick axes and ten independent buttons. Follow the naming conventions strictly. A wrong button or joystick axis name will throw an error.

robot.controller.joystick()​

Returns one of the four joystick axes. There are two types of values that can be returned, scaled and raw values.

robot.controller.joystick(name: str) -> Joystick

robot.controller.joystick().value​

How far the stick is pushed: −100 to 100, and 0 when centred. The joystick axis range matches the thruster's duty, so a stick can drive a thruster directly.

power = robot.controller.joystick("ONE").value

robot.controller.joystick().raw​

The unscaled reading behind value: 0–4095, with centre at 2048. raw is used for checking a stick's true centre or writing your own scaling.

joystick_value = robot.controller.joystick("ONE").raw

robot.controller.button().is_down​

Returns the button state. True while the button is held down, False when released.

robot.controller.button(name: str).is_down -> bool

if robot.controller.button("A").is_down:
    ...

while robot.running:
  was_down = False
  down = robot.controller.button("A").is_down
  if down and not was_down:
      ...
  was_down = down

Effectors​

Declare the type of effector in configure() and fetch it with robot.thruster() or robot.servo(). These are the generic behaviours of effectors.

1. An effector will follow the last command given in the current match phase.
2. Effector inputs are clamped.
3. Idle state differs by effector type.

robot.thruster().set_duty()​

Set the duty cycle of the thruster from a range of -100 to 100, with 0 being the idle state. Note that this does not represent the exact speed or power of the thruster.

robot.thruster(port: str).set_duty(duty: float) -> None

robot.thruster("M1").set_duty(100)

robot.servo().angle()​

Turns a positional servo to an angle from 0° to 180° and holds it there. Due to the nature of positional servos, it will always hold a position within its working range. The idle state of the servos is 90°. Keep that in mind when writing your code.

robot.servo(port: str).angle(deg: float) -> None

robot.servo("M2").angle(120)

robot.servo().set_speed()​

Set the movement speed of the servo. The speed range is 100 deg/s to 360 deg/s. If the speed isn't defined, the servo will default to 180 deg/s.

robot.servo(port: str).set_speed(speed: float) -> None

robot.servo("M2").set_speed(180)

Sensors​

Like effectors, sensors are declared in configure() and fetched with robot.imu() or robot.radiobeacon(). Every sensor has one method: read().

read() returns the latest data measured by the sensor. Every sensor reading carries these three fields:

robot.imu().read()​

IMU sensor: Acceleration, Turn Rate and Magnetic field.

robot.imu(port: str).read() -> ImuReading

reading = robot.imu("S1").read()
if reading.ok:
    print(reading)

Returns: ImuReading with ok, age, timestamp and:

robot.radiobeacon().read()​

Long-range radio receiver. It reports how strong a beacon's signal is and which beacon sent it — not a direction or a distance, though strength does tend to rise as you get closer.

robot.radiobeacon(port: str).read() -> RadioBeaconReading

reading = robot.radiobeacon("S6").read()
if reading.ok:
    print(reading)

Returns: RadioBeaconReading with ok, age, timestamp and:

Error Messages​

This page lists the errors raised by the MARLIN Python library. In the MARLIN Console they appear under the [OUT] tag, in two forms:

1. Exceptions — the program stops with a Python traceback. If the last line of the traceback names one of the types below, MARLIN raised it and the tables explain the fix. ZeroDivisionError, NameError, SyntaxError, etc. are ordinary Python errors in your own code.
2. [API] warnings — the program keeps running. MARLIN absorbed the mistake and printed what it did about it.

Messages tagged [EXT], [CON], or [POOL] come from the extension, the Controller, or the Pool Server, not from your code. See the MARLIN Console.

MARLIN idles every effector when a match phase ends, regardless of any error.

ValueError​

TypeError​

KeyError​

LookupError​

RuntimeError​

LinkError​

Raised when the connection between the program, the extension, and the robot fails. These are not code problems — check the control station: Controller connected, Robot Brain paired, battery in. ("C3" in these messages means the Controller.) LinkError is a subclass of RuntimeError.

[API] warnings​

Printed to the MARLIN Console; the program keeps running. Each warning states what MARLIN did about the mistake.