MOSS: a small, mostly 3D-printed litter-picking rover. Cleaner streets, one maker at a time.
Python
base adapter: static-friction floor 100 % by default (the tracks only turn at full duty behind the MDD3A); docs and bench follow
metrox7fe1451fe62a
diff --git a/benches/bench_moss_adapter_cold.py b/benches/bench_moss_adapter_cold.pyindex 99495eb..68564b5 100644--- a/benches/bench_moss_adapter_cold.py+++ b/benches/bench_moss_adapter_cold.py@@ -50,7 +50,7 @@ def settle(s=0.06):# ── 0. gamepad scale: full stick = the base's limit, not the generic 0.6 m/s ──print("0. teleop_speeds / teleop_envelope (track 0.30 m, 0.45 m/s at 100 %, turn gain 2)")os.environ.pop("MOSS_TURN_GAIN", None)-G100 = MossGeometry(track_m=0.30, mps_at_limit=0.45, max_pct=100)+G100 = MossGeometry(track_m=0.30, mps_at_limit=0.45, max_pct=100, min_pct=0) # floor off: the mapping itself_lin, _ang = teleop_speeds(G100)check(abs(_lin - 0.45) < 1e-9, "full stick forward -> 0.45 m/s (= 100/100)")check(abs(_ang - 6.0) < 1e-9, "full stick sideways -> 6.0 rad/s (gain 2 x the 3.0 rad/s spin)")@@ -89,7 +89,7 @@ elif SKIP_GAMEPAD:# ── 1. pure mapping: twist -> track percent ─────────────────────────────-G = MossGeometry(track_m=0.30, mps_at_limit=0.15, max_pct=25, ticks_per_m=None)+G = MossGeometry(track_m=0.30, mps_at_limit=0.15, max_pct=25, ticks_per_m=None, min_pct=0) # floor off: the mapping itselfprint("1. twist -> tracks (track 0.30 m, 0.15 m/s at 25 %)")check(twist_to_tracks(0.15, 0.0, G) == (25, 25), "vx=0.15 -> L=25 R=25 (the limit)")check(twist_to_tracks(0.06, 0.0, G) == (10, 10), "vx=0.06 -> L=10 R=10")@@ -152,7 +152,13 @@ check(twist_to_tracks(0.0, 0.3, GF) == (-12, 12), "floor 12: tiny spin (-5/+5) -check(twist_to_tracks(0.001, 0.0, GF) == (0, 0), "floor 12: a twist that rounds to 0 is STILL a stop")check(twist_to_tracks(0.15, 0.0, GF) == (25, 25), "floor 12: the limit is untouched")check(twist_to_tracks(0.09, 0.0, GF) == (15, 15), "floor 12: 15 % above the floor passes as is")-check(twist_to_tracks(0.06, 0.0, G) == (10, 10), "floor 0 (default): L=10 R=10 unchanged")+check(twist_to_tracks(0.06, 0.0, G) == (10, 10), "floor 0 (explicit): L=10 R=10 unchanged")+GD = MossGeometry() # the MOSS default: the tracks only turn at full duty+check(GD.min_pct == 100, f"the default floor is 100 (full duty only): {GD.min_pct}")+check(twist_to_tracks(0.02, 0.0, GD) == (100, 100), f"default: a slow forward twist -> 100/100: {twist_to_tracks(0.02, 0.0, GD)}")+check(twist_to_tracks(0.0, 0.2, GD) == (-100, 100), f"default: the planner's slowest pivot (0.2 rad/s) -> -100/+100: {twist_to_tracks(0.0, 0.2, GD)}")+check(twist_to_tracks(-0.02, 0.0, GD) == (-100, -100), "default: slow reverse -> -100/-100 (sign kept)")+check(twist_to_tracks(0.0001, 0.0, GD) == (0, 0), "default: a twist that rounds to 0 is still a stop")check(twist_to_tracks(0.06, 0.0, MossGeometry(track_m=0.30, mps_at_limit=0.15, max_pct=25, min_pct=99)) == (25, 25),"a floor above the limit is clamped to the limit")check(twist_to_tracks(0.15, 0.0, MossGeometry(mps_at_limit=0.15, max_pct=10)) == (10, 10),@@ -269,7 +275,7 @@ check(MossGeometry.from_env().min_pct == MossGeometry.from_env().max_pct, "MOSS_os.environ["MOSS_MIN_PCT"] = "-5"check(MossGeometry.from_env().min_pct == 0, "MOSS_MIN_PCT negative -> 0")os.environ.pop("MOSS_MIN_PCT", None)-check(MossGeometry.from_env().min_pct == 0, "MOSS_MIN_PCT unset -> 0 (floor off, unchanged behaviour)")+check(MossGeometry.from_env().min_pct == 100, "MOSS_MIN_PCT unset -> 100 (the tracks only turn at full duty)")# ── 8. the fake is the firmware: its own refusals ──────────────────────print("8. fake firmware fidelity (Control.h)")diff --git a/docs/base.md b/docs/base.mdindex 1e25cd7..1db6cc9 100644--- a/docs/base.md+++ b/docs/base.md@@ -24,7 +24,8 @@ 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 reversesbeyond 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 need more (see `MOSS_MIN_PCT` in+5 % and 15 % duty; on the floor they only turn at full duty, so the base+adapter raises every non-zero command to 100 % (`MOSS_MIN_PCT`, see[cockpit.md](cockpit.md)).This is the dimOS path. The bench tool in `moss_pi/` drives the same firmware@@ -78,14 +79,14 @@ env override, so a run can be re-scaled without a code change:| `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 (0 = off) | `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_MIN_PCT` | static-friction floor: the lowest percent that turns both tracks (100 on MOSS, 0 = off) | `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 |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_MIN_PCT` (static-friction floor, 0 = off),+above the firmware's 100), `MOSS_MIN_PCT` (static-friction floor, 100 by default, 0 = off),`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` anddiff --git a/docs/cockpit.md b/docs/cockpit.mdindex dd340c8..afd5254 100644--- a/docs/cockpit.md+++ b/docs/cockpit.md@@ -117,21 +117,21 @@ everywhere. The values are PLACEHOLDERS until measured on the robot:| 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` |-| static-friction floor of the base adapter (percent) | 0 (off) | `MOSS_MIN_PCT` |+| static-friction floor of the base adapter (percent) | 100 (full duty only) | `MOSS_MIN_PCT` |The speed knobs are `MOSS_MAX_PCT` (the PWM cap of the base adapter, 100 bydefault) and `MOSS_NERF_SPEED` (the launcher's `--nerf-speed` for the planner,0.5 by default).`MOSS_MIN_PCT` is the static-friction floor: a non-zero track command below it-is raised to it, sign kept (a command that rounds to zero stays a stop). It-matters under the planner: its slowest pivot (0.2 rad/s) maps to about 6 % PWM-with the default `MOSS_TRACK_M`, `MOSS_MPS_AT_LIMIT` and `MOSS_MAX_PCT`, which-does not turn the tracks on the floor, so without a floor the rover sits-still and the planner logs `Robot is stuck. Replanning.` until the goal times-out. The floor is 0 (off) by default: find the lowest percent that turns both-tracks on the floor, and launch with-`MOSS_MIN_PCT=<that> EXPLORE=1 tools/moss-fly.sh explore`.+is raised to it, sign kept (a command that rounds to zero stays a stop). On+MOSS it is 100 by default: the geared motors behind the MDD3A only turn the+tracks at full duty on the floor, so every non-zero command becomes a full-duty+command (straight, pivot left, pivot right, stop) and the planner's slowest+pivot (0.2 rad/s, about 6 % PWM on its own) moves the rover instead of leaving+it to log `Robot is stuck. Replanning.` until the goal times out. A base whose+tracks turn below full duty lowers it: `MOSS_MIN_PCT=<percent>` on the launch+line, measured with `tools/moss_floor_probe.py --go` (stack down).The lidar's floor projection is `base_link`, the rover's rotation centre: mountthe C1 there, or the footprint and the pivot clearance are off by its offset.diff --git a/moss_dimos/moss_adapter.py b/moss_dimos/moss_adapter.pyindex c1f6973..8f37eea 100644--- a/moss_dimos/moss_adapter.py+++ b/moss_dimos/moss_adapter.py@@ -60,7 +60,7 @@ Calibration (env, all optional):(default robot_profile.MOSS.track_m, 0.266 CAD, placeholder)MOSS_MPS_AT_LIMIT floor speed in m/s at MOSS_MAX_PCT, measuredMOSS_MAX_PCT percent ceiling, <= the firmware's 100- MOSS_MIN_PCT static-friction floor in percent (0 = off): a non-zero track command below it is raised to it, sign kept+ MOSS_MIN_PCT static-friction floor in percent (0 = off, default 100: the tracks only turn at full duty): a non-zero track command below it is raised to it, sign keptMOSS_TICKS_PER_M encoder ticks per metre of track travel, measuredMOSS_TURN_GAIN turn authority vs forward speed (teleop_speeds), 0.5..4, default 2MOSS_RAMP_MS "UP DOWN" sent as 'ramp UP DOWN' after connect@@ -148,7 +148,7 @@ class MossGeometry:mps_at_limit: float = 0.45 # PLACEHOLDER: floor speed at 100 % (JGB37-520 178 rpm on a ~60 mm sprocket ~ 0.5 m/s), to measuremax_pct: int = FIRMWARE_MAX_PCTticks_per_m: float | None = None # None = no encoder calibration yet- min_pct: int = 0 # static-friction floor: a non-zero track command below this percent is raised to it (sign kept). 0 = off. MOSS_MIN_PCT, to measure on the floor (the planner's 0.2 rad/s pivots map to ~8 %, which does not move the tracks)+ min_pct: int = 100 # static-friction floor: a non-zero track command below this percent is raised to it (sign kept). 0 = off. MOSS_MIN_PCT. 100 on MOSS: the geared motors behind the MDD3A only turn at full duty, so every non-zero command is a full-duty command (the planner's 0.2 rad/s pivots map to ~8 %, which does not move the tracks)@classmethoddef from_env(cls) -> "MossGeometry":