node-red-contrib-nhc2 1.28.3

Node-RED nodes for Niko Home Control 2 via MQTT

npm install node-red-contrib-nhc2

node-red-contrib-nhc2

Node-RED nodes for Niko Home Control 2 via MQTT (Hobby API). Control and monitor your NHC2 system directly from Node-RED.

Table of Contents

1. Features
2. Prerequisites
3. Installation
4. Usage
   • NHC2 Config Node
   • NHC2 Input Node
   • NHC2 Output Node
   • NHC2 Hue Mapping Node
5. Examples
6. Changelog
7. Contributing
8. License

Features

• Automatic discovery of NHC2 controllers on your network
• Secure MQTT(S) communication with optional reconnect watchdog
• Real-time event listening (status, brightness, etc.)
• Control individual devices or multiple properties
• Integration-ready for Home Assistant and other home automation platforms
• Hue Mapping: Convert NHC2 values to HueMagic payloads for Philips Hue integration
• (New) Optional duplicate output with base + random jitter (for reliability with picky bridges)

Prerequisites

• Node.js ≥ 16.0.0
• Node-RED ≥ 3.1.0
• Niko Home Control 2 with the Hobby API enabled

Installation

cd ~/.node-red
npm install node-red-contrib-nhc2

Restart Node-RED to load the new nodes.

Usage

NHC2 Config Node

Configure your connection to the NHC2 controller.

Settings:

• Host: IP address of the controller (e.g. 192.168.0.202)
• Port: MQTT port (8884 by default for MQTT(S))
• Auto Discover: Enable UDP-based discovery of controllers
• Select Controller (MAC): Choose from discovered controllers
• Username: MQTT topic prefix (default hobby)
• Password: Hobby API password from NHC2 programming software
• Debug: Enable verbose logging output
• Watchdog: Listen for a keep-alive message every 30 s to reset the reconnect timer
• Only send on change: Default for all Output nodes set to Use server setting — skip a command when the value equals the device's last known state (default off)
• Refresh Devices: Manually refresh the device list

NHC2 Input Node

Listen for events emitted by your NHC2 devices.

• Inputs: None
• Outputs: 1

Configuration:

• Config: Select your NHC2 Config node
• All devices: Forward events from every device in the installation (msg.topic = device name). Must be ticked explicitly — a node without a device and without this option does nothing.
• Device Filter: Filter devices by name/model/type
• Device: Select a specific device (UUID)
• Property: Choose a property (Status, Brightness, etc.) or All

Status: red device missing: <name> / no device selected means the node has no device and is inactive; red device not found in NHC2 means the selected device is not in the controller's device list (renamed or removed in the programming). A device that is missing stays selected in the editor as "⚠ … (missing in NHC2)", so saving the dialog doesn't change it.

Output Message:

msg.topic    // Device Name
msg.payload  // Value of the selected property or object of all properties
msg.device   // Full device object returned by the controller

Start-up state: on every (re)connect the node sends the device's current state once, with msg.initial = true. For colour+white lights only the active colour property is included: TunableWhite when ColorMode is TunableWhite, Color when it is Color. The other value is an old stored setting and is left out.

NHC2 Output Node

Send control commands to your NHC2 devices.

• Inputs: 1
• Outputs: 0

Configuration:

• Config: Select your NHC2 Config node
• Device Filter: Filter and select devices
• Device: Choose a device to control
• Property: Property to set (e.g. Status, leave blank for multiple)
• On change: Use server setting (default), Only send on change or Always send. With only-on-change, properties whose value equals the device's last known state are dropped (numbers compared numerically, text case-insensitively, so false matches False); if nothing is left, no command is sent. Momentary commands (Action, Control, value Triggered) are always sent.

Use Only send on change when a flow re-sends the same value periodically (e.g. a sensor that reports every few seconds). The Hobby API rate-limits each client, and every write — even an unchanged one — makes the controller re-evaluate everything that depends on the device.

Input Message Requirements:

• If Property is set: msg.payload must be the value (e.g. true, "On", an integer)
• If Property is blank: msg.payload must be an object { PropertyName: value } or an array of such objects

NHC2 Hue Mapping Node

Maps NHC2 / HA-like payloads to Hue-friendly objects.

Inputs / Outputs

• Inputs: 1
• Outputs: 1

Editor settings

• Number input maps to: brightness | tunable white | color hue
• Accept color-frames as input (default OFF) — accepts {rgb:[r,g,b]}, {r,g,b}, {h,s,v}/{hue,sat,val}, {kelvin}, {mireds}
• Color input may change brightness (default OFF) — when OFF, color never changes brightness
• Auto-include CT when in white mode (default ON) — always emits last CT so Hue leaves colour mode
• Map Kelvin range to full Hue CT span (153–500) (default ON) — minKelvin → 500, maxKelvin → 153
• CT range (Kelvin): minKelvin, maxKelvin
• Listen ColorMode (default ON) — obey { ColorMode:"TunableWhite"|"Color" } or { mode:"white"|"colour" }
• Quiet status
• Duplicate output (send twice) (default OFF) — sends once immediately and again after base + random(0..jitter) ms
  • Base delay (ms) (default 200)
  • Jitter max (ms) (default 100)

