teleop

Launches a VR teleoperation session. On start it prints the robot’s hostname (.local) and local IP address. Enter either one in the VR app at axol.almond.bot to connect. Teleop runs on the real robot by default. Pass --sim to use the browser visualizer instead. On hardware, the axol-rt realtime core runs the arms at 240 Hz with the default impedance controller. With --axol.controller position it runs at 400 Hz, and each joint uses its motor’s firmware position loop (see controller in the robot config). The table below lists the common flags. Every field of the nested axol, teleop, kinematics, vr_server and cart configs is listed with its default in Teleoperation Config Parameters. See Command configuration for the syntax.

For a step-by-step walkthrough, including the VR controller layout, see the Teleoperation guide.

Before opening the VR app, accept the self-signed HTTPS certificate in the VR browser. Go to https://<hostname>.local:8000 or https://<local-ip>:8000 and proceed past the security warning.

Network tip: If VR tracking feels jittery or packets arrive in bursts, set these on your router or access point:

DTIM interval: 1
Beacon interval: 100 ms
WMM APSD (U-APSD): disabled

With these settings the access point stops holding packets between beacons, which delays VR traffic.

Flag	Description
`--sim`	Run in the browser visualizer instead of on the robot. A bare `--sim` works, as does `--sim true`.
`--mantis`	Drive the two Mantis grippers from the rig triggers. Nothing else starts. See Mantis grippers. Can’t be combined with `--sim`.
`--arms BOOL`	Drive the Axol arms (default: `true`). `false` drives only Jelly. Control panel: Axol arms on the Robot tab.
`--left_channel <ch\|null>`	CAN channel for the left arm; `null` disables it. Default: `CAN_LEFT`.
`--right_channel <ch\|null>`	CAN channel for the right arm; `null` disables it. Default: `CAN_RIGHT`.
`--jelly.wheels BOOL`	Drive Jelly’s wheels when their CAN interface is attached (default: `true`). Control panel: Jelly wheels.
`--jelly.channel <ch\|null>`	CAN interface for Jelly’s wheels; `null` disables them. Default: `can_alm_axol_b`, set by `can.setup`.
`--jelly.lift BOOL`	Run Jelly’s lift when its CAN bus is attached (default: `true`). Control panel: Jelly lift.
`--jelly.lift_channel <ch\|null>`	CAN interface for the lift. Default `null` uses `can_alm_axol_c` if it exists, otherwise the wheel bus `can_alm_axol_b`.
`--jelly.imu BOOL`	Use the carrier board’s IMU to hold Jelly’s heading while driving straight (default: `false`).
`--jelly.<field> VALUE`	Any other Jelly setting, such as `--jelly.max_speed`. The full set is the `JellyConfig` dataclass, also shown under Advanced in the control panel.
`--axol.left_stiffness S`	Left arm stiffness, from `0` (fully hand-guidable) to `1` (default, the tuned production gains). A scalar (`0.8`) or one value per joint (`[1.0,1.0,0.8,0.8,0.5,0.5,0.2]`). See `AxolConfig.left_stiffness`.
`--axol.right_stiffness S`	Same, for the right arm.
`--axol.left.gripper.torque_limit FLOAT`	Max torque (Nm) for the left gripper (default: 0.5). Use `right` for the right gripper.
`--axol.gripper TYPE`	Fitted gripper: `parallel` (default, the stock two-finger gripper) or `parcel` (the hinged-plate parcel gripper). Control panel: Gripper on the Robot tab.
`--axol.<side>.<joint>.<gain> VALUE`	Override a per-joint gain, e.g. `--axol.left.elbow.kp 60`. `<side>` is `left` or `right`, `<joint>` is `shoulder_1` to `wrist_3`, and `<gain>` is `kp`, `kd` and so on.
`--teleop.position_multiplier FLOAT`	Scale hand position by this factor (default: `1.0`). At `2.0` the arm moves twice as far as your hand, which helps cover the arm’s full reach.
`--teleop.rotation_multiplier FLOAT`	Scale hand rotation by this factor (default: `1.0`). At `2.0` the gripper turns twice as far as your wrist.
`--teleop.absolute_mode true`	Track hand poses 1:1 in a fixed robot frame solved at engage, instead of moving relative to the engage pose. For sim demos of the mapping only.
`--teleop.base_height H`	With `absolute_mode`, fix the robot base height above the tracking floor, in metres.
`--teleop.reset_torque_threshold FLOAT`	Contact limit (Nm) for every return to rest (default: 6.0). `0` turns it off. See Contact stops.
`--teleop.reset_gravity_comp_kd FLOAT`	Damping (Nm·s/rad) while the arms hang limp after a contact stop (default: 0.25). Same as `gravity-comp` `--kd`.
`--teleop.teleop_torque_threshold FLOAT`	Contact limit (Nm) while you drive the arms (default: `0`, off). The control panel suggests `16.0`.
`--teleop.hold_to_engage BOOL`	`true` makes each grip a hold-to-move switch for its arm (default: `false`, toggle). See Engaging.
`--teleop.park_to_zero BOOL`	On Stop or `Ctrl+C`, move the arms from rest on to the all-zero pose before releasing the motors (default: `true`). See Stopping parks the arms.
`--teleop.reengage {clutch,ramp}`	What an arm does when you re-engage it (default: `clutch`). See Engaging.
`--teleop.box_mode BOOL`	Start in box mode (default: `false`). Parcel gripper only. See Box mode settings.
`--teleop.ik_alpha FLOAT`, `--teleop.pose_cutoff FLOAT`	Pose and IK smoothing filters, which trade smoothness for latency (defaults: `0.3` / `2.5`). See Latency tuning.
`--teleop.record PREFIX`	Record the teleop pipeline to `PREFIX_{ik,cmd,meas,rt}.npz` for `diag.teleop-jitter` or `motion.build`. Unset records nothing.
`--vr_server.interp_smooth_window_s FLOAT`, `--vr_server.interp_max_delay_s FLOAT`	VR pose smoothing window (default: `0.12`, which adds about 60 ms) and jitter-buffer cap (default: `0.15`). See Latency tuning.
`--vr_server.interp_max_lag_s FLOAT`	Skip pose frames that arrive more than this many seconds late (default: `0.5`; `0` turns it off). After a Wi-Fi stall the arms hold, then follow your current pose.
`--cameras DICT`	Map camera slots (`overhead`, `left_arm`, `right_arm`) to ZED serial numbers to stream them to the headset. Default: `{}` (no video). See Camera streaming.
`--camera_eyes DICT`	Which eyes of a stereo camera to stream, by slot: `both`, `left` or `right`. Default: `{}`.
`--resolution {SVGA,HD1080,HD1200}`	Capture resolution for all cameras. Default `null`: each camera’s SDK default (HD1200 on GMSL).
`--kinematics.<field> VALUE`	Override an IK weight or solver setting, e.g. `--kinematics.pos_weight 100`. See `almond_axol.kinematics` for every field.
`--vr_server.port INT`	Port for the VR WebSocket server (default: 8000). `--vr_server.certfile` and `--vr_server.keyfile` set a TLS cert; the default `null` uses a generated cert.
`--log_level {DEBUG,INFO,WARNING,ERROR}`	Default: `INFO`
`--config_path PATH`	Load a whole-config JSON/YAML file. Flags override it. See Command configuration.
`--settings_path PATH` / `--no_settings`	Read another shared settings file, or ignore it. By default `~/.almond/settings.json` applies, beneath `--config_path` and the flags.

