@nielseulink/node-red-contrib-buttonplus 1.0.0

Node-RED nodes for controlling Button+ devices via MQTT

npm install @nielseulink/node-red-contrib-buttonplus

🔘 Button+ nodes for Node-RED

Control Button+ devices from Node-RED over MQTT. Custom nodes with a shared config, configurable output properties, and optional debug output — replacing private subflows with a publishable npm package.

Table of contents

• Features
• Installation
  • npm
  • Node-RED palette manager
  • Local / development install
• Initial setup
• Nodes overview
• Output properties
• Message precedence
• MQTT topics
• Example flow
• Development
• Requirements
• Links

✨ Features

📦 Installation

npm

cd ~/.node-red
npm install @nielseulink/node-red-contrib-buttonplus

Restart Node-RED after installation.

Node-RED palette manager

After publishing to npm, search for buttonplus or @nielseulink/node-red-contrib-buttonplus in Manage palette → Install and restart Node-RED.

Local / development install

From a checkout of this repository:

cd ~/.node-red
npm install /path/to/buttonplus-nodered

Or install a packed tarball:

npm pack
cd ~/.node-red
npm install /path/to/nielseulink-node-red-contrib-buttonplus-1.0.0.tgz

Docker example (sync repo to the container mount, then):

docker exec -it NodeRed npm install --prefix /data --no-save /dev/buttonplus-nodered
docker restart NodeRed

See scripts/install-in-nodered.sh and scripts/sync-to-server.ps1.

🔧 Initial setup

1. Add or select an existing mqtt-broker config node (Node-RED built-in MQTT nodes).
2. Add a Button+ config node and link it to that broker.
3. Set Topic prefix (default buttonplus) and Device (e.g. buttonplus_1).
4. Drag nodes from the Button+ palette category and link each to the shared config node.
5. Deploy.

Each functional node can override page, button and other fields at runtime via msg properties.

📊 Nodes overview

Button+ click — input properties

Button+ LED / update button — shared LED fields

Same page, button, led, led_color, led_delay as above. LED node also supports led_brightness (0–100).

Button+ update button — label fields

Empty node configuration values are always published (as empty strings) to clear fields on the device.

Button+ update display — fields

Button+ update global — fields

Fields empty in both node config and msg are skipped (nothing published for that field).

🎛️ Output properties

All nodes support Output properties: map a destination msg field (left) to a source (right), similar to the Home Assistant Node-RED nodes.

Default behaviour

Click node — available sources

Tip: map payload + buttonplus for a practical default. Use button_page instead of msg.page so click output does not override page settings on other Button+ nodes.

Action nodes — debug source

Add a row such as msg.buttonplus_debug = debug info (input + mqtt sent) to attach:

{
  "input": { /* incoming msg snapshot */ },
  "mqtt": [
    { "topic": "...", "payload": "...", "qos": 0, "retain": false }
  ]
}

📐 Message precedence

For all nodes:

msg property → node configuration → fallback default

Explicit falsy values in msg (false, 0, "") are respected and are not replaced by defaults.

Device id is always taken from the linked Button+ config node, not from individual nodes.

📡 MQTT topics

With prefix buttonplus and device buttonplus_1:

LED none on update/click nodes runs the full off sequence on front and wall.

📋 Example flow

An example is included at examples/basic-flow.json.

After installation it also appears in Node-RED under:

Menu → Import → Import example flow → @nielseulink/node-red-contrib-buttonplus → basic-flow

The example demonstrates MQTT broker setup, shared config, LED pulse, and button click with debug nodes.

🛠️ Development

npm install
npm test
npm pack

Tests cover MQTT payload parsing, LED actions, topic building, resolve helpers, output properties and debug output.

Project layout:

✅ Requirements

No runtime npm dependencies — the package is self-contained.

🔗 Links

License

MIT — see LICENSE.