Skip to content

MARLIN API guide

This guide explains the ideas you need to write MARLIN robot programs.

It assumes you can read basic Python. If you cannot yet, read Python basics first.

Words used on every page

Learn these three first. The rest of the guide assumes them.

Word Meaning
Effector Anything on the robot that moves: a thruster or a servo.
Sensor Anything that measures: an IMU or a radio beacon.
Setpoint The value you last asked an effector to hold, such as 25% thruster power. MARLIN keeps sending it until you change it.

Python used on every page

The examples use three pieces of Python syntax a lot:

You will see It means
... "Your code goes here." Do not type three dots.
robot.run(driver=driver) A named argument. The name on the left is the slot; the value on the right is what goes in it. Writing the same word twice is normal.
{"M1": Thruster} A dictionary: a mapping. Here it maps the port name "M1" to the hardware type Thruster.

If you are new, read the pages in this order:

  1. Program structure
  2. Competition vocabulary
  3. Hardware configuration
  4. Match lifecycle
  5. State and sensor data
  6. Effector commands and safety
  7. Common mistakes

The big picture

Every MARLIN program has the same basic flow:

flowchart TB
    create["Create Robot"]
    configure["Configure sensors and effectors"]
    callbacks["Define phase callbacks"]
    run["Call robot.run(...)"]
    read["Read cached state"]
    command["Command effectors"]

    create --> configure
    configure --> callbacks
    callbacks --> run
    run --> read
    read --> command
    command --> read

You configure the robot once, then MARLIN calls your code during the correct match phase.

Guide pages

Page What it teaches
Program structure How a MARLIN Python file is organised
Competition vocabulary How match terms map to MARLIN code
Hardware configuration How to declare sensors, effectors, and ports
Match lifecycle How initialize, autonomous, driver, and robot.running work
State and sensor data How to read controller input, sensors, and robot status
Effector commands and safety How to command thrusters/servos and think about safety
Common mistakes Problems you are likely to hit while learning

Reference vs. guide

Use this guide when you want explanations and examples.

Use the API reference when you need exact class, method, or property details.

Complete robot program applies every page of this guide to one working file, built one step at a time. Then Examples has individual patterns to drop into it, and shows how to combine two of them.