To check the real control loop rate while teleop runs, open the Diagnostics dashboard. Its CAN timing graph shows command and feedback rate, jitter, response latency and missed 240 Hz deadlines.

axol teleop                                       # real robot
axol teleop --sim                                 # browser visualizer
axol teleop --axol.left_stiffness 0.8
axol teleop --axol.left.elbow.kp 60 --axol.right.gripper.torque_limit 0.7
axol teleop --teleop.position_multiplier 2.0      # scale hand motion 2x
axol teleop --teleop.rotation_multiplier 2.0      # scale hand rotation 2x
axol teleop --sim --teleop.absolute_mode true     # generic absolute-mapping demo only
axol teleop --mantis                              # Mantis rigs: triggers → grippers, no tracking
axol teleop --left_channel null                   # disable the left arm
axol teleop --arms false                           # drive only Jelly (no arms, no hub)
axol teleop --jelly.wheels false                   # leave attached wheels cold (lift still runs)
axol teleop --cameras "{overhead: 41234567, left_arm: 41234568, right_arm: 41234569}"
axol teleop --cameras "{overhead: 41234567}"      # stereo overhead auto-detected, per-lens
axol teleop --config_path my_teleop.json          # whole-config file
axol teleop --no_settings                          # ignore ~/.almond/settings.json (panel settings)

