Actions Reference

Actions Reference

An action is one thing NaviCore does when a button is tapped or a switch changes. Each button tap‑tier (single/double/triple) and each switch position holds up to 5 actions, and every action can carry an optional delay (ms, fired after the press) and a short note (label shown in the tool).

NaviCore dispatches about ten action types, grouped below. You don't type raw strings — each action is authored in the tool's Action Editor by picking from a shared Command Library. See Action Editor and Command Library.

---

WCB unicast

Send a WCB command string to one board.

• Target: WCB board ID 1–20
• Command: any WCB command string, e.g. :PP100
• Chained commands are supported (e.g. ;h,play,a,1,fadein,4^;t6000^;h,fadeout,a,4) up to ~95 characters.

WCB broadcast

Same, but sent to every WCB on the network (no target).

---

Maestro

Drive a Pololu Maestro servo controller. Maestros are addressed by logical slot 1–8; where each slot actually lives is set in Config → Maestro (Locations):

• Local — wired to this board's Serial2 bus (GPIO6).
• Remote — broadcast over ESP‑NOW; any WCB with Kyber_Remote forwards the bytes to its Maestro port.
• Disabled — slot ignored.

Each slot also has a Pololu device number, which must match the number set in Maestro Control Center on the physical unit. NaviCore drives Pololu-protocol device numbers 0–127 only, so multiple Maestros can share a bus and only the addressed device responds. (A compact-protocol selection — device 255 — is silently skipped by the firmware.)

Command forms:

Command	Meaning
setTarget,<ch>,<pos>	Move servo channel to position (quarter‑µs)
setSpeed,<ch>,<spd>	Set channel speed
setAccel,<ch>,<acc>	Set channel acceleration
setSpeedAccel,<ch>,<spd>,<acc>	Set channel speed and acceleration in one action
goHome	Send all channels to their home positions
stopScript	Stop the running Maestro script
restartScript,<n>[,pN][,o]	Restart the script at subroutine n. Optional pN applies the action's own easing profile; o lets the switch's active easing override it
subParam,<sub>,<param>	Restart at subroutine sub with a param (0–16383) pushed onto the Maestro's script stack (Pololu 0x28 — the tool's "Run subroutine + parameter")

Easing profiles referenced by pN are configured in Maestro Setup. NaviCore can also read a Maestro back (getPosition / getMovingState / getErrors); this two-way query powers the "skip if already running" gate on Maestro actions.

---

HCR (Human‑Cyborg Relations vocalizer)

Fire an HCR vocalizer command. The destination is global — set once in Config → Audio → HCR Vocalizer, every HCR action shares it:

• Serial — local port S3, S4, or S5 (9600 baud typical).
• WCB — unicast to a WCB ID 1–20. The vocalizer's serial port is configured on that WCB (via ?HCR,PORT); NaviCore doesn't send it. (HCR over WCB is unicast only — broadcast isn't supported.)

Each HCR action carries a function, an emotion/audio channel, and a track/value:

fn	Function	chan	track/value
2	SetEmotion	0–3 emotion	level 0–99
3	Trigger	0–3 emotion	level 0–99
4	Stimulate	0–3 emotion	level 0–99
5	Overload	—	—
6	Muse (one shot)	—	—
7	Muse gap (auto interval)	min gap 0–99 s	max gap 0–99 s
8	Stop (all audio + emote)	—	—
9	StopEmote	—	—
10	Override emotions	0 = off / 1 = on	—
11	ResetEmotions	—	—
12	FadeIn	1 = A, 2 = B	seconds
13	Auto-muse (continuous)	—	0 = off / 1 = on
14	PlayWAV	0–2 audio	track 0–9999
15	FadeOut	1 = A, 2 = B	seconds
16	StopWAV	0–2 audio	—
17	SetVolume	0–2 audio	0–99
18	Volume Up	0 = ALL, 1 = V, 2 = A, 3 = B	step (0 → 5)
19	Volume Down	0 = ALL, 1 = V, 2 = A, 3 = B	step (0 → 5)

• Emotion channels: 0 = Happy, 1 = Sad, 2 = Mad, 3 = Scared. (Overload isn't a channel — fire it with fn 5; a chan‑4 action is rejected.)
• Audio channels: 0 = V (vocalizer), 1 = A, 2 = B.
• Override emotions (fn 10): locks the brain's emotion normalization so a SetEmotion level holds instead of decaying back to baseline. Turn it off to resume normal decay.
• Muse (fn 6 / 7 / 13): fn 6 plays a single muse now; fn 13 turns the brain's continuous random idle musing on/off; fn 7 sets the random gap (min–max seconds) between auto-muses.
• Fade (fn 12 / 15): ramps one audio channel's volume up (from 0) or down (to 0) over track seconds. Channels A (1) and B (2) only — the vocalizer V channel isn't faded. NaviCore runs the ramp non-blocking whether the HCR is local or over WCB.
• Volume Up / Down (fn 18 / 19): nudges volume by track steps (0 = the default step of 5). Note the channel encoding 0 = ALL, 1 = V, 2 = A, 3 = B here deliberately differs from the 0 = V audio enum used by PlayWAV / StopWAV / SetVolume — legacy Volume actions carried chan 0 meaning all channels.

These match the Body Controller's HCR function numbers exactly. Over WCB, the functions that map to a readable WCB verb — fn 7/10/13 (;H,MUSE,GAP / ;H,OVERRIDE / ;H,MUSE) and the Fade/Volume functions 12/15/18/19 (;H,FADEIN / ;H,FADEOUT / ;H,VOLUP / ;H,VOLDN) — are sent that way, so no WCB firmware change is needed; the rest use ;H,FN,….

Diagnostic: CLI #L20 / #L21 send a test HCR command straight to S3 / S4, bypassing config and mapping — handy for isolating wiring vs. config issues. See CLI Commands.

---

MP3 Trigger (SparkFun v2.x)

Fire an MP3 Trigger. The destination is global — set once in Config → Audio → MP3 Trigger:

• WCB — unicast a ;A,… command to a WCB ID 1–20 whose own MP3 driver does the serial work (configured there with ?MP3,S<port>).
• Serial — local port S3/S4/S5; NaviCore speaks the MP3 Trigger v2 protocol directly (set the port to 38400 baud).

fn	Function	arg
PLAY	Play track	1–255
PLAYFS	Play by file index	0–255
STOP	Start/stop toggle	—
NEXT	Next track	—
PREV	Previous track	—
VOL	Set volume	0 = loudest … 64 = inaudible
VOLUP	Volume up	—
VOLDN	Volume down	—

---

DFPlayer Mini

Fire a DFPlayer Mini (DFRobot, or one of the YX5300 / MH2024K clones) — the other sound board NaviCore can drive. The destination is global — set once in Config → Audio → DFPlayer Mini:

• Serial — local port S3/S4/S5; NaviCore speaks the DFPlayer's own protocol directly. Set that port to 9600 baud — the module supports nothing else, and the tool warns if it doesn't match.
• WCB — unicast a ;D,… command to a WCB ID 1–20 whose own DFPlayer driver does the serial work (configured there with ?DFP,S<port>).

You can run a DFPlayer and an MP3 Trigger at the same time, on different ports. They are separate action types.

fn	Function	args
Play track	Play by global index	1–2999
Play folder/track	Play /<folder>/<track>.mp3	folder 1–99, track 1–255
Play /MP3 folder	Play from the reserved /MP3 folder	1–9999
Stop	Stop playback	—
Next / Previous	Skip forward / back	—
Pause / Resume	Pause and resume	—
Set volume	0 = silent … 30 = loudest	0–30
Volume up / down	Step by 2	—
Loop track	Repeat one track forever	1–2999
Loop all	Loop the whole card	Off / On
Loop folder	Loop one folder	1–99
Random	Play a random track	—
Set EQ	Normal / Pop / Rock / Jazz / Classic / Bass	—
Select device	USB / SD card / AUX / Sleep / Flash	—
Reset module	Reset the DFPlayer	—

The volume scale is backwards from the MP3 Trigger's. A DFPlayer uses 0 = silent, 30 = loudest; an MP3 Trigger uses 0 = loudest, 64 = inaudible. Never copy a volume number from one to the other.

A DFPlayer ignores commands for ~1.5–3 seconds after power-on. If you want sound at boot, give the action a delay of at least 3000 ms — otherwise it is silently dropped.

Organise the SD card as /01/001.mp3, /01/002.mp3, … and use Play folder/track. It is the only addressing mode that stays stable when you add files later — Play track uses the card's internal write order, which reshuffles.

Clone modules vary. Random, Set EQ and Loop folder do nothing on some of them; everything else is reliable.

---

Serial

Write a raw command string to an aux serial port.

• Port: S3, S4, or S5 (set its baud in Config → Aux Serial).
• Command: any string; the dispatcher appends a carriage return.

The stored value is always S3/S4/S5, but the board silkscreen differs: the NaviCore v2 PCB labels these Serial 1/2/3, while WCB 3.2 uses the Serial 3/4/5 headers. On WCB 3.2, S5 rides the Serial 5 header (GPIO9/10). HCR, MP3, and WLED actions can target S5 as well.

---

WLED

Fire a lighting command at a WLED controller. The command is a ;L<id>,<verb> string authored in the Command Library — e.g. ;L1,ON or ;L2,PS,3. The id (1–9) selects a slot in the global WLED routing table (Config → WLED); each id routes independently:

• Local — a WLED wired to this board's aux port S3/S4/S5. NaviCore emits byte-identical JSON to what a WCB would send, so a locally-wired strip behaves the same.
• Remote — forwarded over the WCB network to a WCB ID 1–20, whose own router drives its WLED.

A bare ;L,<verb> (id 0) acts on the lowest-id local WLED slot. See WLED and HCR Audio for verbs and the routing table.

---

Record & Replay

Capture a live control session and play it back. Three action types drive it:

Type	Meaning
Record	Toggle recording on/off. An optional clip name is stored for the clip library.
Play	Load and play a clip; a loop flag replays it continuously (off = once). Press again to stop.
Stop	Explicit halt — saves an in-progress recording, or stops playback.

Record / Play / Stop all defer to the main loop, so triggering one remotely (over WCB) is safe. See Record and Replay.

---

Delays & sequencing

Any action can carry a delay (ms). Delayed actions are queued (up to 8 pending) and fired when their timer elapses — so you can build short sequences within one button, e.g. play a sound now, move a servo 600 ms later.

---

See also: Action Editor and Command Library · Maestro Setup · WLED and HCR Audio · Record and Replay · WCB Network