Operate the MARLIN extension¶

The MARLIN VS Code extension is the control station for your laptop. It is the piece that connects your Python program to the Controller and robot.

Use this page when you want to run a program, connect or disconnect the Controller, understand the buttons, or diagnose messages in the MARLIN Console.

If you just want to get a program running, follow Run your program. For a section-by-section visual walkthrough, see the extension UI tour.

What the extension does¶

The extension does three main jobs:

• connects your laptop to the Controller and robot brain
• runs your MARLIN project's program when a phase starts
• sends match commands such as Auton, Driver, Pause, and E-Stop.

At competitions, the pool server can send those match commands for you.

flowchart LR
    you["You"]
    extension["MARLIN extension"]
    script["Your program"]
    controller["Controller"]
    robot["Robot"]
    pool["Pool server\ncompetition only"]

    you --> extension
    extension --> script
    extension <--> controller
    controller <--> robot
    pool -.-> extension

Before you start¶

1. Install the MARLIN extension from the VS Code Marketplace.
2. Open the MARLIN control station from the MARLIN activity-bar icon.
3. Open or create a MARLIN project (New Project in the control station, or the MARLIN: Create New MARLIN Project command).
4. Connect the Controller to the laptop over USB.

Without a Controller plugged in you can still check that the extension opens and that your Python environment can import marlin (the extension bundles the MARLIN API, so nothing needs to be installed with pip for a normal setup; see Install MARLIN).

Practice or testing flow¶

When you are testing away from the official pool server, connect, pair, and start a phase as described in Run your program.

Competition flow¶

Use this flow when the event pool server is running the match.

1. Enter the pool server URL, team number, and station.
2. Click Save.
3. Connect to the Controller and pair the robot brain.
4. Open your MARLIN project.
5. Wait for the pool server to send Auton, Driver, Pause, and E-Stop commands. The pool server's own Auton/Driver command starts your program for you, the same way the local buttons do.

While the extension is connected to a pool server, the local Pause, Auton, and Driver buttons and the editor title-bar icons are disabled, so an official does not need to tell you to leave them alone. The extension enforces it. E-STOP stays available locally at all times as a safety backstop.

Extension sections¶

Field Network¶

The Field Network section identifies this laptop to a MARLIN pool server.

There is no separate alliance field; the station you choose already encodes Red or Blue.

Click Save after editing these values. If the station is already connected, Save reconnects it immediately with the new values; otherwise it just saves, and you press Connect when the pool server is running.

If you are not using a pool server, leave the server URL blank. That avoids repeated "could not connect to pool server" messages while you are testing locally.

Running the Pool is separate from normal robot programming. See Pool management for the event-staff side.

Controller¶

The Controller section manages the USB serial connection, analog-stick calibration, and the LoRa beacon channel.

The selected port is the USB device connected to the Controller, not the robot. The Controller forwards commands to the robot over the Bluetooth (BLE) link. The port the extension pre-selects is often not the Controller. See Which port is the Controller? for what the name looks like on each operating system.

If Refresh does not show the Controller:

• check the USB cable
• check that the Controller is powered
• unplug and reconnect the Controller
• try another USB port
• look at the MARLIN Console for serial discovery errors.

Calibrate Sticks¶

No two gimbals are alike. A released stick rarely reports exactly the middle of its range, and a stick pushed hard over usually stops short of the electrical end. Without calibration a robot can creep while nobody is touching the panel, and never quite reach full speed. Calibrate Sticks measures both: where each stick rests, and how far it actually travels.

You need a MARLIN project open and the Controller connected. The run has two parts:

1. Centre. The status bar reads Calibrating centre - do not touch the sticks... and samples for about 1.5 seconds. Take your hands off the panel. The average of that sample becomes the centre of each axis, and how much the reading wobbled becomes the deadzone.
2. Travel, one joystick at a time. A dialog appears for the Left joystick, then the Right. Click Measure, then push that joystick all the way over and roll it clockwise around the edge, staying on the edge, for the five seconds the status bar counts down. Leave the other joystick alone. One lap carries both of that stick's axes to both of their ends, so one lap measures both.

Skip drops that one joystick and moves on; Cancel (or closing the dialog) ends the run. Either way, whatever was measured before that is still saved.

