YOSHIMITSU · API Reference

The Hermetic Shinobi as a library: one relaxed sketch, two targets, six stances, and the 極光-gated console that administers the throne.

Architecture

YOSHIMITSU is a library with a thin sketch on top. The whole core lives in src/Yoshimitsu.h; every default lives in src/Yoshimitsu_Loadout.h as _DEFAULT values (pins, timings, gate levels). The sketch — yoshimitsu.ino or the examples/Yoshimitsu_Default/ copy — only holds your* configuration and any overrides you define before the include. Update the library without re-touching your sketch.

Target detection is automatic: ARDUINO_ARCH_RP2040 selects the RP2040-Tiny path (Servo.h, RESET-tap stance switching), ARDUINO_ARCH_ESP32/ARDUINO_ARCH_ESP32S3 selects the ESP32-S3 path (ESP32Servo.h, native USB). Anything else fails at compile time with a clear #error.

graph TB
  SKETCH["yoshimitsu.ino
the relaxed sketch — config only"]
  LOADOUT["Yoshimitsu_Loadout.h
the starting loadout · *_DEFAULT"]
  CORE["src/Yoshimitsu.h
the whole core"]
  STANCES["six stances
KINCHO · MANJI · FLEA
MEDITATION · NSS · BACK"]
  CONSOLE["USB-serial console
極光-gated admin"]
  CRSF["CRSF RX"]
  BRIDGE["MUSHIN bridge
無心 no-mind protocol"]
  PWM["servo PWM
wing L/R · crest"]
  SKETCH --> CORE
  LOADOUT --> CORE
  CRSF --> CORE
  BRIDGE --> CORE
  CONSOLE --> CORE
  CORE --> STANCES
  STANCES --> PWM

The Six Stances

Every stance is a Stance enum value (0–5) chosen at runtime — by USB command, a GPIO0 button (ESP32-S3) or RESET-taps (RP2040-Tiny).

Stance Duty
KINCHO

The parry — CRSF→PWM converter; radio channels become servo microseconds.
MANJI_DRAGONFLY

The levitation — converter plus the local Zephyrus gyro PID on the crest.
FLEA

The lift — power-cycle jig that drops the receiver into bootloader, then MEDITATION.
MEDITATION

The sponge-head — pocket flasher; USB↔UART is a pure transparent bridge for esptool.
NSS

The no-sword bench — direct servo drive (SERVO i us), no radio.
BACK_TURNED

The mirror — deceptive idle; the UART echo never looks back.

Compile-Time Gates

Everything optional compiles out cleanly when disabled — no dead bytes, no dangling references. Override any of these in your sketch before the include.

Console API

Stance commands stay open: KINCHO, MANJI, FLEA, MEDITATION, NSS, BACK, POSE n, plus STATUS, SERVO i us and HELP. Administrator commands are gated behind the prompt: type 極光 first, then DOC, SETUP, JIGUANG, MUTE, CRSF, SCORE, ELRS, LEGEND, BRIDGE, ADMIN or MUSHIN.

極光 DOC prints the cheatcode catalog; 極光 SETUP prints the meditation wizard (stance, voice level, MUSHIN state, receiver power). A non-prompt line hitting a gated command answers "the throne is guarded" and returns.

MUSHIN 無心 — the no-mind protocol

The muscle-memory bridge (spirit→muscle) speaks a 4-field frame over the same two wires as the flasher. Boots armed, persisted in flash.

[0x9B][len][type][payload][xor]
  0x01  INTENT    n × uint16 µs per servo
  0x02  ANNOUNCE  1 Hz keepalive
  0x03  TELEMETRY gyro rate + correction

Deployment

Install the sketches/yoshimitsu folder as an Arduino library, then open File → Examples → Yoshimitsu → Yoshimitsu_Default. Flash once; after that, updates are git pull or a new release — the sketch stays untouched.

Troubleshooting