Engaging

With the default toggle scheme (--teleop.hold_to_engage false):

From rest, squeeze both grips to engage.
After that, each grip toggles its arm between tracking and frozen.

With --teleop.hold_to_engage true:

Each arm moves only while you hold its grip. Either grip alone engages its arm, including from rest.
Releasing a grip freezes that arm, pose and grasp, where it is.
After a forced disengage (a reset, a dropped link or a contact stop), release a held grip once before it engages again.

--teleop.reengage sets what happens when an arm re-engages after a freeze, a walk-away or being moved by hand:

clutch (default): the arm stays put, and your controller’s current pose becomes its new origin. You match the arm.
ramp: the arm eases out to where your controller is, using the mapping from its last engage. The arm matches you. --teleop.reengage_ramp_speed sets the pace (default 0.15 m/s), and --teleop.reengage_ramp_min_s sets the shortest ramp (default 0.75 s).

You can also switch it live with the headset’s Ramp button or the control panel’s Session settings card. A reset clears the saved mapping. Engaging in box mode ignores this setting. Leaving box mode in ramp blends both arms back to the mapping from before box mode. --teleop.absolute_mode true doesn’t select a Mantis source or its mount transform, so it is not a test of physical alignment. To check alignment, run collect-data --mantis.

Contact stops

Two torque watchdogs stop the arms when they hit something. Each compares every joint’s measured torque with the gravity model. When the difference stays above the limit, the move stops and the arms go limp in a gravity-compensation hold. Both work on hardware only.

Return to rest (--teleop.reset_torque_threshold, on by default): guards the startup move and every X reset. Free the arms by hand, then press X to plan the return from where they are.
Tracking (--teleop.teleop_torque_threshold, off by default): guards the arms while you drive them. A stop disengages tracking. Press X to return to rest, then engage again. The same setting applies to collect-data.

Raise a limit if normal moves trip it. Set it to 0 to turn the watchdog off.

Mantis grippers

axol teleop --mantis drives only the two handheld grippers, from the rig triggers. It doesn’t start tracking, the VR server, the tracker bridge, cameras or transforms. To record tracked Mantis data, use collect-data --mantis.

The grippers use the Mantis CAN channels saved in Mantis settings (default can_mantis_l and can_mantis_r).
Both triggers must be reading and released before the grippers turn on. Each gripper then opens fully to find its end stop.
If the trigger stream goes stale, the run stops.

Box mode settings

Box mode needs the parcel gripper (--axol.gripper parcel). With the parallel gripper, box mode and its settings don’t exist, and --teleop.box_mode is ignored with a warning. In box mode the grippers clamp a box between their flat faces, like two hands. One grip drives both arms as a pair, by position and by heading about the vertical. The other grip takes over the lead. While a grip leads, the thumbsticks set the grip width. Freeze the pair and the thumbsticks drive Jelly again (see Driving with the box). To switch box mode on or off during a session, press the headset’s Box button, click both thumbsticks together, or use the control panel’s Session settings card. The switch engages right away.

