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

docs: the pad drives from the battery switch, the speaker on the Jetson's I2S2 (MAX98357A), robot.env on MOSS_PAD_LAYOUT=auto; changelog entry for 24 October

metrox06f0115eda7e
diff --git a/.gitignore b/.gitignore
index db5cefd..80dc0fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ __pycache__/
recordings/
.venv/
firmware/**/build/
+firmware/MOSS_QTPY_MDD3A/build_*/
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b351c36..202304b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
Hardware revisions. Dates are when it was real, not when it was planned.
-- **24 October 2026, no deadman on the pad.** A small tracked rover at walking pace does not need a held button: a stick out of its deadzone drives, centred sticks stop (0.5 s of zeros, then silence); the neutral-first trust gate and the firmware's 300 ms stop stay. `MOSS_PAD_DEADMAN=r1` (or an SDL button number) in `robot.env` brings the held button back. Launcher, flight check and docs follow.
+- **24 October 2026, the pad drives from the battery switch.** Power on and the rover is drivable once its stack is up: `tools/moss-teleop.service` runs the launcher at boot and retries until the pad and the board answer. No deadman: a small tracked rover at walking pace does not need a held button, a stick out of its deadzone drives and centred sticks stop (0.5 s of zeros, then silence); the neutral-first trust gate and the firmware's 300 ms stop stay, `MOSS_PAD_DEADMAN=r1` in `robot.env` brings the held button back. The pad layout is picked from the device's kernel name (`MOSS_PAD_LAYOUT=auto`): `ds4` joins `android` and `xinput`, for a 2.4 GHz receiver that enumerates as a DualShock 4 (a GameSir Nova 2 Lite on its receiver, DInput mode); `MOSS_PAD_INVERT_Y` and `MOSS_PAD_INVERT_TURN` flip a stick whose sign is the other way round. Sound from the rover itself: a MAX98357A amplifier on the Jetson's I2S2 pins and a wired speaker ([Software.md](Software.md#speaker-on-the-jetsons-i2s)), the sound pack normalised to −1 dBFS peak (it sat at −12 dBFS). USB: a hub carries the pad receiver, the wrist camera and the lidar; the RealSense, the motor board and the servo bus go straight to the Jetson. Six minutes of driving indoors on one charge: driver and motors cool to the touch after it.
- **11 October 2026, dimOS software moves into this repository** (`moss_dimos`): base, lidar odometry, map, planner, explorer, gamepad, recorder, flight check, launcher, cockpit. dimOS itself stays an outside dependency, installed from git ([Software.md](Software.md)).
- **10 October 2026, first drive at the gamepad.** The V0.5 rover, arm mounted, driven on the floor from a gamepad through dimOS: forward, reverse, turns, pivots. What it took and what it showed:
- Firmware `qtpy-mdd3a-v3` on the QT Py ESP32-S3 (`firmware/MOSS_QTPY_MDD3A/`): the 25 % commissioning limit is gone, full stick is 100 % PWM (at 25 % the loaded tracks did not move at all); left track direction fixed in the firmware, encoder counts follow; `ramp UP DOWN` sets the rise and fall slopes live; a build switch for the Cytron MDD10A (PWM + DIR) next to the MDD3A build; the board names its driver in the banner and the telemetry. Host test updated.
diff --git a/Software.md b/Software.md
index 3523649..2ce418e 100644
--- a/Software.md
+++ b/Software.md
@@ -60,6 +60,12 @@ On a computer where dimOS sits on wheels built for that board, install this pack
dimOS's bus (LCM) needs multicast on the loopback interface, a `224.0.0.0/4` route on it, and 64 MB socket buffers (`net.core.rmem_max`, `net.core.rmem_default`). None of it survives a reboot. dimOS checks them at each launch and sets what is missing with sudo, so either the robot's user has passwordless sudo, or `tools/lcm-loopback.service` applies them at boot (install line in [docs/cockpit.md](docs/cockpit.md#the-cockpit-as-a-service)). Without either, a launch stops on a `CalledProcessError` from `sudo ip ...`.
+### Speaker on the Jetson's I2S
+
+The rover's speaker is a MAX98357A I2S amplifier on the Jetson's 40-pin header, I2S2: BCLK on pin 12, LRCLK on pin 35, DIN on pin 40 (the Jetson's data out), 5 V and ground. The header has no function enabled by default; `sudo /opt/nvidia/jetson-io/config-by-function.py -o dt 1="i2s2"` writes a device-tree overlay and a boot entry for it, and the board reboots. Then the I2S2 controls of the `APE` sound card (`amixer -c APE controls | grep -i i2s2`): codec frame mode `i2s`, codec master mode `cbs-cfs`, playback bit format `16`, sample rate `44100`, playback channels `2`, kept across reboots with `sudo alsactl store`. As done on the Orin Nano devkit under JetPack 6; `paplay assets/sounds/hello_01.wav` is the test.
+
+PulseAudio: make the card the default sink (`pactl set-default-sink alsa_output.platform-sound.analog-stereo`, then `pactl set-sink-volume @DEFAULT_SINK@ 100%`) and keep the sink from suspending between cues, which clicks on this amplifier, with a `~/.config/pulse/default.pa` of two lines: `.include /etc/pulse/default.pa` and `unload-module module-suspend-on-idle`. The sound module (`moss_dimos/sounds.py`, [docs/cockpit.md](docs/cockpit.md)) plays into that session: a stack launched from a login shell or over ssh as the robot's user finds it, the boot service's stack does not and stays silent.
+
## Run
```
diff --git a/docs/base.md b/docs/base.md
index 4bb966a..308a711 100644
--- a/docs/base.md
+++ b/docs/base.md
@@ -16,9 +16,9 @@ $ tools/moss-teleop.sh stop # stack down (the firmware deadman stopped the
$ MOCK=1 tools/moss-teleop.sh # same stack on the fake firmware, no motor
```
-Pad (a shanwan receiver in Android mode): **no deadman**, a stick out of its
+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 7 on this pad, 5 on its USB cable),
+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
@@ -104,7 +104,7 @@ same file, so a verdict there is a verdict on what will actually run. The shell'
```
MOSS_DRIVER=mdd10a # the motor driver on the board: the flight check refuses a firmware built for another one
-MOSS_PAD_LAYOUT=xinput # android = the pad on its 2.4 GHz dongle; xinput = the same pad on its USB cable (an Xbox 360 pad to the kernel)
+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 %
```
diff --git a/docs/cockpit.md b/docs/cockpit.md
index f1ef03e..cbc393d 100644
--- a/docs/cockpit.md
+++ b/docs/cockpit.md
@@ -98,8 +98,9 @@ firmware 300 ms after the last drive.
fails on the rover and takes the camera down), and `MOSS_GYRO_FORCE=1` builds it anyway,
as an experiment ([imu.md](imu.md#the-gyro-and-the-odometry));
- the sound module (`moss_dimos/sounds.py`): a pack of short synthesized cues in
- `assets/sounds` played through the robot user's PulseAudio session (a Bluetooth
- speaker once connected, the default sink otherwise) on confirmed events only: the
+ `assets/sounds` played through the robot user's PulseAudio session (its default sink:
+ the on-board amplifier, [Software.md](../Software.md#speaker-on-the-jetsons-i2s), 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