MOSS: a small, mostly 3D-printed litter-picking rover. Cleaner streets, one maker at a time.
Running MOSS: flight check, mapping, exploration, recording, cockpit
MOSS is a small tracked rover (two geared DC motors behind a QT Py ESP32-S3
motor board, an RPLidar C1, a RealSense D455F on the nose, a UVC camera on the
arm). This is the operator's manual for running it on dimOS with this
repository's moss_dimos package: lidar odometry, a 2D costmap, a planner and
a frontier explorer under the tracked base, with a flight check and a web
cockpit in front of them.
Everything below runs ON THE ROBOT, on the computer where the board, the lidar and the cameras are plugged in. The cockpit is a web page served by the robot; open it from any machine on the same network.
The four pieces
| Piece | File | Runs where |
|---|---|---|
| Flight check | tools/moss_preflight.py |
robot, read-only, ten seconds |
| Blueprints | moss_dimos/blueprints.py → moss-dimos.moss-nav, moss-dimos.moss-explore |
robot, inside dimos run |
| Launcher | tools/moss-fly.sh |
robot, gates then stack |
| Cockpit | tools/moss_cockpit.py + tools/moss_cockpit/ |
robot, port 8904 |
The pad-only launcher, tools/moss-teleop.sh (base.md), is the
smallest thing that moves the robot.
Run it
$ tools/moss-fly.sh check # flight check only, nothing launched
$ tools/moss-fly.sh map # gates -> moss-nav: lidar map + pad teleop, recording
$ tools/moss-fly.sh explore # gates -> moss-explore: map + navigation + explorer, NOT armed
$ EXPLORE=1 tools/moss-fly.sh explore # ... and arm exploration once the stack is proven
$ tools/moss-fly.sh stop # stop exploration, then the stack
$ tools/moss-fly.sh log # what the base, the lidar, the odometry and the map said
$ tools/moss-fly.sh cockpit # start the cockpit server if it is not up, print the URL
$ MOCK=1 tools/moss-fly.sh map # fake motor board, no motor; the lidar must still be plugged (mapping needs it)
Every gate refuses rather than guesses, with the fix on the same line: a stack already up, a missing board, a port held by another program, a mute firmware, a battery at the BMS floor, a lidar that does not spin, a stack that does not prove itself in the log within two minutes.
The map opens when the rover has moved 5 cm from its boot pose (the costmap's
mission gate) or when an explore_cmd arrives, and it stays open until the
stack stops: the cockpit's STOP, a goal reached or the end of exploration leave
map writing on. A new launch starts a fresh map.
Nothing moves by itself. moss-nav has no planner: the pad drives, the map
builds. moss-explore adds the planner, the movement manager and the frontier
explorer, but the explorer only starts on an explicit explore_cmd (the
launcher with EXPLORE=1, the cockpit's button, or
.venv/bin/python tools/explore_ctl.py start from the checkout root), and the
planner only on a goal (a tap on the cockpit map, or goal_request on the
bus). Any pad input cancels navigation (dimOS MovementManager), and two deadmen
stay underneath: the adapter stops the tracks 0.5 s after the last twist, the
firmware 300 ms after the last drive.
What the blueprints contain
moss-dimos.moss-nav (mapping):
the control coordinator (
MossControlCoordinator) with the MOSS base adapter (moss_dimos/moss_adapter.py, see base.md), publishing the firmware telemetry on/base_telemetry(JSON: firmware, mode, battery mV, ticks, applied PWM) so nothing else ever has to open the serial port;the gamepad module (
moss_dimos/gamepad.py) with the MOSS envelope, wired straight tocmd_vel;the RPLidar C1 reader (
moss_dimos/rplidar_c1.py) on its own USB serial adapter;lidar odometry (kiss-icp,
moss_dimos/lidar_odometry.py), the pose source: the encoders give metres only onceMOSS_TICKS_PER_Mis set, and the RealSense's gyro gives the odometry its rotation prior (below);the 2D scored costmap (
moss_dimos/costmap2d.py), where the lidar writes obstacles and the depth camera adds the ones below the scan plane, each sensor on its own layer. An obstacle becomes a wall once seen from two places 10 cm apart, never from one spot. The lidar's rays clear the lidar layer within 4 m of the rover; they pass over a shoe and never clear what the camera saw. Only the camera clears its layer: by seeing the floor on a cell, or by seeing through it low (its rays from the nose, between 1.3 and 6 cm above the floor). A cell the camera hit in the last 3 s keeps its score whatever the floor beside it says, so a leg thinner than a cell stays a wall, and a camera hit counts only when the previous depth frame also saw something within one cell, so a walker or a vacuum, which moves more than a cell between frames, is rarely written: a foot planted for two frames can mark a cell, and the camera clears it once it is gone. A table top the rover has turned away from keeps its wall until the camera looks at that spot again and sees floor there. A contact writes nothing into the map: the planner backs off, and the map stays the lidar's and the camera's (MOSS_CONTACT_WALL=1marks a short band ahead of the body for a contact felt while driving straight forward). The knobs areMOSS_OCCUPIED_AT,MOSS_NEW_VIEWPOINT_M,MOSS_HIT_CAP,MOSS_FREE_FLOOR,MOSS_RAY_MAX_M,MOSS_PUBLISH_EVERYandMOSS_CONTACT_WALL(below);the lidar odometry's rotation prior from the RealSense's gyro, on with
MOSS_IMU(the default): the IMU read in the camera's own process gives the yaw rate at 200 Hz, and each registration starts from the yaw integrated since the previous revolution. A full-power pivot turns the rover 25 degrees between two scans, more than the constant-velocity prior follows, and the map would drift.MOSS_GYRO=0turns it off; withMOSS_IMU=0,MOSS_GYRO=1is refused with a warning (it would open dimOS's second IMU pipeline, which fails on the rover and takes the camera down), andMOSS_GYRO_FORCE=1builds it anyway, as an experiment (imu.md);the sound module (
moss_dimos/sounds.py): a pack of short synthesized cues inassets/soundsplayed through the robot user's PulseAudio session (its default sink: the on-board amplifier, Software.md, or a Bluetooth speaker once connected) on confirmed events only: the stack up, a contact, the tracks moving again after a stall, the order to explore, the end of an exploration, the battery crossing low and critical (with hysteresis). Each cue has a cooldown and the player keeps a gap between cues, so the rover never chatters.MOSS_SOUNDS=0leaves it out,MOSS_SOUND_VOLUME(0 to 1) andMOSS_SOUND_SINK(a PulseAudio sink name) tune it; a stack launched as a system service has no audio session and stays silent. A Bluetooth speaker sleeps its link after a few tens of seconds of silence, and a short cue sent into a sleeping link is lost (a silent clip every 240 s did not keep it awake). The module does two things against it: it plays a silent clip everyMOSS_SOUND_KEEP_AWAKE_Sseconds (15; 0 = off), and it plays 0.3 s of silence in front of every cue (MOSS_SOUND_PREROLL_S, up to 2 s; 0 = off), meant to wake the link on the silence rather than on the cue. The cues with their silence are WAV copies written once intoMOSS_SOUND_CACHE(default<tempdir>/moss_sound_cache); a cue whose copy cannot be written plays as it is. The module's first log line gives the period and the pre-roll. One check on the robot:pactl list short modules | grep suspend. When it showsmodule-suspend-on-idle, PulseAudio suspends the sink 5 s after each clip (its default timeout), whatever the keep-awake period. After a reboot the speaker comes back through a systemd user unit,tools/moss-jbl.service, which runstools/moss-jbl-connect.sh:bluetoothctl connect, up toMOSS_JBL_TRIEStries (120) with 5 s between tries, then the speaker's PulseAudio sink becomes the default sink, at the volume PulseAudio remembers for it; a try that connects but finds no sink connects again on the next one. It gives up after about ten minutes of waits (about twenty with the speaker off, each connect waiting out its page timeout). The speaker is paired and trusted once withbluetoothctl; its address lives only in~/.local/state/moss/jbl.env. Install from the checkout as the robot's user, whose user manager starts at boot (sudo loginctl enable-linger $USER, once):mkdir -p ~/.config/systemd/user ~/.local/state/moss echo 'MOSS_JBL_MAC=<speaker address>' > ~/.local/state/moss/jbl.env sed -e "s|MOSS_DIR|$PWD|g" tools/moss-jbl.service > ~/.config/systemd/user/moss-jbl.service systemctl --user daemon-reload && systemctl --user enable moss-jbl && systemctl --user restart --no-block moss-jbl--no-blockreturns at once, the script runs on in the background;journalctl --user -u moss-jblsays when it connected, or why it gave up;the RealSense colour stream at 640x480, 5 fps, carried as JPEG on the bus, and its depth aligned to colour at the same rate, which
lidar_odometryturns into obstacle points from 12 cm (the camera's close-range depth) to 3 m, drawn in amber on the map (MOSS_CAMERA=0leaves it out;MOSS_RS_SERIAL=<serial>picks one camera when several are plugged in, and the flight check looks for the same one);the wrist camera (the UVC camera on the arm, found by its
/dev/v4l/by-idname,MOSS_WRIST_DEVto point at another/dev/videoN), 640x480, 5 fps, JPEG on the bus aswrist_image(MOSS_WRIST=0leaves it out; an absent camera is a warning and the module is skipped);the recorder (below),
MOSS_RECORD=0leaves it out.
moss-dimos.moss-explore adds the recovering A* planner
(moss_dimos/recovering_planner.py) with the MOSS footprint, the movement
manager (pad input wins over navigation for one second) and Explorer2
(moss_dimos/explorer2.py) with the MOSS clearances. The pad is still there,
through the manager.
Three variables decide how far the explorer sends the rover. They are read when
moss-explore is built; unset keeps the default, and a value that is not a
number of 0 or more (0 to 6 for the exponent) is refused with a warning (the default stays):
| Env | Default | What it does |
|---|---|---|
MOSS_EXPLORE_DISTANCE_EXP |
2 | how hard distance counts: a frontier scores its information over (1 + its path cost in metres) to this power; a metre of unmapped floor counts as 4, a metre hugging a wall up to 2. At 1 a frontier twice as far needs only twice the information to win, so a big frontier across the room beats a small one beside the rover; at 2 it needs four times as much |
MOSS_GOAL_MAX_M |
3 m | the longest path cost a goal is sent along (0 = no limit), in the same metres as above; a frontier beyond it only waits while a safe one lies within it. A farther frontier waits until the rover is nearer; when nothing nearer is left it goes out anyway, so the cap never ends a run |
MOSS_EXPLORE_RADIUS_M |
0 in the code; tools/moss-fly.sh exports 4 (one room) unless set |
the run stays within this distance of where exploration started: a frontier whose goal lies farther is never a candidate, and once nothing is left inside, exploration is complete. Set 4 to keep the rover in one room. A doorway is a frontier like any other: a door the rover must not take has to lie outside the radius Each start of exploration (the start button, after STOP or after a tapped goal) re-centres the radius on where the rover stands then. |
The explorer logs the three values in one line when exploration starts
(exploration start: distance exp 2, cap 3 m, radius 0 m); each goal line
gives its path cost.
moss-dimos.moss-gamepad and moss-dimos.moss-base are the base alone, with
or without the pad: base.md.
None of them starts Rerun or dimOS's own web modules: the cockpit is the
display. MOSS_RERUN=1 adds the Rerun bridge for the desktop viewer.
The switches MOSS_CAMERA, MOSS_WRIST, MOSS_RECORD and MOSS_RERUN read
0, false, no and off (any case) as off, anything else as on, and unset
or empty as their default. The flight check reads MOSS_CAMERA the same way.
A premap in the costmap
MOSS_PREMAP=1 lets the costmap start from a map saved on an earlier run. It
takes two inputs, both published by dimOS's relocalization module: loaded_map,
the saved map's points in its own map frame, and the fix, a world -> map
transform on tf that places this run inside that map (sent again every 10 s).
Nothing changes until both have arrived: the costmap runs as it does without a
premap, and nothing waits for one. Then the premap's points between 5 cm and
1.30 m above the floor are placed by the fix's x, y and yaw and written once
into the lidar layer as walls, at the lowest wall score (MOSS_OCCUPIED_AT); a
cell the lidar has already seen free stays free, and the camera layer is never
touched. Nothing is published before the mission, premap or not: the walls go
out with the first grid of the mission, because a grid of walls with no free
floor reads to the explorer as a rover walled in at its start. From there a
premap wall is a lidar wall like any other: one lidar ray through its cell
clears it, since the room may have changed since the map was saved (a table top
or a shoe in the premap is cleared by a ray passing under or over it, and the
camera marks it again when it sees it), and a cleared premap wall is never
written back until the lidar hits that cell again from a new place. Rays clear
up to MOSS_RAY_MAX_M from where the rover stood: farther than that, a premap
wall stays. The floor between the walls stays unknown, so the explorer still
has to look at the room, but a frontier never forms against a premap wall, so a
wall that is no longer there (a door closed when the map was made) holds back
the frontier beside it until the rover comes within MOSS_RAY_MAX_M of it. A
fix more than 2 cm or 1 degree away from the one the premap was written with
clears the premap's cells and writes them again; the same fix sent again does
nothing. Clear map takes the premap out with the rest, until a fix moves or a
different premap arrives. The log says costmap: premap received: M points, K in the band for each new premap, costmap: premap fix received on tf: (x, y, yaw) once when the fix comes first, then costmap: premap written: N walls from M points, tf (x, y, yaw), costmap: premap re-written: tf moved by (d cm, d deg) and costmap: premap cleared; a run on MOSS_PREMAP=1 without the first
two lines received neither input. With MOSS_PREMAP=0, the default, every
loaded_map is ignored and the log says costmap: premap ignored (MOSS_PREMAP=0) once. MOSS_PREMAP reads its value like the four switches
above, when moss-nav or moss-explore is built. The costmap never saves a
premap of its own. The relocalization that produces the two inputs is a separate
module from dimOS main, a version step the robot has not taken. Run apart from
this stack, it is heard only on LCM, on /loaded_map and /tf: run the
relocalization with DIMOS_TRANSPORT=lcm (dimOS main's default transport is
zenoh, which this stack does not hear) and with republish_loaded_map above 0,
for example 10 s, because by default it sends the premap once per accepted fix
(once per run when it stops at its first fix) and LCM does not resend a lost
message. On dimOS main, MOSS_RELOC_MAP runs it inside moss-explore instead
(Running on dimOS main).
Running on dimOS main
pyproject.toml pins the dimOS commit this package runs against, and the same
code also builds and runs its cold benches on dimOS main, where four things
moved. The replanning A* planner now lives under dimos.navigation.go2 and the
frontier explorer under dimos.navigation.experimental: recovering_planner.py
and explorer2.py import from the new place, else from the pinned one. The
RealSense is a native module, a Rust binary that opens the IMU itself before
its video stream (what MossRealSense does on the pinned dimOS) and takes no
base_transform: the blueprints then add MossCameraMount, a static
base_link -> camera_link transform from the robot profile. MOSS_RERUN=1
asks for dimOS's websocket command center by name, because main no longer adds
it by default. And main's default transport is zenoh, not LCM: the launchers
export DIMOS_TRANSPORT=lcm, so nothing changes under them, but a dimos run
typed by hand needs it exported first, or tools/explore_ctl.py and the
cockpit, which speak LCM, reach nobody (bench_explore_ctl_cold expects LCM
when neither DIMOS_TRANSPORT nor TRANSPORT is set, and fails on main for
that one case). The camera's binary is not on PyPI. dimOS looks for it in its
own source tree: a pip install has none, so at its first start dimOS clones its
main branch from GitHub and builds there through nix. On the robot, install
dimOS from a git checkout instead, editable, and build the binary there once:
cargo build --release in dimos/hardware/sensors/camera/realsense/rust,
against the robot's own librealsense2, found through pkg-config (the crate is
realsense-sys 2.56, and one dependency comes from git, so the build needs the
network). Without the binary, MOSS_CAMERA=0 runs the stack, with no depth
obstacles and no IMU contacts. Main also brings dimOS's lidar relocalizer:
MOSS_RELOC_MAP=<premap.pc2.lcm> adds LidarWindowRelocalization to
moss-explore as a spectator. It reads lidar and publishes the world ->
map fix on tf and the premap on loaded_map; only the costmap reads them,
and only with MOSS_PREMAP=1, and nothing goes back to the odometry. Inside
the stack it is on the stack's own transport, but by default it sends the
premap once per run: with MOSS_PREMAP=1, add --republish-loaded-map 10
to the dimos run line. --map-file X replaces the premap's path. Unset, the
blueprint is the one without it; on the pinned dimOS, moss-explore does not
build with it set. benches/bench_moss_reloc_cold.py checks that wiring, and
runs the module on a recording when MOSS_RELOC_BENCH_DATA names a directory
holding a premap and the run it was built from.
The robot profile
moss_dimos/robot_profile.py carries MOSS's geometry: lidar height and masks,
body box, footprint, planner widths, camera mount. Every module reads it when
it needs a value, so an environment variable set before the launch applies
everywhere. The values are PLACEHOLDERS until measured on the robot:
| Value | Placeholder | Env |
|---|---|---|
| lidar scan plane above the floor | 0.20 m | MOSS_LIDAR_HEIGHT_M |
| lidar yaw offset (its 0 deg mark vs the nose) | 0 deg | MOSS_LIDAR_YAW_DEG |
| lidar returns ignored closer than | 0.15 m | MOSS_SCAN_MIN_RANGE_M |
| masked lidar sectors, and the range they apply within | none, 0.30 m | MOSS_SCAN_MASK_DEG="a b, c d", MOSS_SCAN_MASK_RANGE_M |
| returns that are the robot itself (half extents) | 0.22 x 0.18 m | MOSS_BODY_BOX_M="0.22 0.18" |
| area cleared under the body (half extents) | 0.20 x 0.16 m | MOSS_BODY_CLEAR_M="0.20 0.16" |
| robot width for the planner | 0.34 m | MOSS_ROBOT_WIDTH_M |
| pivot diameter | 0.50 m | MOSS_PIVOT_DIAMETER_M |
| control margin | 0.05 m | MOSS_CONTROL_MARGIN_M |
| track centre distance | 0.266 m (CAD) | MOSS_TRACK_M |
| nose camera position on the base | 0.156, 0, 0.075 m (CAD) | MOSS_CAMERA_XYZ_M="0.156 0 0.075" |
| nose camera pitch | 0 deg | MOSS_CAMERA_PITCH_DEG |
| full-duty pulse period of the base adapter (ms, 0 = off) | 0 | MOSS_PULSE_MS |
| static-friction floor of the base adapter when pulsing is off (percent) | 50 | MOSS_MIN_PCT |
| percent every pivot is sent at, both tracks (0 = as asked) | 100 | MOSS_PIVOT_PCT |
| bus voltage the floor was measured at, for the battery compensation (mV, 0 = off) | 12400 | MOSS_BUS_REF_MV |
| a pivot with one frozen track turns on the other track instead of counting as a contact | on | MOSS_ONE_TRACK_PIVOT |
The speed knobs are MOSS_MAX_PCT (the PWM cap of the base adapter, 100 by
default) and MOSS_NERF_SPEED (the launcher's --nerf-speed for the planner,
0.7 by default).
The base runs on continuous power: the tracks turn from 40 % on a full pack,
so MOSS_MIN_PCT (50 by default, 10 of margin for the sag under load) raises
every non-zero command to the floor, an arc scaled up whole so its curvature
survives, and every pivot goes out at MOSS_PIVOT_PCT (100) on both tracks.
A percent is a duty of the bus voltage, so a pack at 10.5 V under load puts
15 % less on the motors than the 12.4 V the floor was measured at: the adapter
scales every command by MOSS_BUS_REF_MV / bus (never below 1, at most 1.5,
capped at 100). A pivot whose one track freezes while the other turns is that
track not turning in that direction under the pivot's load, not a contact:
the adapter brakes it and turns on the other track for the rest of the run
(MOSS_ONE_TRACK_PIVOT, said once in the log). tools/moss_floor_probe.py --go measures the floor (raw percents: it turns the compensation and the
rewrite off), tools/moss-pulse-test.sh and MOSS_PULSE_MS keep the
full-duty pulse mode for a base whose tracks only turn at full power
(base.md).
The lidar's floor projection is base_link, the rover's rotation centre: mount
the C1 there, or the footprint and the pivot clearance are off by its offset.
Other variables:
| Env | What it does |
|---|---|
MOSS_PORT, MOSS_LIDAR_PORT |
the motor board's and the lidar's serial ports; by default the QT Py's and the CP2102N's /dev/serial/by-id paths. Only a dimos run by hand reads them from the shell: tools/moss-fly.sh and tools/moss-teleop.sh always take the by-id paths |
MOSS_RS_SERIAL |
the RealSense to use, by serial number |
MOSS_REQUIRE_PAD=1 |
a missing pad fails the flight check instead of warning |
MOSS_COCKPIT_PORT |
the cockpit's port, 8904 by default (also --port; tools/moss-cockpit.service sets it) |
MOSS_IDLE_STOP_S |
how long a moss-nav or moss-explore stack may see no activity before the cockpit stops it, 300 s by default, 0 = never, at least 30 (a shorter value is refused: 300 s); read when the cockpit starts, from its own environment (the service's), see "The stack stops itself" |
PROOF_S |
how long tools/moss-fly.sh waits for the stack to prove itself in its log, 120 s by default |
MOSS_MOCK_BUS=1 |
the fake firmware, no motors (MOCK=1 on the launchers sets it) |
MOSS_STATE_DIR |
the state directory, ~/.local/state/moss by default: recordings, the saved flight check |
MOSS_BRAKE_S |
how long the pad sends zeros after the sticks return to centre (or the optional deadman is released), 0.5 s by default, 0 to 1.0 s |
MOSS_TURN_GAIN |
turn authority against forward speed on the pad, 2 by default, 0.5 to 4 (base.md) |
MOSS_OCCUPIED_AT |
how many hits a costmap cell needs to be a wall, 2 by default, 1 to 10: two places at least MOSS_NEW_VIEWPOINT_M apart, never one spot, so somebody standing next to a parked rover never walls it in. 1 makes the first sighting a wall: a faster block, and every passer-by a wall |
MOSS_NEW_VIEWPOINT_M |
how far the rover must move before the same cell takes another hit, 0.10 m by default, 0 to 1 |
MOSS_HIT_CAP |
how certain a costmap cell can get, 10 by default, 2 to 127. A lidar cell at the cap needs 2 x (cap - 1) revolutions with rays through it to be forgotten (1.8 s at 10, 0.6 s at 4), a camera cell at most cap - 1 looks of the camera through it once its 3 s are over (one look can take more than one point off): lower it to forget passers-by faster, at the price of walls that fade sooner once nothing sees them |
MOSS_FREE_FLOOR |
how free a costmap cell can get, -3 by default, -128 to 0. Nearer 0, something that appears on floor seen free for long becomes a wall after fewer viewpoints (for the lidar: 3 at -1, 5 at -3) |
MOSS_RAY_MAX_M |
how far from the rover the lidar's rays clear the costmap's lidar layer (and the camera's rays its own), 4 m by default (0 = never). Anything farther than that from every place the rover stood is never forgotten: 6 forgets somebody who stood 4.5 m away, and longer rays cost more CPU per revolution |
MOSS_PUBLISH_EVERY |
one costmap grid every N lidar revolutions, 2 by default (5 grids a second), 1 to 20. Every subscriber decodes every grid and the recorder writes each one: raise it if the load climbs |
MOSS_CONTACT_WALL |
1 turns a contact into a wall on the costmap: the band 2 to 20 cm beyond the body's front, across its width, when the rover was driving straight forward (3 cm or more along its heading and less than 10 degrees of turn over the last 0.5 s). Off by default: a contact is a reflex, only the lidar and the camera write the map |
MOSS_PREMAP |
1 lets the costmap take a premap: the points dimOS's relocalization publishes on loaded_map, placed by its world -> map fix on tf, become lidar walls at the lowest wall score, published with the first grid of the mission, cleared by a lidar ray within MOSS_RAY_MAX_M like any wall, written again when the fix moves more than 2 cm or 1 degree. Run apart, the relocalization must publish on LCM (DIMOS_TRANSPORT=lcm); MOSS_RELOC_MAP runs it inside moss-explore. Off by default: every loaded_map is ignored, said once in the log. Read when moss-nav or moss-explore is built (A premap in the costmap) |
MOSS_RELOC_MAP |
dimOS main only: a premap file (.pc2.lcm, absolute path) adds dimOS's lidar relocalizer, LidarWindowRelocalization, to moss-explore. It reads lidar and publishes the world -> map fix on tf and the premap on loaded_map, which the costmap uses only with MOSS_PREMAP=1; with it, add --republish-loaded-map 10 to the dimos run line (the premap goes out once per run by default). --map-file X replaces the path. Unset by default: no relocalizer. Read when moss-explore is built (Running on dimOS main) |
Recording
MossRecorder (moss_dimos/memory.py: a dimOS Recorder with a WAL-safe
rotation) writes the whole run into one SQLite database,
~/.local/state/moss/recordings/moss.db (MOSS_STATE_DIR moves the state
directory; a symlink to a larger disk works). Streams: odom,
global_costmap, lidar (world-frame cloud), cmd_vel, base_telemetry,
color_image (JPEG), wrist_image (JPEG) and episode_marker. The previous
run is rotated aside with its -wal and -shm files (moss.<stamp>.db, the
last ten kept).
The cockpit's "Record episode" button does not start or stop the recorder: it
writes a marker ({"action": "start"|"stop", "name": ..., "ts": ...}) on the
episode_marker stream. dimOS's dataprep cuts episodes on its own status
stream or on hand-entered ranges, not on these markers; cutting on them takes a
small script of your own. Reading a recording without the robot:
$ .venv/bin/dimos mem summary ~/.local/state/moss/recordings/moss.db
$ .venv/bin/dimos dataprep build --source <db> --format lerobot --output <dir> --config <json>
--config is required: a JSON DataPrepConfig naming the observation and action
streams (for MOSS: color_image, odom, cmd_vel) and the episode extractor.
Reading a run
After every exploration run, draw the run before talking about it: counters
("12 stuck, 9 contacts") hide what the robot did, one picture shows it.
.venv/bin/python tools/run_film.py reads the newest exploration run's
main.jsonl and the newest recording in <MOSS_STATE_DIR>/recordings/
(--log and --db pick others) and writes the film of the run next to the
recording, <run>.film.png: the trajectory coloured by time (light to dark)
over the obstacles of the map the run built, with every goal, reached goal,
abandon, contact escape, contact, IMU contact, encoder stall and cornered
back-off where it happened. It prints the verdict: minutes and metres driven,
goals chosen, reached and abandoned, the back-offs (after a contact, or
cornered: the planner's bump and reverse escape that answer a cornered line
belong to that back-off and count as neither a contact nor an abandon), the
contacts the IMU felt and the ones the stall guard inferred, the abandon
triggers, and the stuck or contact events per minute; above one per minute,
look at the map before any conclusion. Then tools/decision_replay.py (same
defaults; --decision N for goal N, --decision final for the last call)
rebuilds each explorer decision from the recording and runs it through the real
explorer2.next_target, printing every frontier cluster with its gain, its path
cost, its multipliers and why the others lost, next to what the run logged. The
film needs dimOS and matplotlib: when the venv lacks matplotlib, the script
says so and draws nothing (.venv/bin/pip install matplotlib). The replay
decodes the map itself.
The cockpit
tools/moss_cockpit.py is a stdlib HTTP server on port 8904 (MOSS_COCKPIT_PORT
or --port) that taps the
dimOS bus (explicit LCM channels, decoded on request, never a serial port) and
serves one page, tools/moss_cockpit/index.html, in the MOSS brand (Space
Grotesk, studio blue, mint accent, salmon counterpoint; fonts and marks served
locally, no CDN, the field has no internet).
Panels: flight check (the last moss_preflight.py --json), base (battery on a
3S scale, mode, applied PWM per track, ticks, firmware), system (CPU, RAM,
temperatures, disk), the live map (occupancy grid + lidar scan + pose + path +
goal; drag to pan, wheel or pinch to zoom, tap to send a goal), the two cameras
under the map (nose = RealSense colour, wrist = the arm's camera; MJPEG, 5 fps
each, one "Pause video" for both), controls (launch map / explore, stop stack,
start / stop exploration, record episode, STOP), what it decides (below) and
the log tail.
STOP on the page is a soft stop: it publishes stop_explore_cmd,
stop_movement and a zero twist. The hard stops are the firmware deadman
(300 ms) and tools/moss-fly.sh stop.
The stack stops itself. A stack left up with nothing to do drains the battery:
on the board's input rail, the explore stack idle on a parked rover drew about 2 W
more than no stack at all (one measurement at the time of this change). The cockpit
stops a moss-nav or moss-explore stack (the two that run the lidar odometry and
the costmap) that saw no activity for MOSS_IDLE_STOP_S seconds (300 by default)
with the message stopping the stack to preserve battery (idle 5 min), in its
journal, above the stop's lines in /launch.json and on the page's status line
with its time (..., stopped at 14:05), where it stays until the next action. The
cockpit keeps that note in memory only: a restarted cockpit no longer shows it. The
stop is the same tools/moss-fly.sh stop as the Stop stack button (exploration off
first, then the stack down). moss-gamepad and any other MOSS blueprint stay up:
tools/moss-teleop.sh keeps its stack up with the pad on the table. Activity is
any of: base telemetry whose output_pct is not [0, 0] (a track commanded, by
the pad, the planner or the explorer) and whose firmware line is at most 1 s old
(with the board lost, the coordinator repeats its last line), a cmd_vel with a
non-zero linear.x or angular.z, an explore_cmd, a goal_request, an
episode_marker, an open episode, the odometry pose more than 2 cm or 2 degrees
from where it was 10 s before (the rover pushed by hand; drift at rest never adds
up to that), and any command sent from the page. An exploration with nothing left
to drive is idle. The count runs from the stack's start (from the cockpit's own
start when the cockpit came up later) on the monotonic clock, so a clock step
changes nothing, and each run is stopped once at most.
While a moss-nav or moss-explore stack runs, the line under the chip reads
idle 3:20, stops at 5:00 to preserve battery · keep the stack up: dim until half
the limit, in the warning colour for the last minute. The line is a button: a press
(POST /cmd/keepalive) starts the count again, and the line shows it at once. The
cockpit never stops a stack it cannot see: one on another bus than LCM or with
another LCM_DEFAULT_URL than the cockpit's, any stack while it does not listen to
the bus, or while nothing arrived on any channel it listens to for 10 s (every MOSS
stack publishes base_telemetry twice a second: silence means the cockpit is deaf,
not that the rover is idle). It never stops a registry entry whose pid is no longer
a dimos run (a stale entry after a power cut). It waits for a launch or a flight
check in progress, up to 120 s, and a stop that fails to start is tried again each
second. The journal says once per run why a due stop was held. /state.json
carries idle: {enabled, idle_s, stop_in_s, limit_s, last_source, blind} next to
stack: last_source names what restarted the count last (start, telemetry,
cmd_vel, odom, explore_cmd, goal_request, episode, post, keepalive,
demo) and blind why the cockpit cannot see the run, so a run that never stops
says why. To turn it off, set MOSS_IDLE_STOP_S=0 in the service (sudo systemctl edit moss-cockpit, a line Environment=MOSS_IDLE_STOP_S=0 under [Service]) and
restart the cockpit; a value under 30 s is refused (the cockpit says so and keeps
300 s). In the demo, the synthetic rover's driving counts as activity, and a halted
demo stack stops itself the same way, on the first request past the limit.
A goal tapped on the map goes out at once when nothing is exploring. While
exploring, the page stops the explorer first and sends the goal three seconds
later, after the explorer's own last goal, which would override it otherwise.
The cockpit refuses goals, exploration and launches when the running stack is
not a MOSS one (its blueprint name must start with moss), so another dimOS
stack sharing the computer and the bus never receives its commands; STOP is
always allowed. Commands that publish on the bus need the stack on LCM
(DIMOS_TRANSPORT, else TRANSPORT, set to lcm; the launchers export both,
lcm by default) and are refused with the reason otherwise. Every POST /cmd/* must carry the header
X-Requested-With: moss-cockpit (the page does, a cross-site form cannot).
Endpoints, for anything else that wants the data: /state.json, /map.png,
/map_meta, /scan.json, /path.json, /log.json, /decisions.json (below),
/preflight.json, /launch.json, /camera.mjpg (?cam=nose, the default, or
?cam=wrist), and POST /cmd/{explore,goal,stop,episode,stack}.
/scan.json splits the latest lidar cloud by height: points (and n) are the lidar returns, at
the profile's lidar height; camera (and camera_n) are the depth camera's obstacle points, at
their true height, which the page draws in amber; pose is the rover's pose at the
scan's time (x, y, yaw, age_s), so the page moves the rover marker at the scan's
rate (3 Hz) rather than the state's (1 Hz). The raw /pointcloud fallback has no
camera key. The map panel's Clear map button (/cmd/map with action: clear,
tools/explore_ctl.py clear from a shell) makes the costmap start a fresh grid centred on
the rover, without stopping the stack or the run: an open exploration keeps writing from
the next revolution. The base panel shows a STALLED badge for at least 4 s whenever the
base adapter's stall guard fires (a commanded track whose encoder did not move for
1 s: the tracks stop and the planner backs off), and a stalls row counts them
over the run.
tools/moss_cockpit.py --demo serves synthetic data for working on the page
without a robot.
Simple and Advanced
The page has two views. Advanced is the whole cockpit described above. Simple is one
column for a phone or a tablet: the word for now (OFFLINE, NO STACK, LAUNCHING, NO TELEMETRY,
BATTERY LOW, STALLED, EXPLORING, DRIVING, READY, DISARMED; the worst first) with a line that
says what it means for the hand on the pad, the battery, one camera (a button switches nose and
wrist; the one not shown is not streamed), a STOP that stays in reach at the bottom of the
screen, Launch map and Stop stack, and one line of log (the page's last answer while it is
fresh, then the newest log line). ?view=simple or ?view=advanced picks a view and the
browser remembers it; without either, a first visit narrower than 700 px opens Simple. The
button at the top right switches at any time.
What it decides
The map shows what the rover sees; the "What it decides." panel says what it
made of it and what it did as a consequence. Nothing new runs on the robot for
this: the explorer, the planners, the base adapter, the costmap and the contact
sources already write each of their decisions into the run's log (main.jsonl
in the run's log directory). The cockpit reads that file and turns every
decision line into one short line, in the order the stack wrote them, and
keeps one word on top for the state now.
| Kind | Who says it | The line in the log | On the page |
|---|---|---|---|
goal |
explorer | goal 3: (-1.67, -0.12) 3.9 m away (beyond the cap: ...), 110 frontier cells, ... |
Goal 3: 3.9 m away (110 cells, beyond the cap) |
goal_dropped |
explorer | planner gave up on that goal: ..., goal timeout after 30 s having closed 0.05 m of 2.40 m: ... |
Goal dropped: the planner gave up / 0.05 of 2.40 m closed in 30 s |
goal_dropped |
global planner | No path found to the goal., No safe goal found near requested target. |
Goal dropped: no path to (1.03, -2.72) / no safe spot near it |
goal_dropped |
recovering planner | Goal abandoned, no recovery motion (stuck) |
Stuck: goal abandoned |
waiting |
explorer | 10 of 20 clusters are on a recently failed goal: waiting ... |
Waiting: 10 of 20 frontiers are failed goals |
retry |
explorer | starvation escape: ... reopening the oldest failed goal at (-1.27, 1.28) |
Retrying an old goal at (-1.27, 1.28) |
obstacle |
local planner | Obstacle detected ahead, stopping local planner. |
Obstacle ahead: stop |
obstacle |
explorer | born cornered: 0.40 m2 of reachable floor and no frontier - one 0.20 m back-off ... |
Cornered (0.40 m2 of floor, no frontier): backing off 0.20 m |
replan |
global planner | a reason, then Replanning. (see below) |
Replanning / Stuck: replanning / Off track: replanning / Navigation failed: replanning |
new_goal |
global planner | Got new goal, Found safe goal., Travelling to goal 1.29m away from requested goal. |
Planner: new goal / safe goal found / safe goal 1.29 m from the requested one |
reached |
local planner | Reached goal position, starting final rotation |
Goal reached |
contact |
base adapter | STALL #1: tracks commanded L=+76% R=+64% but the encoders moved L=+1 R=+0 ticks in 1.0 s |
Contact #1: both tracks blocked (commanded ..., encoders moved ...) |
contact |
recovering planner | BUMP received, Contact during an escape: stopping dead, Contact escape |
Bump: backing off / Contact during an escape: stop dead / Escape done: 0.20 m in 2.1 s, Escape timed out: only 0.05 m in 5.0 s, Escape aborted after 0.05 m |
contact |
costmap (MOSS_CONTACT_WALL=1) |
costmap: contact at (-0.88, +0.73) heading +147 deg: 32 cells ahead marked as a wall |
Wall remembered ahead (32 cells) |
push |
base adapter | tracks frozen at L=+56% R=+50% - pushing at 75 % for 1 s ... |
Tracks frozen at L=+56% R=+50%: pushing at 75 % |
pivot_fallback |
base adapter | pivot L=+100% R=-100%: the right track did not turn ... |
Right track did not turn in reverse (...): pivoting on the left track from now on |
imu |
IMU contact detector | IMU contact: forward -4.8 m/s^2 (threshold 4.0) while commanded L=+70% R=+60% |
the line itself |
mission |
explorer | exploration start: ..., the stop lines, exploration complete: ... |
Exploration started (cap 3 m, radius 4 m) / stopped (stop button or pad) / complete |
A contact names the track that did not move: a track counts as blocked when it
was commanded and its encoder moved fewer than 20 ticks over the stall window
(the base adapter's own rule). Some decisions read the record's fields as well
as its text: how far an escape went and how long it took (travelled_m,
seconds), whether it was cut short (aborted), whether a bump moved anything
(acted), what made the planner give a goal up (trigger), the spot it could
not reach (x, y). Every other line (twists, telemetry, the camera's obstacle
counts, sounds, transport) is not a decision and does not appear.
A replan is shown only when the planner really replans. The global planner
first logs why it might (Robot is stuck. Replanning., Replanning path due to obstacle found., Robot veered off track. Replanning., Failure in navigation.), then decides. dimOS logs Replanning. when it replans, and that
line is what shows the reason. MOSS's planner logs Goal abandoned, no recovery motion when it gives the goal up, and that line is shown instead. Two cases
drop the reason: Replan requested without a goal; ignoring., and no answer
within 0.5 s. The second happens when MOSS's planner ignores a stuck verdict
while the rover turns in place, waits, or backs off from a contact. A turn in
place is not being stuck. A stuck verdict the planner ignored is therefore not
in the feed: the rover is still heading for its goal.
A line that only repeats the decision just before it is left out (within one second, unless said otherwise). That covers:
- the planner taking the explorer's goal;
- the planner's second
No safe goal found.; - the explorer's "planner gave up" right after the planner gave its own reason, so the reason stays;
- the bump the explorer publishes when it backs out of a corner;
- the second of the two stop lines a STOP produces;
- the explorer's "stay here" goal and its arrival, within 0.2 s of its stop.
A goal tapped after that is a new decision. A BUMP received during an escape
moves nothing: the line before it says the rover stopped dead, and the bump
gets no row. Identical lines one after the other, such as the explorer saying
every second that it waits, make one row ending in a count such as (x10), so
a long wait never pushes the contacts out of the page's 30 rows.
| Word | When |
|---|---|
| IDLE | no stack is running (the last run's lines stay below it until the next run) |
| READY | a stack and no decision yet; a tapped goal reached, dropped, or an escape over while nothing explores |
| HEADING | a goal chosen (by the explorer or tapped on the map), a goal reached while exploring, a replan that keeps the goal (off track, a navigation failure) |
| OBSTACLE | the local planner stopped on an obstacle, or the planner replans around it: 3 s |
| STUCK | the planner's stuck replan or its giving a goal up when stuck (3 s), the base pushing harder on frozen tracks (4 s) |
| BACKING OFF | a contact (an encoder stall, the bump, the wall remembered, an IMU contact) or the explorer backing out of a corner: until the escape's end line, at most 6 s (the escape's 5 s timeout plus one second for a lost line) |
| WAITING | the explorer waits (every frontier left is a failed goal), dropped a goal, has just started, or an escape is over |
| STOPPED | exploration stopped (STOP, the pad, a stop command); an escape ending after the STOP leaves it |
| DONE | exploration complete |
OBSTACLE, STUCK and BACKING OFF are held for their time even when the next line comes a millisecond later, so they can be seen; while several run the strongest shows (BACKING OFF, then STUCK, then OBSTACLE). The end of an escape and the end of the mission end every hold. Outside a hold the word is what the last other line said. Under the word, the detail is the goal being driven to or the text of the line that set the word.
GET /decisions.json?n=40 serves it: {"now": {"word", "detail", "since"}, "events": [...], "run"}, where each event is {"ts", "kind", "text", "src", "seq"}: ts the log's own timestamp (ISO, UTC, with a Z), src one of
explorer, planner, base, costmap, recovery, imu and mission, seq one more per
decision, never going back while the cockpit runs. The cockpit reads
main.jsonl incrementally (its last MiB at first, then only what was
appended), at most twice a second whoever asks, and keeps the last 500 rows.
When the stack stops, its rows and its run name stay, under IDLE "No stack
running (last run: ...)", as its map does; the next run's log starts a new
feed. A dimos run with no registry entry (run in the foreground, or a
registry swept by dimos status) has no log the cockpit can find: the word is
READY, "Stack running, its log is not found", and the feed is empty. --demo
plays a scripted cycle through the same parser: goal, obstacle, replan,
contact, escape, goal dropped, next goal, arrival.
The feed says what the stack decided, not everything the sensors saw: an obstacle the camera saw and the planner never acted on is on the map, in amber, not in the feed.
Contacts from the RealSense's IMU, which do not depend on the tracks gripping: imu.md.
The cockpit as a service
By hand, tools/moss-fly.sh cockpit starts the server and prints its address;
the launcher also restarts a server older than tools/moss_cockpit.py, and
refuses one that runs from another checkout, naming its directory. To have it
start with the robot, install tools/moss-cockpit.service. The unit is a
template: MOSS_USER is the account that runs the stack, MOSS_DIR the
absolute path of this checkout (with its .venv). From the root of the
checkout:
$ sed -e "s|MOSS_USER|$USER|g" -e "s|MOSS_DIR|$PWD|g" -e "s|MOSS_UID|$(id -u)|g" tools/moss-cockpit.service \
| sudo tee /etc/systemd/system/moss-cockpit.service >/dev/null
$ sudo systemctl daemon-reload && sudo systemctl enable moss-cockpit && sudo systemctl restart moss-cockpit
restart, not enable --now: enable --now leaves a cockpit that is already
running as it is, still serving from its old checkout. KillMode=process keeps
a stack launched from the page alive when the cockpit restarts; stop a flight
with tools/moss-fly.sh stop. The installed unit holds absolute paths: after
moving the checkout, stop any flight (tools/moss-fly.sh stop), run the two
lines above again from the new place, and check that the running cockpit is
this checkout: readlink /proc/$(systemctl show -p MainPID --value moss-cockpit)/cwd
prints its path.
A stack launched from the page needs the same LCM settings as one launched from
a shell (Software.md, First run): either
passwordless sudo for the stack's user, or tools/lcm-loopback.service, which
turns on loopback multicast, adds the 224.0.0.0/4 route on lo and raises the
socket buffers once at boot:
$ sudo cp tools/lcm-loopback.service /etc/systemd/system/
$ sudo systemctl daemon-reload && sudo systemctl enable --now lcm-loopback
Limits
- The geometry and the base numbers are placeholders until measured: ground speed, ticks per metre, track width, lidar pose, the footprint and the static-friction floor. base.md says how to measure the base's.
- The gyro prior reads the yaw rate on one axis of the camera's frame
(
gyro_axis="-y"), the right one for the level, upright mount: a camera mounted upside down flips its sign, and there is no switch for the axis. - Every launch starts a fresh map: no map is saved between runs and there are no keep-out zones. The recording keeps the run.
- A recording is not replayed through the stack; the SQLite file is readable with the dimOS tools above.
- The planner's slowest pivot (0.2 rad/s, about 6 % PWM at the defaults) sits
inside the motors' dead band at the current gearing: planned turns in place
stall without a static-friction floor (
MOSS_MIN_PCT, above).
Deploying from another machine
The robot can run a git clone or an rsync copy of this repository. With rsync, leave the venv and the package metadata out of the sync and install the package on the robot itself:
$ rsync -a --exclude .venv --exclude .git --exclude 'moss_dimos.egg-info' ./ <user>@<robot>:moss/
$ ssh <user>@<robot> 'cd moss && uv pip install --python .venv/bin/python -e . --no-deps'
uv's installer puts it in ~/.local/bin, which a command run over ssh may not
have on its PATH: give the full path there if uv is not found. In a venv made
with python3.12 -m venv, .venv/bin/pip install -e . --no-deps does the same.
New blueprint names only become runnable after that install on the robot. An
rsync that carries moss_dimos.egg-info/ from a development machine overwrites
the robot's copy: the flight check then reports the MOSS blueprints missing
while the venv knows them. Run the install again on the robot to regenerate it.
Cold benches
benches/bench_moss_preflight_cold.py, benches/bench_moss_fly_gates_cold.py,
benches/bench_moss_cockpit_cold.py and benches/bench_explore_ctl_cold.py
cover these tools, without the robot. Run one with
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. .venv/bin/python benches/<name>.py, or
every bench with benches/run_all.sh (Software.md).
bench_explore_ctl_cold.py needs lcm and dimos_lcm, which come with dimOS;
the other three run on any Linux machine and skip, with a line that says so,
the sections that need dimOS.