node-red-contrib-iobroker 1.0.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.
🤔 Which Solution is Right for You?
📊 Decision Guide: ioBroker Node-RED Adapter vs. These Nodes
| Scenario | Use ioBroker Node-RED Adapter | Use These External Nodes |
|---|---|---|
| 🏠 Simple Home Setup | ✅ Recommended | ❌ Overkill |
| 🏭 Installation on Appliances/PLCs | ❌ Not possible | ✅ Recommended |
| ⚡ High Performance Needs | ❌ Shared resources | ⚠️ May be beneficial |
| 🔄 Node-RED Updates/Maintenance | ❌ Tied to ioBroker | ✅ Recommended |
| 📊 Advanced Features | ❌ Limited | ✅ Recommended |
🎯 Use ioBroker Node-RED Adapter for:
- Simple home automation with basic requirements
- One-click installation is priority
- Minimal configuration effort desired
- Shared hosting is acceptable
🚀 Use These External Nodes for:
- Appliances and PLCs (Wago, Beckhoff, etc.) with Node-RED
- High-performance applications (may benefit from dedicated resources)
- Specialized features like history data, logs
- Latest Node-RED versions immediately (no adapter dependency)
- Full Node-RED configuration access (all settings & modules)
- Dedicated resources and potential for better error isolation
🚀 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 Admin instance:
- WebSocket adapter (port 8084) - 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 adapter (requires Admin adapter)
⚠️ Important Notes
🔧 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
- 📊 Logging: Logging Guide - Understanding log messages and troubleshooting
- 🎯 Use Cases: Common Use Cases
- 📖 Full Documentation: GitHub Repository
- 🐛 Bug Reports: GitHub Issues
- 📘 ioBroker Forum: ioBroker.net
📄 License
MIT
