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 is built around a command-first model: you pick a real droid command from a browsable Command Library, fill its parameters, and only then choose where to send it — the tool works out the underlying action type for you.

This page covers the editor UI and how commands are routed. For the meaning of 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.

---

What changed: command-first editing

Older builds asked you to pick an action type first (WCB unicast, Maestro, HCR, Serial…) from a dropdown, then fill per-target fields. That dropdown is gone from view. The action-type <select> still exists in the DOM as the single read-back source of truth, but it is hidden and set for you — by the library command you pick or by the Send to dropdowns — never chosen by hand.

A few consequences of the redesign:

• There is no visible "action type" dropdown anymore.
• The old per-target or: quick-add shortcut buttons (Maestro / Record / Play / Stop) were retired. Those are now authored from the library like every other command.
• A blank action row starts life as an empty wcb_unicast command rather than "nothing", so read-back works the instant you type or pick a command.
• Any docs that say "pick a type first" are stale.

---

Opening the editor

Open a control's action editor from the mapping grid in the Config Tool Guide. What the tabs look like depends 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 (MAX_ACTIONS_PER_TIER). 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 (the button reads 📚 Change once a command is already set) to open the 📚 Command Library modal. From here you can search by command name, category, or board, or expand a board section to browse its commands.

What ships 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 fallback under file://. 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.

The inline seed removed HCR and MP3 boards — the vendored DroidNet library is a firmware-accurate superset for both, so it is the single source of truth there. If the vendored files fail to load (e.g. under a bare file:// open with no server), the picker is sparse until you Import or Fetch.

Grouping, superseding, and order

• The six AstroPixels boards fold into one collapsible AstroPixels picker group instead of six flat rows.
• Two upstream boards are hidden in favor of NaviCore's more accurate versions: the vendored maestro is superseded by Maestro (via WCB), and maestro-native by Maestro (Pololu servo). Don't go looking for the superseded ones — they won't appear.
• Board display order is pinned (audio/servo boards up top, WLED and low-level WCB config at the bottom); unlisted boards sort into the middle in their natural order.

---

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-opening the builder on a row that already has a command decodes the wire string back to its library command and jumps straight into the composer, pre-filled — so re-editing is an edit, not a from-scratch pick. Decoding uses per-command patterns; ambiguous templates refuse to guess and just drop you back to the list. A ;W<wcb>;S<port> device prefix is stripped before decoding.

You can also skip the builder entirely: 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

Back on the row, two dropdowns decide where the command goes. They set the hidden action type automatically, so nothing about how the config saves changes.

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 derive the firmware action type like this:

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 device 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). The 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 automatically 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 auto-routes to that WCB · serial port. The match is normalized (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 to an advertised device only happens on fresh authoring from a blank row. Re-editing (📚 Change) a row that already has a command preserves the destination you chose — it does not re-route.

⚠️ WDP device-label auto-routing and the Serial 3 · H-CR dropdown text only work over a direct USB connection. When connected Via-WCB the 252-byte bridge frame can't carry the port labels, so the tool falls back to plain Serial <n> and WDP auto-route is unavailable. It also needs firmware new enough to emit portLabels. See Remote Management over WCB and Connecting.

---

Command types and firmware dispatch

The hidden type <select> carries one of these values: '' (none), wcb_unicast, wcb_broadcast, maestro, serial, hcr, mp3, wled, record, play, stop. The firmware's rcExecuteActionNow() dispatches each:

Type	What the firmware does
wcb_unicast	wcb->send(boardId, cmd) — boardId 1–20
wcb_broadcast	wcb->broadcast(cmd) to every WCB
maestro	executeMaestroCmd(slot, cmd) — 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 executor (destination config.hcrDest)
mp3	MP3 Trigger executor (destination config.mp3Dest)
wled	WLED executor — routed by the WLED id in the command
record / play / stop	Controller-local record & replay (see below)

NUM_MAESTRO_SLOTS = 8 and RC_NUM_MAESTROS = 8 — an action just references a slot; a disabled slot won't drive anything, and remote Maestro slots go out over ESP-NOW (no return path).

---

Record / Play / Stop (controller-local)

Record, Play, and Stop are NaviCore Controller library commands (controller-native) — 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. Untrusted input is shape-validated defensively before it's accepted.

---

WCB status extras

The library and Send-to dropdowns lean on 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.) is surfaced live-only in WCB_STATUS.temporary[]; the tool tags it · temp and hides its Forget button (there's nothing to forget — it ages out on its own). Absent on older firmware.

See WCB Network for the mesh model behind these.

---

Gotchas & caveats

• Delays run in parallel, not cumulative. Every action in a tier is dispatched 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.
• Legacy HCR/MP3 editors (the fn/chan/track fields) only appear for actions that were already saved that way. New HCR/MP3 actions are authored as library wire commands with auto-filled destinations from config.hcrDest / config.mp3Dest.
• 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). An already-saved value round-trips, and the fail-open window is rcConfig.maeGateMs (default 250 ms).
• Superseded boards (maestro, maestro-native) are hidden by design — don't reference them.
• Save from the top-bar Save (or the mapping Apply) to write the config to the board. The action shape on disk is documented 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