====== Node-RED Nodes ======

Custom Node-RED palette for controlling all Wonder Controlz ecosystem products. Provides visual, drag-and-drop nodes that integrate directly into the Node-RED flow editor — no HTTP requests or protocol knowledge needed.

**Status:** CAN I/O nodes — production. Audio nodes — production. Video, lighting, and RFID nodes — planned.

===== Overview =====

The Wonder Controlz node library covers two communication domains:

  * **CAN bus nodes** — for I/O modules ([[products:er-01-rev-a|er-01-rev-a]], [[products:er-rfid|er-rfid]])
  * **HTTP nodes** — for software products ([[products:er-audio|er-audio]], [[products:mpv-control|mpv-control]], [[products:er-lights|er-lights]])

Each domain has its own **config node** (CAN interface or HTTP server connection) shared by all device nodes in that family.

===== CAN Bus Nodes =====

For controlling I/O modules connected via CAN bus.

==== Config: CAN Interface ====

Configures the CAN bus connection (e.g., ''can0''). All CAN nodes reference this config.

==== Digital Input ====

Receives state change events from a digital input on an I/O module.

  * **Output:** ''msg.payload'' = ''true'' (closed) / ''false'' (open)
  * **Status indicator:** green dot (ON), grey ring (OFF)
  * **Configuration:** device ID + channel number

==== Digital Output ====

Sets a digital output on an I/O module.

  * **Input:** ''msg.payload'' = ''true'' / ''false''
  * **Status indicator:** reflects actual state (feedback from device)
  * **Configuration:** device ID + channel number

==== PWM Output ====

Sets a PWM output value (0–1000) on an I/O module.

  * **Input:** ''msg.payload'' = number (0–1000)
  * **Status indicator:** shows percentage
  * **Validation:** rejects out-of-range values
  * **Configuration:** device ID + channel number

==== Servo Output ====

Moves a servo to a target position with configurable ramp profile.

  * **Input:** ''msg.payload'' = number (0–1000) or object with ''targetValue'', ''rampTime'', ''rampType''
  * **Ramp profiles:** Linear, Smoothstep (5 levels of smoothing)
  * **Ramp time:** 0–25.5 seconds
  * **Configuration:** device ID + channel number + default ramp settings

==== USB HID ====

Receives keyboard and mouse events from a USB device connected to an I/O module.

  * **Output (keyboard):** ''msg.topic'' = ''"keyboard"'', ''msg.payload'' = key code + state (pressed/released)
  * **Output (mouse):** ''msg.topic'' = ''"mouse"'', ''msg.payload'' = buttons + X/Y delta
  * **Configuration:** device ID

===== Audio Nodes =====

For controlling [[products:er-audio|er-audio]] instances. See the [[products:er-audio#node-red_integration|er-audio Node-RED Integration]] section for full details.

==== Config: er-audio Server ====

Connection to an er-audio instance (host + port). Shared by all player nodes targeting the same machine.

==== Player ====

**One node = one audio track.** Each player node manages a single audio file on a specific output device.

  * **GUI configuration:** file and device dropdowns populated live from the er-audio API, volume and pan sliders, play mode (one-shot / loop)
  * **Auto Init:** automatically creates the player when the flow deploys or restarts
  * **Commands:** start, pause, stop, reset, status (via ''msg.payload'')
  * **Runtime overrides:** ''msg.volume'' and ''msg.pan'' adjust playback on the fly
  * **Built-in testing:** Start/Pause/Stop buttons in the editor panel — test without deploying
  * **Status indicator:** green (playing), yellow (paused), blue (ready), red (error)

===== Planned Nodes =====

^ Family ^ Nodes ^ Status ^
| Video (mpv-control) | Video command (load, play, pause, stop, loop) | Planned |
| Lighting (er-lights) | Animation, segment, scene control | Planned |
| RFID (er-rfid) | Tag reader events, reader power control | Planned |

→ **[[products:node-red-nodes-reference|Full node reference with configuration details and examples]]**

===== Design Principles =====

  * **Visual-first** — configure everything in the GUI, no coding required
  * **Status feedback** — color-coded indicators show device state at a glance
  * **Labels as topics** — each node can have a label that becomes ''msg.topic'' for downstream routing
  * **No software debounce** — hardware RC filters in the I/O modules handle this
  * **Independent transports** — CAN and HTTP nodes share common protocol definitions but operate independently