When it finishes, the status bar names what came out calibrated, for example Sticks calibrated: centre, travel on both joysticks (deadzone 12 counts), and the MARLIN Console logs the numbers using the panel labels:

[EXT] Saved stick calibration to project.marlin: ONE centre 2043 travel 210-3880, TWO centre 2051 travel 260-3820, THREE centre 2039 travel full range, FOUR centre 2044 travel full range, deadzone 12 counts

travel full range means that axis was never measured. You skipped it, or the lap did not reach far enough. A lap has to get at least 200 counts past centre on a side before that side is believed; otherwise the extension keeps the uncalibrated end rather than build a hair-trigger axis out of a lazy lap. Each side is judged on its own, so a sweep that was generous one way and shy the other keeps the good half. If a joystick was swept but fell short, the status bar says so, with the Left joystick did not reach the edge all the way round, measure it again, and you can run it again.

The result is written to the stick_center line of project.marlin and applied to the live connection at once; you do not need to reconnect. Calibration belongs to the project, so it travels with the folder and each project starts uncalibrated until you run it. An axis that has never been calibrated behaves exactly as it did before calibration existed, and a project.marlin written by an older version of the extension still loads. Its axes read back as uncalibrated.

Robot Brain¶

The Robot Brain section pairs the Controller, over Bluetooth, to the robot brain, and shows its live telemetry.

To pair: press the pairing button on the robot brain, click Rescan, pick your brain from the list, then click Connect. The Controller must already be connected. It is what performs the Bluetooth pairing.

If a robot brain is already paired to someone else's Controller, hold its pairing button for about 4 seconds, then press Connect again within 30 seconds. A robot brain that overheats stops itself and reports it in the MARLIN Console; the extension brings it back once it has cooled.

Your Program¶

The Your Program section creates a MARLIN project and stops the running program.

Starting Auton or Driver, from Match Control or the editor title-bar icons, launches src/main.py from the open MARLIN project automatically if it is not already running, and restarts it if the file changed since it last started. Stop always ends the program, even one stuck in a loop, and stays available during an E-Stop.

If the MARLIN Console says Python cannot import marlin, check that the selected Python interpreter is 3.10 or newer. See Install MARLIN.

Match Control¶

The Match Control section starts each match phase and sends safety commands.

Auton and Driver choose which part of your program runs: Auton runs your autonomous(robot) function, and Driver runs your driver(robot) function. The same Start Auton and Start Driver icons also appear in the editor title bar whenever a MARLIN project is open, and do the same thing as the Match Control buttons.

E-Stop is deliberately separate from your code. A bug in your program should not be able to block emergency stop behaviour. Clear E-Stop clears a locally issued E-Stop at any time. While the extension is connected to a pool server, Clear E-Stop cannot clear a pool-issued E-Stop; only the pool dashboard can clear it. If the extension loses its pool server connection, Clear E-Stop can then clear that E-Stop locally.

MARLIN Console¶

Console messages appear in a separate MARLIN Console panel, opened with the Open Console button in the control station or the MARLIN: Open Console command. It has a source filter (All messages, [EXT] Extension, [CON] Controller, [FLD] Field, [OUT] Student script, [IN] Console input), a Clear button, and an input box for answering an input() call in your running program.

Categories you will see include:

• [EXT] extension-level problems, such as Python failing to import marlin.
• [CON] Controller/serial activity, including named controller button and trigger presses when connected.
• [FLD] pool server connection and match messages.
• [OUT] your running program's own output.
• [OUT] [API] a runtime message from the MARLIN library itself rather than from your code, such as a phase starting with no callback to run. [API] is a prefix on this channel, never a source of its own, so it always follows [OUT].

If something goes wrong, read the newest console message first. It usually points to the missing install step or connection that needs attention.

Settings that persist¶

VS Code extensions can store settings between sessions. The control station may remember:

• the pool server URL, team number, and station
• the last-used robot brain name
• extension settings such as the Python path and beacon channel.

The Controller port is not remembered between sessions. On each restart the extension selects the first port it finds; use Refresh and pick the correct one if you have more than one serial device attached.

This is convenient between sessions, but it can also be confusing if an old pool server URL keeps producing connection errors. If that happens, clear the pool server URL or update it to the current server.