Flag	Description
`--teleop.box_lead_hand`	Hand that leads when box mode turns on: `right` (default) or `left`.
`--teleop.box_grasp`	`straight` (default, fingers point straight forward) or `flush` (each gripper turned inward onto the plate’s chamfer). Click either stick while leading to switch.
`--teleop.box_flush_deg`	How far the flush grasp turns each gripper inward (default: `39`°).
`--teleop.box_face_left` / `box_face_right`	Which side of each gripper faces the box: `auto` (default), `+x` or `-x`.
`--teleop.box_grip_tilt`	Fixed inward yaw trim in degrees (default: `0`). A calibration value, not a live control.
`--teleop.box_width_speed`	How fast the thumbsticks change the width (default: `0.08` m/s).
`--teleop.box_width_min` / `box_width_max`	Width limits between the two contact faces (defaults: `0.02` / `0.70` m). The gripper bodies raise the minimum. The straight grasp stops at about 77 mm.
`--teleop.box_align_duration`	Time to blend into the pair when box mode engages (default: `1.5` s).
`--teleop.box_elbow_out`	How far out the elbows are held, in degrees from straight down (default: `30`). Push either thumbstick forward or back to adjust it live.
`--teleop.box_elbow_speed`	How fast the thumbsticks move the elbows (default: `30`°/s).
`--teleop.box_elbow_weight`	Strength of the elbow hint (default: `10`). `0` turns it off, and the thumbsticks don’t move the elbows.
`--teleop.box_squeeze_lean`	Lean each gripper into the box as you squeeze, so the face presses evenly from root to tip (default: `1`; `0` is off). Live control: Squeeze lean.
`--teleop.box_squeeze_trim`	Largest extra inward turn, in degrees, added while squeezing to square each face to the box (default: `5`; `0` is off). Live control: Squeeze trim.
`--teleop.box_squeeze_force`	Clamp force cap per arm, in N (default: `0`, off). Live control: Squeeze force.
`--teleop.box_wrist_torque`	Torque cap (Nm) on `wrist_2` and `wrist_3` in box mode (default: `5`; `0` is off). It also sets the automatic clamp force limit, about 39 N a side.
`--teleop.box_squeeze_torque`	Torque cap (Nm) on the squeezing shoulder joints, `shoulder_2` and `shoulder_3` (default: `0`, off). It also slows the arms moving toward each other. Live control: Squeeze cap.

The wrist and shoulder torque caps work on hardware only.

Camera streaming to the headset

With --cameras set, teleop opens the ZED cameras attached to the robot by serial number and streams them to the headset over WebRTC. All feeds show at once, and you can move and resize each one with the controllers. See the VR Interface guide for the layout.

Streaming needs pyzed (zed.install) and the GStreamer hardware encoder stack (gst.install). The hosted installer sets up both.
The headset stream runs at 30 fps. Cameras can capture faster for recording or policies.
Stereo ZED X cameras are detected from their serial number. A stereo overhead camera streams both eyes and shows each eye to its own lens. A stereo wrist camera streams one eye, like a mono camera. Use --camera_eyes to change this.
Without the GStreamer stack, teleop falls back to the ZED SDK.
If no hardware encoder is present, the video is encoded in software. Use --resolution SVGA in that case.

The video runs in a separate process, so it doesn’t slow the control loop. axol provision pins the Jetson’s encoder clocks to their maximum for low latency.

Jelly

When Axol is on Jelly (an omni-wheel base with a telescoping lift), you can drive it from the headset thumbsticks. The left stick moves, the right stick turns, and the stick clicks run the lift. For the full controls see the VR interface guide. Teleop finds Jelly from the attached CAN devices:

It drives the wheels when their interface (can_alm_axol_b) exists.
It runs the lift when its bus exists (can_alm_axol_c, or the shared wheel bus). If the lift bus is down at start, the lift is disabled with a warning and the wheels still drive.
can.setup and the control panel’s CAN discovery set these names. Teleop brings Jelly’s CAN up on start, so you don’t need can.enable.

To leave attached hardware off, pass --jelly.wheels false or --jelly.lift false (the control panel’s Jelly wheels and Jelly lift switches). Jelly motion is never recorded into a dataset, and a policy never drives it. --arms false drives only Jelly. Teleop doesn’t start the arms or open the Axol hub’s CAN bus, so the arms don’t need to be connected. Teleop does the same, with a warning, when the arms’ CAN interfaces are missing and Jelly’s are present.

This command takes its config through draccus. Field names use underscores, nested fields are separated by dots, None is null, and lists use [a,b,c]. See Command configuration.

Get Started

Operations

Mantis

Remote Teleop

Web Interfaces

Advanced

Engaging

Contact stops

Mantis grippers

Box mode settings

Camera streaming to the headset

Jelly

​Engaging

​Contact stops

​Mantis grippers

​Box mode settings

​Camera streaming to the headset

​Jelly

Engaging

Contact stops

Mantis grippers

Box mode settings

Camera streaming to the headset

Jelly