MOSS: a small, mostly 3D-printed litter-picking rover. Cleaner streets, one maker at a time.
Python
"""MossSounds: the rover's nonverbal voice, a sound pack played on confirmed events.
Sixty short synthesized cues (assets/sounds, twenty event families, three
variants each) and a non-blocking player (sound_pack/player.py: one subprocess
per cue through PulseAudio's `paplay` or PipeWire's `pw-play`, cooldown per
event, priority queue, a global gap so the rover never chatters). This module
maps the stack's events onto the families that EXIST on the robot today;
every other family stays silent until its event does.
In bump : Bool a contact (the base's stall guard, the explorer's back-off) -> bump_surprise
In base_telemetry : String JSON from the coordinator (2 Hz): stall_count, bus_mV ->
recovery_success once the tracks move again after a stall,
battery_low / battery_critical on the bus voltage (hysteresis)
In explore_cmd : Bool the order to explore -> resume
In explore_done : Bool the explorer found nothing left -> mission_complete
boot_ready plays once when the module starts (the stack is up). Nothing plays
twice in a row within an event's cooldown, and nothing plays while muted.
Environment: MOSS_SOUNDS (on by default; 0 = the blueprint leaves the module
out), MOSS_SOUND_VOLUME (0..1, default from assets/sounds/config.json),
MOSS_SOUND_SINK (a PulseAudio sink name or index; default = the session's
default sink, which is the Bluetooth speaker once it is connected),
MOSS_SOUND_BACKEND (paplay or pw-play; default: paplay when present),
MOSS_SOUND_KEEP_AWAKE_S (a silent clip every this many seconds, default 15,
0 = off), MOSS_SOUND_PREROLL_S (silence played in front of every cue, default
0.3 s, 0 = off), MOSS_SOUND_CACHE (where the pre-rolled copies are written,
default <tempdir>/moss_sound_cache). The keep-awake period is read when the
module starts and said in its first log line, with the pre-roll.
The player needs the user's audio session: a stack launched from a login
shell or over ssh as the robot's user finds it (XDG_RUNTIME_DIR); a system
service would not. Without a backend the module logs once and stays silent.
"""
from __future__ import annotations
import json
import os
import shutil
import subprocess
import threading
import time
from pathlib import Path
from typing import Any
from dimos.core.core import rpc
from dimos.core.module import Module
from dimos.core.stream import In
from dimos.msgs.std_msgs.String import String
from dimos.utils.logging_config import setup_logger
from dimos_lcm.std_msgs import Bool
from moss_dimos import robot_profile
from moss_dimos.sound_pack.player import env_seconds
logger = setup_logger()
ASSETS_DIR = Path(__file__).resolve().parent.parent / "assets" / "sounds"
BACKENDS = ("paplay", "pw-play") # PulseAudio first: on the Jetson the Bluetooth speaker is a PulseAudio sink (module-bluez5),
# PipeWire there has no Bluetooth; MOSS_SOUND_BACKEND forces one of the two
BATTERY_LOW_MV = 10800 # 3S pack, read UNDER LOAD (the telemetry comes while the tracks turn: a half-full
# pack sags to about 11.0 V): low below this...
BATTERY_LOW_CLEAR_MV = 11200 # ...and back to normal above this (hysteresis: one sag does not toggle it)
BATTERY_CRITICAL_MV = 10400 # the flight check refuses to launch below 10.8 V at rest; critical under load is lower
BATTERY_SAMPLES = 6 # consecutive telemetry lines (3 s at 2 Hz) below a threshold before it counts
RECOVERY_WINDOW_S = 20.0 # a stall followed by motion inside this window = a recovery
RECOVERY_MIN_TICKS = 100 # encoder ticks that count as "moving again" after a stall
KEEP_AWAKE_S = 15.0 # default of MOSS_SOUND_KEEP_AWAKE_S: a Bluetooth speaker sleeps its link after a few tens
# of seconds of silence and the cues are rare: a short silent clip this often, meant to keep it on
# (assets/sounds/keep_awake.wav); 0 = off
KEEP_AWAKE_MAX_S = 3600.0 # a longer period is clamped to this
def sound_volume(default: float, env: dict | None = None) -> float:
"""MOSS_SOUND_VOLUME clamped to 0..1; unset or unreadable -> default."""
raw = (env if env is not None else os.environ).get("MOSS_SOUND_VOLUME", "")
try:
v = float(raw)
except (TypeError, ValueError):
return default
if v != v:
return default
return max(0.0, min(1.0, v))
def keep_awake_period(env: dict | None = None) -> float:
"""MOSS_SOUND_KEEP_AWAKE_S in seconds: unset or not a number -> KEEP_AWAKE_S,
0 or below -> 0 (off), above KEEP_AWAKE_MAX_S -> KEEP_AWAKE_MAX_S."""
return env_seconds("MOSS_SOUND_KEEP_AWAKE_S", KEEP_AWAKE_S, KEEP_AWAKE_MAX_S, env)
def playback_backend(env: dict | None = None) -> str | None:
"""The playback command: MOSS_SOUND_BACKEND when set and on the PATH, else the
first of BACKENDS on the PATH, None when there is none."""
forced = (env if env is not None else os.environ).get("MOSS_SOUND_BACKEND", "").strip()
if forced:
return forced if forced in BACKENDS and shutil.which(forced) else None
for name in BACKENDS:
if shutil.which(name):
return name
return None
class EventMapper:
"""The stack's events -> sound families, with the state the decisions need.
Pure: call `on_*` and read the list of family names it returns; the module
hands them to the player. Benched without audio."""
def __init__(self, now: float | None = None) -> None:
self._stalls = 0
self._stall_t: float | None = None
self._stall_ticks: tuple[int, int] | None = None
self._battery_state = "ok" # ok | low | critical
self._below_low = 0
self._below_critical = 0
def on_bump(self, data: bool) -> list[str]:
return ["bump_surprise"] if data else []
def on_explore_cmd(self, data: bool) -> list[str]:
return ["resume"] if data else []
def on_explore_done(self, data: bool) -> list[str]:
return ["mission_complete"] if data else []
def on_telemetry(self, doc: dict, now: float) -> list[str]:
out: list[str] = []
out += self._stall_events(doc, now)
out += self._battery_events(doc)
return out
def _stall_events(self, doc: dict, now: float) -> list[str]:
"""A new stall remembers the ticks; motion of RECOVERY_MIN_TICKS on
either track within RECOVERY_WINDOW_S after it = recovery_success.
(The contact cue itself comes from `bump`, published by the coordinator.)"""
out: list[str] = []
stalls = int(doc.get("stall_count") or 0)
ticks = doc.get("ticks")
ticks = (int(ticks[0]), int(ticks[1])) if isinstance(ticks, (list, tuple)) and len(ticks) == 2 else None
if stalls > self._stalls:
self._stalls = stalls
self._stall_t = now
self._stall_ticks = ticks
return out
if self._stall_t is not None and ticks is not None and self._stall_ticks is not None:
if now - self._stall_t > RECOVERY_WINDOW_S:
self._stall_t = None
elif max(abs(ticks[0] - self._stall_ticks[0]), abs(ticks[1] - self._stall_ticks[1])) >= RECOVERY_MIN_TICKS:
self._stall_t = None
out.append("recovery_success")
return out
def _battery_events(self, doc: dict) -> list[str]:
"""ok -> low below BATTERY_LOW_MV for BATTERY_SAMPLES lines, low -> ok above
BATTERY_LOW_CLEAR_MV; low -> critical below BATTERY_CRITICAL_MV for the
same count. Each entry into low or critical plays once."""
mv = doc.get("bus_mV")
try:
mv = int(mv)
except (TypeError, ValueError):
return []
if mv <= 0:
return []
out: list[str] = []
self._below_low = self._below_low + 1 if mv < BATTERY_LOW_MV else 0
self._below_critical = self._below_critical + 1 if mv < BATTERY_CRITICAL_MV else 0
if self._battery_state == "ok" and self._below_low >= BATTERY_SAMPLES:
self._battery_state = "low"
out.append("battery_low")
if self._battery_state == "low" and self._below_critical >= BATTERY_SAMPLES:
self._battery_state = "critical"
out.append("battery_critical")
if self._battery_state != "ok" and mv > BATTERY_LOW_CLEAR_MV:
self._battery_state = "ok"
return out
class MossSounds(Module):
"""The sound pack on the bus. Ins only; see the module docstring."""
bump: In[Bool]
base_telemetry: In[String]
explore_cmd: In[Bool]
explore_done: In[Bool]
def __init__(self, assets_dir: str | None = None, volume: float | None = None,
sink: str | None = None, **kwargs: Any) -> None:
super().__init__(**kwargs)
self._assets_dir = Path(assets_dir) if assets_dir else ASSETS_DIR
self._volume = volume
self._sink = sink
self._player = None
self._mapper = EventMapper()
self._silent_reason: str | None = None
self._keep_awake_s = KEEP_AWAKE_S
@rpc
def start(self) -> None:
super().start()
self._keep_awake_s = keep_awake_period()
backend = playback_backend()
if backend is None:
self._silent_reason = f"no playback backend on the PATH ({' / '.join(BACKENDS)})"
logger.warning(f"MOSS sounds: {self._silent_reason} - the rover stays silent")
return
try:
from moss_dimos.sound_pack.player import MossSoundPlayer
config = {"backend": backend}
if self._sink:
config["target"] = self._sink
self._player = MossSoundPlayer(root=self._assets_dir, config=config,
log=lambda text: logger.warning(f"MOSS sounds: {text}"))
vol = sound_volume(self._player.volume) if self._volume is None else self._volume
self._player.set_volume(vol)
except Exception as exc: # noqa: BLE001 - a broken pack never stops the stack
self._silent_reason = f"{type(exc).__name__}: {exc}"
logger.warning(f"MOSS sounds: player not started ({self._silent_reason}) - the rover stays silent")
self._player = None
return
awake = f"every {self._keep_awake_s:g} s" if self._keep_awake_s > 0 else "off"
preroll = f"{self._player.preroll_s:.2f} s" if self._player.preroll_s > 0 else "off"
logger.info(f"MOSS sounds: up, {len(self._player.rules)} event families, backend {backend}, "
f"sink {self._sink or 'default'}, volume {self._player.volume:.2f}, keep-awake {awake}, "
f"pre-roll {preroll}, assets {self._assets_dir}")
self._play(["boot_ready"])
self._keep_awake(backend)
def _keep_awake(self, backend: str) -> None:
"""A silent clip every MOSS_SOUND_KEEP_AWAKE_S seconds on the same output, so a
Bluetooth speaker in the bin does not go to sleep between two cues (it did on the
floor, and the cues after that went nowhere). A daemon thread, stopped with the module."""
clip = self._assets_dir / "keep_awake.wav"
period = self._keep_awake_s
if period <= 0 or not clip.is_file():
return
self._awake_stop = threading.Event()
def loop() -> None:
from moss_dimos.sound_pack.player import playback_command
while not self._awake_stop.wait(period):
if self._player is None:
return
try:
cmd = playback_command(clip, backend, self._sink, 0.05)
subprocess.run(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL, timeout=10)
except Exception as exc: # noqa: BLE001 - a missed breath is not an error
logger.warning(f"MOSS sounds: keep-awake clip failed ({type(exc).__name__}: {exc})")
threading.Thread(target=loop, name="moss-sounds-keep-awake", daemon=True).start()
@rpc
def stop(self) -> None:
stop_evt = getattr(self, "_awake_stop", None)
if stop_evt is not None:
stop_evt.set()
if self._player is not None:
try:
self._player.close()
except Exception: # noqa: BLE001
pass
self._player = None
super().stop()
@rpc
def set_mute(self, muted: bool = True) -> bool:
if self._player is None:
return False
self._player.set_mute(bool(muted))
return True
@rpc
def set_volume(self, volume: float) -> bool:
if self._player is None:
return False
self._player.set_volume(max(0.0, min(1.0, float(volume))))
return True
def _play(self, families: list[str]) -> None:
if self._player is None:
return
for name in families:
queued = self._player.emit(name)
logger.info(f"MOSS sounds: {name} {'queued' if queued else 'suppressed (cooldown, mute or queue)'}")
async def handle_bump(self, msg: Bool) -> None:
self._play(self._mapper.on_bump(bool(getattr(msg, "data", False))))
async def handle_explore_cmd(self, msg: Bool) -> None:
self._play(self._mapper.on_explore_cmd(bool(getattr(msg, "data", False))))
async def handle_explore_done(self, msg: Bool) -> None:
self._play(self._mapper.on_explore_done(bool(getattr(msg, "data", False))))
async def handle_base_telemetry(self, msg: String) -> None:
try:
doc = json.loads(getattr(msg, "data", "") or "{}")
except (TypeError, ValueError):
return
if isinstance(doc, dict):
self._play(self._mapper.on_telemetry(doc, time.monotonic()))
def sounds_enabled(env: dict | None = None) -> bool:
"""MOSS_SOUNDS: on unless set to 0 / false / no / off."""
return robot_profile.env_on("MOSS_SOUNDS", True, env)