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

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.py
index 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 itself
print("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.md
index 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 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 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` and
diff --git a/docs/cockpit.md b/docs/cockpit.md
index 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 by
default) 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: mount
the 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.py
index 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, measured
MOSS_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 kept
MOSS_TICKS_PER_M encoder ticks per metre of track travel, measured
MOSS_TURN_GAIN turn authority vs forward speed (teleop_speeds), 0.5..4, default 2
MOSS_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 measure
max_pct: int = FIRMWARE_MAX_PCT
ticks_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)
@classmethod
def from_env(cls) -> "MossGeometry":