====== Node-RED Nodes — Reference ======

Detailed reference for all Wonder Controlz Node-RED nodes. For an overview, see the [[products:node-red-nodes|main Node-RED Nodes page]].

The nodes are distributed in two packages:
  * **node-red-nevo-er** — CAN bus nodes (I/O modules)
  * **node-red-er-audio** — audio nodes (bundled with er-audio)

----

===== CAN Bus Nodes (node-red-nevo-er) =====

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

Shared configuration node for the CAN bus connection.

^ Property ^ Default ^ Description ^
| Interface | can0 | CAN interface name (e.g., can0, can1) |

All CAN device nodes reference this config node. Multiple nodes can share the same interface.

----

==== Digital Input ====

**Type:** Input (no inputs, 1 output)\\
**Category:** function\\
**Palette label:** digital-in

Listens for state changes on a digital input channel of an I/O module.

**Configuration:**
^ Property ^ Description ^
| Name | Display name (optional) |
| Interface | CAN interface (from config node) |
| Device ID | CAN address of the target I/O module |
| Channel | Input channel number (starting from 0) |

**Output message:**
^ Field ^ Description ^
| ''msg.topic'' | Channel number |
| ''msg.payload'' | ''true'' (contact closed) or ''false'' (contact open) |

**Status indicator:** green dot = ON, grey ring = OFF, red ring = error.

----

==== Digital Output ====

**Type:** Output (1 input, no outputs)\\
**Category:** function\\
**Palette label:** digital-out

Sets a digital output on an I/O module.

**Configuration:**
^ Property ^ Description ^
| Name | Display name (optional) |
| Interface | CAN interface |
| Device ID | CAN address of the target I/O module |
| Channel | Output channel number (starting from 0) |

**Input message:**
^ Field ^ Type ^ Description ^
| ''msg.payload'' | boolean | ''true'' = ON, ''false'' = OFF. Non-boolean values are rejected. |

**Status indicator:** reflects actual state received as feedback from the device.

----

==== PWM Output ====

**Type:** Output (1 input, no outputs)\\
**Category:** function\\
**Palette label:** pwm-out

Sets a PWM output value on an I/O module.

**Configuration:**
^ Property ^ Description ^
| Name | Display name (optional) |
| Interface | CAN interface |
| Device ID | CAN address of the target I/O module |
| Channel | PWM channel number (starting from 0) |

**Input message:**
^ Field ^ Type ^ Range ^ Description ^
| ''msg.payload'' | number | 0–1000 | PWM value (0 = off, 1000 = full). Out-of-range values are rejected. |

**Status indicator:** shows percentage (e.g., "50%").

----

==== Servo Output ====

**Type:** Output (1 input, no outputs)\\
**Category:** function\\
**Palette label:** servo-out

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

**Configuration:**
^ Property ^ Default ^ Description ^
| Name | — | Display name (optional) |
| Interface | can0 | CAN interface |
| Device ID | — | CAN address of the target I/O module |
| Channel | — | Servo channel number (starting from 0) |
| Target | 500 | Default target position (0–1000) |
| Ramp Time | 0 | Default ramp duration (0–255, in 100 ms increments) |
| Ramp Type | 0 | Default profile: 0 = Linear, 1–5 = Smoothstep (increasing smoothness) |

**Input message — simple:**
^ Field ^ Type ^ Description ^
| ''msg.payload'' | number | Target position (0–1000). Uses default ramp settings. |

**Input message — advanced (object):**
<code javascript>
msg.payload = {
    targetValue: 750,   // position 0–1000
    rampTime: 15,       // 0–255 (×100 ms = 1.5 seconds)
    rampType: 3         // 0=Linear, 1–5=Smoothstep
};
</code>

All fields are optional — missing values fall back to the node's configured defaults.

----

==== USB HID ====

**Type:** Input (no inputs, 1 output)\\
**Category:** function\\
**Palette label:** usb

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

**Configuration:**
^ Property ^ Description ^
| Name | Display name (optional) |
| Interface | CAN interface |
| Device ID | CAN address of the target I/O module |

**Output — keyboard event:**
<code javascript>
{
    topic: "keyboard",
    payload: {
        keyCode: 65,    // ASCII key code
        state: 1        // 1 = pressed, 0 = released
    }
}
</code>

