261 lines
7.7 KiB
Markdown
261 lines
7.7 KiB
Markdown
# MQTT Bridge WIP
|
|
|
|
**Version:** 0.5.0-1
|
|
**Status:** Production Ready
|
|
**Last Updated:** 2025-12-30
|
|
|
|
---
|
|
|
|
## ✅ Completed (v0.5.0)
|
|
|
|
### Backend Implementation
|
|
- ✅ **USB Detection Library** (`/usr/share/mqtt-bridge/usb-database.sh`)
|
|
- VID:PID database with 17 known USB IoT devices
|
|
- Support for 4 adapter types: Zigbee (6), Z-Wave (3), ModBus (4), Serial (4)
|
|
- Functions: `detect_adapter_type()`, `find_usb_tty()`, `test_serial_port()`, `get_device_name()`
|
|
|
|
- ✅ **Enhanced RPCD Backend** (`/usr/libexec/rpcd/luci.mqtt-bridge`)
|
|
- 7 new USB RPC methods:
|
|
- `get_usb_devices` - List all USB devices
|
|
- `detect_iot_adapters` - Detect Zigbee/Z-Wave/ModBus adapters
|
|
- `get_serial_ports` - List serial ports with attributes
|
|
- `get_adapter_info` - Get adapter details by ID
|
|
- `test_connection` - Test serial port accessibility
|
|
- `configure_adapter` - Create/update UCI adapter config
|
|
- `get_adapter_status` - Real-time health monitoring
|
|
|
|
- ✅ **UCI Configuration** (`/etc/config/mqtt-bridge`)
|
|
- Broker settings (host, port, credentials)
|
|
- Bridge configuration (topics, retention, auto-discovery)
|
|
- Monitor section (USB scan interval, auto-configure)
|
|
- Adapter sections (per-device configuration with health tracking)
|
|
|
|
### Frontend Implementation
|
|
- ✅ **API Module** (`mqtt-bridge/api.js`)
|
|
- All 7 USB RPC methods exposed
|
|
- Promise-based API for USB detection and configuration
|
|
|
|
- ✅ **Overview View** (`overview.js`)
|
|
- MQTT broker connection status
|
|
- USB adapter statistics by type
|
|
- Health status summary (online/error/missing/unknown)
|
|
- Quick actions (scan USB, reconnect broker)
|
|
|
|
- ✅ **Adapters View** (`adapters.js`)
|
|
- Configured adapters grid with status cards
|
|
- Detected devices section (real-time USB scanning)
|
|
- Import wizard (one-click import from detected to configured)
|
|
- Adapter management (test, configure, remove)
|
|
- Color-coded health indicators
|
|
|
|
### Theme Integration
|
|
- ✅ **SecuBox Theme System**
|
|
- Both views use `secubox-theme/theme.js`
|
|
- Theme.init() initialization
|
|
- CSS variables (--sh-* prefix)
|
|
- Dark/Light/Cyberpunk theme support
|
|
- Responsive design
|
|
|
|
### Documentation
|
|
- ✅ **Comprehensive README.md** (679 lines)
|
|
- Feature overview with all 17 supported devices
|
|
- Complete API reference with examples
|
|
- UCI configuration guide
|
|
- Troubleshooting section
|
|
- Integration examples (Home Assistant, Zigbee2MQTT, Node-RED)
|
|
- Development guide
|
|
|
|
- ✅ **Updated module-status.md**
|
|
- Added MQTT Bridge as IoT & Integration category
|
|
- Updated totals (16 modules, 112 views, 288 RPC methods)
|
|
- Version history and feature list
|
|
|
|
### Menu & ACL
|
|
- ✅ **Menu Configuration** (`menu.d/luci-app-mqtt-bridge.json`)
|
|
- SecuBox → Network → MQTT IoT Bridge
|
|
- Overview and Adapters submenu items
|
|
|
|
- ✅ **ACL Configuration** (`acl.d/luci-app-mqtt-bridge.json`)
|
|
- Read permissions for all USB detection methods
|
|
- Write permissions for configuration methods
|
|
|
|
---
|
|
|
|
## 🔄 In Progress
|
|
|
|
### Testing & Validation
|
|
- ⏳ Run `./secubox-tools/validate-modules.sh`
|
|
- ⏳ Fix any permission issues with `./secubox-tools/fix-permissions.sh`
|
|
- ⏳ Local build testing with `./secubox-tools/local-build.sh`
|
|
- ⏳ Deploy to test router and verify USB detection
|
|
|
|
### Hardware Testing
|
|
- ⏳ Test with physical Zigbee adapter (CC2531 or ConBee II)
|
|
- ⏳ Test with Z-Wave stick (Aeotec Z-Stick)
|
|
- ⏳ Test with ModBus RTU adapter (FTDI FT232)
|
|
- ⏳ Verify auto-detection and health monitoring
|
|
|
|
---
|
|
|
|
## 📋 Backlog / Future Enhancements
|
|
|
|
### Priority 1 - Core Functionality
|
|
- [ ] MQTT broker connection implementation
|
|
- Connect to broker using mosquitto client library
|
|
- Publish/subscribe to topics
|
|
- Message buffering and retry logic
|
|
|
|
- [ ] Device pairing workflow
|
|
- Zigbee permit join integration
|
|
- Z-Wave inclusion/exclusion
|
|
- ModBus slave discovery
|
|
|
|
- [ ] Message routing
|
|
- Topic templates per adapter type
|
|
- Payload transformation (JSON/binary)
|
|
- Device state caching
|
|
|
|
### Priority 2 - Advanced Features
|
|
- [ ] Automation rules engine
|
|
- Trigger on adapter health changes
|
|
- Alert notifications (email/SMS)
|
|
- Custom scripts on events
|
|
|
|
- [ ] Historical data storage
|
|
- Message logging to SQLite
|
|
- Statistics and analytics
|
|
- Export to CSV/JSON
|
|
|
|
- [ ] Multi-broker support
|
|
- Connect to multiple MQTT brokers
|
|
- Bridge between brokers
|
|
- Failover and redundancy
|
|
|
|
### Priority 3 - Integrations
|
|
- [ ] Home Assistant MQTT discovery
|
|
- Auto-generate discovery messages
|
|
- Entity registry management
|
|
- State synchronization
|
|
|
|
- [ ] Zigbee2MQTT integration
|
|
- Auto-configure from Zigbee2MQTT
|
|
- Device passthrough mode
|
|
- Coordinator selection
|
|
|
|
- [ ] Z-Wave JS integration
|
|
- Z-Wave network management
|
|
- Node inclusion/exclusion
|
|
- Association configuration
|
|
|
|
### Priority 4 - UI/UX Improvements
|
|
- [ ] Device dashboard view
|
|
- Per-device status cards
|
|
- Recent messages per device
|
|
- Quick actions (pair, unpair, configure)
|
|
|
|
- [ ] Live message viewer
|
|
- Real-time MQTT message stream
|
|
- Topic filtering
|
|
- Publish test messages
|
|
|
|
- [ ] Configuration wizard
|
|
- Step-by-step setup for new users
|
|
- Adapter detection and import
|
|
- Broker configuration assistant
|
|
|
|
---
|
|
|
|
## 🐛 Known Issues
|
|
|
|
### Minor Issues
|
|
- None currently identified
|
|
|
|
### To Investigate
|
|
- Test USB device hotplug (plug/unplug during operation)
|
|
- Verify health monitoring updates in real-time
|
|
- Check serial port permissions on different OpenWrt versions
|
|
|
|
---
|
|
|
|
## 🔧 Technical Debt
|
|
|
|
### Code Quality
|
|
- Add input validation to all RPC methods
|
|
- Improve error messages with actionable suggestions
|
|
- Add logging to USB detection library
|
|
- Write unit tests for VID:PID matching
|
|
|
|
### Performance
|
|
- Optimize USB scanning (cache results, debounce scans)
|
|
- Reduce API polling frequency with event-driven updates
|
|
- Implement WebSocket for real-time status updates
|
|
|
|
### Security
|
|
- Add authentication to MQTT broker configuration
|
|
- Sanitize all user inputs in RPC methods
|
|
- Validate serial port paths before access
|
|
- Implement rate limiting on USB scans
|
|
|
|
---
|
|
|
|
## 📊 Implementation Statistics
|
|
|
|
| Metric | Count |
|
|
|--------|-------|
|
|
| **Version** | 0.5.0-1 |
|
|
| **Views** | 2 (overview, adapters) |
|
|
| **RPC Methods** | 7 (USB-focused) |
|
|
| **Supported Devices** | 17 (Zigbee: 6, Z-Wave: 3, ModBus: 4, Serial: 4) |
|
|
| **JavaScript Lines** | ~500 |
|
|
| **Shell Script Lines** | ~800 (RPCD + library) |
|
|
| **Documentation Lines** | 679 (README.md) |
|
|
|
|
---
|
|
|
|
## 🚀 Next Steps
|
|
|
|
1. **Immediate** (v0.5.0 completion):
|
|
- Run validation scripts
|
|
- Fix any permission issues
|
|
- Test on hardware router
|
|
- Verify all USB detection works
|
|
|
|
2. **Short-term** (v0.5.1):
|
|
- Implement MQTT broker connection
|
|
- Add device pairing workflow
|
|
- Create message routing logic
|
|
|
|
3. **Medium-term** (v0.6.0):
|
|
- Add automation rules engine
|
|
- Implement historical data storage
|
|
- Create device dashboard view
|
|
|
|
4. **Long-term** (v1.0.0):
|
|
- Complete Home Assistant integration
|
|
- Add Zigbee2MQTT support
|
|
- Implement Z-Wave JS integration
|
|
|
|
---
|
|
|
|
## 📝 Notes
|
|
|
|
- **Module Disabled by Default**: Enable via SecuBox Modules page once backend daemon is implemented
|
|
- **USB Permissions**: RPCD script must be executable (755) to access /sys/bus/usb/devices/
|
|
- **Serial Ports**: /dev/ttyUSB* and /dev/ttyACM* require read/write permissions
|
|
- **Theme System**: All views follow SecuBox theme conventions with CSS variables
|
|
- **Backward Compatibility**: Legacy `/usr/sbin/mqtt-bridge-monitor` wrapper maintained for compatibility
|
|
|
|
---
|
|
|
|
## 🔗 Resources
|
|
|
|
- **Module README**: `luci-app-mqtt-bridge/README.md`
|
|
- **Module Status**: `docs/module-status.md` (section: IoT & Integration)
|
|
- **API Documentation**: README.md § API Reference
|
|
- **Configuration Examples**: README.md § UCI Configuration
|
|
|
|
---
|
|
|
|
*Last updated: 2025-12-30*
|
|
*Status: v0.5.0 Complete - Ready for validation and hardware testing*
|