Skip to content

armgit / moss

Public Imported from GitHub
0

MOSS: a small, mostly 3D-printed litter-picking rover. Cleaner streets, one maker at a time.

Python
10.9 KB
Raw Blame

The tracked base adapter

moss_dimos/moss_adapter.py lets dimOS drive MOSS: the dimOS control coordinator and a gamepad module on top, this adapter underneath. MOSS has two tracks on geared DC motors, driven by a QT Py ESP32-S3 running the firmware in firmware/MOSS_QTPY_MDD3A/, over the board's native USB CDC at 115200 baud.

Run it (on the robot, MOSS wired)

The gated way, with the pad receiver and the QT Py on the robot's USB:

$ tools/moss-teleop.sh            # gates: no stack up, js0, QT Py port free, firmware disarmed, battery >= 10.8 V -> stack
$ tools/moss-teleop.sh log        # what the base and the pad said
$ tools/moss-teleop.sh stop       # stack down (the firmware deadman stopped the tracks 300 ms after the last drive)
$ MOCK=1 tools/moss-teleop.sh     # same stack on the fake firmware, no motor

Pad (a 2.4 GHz receiver, layouts below): no deadman, a stick out of its deadzone drives and centred sticks stop (MOSS_PAD_DEADMAN=r1 brings a held button back: R1 is SDL button 5 on a ds4 or xinput pad, 7 on the shanwan receiver in Android mode), left stick up/down = forward/back, right stick left/right = turn, R2 = boost (MOSS_PAD_INVERT_Y=1 / MOSS_PAD_INVERT_TURN=1 in robot.env flip a stick whose sign is the other way round). MOSS_PAD_LAYOUT names the button and axis numbers: android (the shanwan receiver), xinput (an Xbox 360 pad to the kernel), ds4 (a DualShock 4 to the kernel, which is what the GameSir 2.4G receiver is in its DInput mode), or auto, which picks one from the pad's kernel name at launch. The GameSir receiver in its XInput mode (3537:1098) has no Linux driver: hold View + Menu on the pad to cycle modes until it shows up as a DualShock 4. (capped at MOSS_MAX_PCT). The stick scale comes from the base's envelope (teleop_speeds: full stick = MOSS_MPS_AT_LIMIT, full turn = a pivot at that limit), so the stick stays proportional across its travel. With the default MOSS_TURN_GAIN of 2, the inner track stops at half turn stick and reverses beyond it; a gain of 1 only ever stops it. Releasing R1 sends 0.5 s of zeros, then silence (MOSS_BRAKE_S, 0 to 1.0 s). Unloaded, the motors start between 5 % and 15 % duty; on the floor they only turn at full duty, so the base adapter delivers every non-zero command as full-duty pulses (MOSS_PULSE_MS, see cockpit.md).

MOSS_TRACK_SIGN=-1 in robot.env flips the sign of both tracks on the wire and takes it off the encoder ticks, for a build whose firmware positive drives the rover backwards: every commander (the planner, the mission, a script) keeps forward positive, the pad needs no inversion of its own any more, and the odometry counts forward as positive. Prove it with a tape measure before setting it: a vx=+0.1 twist for two seconds must move the rover forward.

This is the dimOS path. The bench tool in moss_pi/ drives the same firmware without dimOS and reads raw SDL button 4 as its deadman: L1 on an Xbox-layout pad, not on this one (Software.md).

By hand, from the root of the checkout:

