tracker.*

Commands and configuration files for Mantis tracking, including Lighthouse validation and recalibration.

The axol tracker.* commands set up and check the trackers for Mantis Tracking. The Tracking section of the control panel’s Mantis settings runs the same commands. This page lists their flags and file formats. For the setup walkthrough, see Mantis Tracking.

Command	Purpose	Panel equivalent
tracker.bridge	Stream tracker poses and trigger values to the VR server.	Started and stopped by a Mantis collect-data run.
tracker.identify	Bind the powered trackers to the left and right rig.	Identify trackers
tracker.pair	Pair a VIVE Tracker 3.0 with its Watchman dongle.	Pair tracker
tracker.install	Install libsurvive and the Vive udev rule.	Install Lighthouse support
tracker.lighthouse.check	Check which base stations and trackers are reporting.	Check base stations
tracker.lighthouse.validate	Check tracking quality with guided holds and a sweep.	Validate tracking
tracker.lighthouse.calibrate	Recalibrate the base stations, then validate.	Recalibrate Lighthouse
tracker.ultimate.install	Install the VIVE Ultimate Tracker runtime and dongle udev rule.	Install Ultimate support
tracker.ultimate.check	Check that the computer is ready for Ultimate trackers.	None (CLI only)

When you run axol collect-data --mantis true from the command line, it uses the tracking source, bindings and Quest calibration saved in the panel. It starts the bridge and runs the same readiness checks as the panel.

• Don’t start a second tracker.bridge next to a collection run. It can’t take control of the poses.
• axol teleop --mantis doesn’t use tracking. It drives the grippers from the rig triggers over CAN.
• Quest uses none of these commands. The headset is the pose source, and you choose its calibration in the panel.
• Collect DAgger and Run Policy don’t support Mantis.

# One-time per tracker family: bind physical trackers to sides.
axol tracker.identify --backend survive
axol tracker.identify --backend ultimate

# One command owns both the operation and its bridge.
axol collect-data --mantis true --repo_id myorg/bringup --task test \
    --mantis_allow_uncalibrated true   # bring-up capture only, not training data

axol tracker.bridge

Streams each tracker’s pose and each side’s trigger value to the VR server as VRFrame messages.

Flag	Description
--backend {survive,ultimate,synthetic,static}	Tracker backend. Default: the saved config, else survive. synthetic streams generated motion and static holds fixed poses, for tests without trackers.
--left KEY / --right KEY	Override the saved binding: a Lighthouse serial such as LHR-E0FCD01B, or an Ultimate MAC address.
--host HOST	VR server host, the computer running teleop or collect-data. Default: localhost.
--port INT	VR server port. Default: 8000.
--hz FLOAT	Frame rate. Default: 120.
--trigger-can-left IFACE / --trigger-can-right IFACE	CAN interface of that side’s trigger. Default: the saved config, else can_mantis_l / can_mantis_r.

How the bridge handles problems:

• A tracker loses tracking. That side holds its last good pose and logs a warning.
• A trigger stops sending for about 250 ms. That side holds its last grip command and logs the dropout.
• survive-cli crashes. The bridge restarts it after about a second. The rigs hold still until both trackers report again. More than 3 crashes in a minute stops the bridge, and the error shows the last lines of survive-cli’s output.
• A tracker drops off USB. The bridge restarts survive-cli every 5 seconds, for up to 60 seconds, until every tracker reports again.

After tracking comes back in a collection run, the bridge waits for both trackers, then for the two-trigger start gesture, before the arms follow again. If a trigger is missing, the collection run fails its readiness check.

A bridge you start yourself has keyboard controls: Enter engages or disengages, r returns to rest, and q quits. If a trigger is missing, it warns and keeps that gripper fully open.

Hardware-free protocol demo

To try the bridge without Mantis, run the sim and a static bridge:

axol teleop --sim --teleop.absolute_mode true  # terminal 1
axol tracker.bridge --backend static            # terminal 2

Press Enter in the bridge terminal to engage. The simulated arms stay at the static poses. This tests only the connection to the VR server and IK. It is not an acceptance check. The static and synthetic backends don’t need tracker.identify.

axol tracker.identify

Finds the powered trackers, then asks you to move each rig in turn. The tracker that moves most is bound to that side. For Lighthouse, it first runs the same check as tracker.lighthouse.check and won’t bind while two base stations share a channel. Lighthouse and Ultimate bindings are saved separately, so you can switch between them in the panel.

Flag	Description
--backend {survive,ultimate,synthetic}	Backend to use and save. Default: the saved config, else survive.