**Output — mouse event:**
<code javascript>
{
    topic: "mouse",
    payload: {
        buttons: 1,     // button bitmask
        x: 10,          // X delta (-128 to +127)
        y: -5           // Y delta (-128 to +127)
    }
}
</code>

----

===== Audio Nodes (node-red-er-audio) =====

Bundled with the [[products:er-audio|er-audio]] project. Pre-installed on devices delivered with er-audio. The **ER-Audio** category appears in the Node-RED palette.

----

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

Shared connection to an er-audio instance.

^ Property ^ Default ^ Description ^
| Name | — | Configuration name (optional) |
| Host | localhost | Hostname or IP of the er-audio server |
| Port | 8080 | API port |

If er-audio runs on the same [[main_pc|Main PC]], use ''localhost''. For a dedicated audio machine, use its LAN IP.

----

==== Player ====

**Type:** Input/Output (1 input, 1 output)\\
**Category:** ER-Audio\\
**Palette label:** player\\
**Icon:** music note

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

**Configuration:**
^ Property ^ Default ^ Description ^
| Name | (filename) | Display name |
| Server | — | er-audio server connection (config node) |
| File | — | Audio file — dropdown populated live from er-audio media directory |
| Device | hw:0,0 | Audio output — dropdown populated live from detected interfaces |
| Volume | 1.0 | Initial volume (slider 0.0–1.0) |
| Pan | 0.0 | Stereo panning (slider: L ← C → R) |
| Mode | One Shot | ''One Shot'' (play once) or ''Loop'' (repeat) |
| Auto Init | checked | Automatically create the player when the flow deploys |

**Commands** — send as ''msg.payload'' or ''msg.command'':

^ Command ^ Description ^
| ''start'' / ''play'' | Start playback. Auto-initializes if player doesn't exist yet. |
| ''pause'' | Pause (resume with start). |
| ''stop'' | Stop and reset to beginning. |
| ''reset'' / ''reinit'' | Destroy and recreate the player. Use on game reset. |
| ''status'' | Query current state from API. |

**Runtime overrides** — send alongside any command:

^ Field ^ Type ^ Description ^
| ''msg.volume'' | number (0.0–1.0) | Adjust volume on the fly during playback |
| ''msg.pan'' | number (-1.0–1.0) | Adjust stereo panning on the fly |

**Output message:**
^ Field ^ Description ^
| ''msg.payload'' | API response (player status object) |
| ''msg.playerId'' | Player identifier |
| ''msg.state'' | Current state: ''playing'', ''paused'', ''stopped'', ''ready'' |

**Status indicators:**
^ Color ^ State ^
| Grey ring | Idle (not initialized) |
| Yellow dot | Initializing |
| Blue dot | Ready |
| Green dot | Playing |
| Yellow dot | Paused |
| Blue ring | Stopped |
| Red ring | Error |

**Built-in testing in the editor:**

The node's edit panel includes **Start**, **Pause**, and **Stop** buttons for immediate playback testing without deploying the flow. Volume and pan can be adjusted live during testing. The test player is automatically cleaned up when the panel is closed or saved.

**Lifecycle:**
  * On **deploy/restart** (with Auto Init enabled): player is automatically created in er-audio with the configured file, device, volume, and pan
  * On **node deletion**: player is removed from er-audio
  * On **redeploy**: player is reinitialized with current settings

----

===== Usage Examples =====

==== Simple trigger ====
<code>
[Inject: "start"] → [er-audio-player]
</code>

==== Game reset (escape room) ====
<code>
[Game Reset trigger] → [Function: msg.payload="reset"] → [player: ambience]
                     → [Function: msg.payload="reset"] → [player: music]
                     → [Function: msg.payload="reset"] → [player: effects]
</code>

==== Dynamic volume from dashboard ====
<code>
[Dashboard Slider 0-100] → [Function: msg.volume = msg.payload/100; msg.payload="start"] → [player]
</code>

==== Multiple audio zones ====
<code>
[Trigger Zone A] → [player: Device=hw:0,0]
[Trigger Zone B] → [player: Device=hw:1,0]
[Trigger Zone C] → [player: Device=hw:2,0]
</code>