$ ls /dev/serial/by-id/*QT_Py*     # the motor board (the CP2102N next to it is the RPLidar C1)
$ export MOSS_PORT=/dev/serial/by-id/usb-Adafruit_QT_Py_ESP32-S3_..._-if00
$ export GLIBC_TUNABLES=glibc.rtld.optional_static_tls=4194304   # as the launchers do: some aarch64 (Jetson) imports fail without it; harmless elsewhere
$ .venv/bin/dimos run moss-dimos.moss-gamepad          # gamepad -> tracks
$ .venv/bin/dimos run moss-dimos.moss-base             # base only, cmd_vel from elsewhere

Without hardware: MOSS_MOCK_BUS=1 .venv/bin/dimos run moss-dimos.moss-gamepad (same GLIBC_TUNABLES export on a Jetson) drives the fake firmware (moss_dimos/moss_mock.py) end to end; the .venv/bin/dimos log lines MOSS base MOCK: twist ... -> tracks L=..% R=..% are the proof.

Cold bench (no hardware, no dimOS): PYTHONPATH=. python3 benches/bench_moss_adapter_cold.py.

What the firmware imposes, and what the adapter does about it

Firmware (Control.h) Adapter
arm puts it READY for 10 s, then it disarms itself a drive refused ERR not_armed re-arms and retries once; nothing is guessed from telemetry
drive L R in percent, -100..+100, refused beyond MossGeometry.max_pct <= 100, clamped; the twist is scaled to it
a drive not refreshed within 300 ms stops the tracks (timeout) keepalive re-sends the last drive every 100 ms while the last twist is < 0.5 s old; beyond that one stop, then silence
any invalid line stops and disarms only arm / drive / stop / status ever go on the wire, plus one ramp UP DOWN at connect when MOSS_RAMP_MS is set
telemetry JSON every 200 ms (mode, ticks, ...) mode and encoder ticks are read from it; ticks feed odometry once calibrated

Two deadmen, both on the robot: the adapter's (0.5 s, in the dimOS process) and the firmware's (0.3 s, on the ESP32). A cockpit on a laptop that loses the link stops the tracks without anyone's help.

A third guard watches the body itself, for unattended runs: the speed watchdog, tools/speed_guard.py. It reads the run's dimOS log and measures the speed between consecutive lidar odom #N lines (one every 2 s), dated by the timestamps the log carries. One interval faster than the profile's max_speed_mps (0.45 m/s, MOSS_MAX_SPEED_MPS) stops the run: the exploration stop on the bus (tools/explore_ctl.py stop), then tools/moss-fly.sh stop, and the firmware deadman stops the tracks 300 ms later. It guards one run and stands down by itself when a newer run starts or the log stays silent for 30 s. The ceiling is the planner's cruise plus a margin: dimOS's follower drives at 0.55 m/s times the launcher's speed scale (MOSS_NERF_SPEED, 0.7), 0.385 m/s, and 0.45 m/s leaves 0.065 m/s above it. A ceiling at or under that cruise would stop every normal run, so the watchdog refuses to start with one and says which number to change. tools/moss-fly.sh does not arm it on its own: once the stack is proven, run tools/arm_speed_guard.sh <run log dir> by hand (without the argument it takes the newest run). The script kills the previous run's watchdog by the pid in /tmp/moss_speed_guard.pid, starts a fresh one and exits 1 unless that file then names a process born after the launch; the watchdog writes to /tmp/moss_speed_guard.log. Like the speeds below, the ceiling is a placeholder: once the floor speed is measured (MOSS_MPS_AT_LIMIT), check that what an exploration run really drives stays under it.

The coordinator publishes the firmware telemetry on /base_telemetry every 0.5 s (JSON: ts, fw, driver, mode, reason, bus_mV, ina_ok, ticks, target_pct, output_pct, ramp_ms, firmware_age_s, mock), so nothing else ever has to open the serial port.

robot.env: what this robot is, declared once

~/.local/state/moss/robot.env (or $MOSS_STATE_DIR/robot.env), KEY=VALUE lines. The launchers (tools/moss-fly.sh, tools/moss-teleop.sh) read it before anything else, the flight check reads the same file, so a verdict there is a verdict on what will actually run. The shell's own exports win.

MOSS_DRIVER=mdd10a          # the motor driver on the board: the flight check refuses a firmware built for another one
MOSS_PAD_LAYOUT=auto        # picked from the pad's kernel name at launch; android, xinput or ds4 pins it
MOSS_MIN_PCT=20             # measured floor: both tracks turn from 20 %

The flight check then refuses, in red, what used to pass as "OK": a firmware that does not match MOSS_DRIVER, a pad the receiver has never heard (every axis at its never-reported value), a pad plugged in a layout other than the declared one. And tools/moss-teleop.sh prints "YOU CAN DRIVE" only once the stack itself has written that it saw the sticks at neutral and trusts the commands.

Calibrate before trusting a number

The firmware is open loop (PWM percent). Three numbers turn a twist into tracks and ticks into metres; all three ship as PLACEHOLDERS and each has an env override, so a run can be re-scaled without a code change:

Env Meaning How to measure
MOSS_TRACK_M distance between the two track centrelines (0.266 m from the CAD) tape measure, sprocket centre to sprocket centre
MOSS_MPS_AT_LIMIT floor speed at MOSS_MAX_PCT (0.45 m/s placeholder) full stick (or drive 100 100) for 3 s on the floor, tape measure, divide
MOSS_TICKS_PER_M encoder ticks per metre of track travel (unset) zero, push or drive the rover exactly 1 m, read ticks in a status line, average the two sides
MOSS_MIN_PCT static-friction floor: the lowest percent that turns both tracks (50 on MOSS: 40 measured on a full pack, 10 of margin; 0 = off). An arc whose inner track sits under the floor is scaled up whole, so the curvature the planner asked for survives; raising only the inner track would straighten it tools/moss_floor_probe.py --go with the stack down, the rover on blocks or with a clear metre ahead: it steps the percent up, reads the encoders around each step and prints the value to export

| MOSS_BUS_REF_MV | the bus voltage the floor and the speeds were measured at (12400 = a full 3S pack; 0 = off). A percent is a duty of the bus, so a pack at 10.5 V under load puts 15 % less voltage on the motors for the same command and the tracks creep or freeze: every command is scaled by reference/bus (never below 1, at most 1.5, capped at the limit) | read bus_mV in the telemetry while the probe measures the floor | | MOSS_ONE_TRACK_PIVOT | a pivot whose one track freezes while the other turns is not a contact: that track did not turn in that direction under the pivot's load. It is braked (0) and the pivot turns on the other track for the rest of the run, said once in the log; both tracks frozen in that turn is a contact. On by default, 0 = such a pivot is a stall | the stack log: pivot ... did not turn |

Until MOSS_TICKS_PER_M is set, read_odometry() returns None and read_velocities() returns the commanded twist: an honest "no measurement" rather than a pose made of guesses. Set it and both come from the encoders.

The other base knobs: MOSS_MAX_PCT (percent ceiling, 100 by default, never above the firmware's 100), MOSS_PULSE_MS (full-duty pulse period, 0 = off, the default: continuous power), MOSS_MIN_PCT (static-friction floor when pulsing is off, 50 by default), MOSS_PIVOT_PCT (every pivot sent at this percent on both tracks, 100 by default), MOSS_RAMP_MS ("UP DOWN", sent as ramp UP DOWN at connect), MOSS_PORT (the serial port; by default the QT Py's /dev/serial/by-id path; only a dimos run by hand reads it from the shell, tools/moss-teleop.sh and tools/moss-fly.sh always take the by-id path) and MOSS_MOCK_BUS=1 (the fake firmware, no motors). The other variables are listed in cockpit.md.

vy (strafing) is accepted and ignored: a tracked base cannot do it, and the stock dimOS twist joints still send it. dof is reported as 3 for that reason.