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
