Action Editor and Command Library

Action Editor and Command Library

The action editor is where you decide what NaviCore does when a button is tapped, a switch moves, or a knob turns. It works command-first: you pick a real droid command from a browsable Command Library, fill in its parameters, and choose where to send it. You never pick an "action type" — the tool sets that from the command and destination you chose.

This page covers the editor UI and command routing. For each action type's parameters (HCR functions, MP3 functions, Maestro verbs), see Actions Reference. For opening the editor and the live monitor, see Config Tool Guide.

---

Opening the editor

Open a control's action editor from the mapping grid in the Config Tool Guide. The tabs depend on the control:

Control	Tabs	Meaning
Button	Single tap / Double tap / Triple tap	One tier per tap count; each tab shows a live saved-count badge
Switch	Position tabs (p0 / p1 / p2)	SW Down (Mode 1) / SW Mid (Mode 2) / SW Up (Mode 3)
Knob	Mode 1 / Mode 2 / Mode 3	Outputs while the 3-way mode switch is down / mid / up

Each tier holds up to 5 actions. Add rows with + Add action; the button stops at five.

Every action row carries two extra fields:

• Delay(ms) — 0–10000, in 50 ms steps. See Delays run in parallel below.
• Note — a short optional comment, max 19 characters.

Each tier also has its own cheat-sheet Note (a plain-language caption like "Happy greeting"), also capped at 19 characters. These captions feed the printable Cheat Sheet.

---

The Command Library

Click 📚 Command Builder on any action row (it reads 📚 Change once a command is set) to open the 📚 Command Library modal. Search by command name, category, or board, or expand a board section to browse its commands.

What's in the library

The catalog is assembled from three sources at page load:

1. An inline curated seed (navicore-command-library/v1, version 0.4.0-wled-id) — always available with zero delay, and the only source under a bare file:// open. It ships three boards:
   • WLED Lighting (;L<id>,VERB)
   • Maestro (Pololu servo) — the local/remote servo command set
   • Maestro (via WCB) — the ;M sequence trigger plus servo/script verbs
2. The vendored DroidNet Command Library, auto-loaded from cmdlib/droidnet/manifest.json (a same-origin static read — no manual Fetch needed).
3. NaviCore's controller-native commands from cmdlib/navicore/manifest.json (Record / Play / Stop).

The DroidNet library is version 4.2.0, generated from C2B5 firmware + WIPDocs, R2UppitySpinnerV3 ALT 3.5.3, Printed Droid Magic Panel, and WCB 6.1.5. It supplies HCR, MP3, AstroPixels, FlthyHPs, PSI, R-Series logics, magic panels, Roam-A-Dome, CHiRP, and more.

HCR and MP3 commands come from the vendored DroidNet library — a firmware-accurate superset. If the vendored files can't load (e.g. a bare file:// open with no server), the picker is sparse until you Import or Fetch.

Grouping and order

• The six AstroPixels boards fold into one collapsible AstroPixels group.
• Two DroidNet boards are hidden in favor of NaviCore's own: maestro → Maestro (via WCB), and maestro-native → Maestro (Pololu servo).
• Board order is pinned — audio/servo boards up top, WLED and low-level WCB config at the bottom; unlisted boards sort into the middle.

---

The Command Builder (composer)

Click a command to open its composer. Fill the parameters, then click Use command → (or ← Back to reselect, ✕ to cancel). A live monospace preview shows the exact wire string as you type.

Parameter fields render by type:

Param type	Field
Enum	Dropdown showing a friendly label + the underlying code
Int	Number field with the command's min/max
Servo position	Two linked fields — see below
Bool	Checkbox
Text	Free text

Servo positions (unit:'servoPulse') show two linked fields that update each other: PWM µs (500–2500) and the raw Maestro value (2000–10000, = µs × 4). The command stores the Maestro quarter-µs value.

Re-open the builder on a row that already has a command and it decodes the wire string back to its library command, dropping you into the composer pre-filled — so re-editing is an edit, not a from-scratch pick. Ambiguous templates refuse to guess and send you back to the list. A ;W<wcb>;S<port> device prefix is stripped before decoding.

You can also skip the builder: type or paste a command straight into the Command field (max 95 characters). A decoded-command hint (📚 Board · Command) appears under the row when the string matches a known library entry.

---

"Send to" — choosing the destination

Two dropdowns on the row decide where the command goes; they set the action type for you.

WCB (the target):

Value	Meaning
All boards (broadcast)	Send to every WCB on the network
WCB <n>	A specific WCB (labeled with its alias when known)
This controller	Run it locally on this NaviCore

Serial (dependent on the target):

Value	Meaning
Auto-route (by type)	Let the receiving WCB route the command by its type (no explicit port)
Serial 0–5	A specific serial port on that WCB (0 = USB console; labeled with the device the WCB advertises, e.g. Serial 3 · H-CR)
S3 / S4 / S5	A local aux serial port — only when the target is This controller

The two dropdowns map to a firmware action type:

WCB	Serial	Firmware action
This controller	S3/S4/S5	serial (+ that aux port)
All boards	—	wcb_broadcast
A WCB	Auto-route	wcb_unicast (+ that WCB)
A WCB	A real port	wcb_broadcast whose command is prefixed ;W<wcb>;S<port>