Behavior

• On/Off: boolean, {switch:true|false}, or { Status:"On"|"Off" } → { on:… }
• Brightness: {Brightness:"62"} / {brightness:62} → { brightness:62 } (sticky until changed)
• Tunable White:
  • {TunableWhite:"cwww(k, x)"} → colorTemp from k; x is ignored for brightness
  • {temperature: 0..100} → mapped across [minKelvin..maxKelvin], then converted to Hue mireds
  • {kelvin:k} / {mireds:m} (when color-frames enabled)
  • Output always uses colorTemp (mireds), clamped 153–500
  • If Map Kelvin range… is ON: minKelvin → 500, maxKelvin → 153 linearly
• Color: {Color:"hsv(h,s,v)"} or {Color:"rgb(r,g,b)"} → { rgb:[r,g,b] }
  • By default, no brightness included; turn on Color input may change brightness to let HSV/V set it
• Mode switching: { ColorMode:"TunableWhite" } (or { mode:"white" }) → emits latest colorTemp so Hue leaves colour mode; brightness sticks
• Duplicate output (optional): if enabled, node label/status shows x2 and a second message is emitted.

Single integer input (0–100)

Selectable via Number input maps to:

• Brightness (default): 42 → { "brightness": 42, "on": true }
• Tunable white: 42 → colorTemp mapped from 42% of [minKelvin..maxKelvin] → mireds (clamped 153–500)
• Color hue: 42 → hue≈42*3.6°, RGB from HSV(h,100%,V=last_brightness) → { "rgb":[r,g,b] }

Per-message overrides

msg.delayMsBase   // number (ms) — overrides Base delay (default 200)
msg.delayMsJitter // number (ms) — overrides Jitter max (default 100)

Examples

// Sticky brightness
{ "Brightness":"37" }                  // → { "brightness": 37, "on": true }
{ "TunableWhite":"cwww(2700, 100)" }   // → { "colorTemp": 500, "on": true } // if map-to-full ON & minK=2700

// Percent temperature across your K-range
{ "temperature": 50 }                  // → colorTemp from 50% of [minKelvin..maxKelvin] → mireds (153–500)

// Explicit Kelvin
{ "kelvin": 6500 }                     // → { "colorTemp": 153 }  // with map-to-full ON and maxK=6500

// Color
{ "Color": "hsv(241,100,100)" }        // → { "rgb": [..,..,..], "on": true }  // no brightness unless option enabled

ℹ️ Outputs never include a color alias or colorTempKelvin; use rgb and colorTemp only.

Examples

In Node-RED: Import → Examples → node-red-contrib-nhc2. Each example opens in its own tab with a comment node that explains it. After importing, enter the Hobby API password (token) in the NHC2 controller config node (the controller is found automatically), select your NHC devices in the nhc2 nodes and - where used - your Home Assistant entities.

The examples contain no addresses, passwords or device ids. They share one NHC2 controller and one Home Assistant server config node, so importing several of them reuses those.

Changelog

For the full changelog, see CHANGELOG.md.

Version 1.22.0 (2025-11-10)

Highlights

• Optional duplicate output (“send twice”) with base + random jitter — default OFF
• New delay controls (Base delay, Jitter max) with per-message overrides
• Editor UX: clearer inline explanations for every setting + expanded Help
• Robustness: timers cleared on redeploy; status shows “x2” when duplicate is active

New

• Duplicate output (send twice): immediate send + second send after base + random(0..jitter) ms
  • Editor options: Duplicate output, Base delay (ms), Jitter max (ms)
  • Per-message overrides: msg.delayMsBase, msg.delayMsJitter
  • Node label and status append x2 when enabled
• Listen to ColorMode explicitly exposed in the editor with guidance (defaults ON)

Improvements

• Editor copy: concise hints under each control (mode, color frames, CT mapping, etc.)
• Help panel: expanded with clear I/O examples, behavior notes, and override fields
• Status text: now reflects duplicate state (x2) alongside mode/brightness/CT/RGB
• Lifecycle: cleans up any pending duplicate timers on node close/redeploy

Fixes

• RGB→HSV conversion: corrected min/max handling to avoid rare hue errors

Compatibility

• Duplicate feature is OFF by default; existing nodes keep their saved settings
• When enabling duplicates, ensure downstream flows are idempotent

Developer Notes

• Per-message CT range overrides remain: msg.minKelvin, msg.maxKelvin
• Brightness stickiness and color→brightness interaction unchanged (configurable)

Contributing

Contributions, issues, and feature requests are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT © Peter Løbner — Niko Home Control 2