plan.md

Reachy Mini Morse Code — plan

Goal

A shareable browser app (HF Space, JS, bare-HTML + CDN host shell, mirroring marionette-js) that lets a Reachy Mini communicate in Morse code:

• The robot transmits by hitting its antennas together — each hit makes an audible click.
• A phone / laptop transmits by beeping through its speaker.
• Either device (or a second robot) listens through a microphone, detects the impulses, and decodes them back to text.
• Two Reachy Minis face-to-face can therefore talk to each other.

Why an "impulse" wire code (the key design decision)

An antenna hit is impulsive: it produces one short click. You cannot make a click "longer" the way a tone can be held, so we cannot use the classic Morse discriminator (dot = short tone, dash = long tone) on the robot channel.

To keep every channel interoperable through one detector (robot-clicks, phone-beeps, robot↔robot), the on-the-wire code is built from onsets only (the instant each sound starts), and dot vs dash is carried by rhythm:

• dot = 1 impulse
• dash = 2 impulses spaced by dahGapMs (a quick double-tap)
• elements within a letter separated by elemGapMs
• letters separated by letterGapMs
• words separated by wordGapMs

with dahGapMs < elemGapMs < letterGapMs < wordGapMs (well separated so the decoder can bin each inter-onset interval unambiguously). This is still real Morse semantically — the learn-chart shows the standard .- patterns — it is just transmitted as an impulse rhythm instead of tone length. The user explicitly framed Morse as "an equivalence between letters and rhythm", which is exactly this.

Beeps use the same impulse code (short clicks) so a beeping phone and a tapping robot are mutually intelligible. (An "audible long-tone" cosmetic mode can be added later; it is not the machine-decodable wire format.)

All timings live in one timing.js config with a single unitMs speed knob, so they can be calibrated on real hardware (click sharpness, room reverb, mic latency) without touching logic.

Detection algorithm (ported from marionette/tests/audio_analysis.py)

detect_transient_onsets, proven in the Marionette audio-sync tests:

1. High-pass filter (~2 kHz) to isolate sharp clicks from room rumble / voice.
2. Short-term energy in 5 ms windows.
3. Spectral flux = positive energy differences.
4. Normalise, peak-pick with a min-separation guard.

Ported to the Web Audio API (BiquadFilter highpass + per-frame energy/flux in an AudioWorklet/ScriptProcessor) for live mic decoding, and to a pure-JS offline function reused verbatim in unit tests against synthetic audio.

Architecture (bare-HTML + CDN host shell, like marionette-js)

index.html   #root (host shell mount) + #app (in-iframe surface), CDN SDK pin
main.js      dispatcher: standalone mountHost() | embed connectToHost()
style.css    mobile-first, OKLCH palette, dark/light from handle.theme
lib/
  morse.js        text <-> morse string ('.- ...') tables + encode/decode  [pure, tested]
  timing.js       unit/gap config + WPM-ish speed presets                  [pure, tested]
  wire.js         morse <-> timed impulse schedule (emit) and onset-times
                  -> morse decode (gap binning)                            [pure, tested]
  detector.js     offline + streaming transient-onset detector (Web Audio) [DSP core tested]
  synth.js        Web Audio click/beep emitter (plays a wire schedule)
  robot-tapper.js drives antennas to clap on schedule (setAntennasDeg)
  mic.js          getUserMedia -> streaming detector -> onset times
  viz.js          canvas waveform + live onset markers
  animation-helpers.js  re-export SDK /animation (safelyReturnToPose)      [stubbed in tests]
views/
  composer.js     type text -> choose emitter (robot antennas | this device) -> send
  listener.js     live mic visualization + decoded text
  learn.js        Morse chart (letter <-> .- <-> rhythm), tap-to-hear
  topbar.js / settings.js  speed + detector threshold + theme
tests/unit/       morse, wire, detector (synthetic round-trip) — vitest
public/icon.svg
README.md         HF Space frontmatter (sdk: static, hf_oauth, tags)

Robot antenna "clap" (from marionette/tests/test_antenna_collision.py)

Right antenna held, left antenna slams in to contact and back — low-PID antennas make this safe and audible. In the JS SDK we drive it in real time with setAntennasDeg(right, left) on a timed schedule from wire.js. Exact contact angles + hold time get calibrated on hardware; defaults seeded from the Marionette recipe (right ≈ −39°, left rest 0° → slam ≈ +40°).

What needs hardware (deferred — will ping Rémi)

1. Mic + speaker calibration: emit the impulse schedule from the Mac speaker, record with the Mac mic, confirm the detector recovers the onsets through-air and tune unitMs / thresholds / highpass. (Noise — needs Rémi.)
2. Robot antenna-click test: confirm the clap is audible + detectable and tune the contact angles / hold. (Needs the robot connected.)

Everything else (codec, detector DSP, full UI, synth, robot-tapper wiring) is built and validated in software first (synthetic-audio round-trip, no mic/speaker/robot).

Open questions (defaulted; will confirm with Rémi, non-blocking)

• App/Space name: morse-code / "Reachy Mini Morse Code". Deploy to RemiFabre/<name> (user is logged in as RemiFabre, org pollen-robotics).
• Default speed: ~`unitMs = 120 ms` (slow & robust) — final value from calibration.
• Long-tone cosmetic beep mode: out of scope for v1 (impulse code only).