A command sent to a specific WCB serial port is stored as a broadcast with a ;W<wcb>;S<port> prefix, not a unicast. If you hand-type your own ;W… routing into the Command field, the tool won't double-prefix it.

Two special cases have no WCB/Serial pair:

• Maestro commands pick a Maestro slot (1–8) instead. Each option is labeled Maestro N — Local/Remote · dev X (or disabled). A slot's wiring — Local Serial2 vs Remote ESP-NOW by device number — is set in the Maestro tab; see Maestro Setup.
• WLED commands have no picker — they route by the WLED id inside the command (;L<id>,…), wired in the WLED tab. The row just shows a note. See WLED and HCR Audio.

---

Auto-routing to a known device

When you author a command fresh from a blank row, the tool pre-fills its destination to where that device actually lives:

• WDP port labels — each WCB advertises a device label per serial port over WDP (from the device's own @WDP1 announce), surfaced in WCB_STATUS.portLabels. If a WCB advertises a label matching the board you picked, the command routes to that WCB · serial port. The match is case- and punctuation-insensitive. This is the only auto-route for raw-serial devices (Magic Panel, PSI, R-Series…) that have no native WCB routing.
• Configured device home — HCR and MP3 commands fall back to their global destination (config.hcrDest / config.mp3Dest) when no live WDP label is found.

⚠️ Auto-routing happens only on fresh authoring from a blank row. Re-editing (📚 Change) a row keeps the destination you chose — it does not re-route.

⚠️ WDP device-label auto-routing and the Serial 3 · H-CR dropdown text need a direct USB connection. Over Via-WCB the 252-byte bridge frame can't carry the port labels, so the tool shows plain Serial <n> and WDP auto-route is unavailable. It also needs firmware that emits portLabels. See Remote Management over WCB and Connecting.

---

Command types and firmware dispatch

Each action has a type, one of wcb_unicast, wcb_broadcast, maestro, serial, hcr, mp3, wled, record, play, stop. The firmware dispatches each:

Type	What the firmware does
wcb_unicast	Sends cmd to one WCB — boardId 1–20
wcb_broadcast	Sends cmd to every WCB
maestro	Runs on Maestro slot 1–8; the slot's wiring (Local Serial2 or Remote ESP-NOW) is set in the Maestro tab
serial	Writes the command to local aux port S3, S4, or S5
hcr	HCR vocalizer (destination config.hcrDest)
mp3	MP3 Trigger (destination config.mp3Dest)
dfplayer	DFPlayer Mini (destination config.dfpDest)
wled	WLED — routed by the WLED id in the command
record / play / stop	Controller-local record & replay (below)

There are 8 Maestro slots; an action just references a slot. A disabled slot drives nothing, and remote slots go out over ESP-NOW with no return path.

---

Record / Play / Stop (controller-local)

Record, Play, and Stop are NaviCore Controller library commands — they run on this controller, not a WCB:

• Record clip (toggle) — a blank clip name auto-saves as rec_N.
• Play clip — carries a Loop checkbox (stored as fn = 1).
• Stop record / playback — an explicit halt.

Clip names are sanitized to [A-Za-z0-9_-] and truncated to 32 characters on save, so what you type may differ slightly from what's stored. Full workflow is in Record and Replay.

---

Extending the library

The catalog can grow at runtime from the library modal:

• Import… a .json file — either NaviCore's own boards[] schema or a DroidNet components[] board file.
• Fetch a DroidNet-shaped manifest + boards from a URL (default: travisccook/Droidnet-Command-Library) under Check online for a newer library.

Boards merge by id — an incoming board with the same id replaces the existing one. Imported input is shape-validated before it's accepted.

---

WCB status extras

The library and Send-to dropdowns use live mesh status (WCB_STATUS):

• Aliases — friendly names a board reports via ?WHOAMI, shown next to WCB <n> in the target dropdown.
• Temporary peers — a WDP "temporary" peer (a management relay etc.) shows up in WCB_STATUS.temporary[]; the tool tags it · temp and hides its Forget button (it ages out on its own). Shown only when the firmware reports it.

See WCB Network for the mesh model behind these.

---

Gotchas & caveats

• Delays run in parallel, not cumulative. Every action in a tier fires the moment the trigger fires; each Delay(ms) schedules that action for trigger_time + delay. Two actions both set to 3000 both fire 3 s after the press — a common sequencing footgun.
• HCR/MP3 fn/chan/track editors appear only for actions saved in that direct form. Author new HCR/MP3 actions from the library; their destination auto-fills from the HCR/MP3 tabs.
• The skip-if-running gate is hidden. For ;M Maestro verbs the firmware can still skip an already-running move, but the UI checkbox is hidden (the controller can't reliably tell whether a Maestro script is running). A saved value round-trips, and the fail-open window is rcConfig.maeGateMs (default 250 ms).
• Save from the top-bar Save (or the mapping Apply) to write the config to the board. The on-disk action shape is in Configuration Schema; the wire protocol is in Serial JSON Protocol.

---

Next: Actions Reference · Maestro Setup · Record and Replay · See also: Config Tool Guide · Cheat Sheet