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
• 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
• Device Filter: Filter devices by name/model/type
• Device: Select a specific device (UUID)
• Property: Choose a property (Status, Brightness, etc.) or All

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

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)

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

Import examples/usage_example.json into Node-RED to see a complete demo flow.

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