Saves ~/.almond/tracker/config.json:

{
  "backend": "survive",
  "left": "LHR-E0FCD01B",
  "right": "LHR-BDD65467",
  "bindings": {
    "survive": {"left": "LHR-E0FCD01B", "right": "LHR-BDD65467"},
    "ultimate": {"left": "A1:B2:C3", "right": "D4:E5:F6"}
  },
  "ultimate_quat_order": "wxyz",
  "ultimate_up_axis": "z",
  "expected_base_stations": 2,
  "lighthouse_quality": "standard"
}

Check base stations sets expected_base_stations (--expected_stations). lighthouse_quality is the Lighthouse tracking policy.

Lighthouse trackers are bound by serial number. libsurvive’s device names (WM0, WM1) can swap between runs, so Axol clears a saved binding that uses one. Run Identify trackers once to bind by serial.

axol tracker.pair

Pairs one VIVE Tracker 3.0 with its Watchman dongle. Unplug the tracker from USB and make sure it is blinking blue. Run it once for each tracker and dongle.

A dongle can pair only when no tracker is connected to it. If every dongle already has a powered tracker, the command says they are already paired. To pair a different tracker to a dongle, switch off the tracker that is paired to it first.

axol tracker.install

Installs a tested build of libsurvive (commit f1e6eddb669320f2a30760f4b42936bdb4306da0) with Almond’s fixes, plus the Vive udev rule. axol provision runs it for you. Run it again to repair the install.

axol tracker.install

Almond’s fixes are in almond_axol/tracker/libsurvive_patches/. They fix crashes with three or four base stations and during long sessions, deliver poses without delay, and add the strict tracking policy. Under the standard policy, libsurvive tracks as it normally does.

If the build is already current, tracker.install only refreshes the udev rule and checks the installed files.

After you update Axol, stop collection, install the updated runtime, and restart the service:

axol tracker.install
sudo systemctl restart axol

Install Lighthouse support in the control panel runs the same installer. If you use the strict tracking policy, run Recalibrate Lighthouse and complete its validation before you collect. A libsurvive you build yourself, or separately installed Python bindings, won’t work in its place.

Close SteamVR if it is running, because it competes for the trackers.

Lighthouse tracking policy

lighthouse_quality in ~/.almond/tracker/config.json sets how strictly Axol checks Lighthouse tracking. In the control panel it is Tracking policy, under Mantis settings. It applies to collection, the tracker bridge, Check base stations and Identify trackers on this computer.

	standard (default)	strict
Base station calibration	libsurvive keeps refining it and saves it. A new or moved setup calibrates during Check base stations and Identify trackers.	Changes only during Recalibrate Lighthouse.
Before collecting	Validate tracking is optional.	A passing validation from the last 12 hours is required.
While collecting	The episode QA gate (--qa_gate) judges each take.	Axol watches tracking live. Any tracking fault marks the take for a retake, even with --qa_gate false.

Under standard, a passed check shows as Last check passed 10 min ago. Calibration refined since then., because libsurvive keeps refining the calibration.

Choose strict for a fixed installation whose base stations never move, where you’d rather retake than keep a slightly worse take. Choose standard for portable setups, rooms with two base stations, and bring-up. Change the policy only while no operation is running.

axol tracker.lighthouse.check

axol tracker.lighthouse.check --expected_stations 3

Hold both trackers still and in view of the base stations. The check listens for about 20 seconds. On a new computer, or after you add or re-channel a base station, it can take a minute or more for the trackers to start reporting. The check keeps listening for up to 150 seconds until both do.

It prints each base station channel the trackers received, with the station serial numbers, and the trackers that are reporting. It fails, and says how to fix it, when:

• two base stations share a channel
• it sees fewer base stations than you expect
• fewer than two trackers report

Only base stations heard during the check count. If the station on a channel isn’t the one that was there last time, the check says so. With two base stations, that means both are set to that channel.

The result is saved to ~/.almond/tracker/lighthouse_survey.json. The panel needs a passing check before the Trackers step.

Under the strict policy, the check never calibrates. On a new computer, or after you add or re-channel a base station, run Recalibrate Lighthouse first.

The base station calibration lives in libsurvive’s file ~/.config/libsurvive/config.json, or under $XDG_CONFIG_HOME when that is set. The service, which runs as root, uses /root/.config/libsurvive/config.json.

axol tracker.lighthouse.validate

axol tracker.lighthouse.validate --expected_stations 3

Stop collection and any other tracker command first. Then:

1. Put both identified rigs still on the table, with their trackers in view.
2. Follow the prompts: a 5-second hold, a 12-second slow sweep through the workspace (at least 10 cm and 15° per rig), and a 5-second hold at another position. Move only during the sweep.

The check covers base station reception, how steady each tracker is when still, and smooth tracking through the workspace. It doesn’t certify absolute accuracy, or that tracking will stay reliable later.

Before the measurements start, the trackers can take up to two minutes to pick up every base station. Keep both trackers in view and let the check continue. Restarting it starts that wait over. If it times out, it says what is missing and leaves the calibration unchanged.

Flag	Description
--expected_stations INT	Number of base stations, 1 to 4. Saved for future checks. Default: the saved setting.
--web-prompts	Use the control panel’s prompts. The panel passes this for you.

Under the strict policy, validate before the first session each day. A report expires after 12 hours, or sooner if the setup changes. If validation fails, fix the visibility, base station or identity problem and run it again. If the report asks for recalibration, run Recalibrate Lighthouse, because validation alone can’t clear that fault. This command never changes the calibration.

axol tracker.lighthouse.calibrate

axol tracker.lighthouse.calibrate --expected_stations 3

Run it after a base station or tripod moves, or when tracking seems wrong. It takes the same flags as tracker.lighthouse.validate.

1. Rest both rigs at three different positions and orientations, for eight seconds each, when prompted. Keep the tracker sensors in view.
2. Complete the same hold, sweep and hold as tracker.lighthouse.validate.

The new calibration replaces the old one only if the validation passes. If any step fails, the procedure stops, the previous calibration stays, and the error names the failed step. With both sides already identified, a passing recalibration counts as a validation, so you don’t need to validate again.

If Identify trackers can’t finish because tracking is unstable, you can recalibrate before you identify sides. It must find two trackers. When it succeeds, the panel shows Calibration saved. Identify sides, then validate tracking. Recording stays blocked until Identify sides and Validate tracking pass.

Recalibrating changes the base station calibration, not the tracker-to-gripper transform. It doesn’t change recordings you already made. Run the dynamic acceptance checks before your next collection.

axol tracker.ultimate.install

axol tracker.ultimate.install

Installs the VIVE Ultimate Tracker runtime: pyvut (commit fcfcd33f4c1f16b0d84f5f741dc1319abdc7942a), the hid>=1.0.5 Python package (not the unrelated hidapi), the system HID libraries and a udev rule for dongle 0bb4:0350. It is safe to run again. Don’t replace it with uv pip install or a chmod of /dev/hidraw*. The Windows pairing and mapping steps you do first are on the tracking page.

Ultimate Wi-Fi file

The panel’s Wi-Fi step writes ultimate_wifi.json, the network settings for the trackers’ shared map. To set it up by hand, create ~/.almond/tracker/ultimate_wifi.json (or $ALMOND_HOME/tracker/ultimate_wifi.json) in this shape, then chmod 600 it:

{
  "ssid": "YOUR_FALLBACK_TRACKER_SSID",
  "pass": "YOUR_FALLBACK_TRACKER_PASSWORD",
  "country": "US",
  "freq": 5240
}

All four fields are required. The trackers report the network they actually use, so ssid, pass and freq are only a fallback. Choose a country and freq that are valid where you work. The readiness check reports whether the file is valid, never the values in it.

axol tracker.ultimate.check

axol tracker.ultimate.check

Checks that the computer is ready for Ultimate trackers, the same way the panel does before an operation starts. It checks the installed packages, USB and HID access, bindings, pose settings and the Wi-Fi file. It fails if the Wi-Fi file is missing or insecure, or if your account can’t open the HID device. It doesn’t connect to the dongle or check live tracking. To check live poses, run tracker.identify again.

Transform file

~/.almond/mantis/tcp_transform.json holds measured tracker-to-gripper transforms for each side, keyed by the identified device. Axol has built-in factory values for the standard Tracker 3.0 and Ultimate mounts, and for Quest 3 Touch Plus controllers (quest:meta-quest-touch-plus:grip). It uses a factory value when no conflicting entry is saved. A saved entry overrides the factory value. Other Quest controllers have no factory value and need an entry for both sides.

