node-red-contrib-iobroker 0.12.0
Node-RED nodes for ioBroker integration via WebSocket. Provides input, output, get, object management, historical data access, and live log monitoring capabilities.
Node-RED Nodes for ioBroker Integration
π Languages: πΊπΈ English | π©πͺ Deutsch
External Node-RED integration nodes for ioBroker communication. NOT an ioBroker adapter - standalone package for external Node-RED instances to connect with ioBroker via WebSocket.
π Quick Start
Installation
Install the nodes through the Node-RED Palette Manager:
- Open Node-RED interface
- Click on hamburger menu (three lines) β Manage palette
- Go to "Install" tab
- Search for "node-red-contrib-iobroker"
- Click "Install" button
Basic Setup
- Create dedicated Admin adapter instance (recommended):
- Install second Admin adapter instance in ioBroker
- Configure on different port (e.g., 8091)
- Use exclusively for Node-RED connections
- Configure iob-config node with your dedicated instance:
- Host: hostname or IP address
- Port: 8091 (your dedicated Admin instance)
- Authentication: Optional username/password
- Use the nodes in your flows
ποΈ Architecture Overview
The diagram shows the recommended architecture with a dedicated Admin adapter instance for Node-RED connections, separate from the main Admin interface used by regular users.
π¦ Available Nodes
Node | Purpose | Example Use | Documentation |
---|---|---|---|
WS ioB in | Subscribe to state changes | Monitor temperature sensors | π Details |
WS ioB out | Send values to states with auto-creation | Control lights, switches | π Details |
WS ioB get | Read current state values | Get sensor readings on demand | π Details |
WS ioB getObj | Retrieve object definitions with enum assignments | Access device metadata with room/function info | π Details |
WS ioB inObj | Monitor object changes | Track adapter installations | π Details |
WS ioB history | Access historical data | Energy consumption analysis | π Details |
WS ioB log | Live log monitoring | System health monitoring | π Details |
WS ioB sendTo | Send commands to ioBroker adapters | Telegram notifications, database queries | π Details |
π§ Configuration
Recommended Setup: Dedicated Admin Instance
Why use a dedicated Admin instance?
- Isolates Node-RED traffic from main admin interface
- Prevents conflicts with regular admin usage
- Avoids duplicate events when the Admin interface is open in browser
- Allows custom security settings
Setup Steps:
- Install second Admin adapter instance in ioBroker:
- Go to Adapters β Admin β Add Instance
- Configure custom port (e.g., 8091)
- Enable/disable features as needed
- Configure security for Node-RED access:
- Create dedicated user for Node-RED
- Set appropriate permissions
- Configure session duration β₯3600 seconds
Server Configuration (iob-config)
Connection Settings:
- Name: Descriptive name for your ioBroker instance
- Host: IP address (e.g., 192.168.1.100) or hostname (e.g., iobroker.local)
- Port: Your dedicated Admin instance port (e.g., 8091)
- Use SSL: Enable for HTTPS/WSS connections
Authentication Settings:
- No Authentication (default): Leave username/password empty
- OAuth2: Enter valid ioBroker username/password
Alternative Adapter Options
If you prefer not to use a dedicated Admin instance:
- WebSocket adapter (port 8084) - Dedicated WebSocket adapter for external connections
- Web adapter (port 8082) - Requires "Use pure web-sockets" option enabled
β οΈ Important Limitations with Alternative Adapters:
- WS ioB log node does not work with WebSocket or Web adapters (requires Admin adapter)
- WS ioB getObj node is limited to state, channel, and device object types only
β¨ Features
- Real-time WebSocket communication with automatic reconnection
- Wildcard pattern support - subscribe to multiple states at once
- Automatic object creation for missing ioBroker objects
- Shared connection management - multiple nodes share connections
- Historical data access from History adapters (History, SQL, InfluxDB)
- OAuth2 authentication for secured installations
- SSL/TLS support for encrypted connections
β οΈ Important Notes
π‘ For simpler installation: In most cases, it's easier to use the ioBroker Node-RED adapter if you prefer a straightforward setup.
π§ Known Issue - Authentication Token Expiry: There is currently a known issue with authentication and expiring tokens that can cause connection drops. Do not use login session durations shorter than 3600 seconds (1 hour) in your ioBroker adapter settings!
π Additional Resources
- π Release Notes: Changelog
- π Troubleshooting: Troubleshooting Guide
- π― Use Cases: Common Use Cases
- π Full Documentation: GitHub Repository
- π Bug Reports: GitHub Issues
- π ioBroker Forum: ioBroker.net
π License
MIT