gandalf/secubox-openwrt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
80c496b57e
secubox-openwrt/.codex/apps/mqtt-bridge/WIP.md

7.7 KiB
Raw Blame History

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