{
  "left": {
    "survive:LHR-E0FCD01B": {"pos": [0.0, 0.0, 0.0], "quat": [0.0, 0.0, 0.0, 1.0]},
    "ultimate:AA:BB:CC:DD:EE:01": {
      "pos": [0.0, 0.0, 0.0],
      "quat": [0.0, 0.0, 0.0, 1.0],
      "ultimate_pose_convention": {"quat_order": "wxyz", "up_axis": "z"}
    },
    "quest:oculus-touch-v3:grip": {"pos": [0.0, 0.0, 0.0], "quat": [0.0, 0.0, 0.0, 1.0]}
  },
  "right": {
    "survive:LHR-87654321": {"pos": [0.0, 0.0, 0.0], "quat": [0.0, 0.0, 0.0, 1.0]},
    "ultimate:AA:BB:CC:DD:EE:02": {
      "pos": [0.0, 0.0, 0.0],
      "quat": [0.0, 0.0, 0.0, 1.0],
      "ultimate_pose_convention": {"quat_order": "wxyz", "up_axis": "z"}
    },
    "quest:oculus-touch-v3:grip": {"pos": [0.0, 0.0, 0.0], "quat": [0.0, 0.0, 0.0, 1.0]}
  }
}

The values above are placeholders, not a usable calibration. Replace each key with the identifier from ~/.almond/tracker/config.json, or the Quest key the panel shows, and each value with your measurement.

• pos is the gripper TCP origin in the tracker’s frame, in metres.
• quat is the TCP orientation in the tracker’s frame, as [qx, qy, qz, qw]. It is normalized when loaded.

You can also write the file with PUT /api/tracker/calibration/<source>. The control panel doesn’t edit it.

Rules Axol applies when it loads the file:

• Quest collection needs a quest:<reported-profile>:grip entry on both sides, or the built-in Quest 3 Touch Plus value. A bare quest key, a different controller profile, missing profile details or a target-ray entry is refused.
• Ultimate entries need an ultimate_pose_convention that matches the active ultimate_quat_order and ultimate_up_axis. An entry without one, or with a different one, blocks the factory value for that side until you fix or remove it.
• An unkeyed entry, a bare survive or ultimate key, or an entry for a tracker you no longer use also blocks the factory value for that side until you re-key or delete it.
• Production collect-data needs a saved device entry or a factory value on both sides. Use --mantis_allow_uncalibrated true only for a calibration capture that won’t be used for training.

Vive factory values

Both Vive tracker types sit flat on top of the rig, behind the gripper motor. Both use the rotation Ry(180°), stored as the quaternion [0, 1, 0, 0]. The tracker’s +z axis points along the gripper fingers (gripper −z), its +x axis along the gripper’s −x, and the y axes match.

Positions are given in the gripper frame, whose origin is the center of the gripper motor’s mounting face:

Tracker	Tracker origin in the gripper frame	Stored value, both sides
Tracker 3.0	[0, −35, 47] mm: 47 mm behind and 35 mm above the motor face	[0, 0.035, 0.047, 0, 1, 0, 0]
Ultimate	[0, −46, 47] mm: 11 mm higher than the Tracker 3.0	[0, 0.046, 0.047, 0, 1, 0, 0]

Datasets recorded with axol 0.2.4 or older store gripper orientations rotated about 90° from how the rig was held, and Axol can’t replay them. Repair them with axol migrate-dataset --mantis-tcp-rotation. collect-data won’t add episodes to a dataset that hasn’t been repaired.

Datasets recorded with axol 0.2.5 to 0.2.16 place the tracker 92 mm in front of the gripper instead of 47 mm behind it. Their meta/axol.json records vive-flat-back-ry180-v0.2.5 as the mantis_tcp_transform id, and collect-data won’t add episodes to them.

Quest factory value

Quest 3 Touch Plus controllers (quest:meta-quest-touch-plus:grip) sit in standard cradles. Their grip origin is at [0, −45, 62] mm in the gripper frame, 62 mm behind and 45 mm above the motor face. The grip axes are turned 180° about the gripper’s z axis, with a cradle tilt of about 10°. The left cradle mirrors the right, so the tilt mirrors too:

Side	Stored value
Right	[-0.00942, -0.03804, -0.06583, 0.06655, -0.05350, 0.99629, 0.01054]
Left	[0.00942, -0.03804, -0.06583, 0.06655, 0.05350, -0.99629, 0.01054]

Other controllers need a measured entry.

Deriving a missing constant

If you have no transform for your source, such as a Quest controller other than the Touch Plus or an Ultimate with a non-standard pose setting:

1. Pass the acceptance checks for side, scale and recovery.
2. Record a short capture with --mantis_allow_uncalibrated true.
3. Work out the transform from that capture, and save it under the exact source and device key.
4. Repeat the loss and recovery check.

collect-data --mantis stays blocked until both sides have a transform. Never use an uncalibrated capture as training data.