Core Concepts

Install the package with uv sync (see Installation), then import from its submodules, such as almond_axol.robot and almond_axol.teleop. The Axol SDK is organized into focused modules:

almond_axol/
├── robot/        Axol (the robot) and Sim (visualizer) — start here
├── rt/           Axol's realtime hardware control core (axol-rt, 240 Hz)
├── kinematics/   Bimanual IK solver (JAX + pyroki)
├── teleop/       VR headset → IK → robot control loop
├── vr/           WebSocket server that receives VR frames
├── zed/          Local ZED camera enumeration + daemon control
├── motor/        Low-level async CAN motor interface
├── serve/        Web control-panel server (FastAPI) behind `axol serve`
├── policy/       Serve your own model to run-policy (no LeRobot needed)
└── lerobot/      LeRobot Robot / Teleoperator / Camera wrappers (requires lerobot extra)
    ├── robot/    AxolRobot — LeRobot Robot wrapping the async hardware driver
    ├── teleop/   AxolVRTeleop — LeRobot Teleoperator wrapping VRTeleop
    └── camera/   ZedCamera — LeRobot Camera for a locally attached ZED

The browser front-ends are outside the Python package, in web/. The VR teleop interface and the web control panel are both built to web/app/dist and served by axol serve. End-to-end data flow for teleoperation:

VR headset → VRServer (WSS) → VRTeleop → KinematicsSolver → Axol (axol-rt, 240 Hz) → motors

End-to-end data flow for LeRobot data collection:

VR headset → AxolVRTeleop.get_action() → AxolRobot.send_action() → motors
                                                 ↑
                                  AxolRobot.get_observation() → dataset
                                  (joints from telemetry, cameras from ZedCamera)

Async context managers

Axol, Sim, VRTeleop and VRServer open and close hardware resources in __aenter__ and __aexit__. Always use them with async with.

Joint arrays

Every method that reads or writes joint state uses an np.ndarray of shape (8,) in Joint enum order: SHOULDER_1, SHOULDER_2, SHOULDER_3, ELBOW, WRIST_1, WRIST_2, WRIST_3, GRIPPER. Arm joints are in radians. The gripper runs from 0.0 (closed) to 1.0 (fully open).

Telemetry vs. one-shot reads

.positions and .torques are cached properties that don’t block. Read them in a tight control loop without await. While the robot is enabled, the realtime core keeps these caches filled, so you don’t need to start telemetry. On a robot that is connected but not enabled, start_telemetry(hz) starts a background polling loop that fills the same caches. The cache is empty until the first reply arrives, and a MyActuator motor rebooting after a control-mode change can take a moment to answer. Call await wait_for_telemetry() once after start_telemetry(), before the first .positions read. Without the core, direct calls such as await get_positions() send individual CAN reads. They suit diagnostics but are too slow for real-time control.

Get Started

Operations

Mantis

Remote Teleop

Web Interfaces

Advanced

Core Concepts

Async context managers

Joint arrays

Telemetry vs. one-shot reads

​Async context managers

​Joint arrays

​Telemetry vs. one-shot reads

Async context managers

Joint arrays

Telemetry vs. one-shot reads