secubox-openwrt/package/secubox/luci-app-mqtt-bridge/README.md

SecuBox MQTT IoT Bridge

Version: 0.5.0-1 Status: Production Ready Category: IoT & Integration Maintainer: CyberMind contact@cybermind.fr

MQTT IoT Bridge with comprehensive USB device support for SecuBox routers. Automatically detects and configures USB IoT adapters (Zigbee, Z-Wave, ModBus, Serial) and bridges them to an MQTT broker for home automation and industrial IoT applications.

---

Features

Core Functionality

• MQTT Broker Integration: Connect to local or remote MQTT brokers
• USB IoT Adapter Detection: Automatic detection of 17 known USB devices
• Multi-Protocol Support: Zigbee, Z-Wave, ModBus RTU, and generic USB Serial
• Real-Time Health Monitoring: Track adapter status (online/error/missing/unknown)
• Configuration Management: UCI-based persistent configuration
• SecuBox Theme Integration: Consistent UI with dark/light/cyberpunk themes

Supported USB IoT Adapters

Zigbee Adapters (6 devices)

• Texas Instruments CC2531 (VID:PID 0451:16a8)
• Dresden Elektronik ConBee II (VID:PID 1cf1:0030)
• Sonoff Zigbee 3.0 USB Plus (VID:PID 1a86:55d4)
• Silicon Labs CP2102 (VID:PID 10c4:ea60) - Generic Zigbee
• SMSC USB2134B (VID:PID 0424:2134)
• CH340 (VID:PID 1a86:7523) - Sonoff Zigbee 3.0

Z-Wave USB Sticks (3 devices)

• Aeotec Z-Stick Gen5 (VID:PID 0658:0200)
• Aeotec Z-Stick 7 (VID:PID 0658:0280)
• Z-Wave.Me UZB (VID:PID 10c4:8a2a)

ModBus RTU Adapters (4 devices)

• FTDI FT232 (VID:PID 0403:6001) - USB-Serial
• Prolific PL2303 (VID:PID 067b:2303)
• CH340 (VID:PID 1a86:7523)
• CP210x UART Bridge (VID:PID 10c4:ea60)

Generic USB Serial Adapters

• Any USB-to-serial adapter detected via /dev/ttyUSB* or /dev/ttyACM*

---

Views

1. Overview (overview.js)

• MQTT broker connection status
• Total connected devices count
• USB adapter statistics by type (Zigbee/Z-Wave/ModBus/Serial)
• Health status summary (online/error/missing/unknown)
• Recent MQTT messages and topics
• Quick actions (scan USB, reconnect broker)

2. Adapters (adapters.js)

• Configured Adapters Grid: All UCI-configured adapters with status
• Detected Devices Section: Real-time USB device scanning results
• Import Wizard: One-click import from detected devices to configuration
• Adapter Management: Test connection, configure, remove actions
• Health Indicators: Color-coded status (green=online, red=error, yellow=missing, gray=unknown)

---

RPC Methods (7 total)

USB Detection & Management

get_usb_devices

Lists all USB devices connected to the system with vendor/product info.

Parameters: None Returns:

{
  "devices": [
    {
      "bus": "usb1",
      "device": "1-1",
      "vendor": "0451",
      "product": "16a8",
      "adapter_type": "zigbee",
      "device_name": "Texas Instruments CC2531",
      "port": "/dev/ttyUSB0"
    }
  ]
}

detect_iot_adapters

Identifies IoT adapters by VID:PID matching against known device database.

Parameters: None Returns:

{
  "zigbee": [
    {
      "vendor": "0451",
      "product": "16a8",
      "name": "Texas Instruments CC2531",
      "port": "/dev/ttyUSB0"
    }
  ],
  "zwave": [],
  "modbus": []
}

get_serial_ports

Lists all serial ports (/dev/ttyUSB*, /dev/ttyACM*) with attributes.

Parameters: None Returns:

{
  "ports": [
    {
      "device": "/dev/ttyUSB0",
      "driver": "ch341",
      "vendor": "1a86",
      "product": "7523",
      "adapter_type": "zigbee"
    }
  ]
}

get_adapter_info

Returns detailed information for a specific adapter by ID.

Parameters: { "adapter": "zigbee_cc2531" } Returns:

{
  "id": "zigbee_cc2531",
  "enabled": true,
  "type": "zigbee",
  "vendor": "0451",
  "product": "16a8",
  "port": "/dev/ttyUSB0",
  "baud": "115200",
  "channel": "11",
  "detected": true,
  "health": "online"
}

test_connection

Tests serial port accessibility and readability.

Parameters: { "port": "/dev/ttyUSB0" } Returns:

{
  "success": true,
  "port": "/dev/ttyUSB0",
  "readable": true,
  "writable": true,
  "error": null
}

configure_adapter

Creates or updates a UCI adapter configuration.

Parameters:

{
  "adapter_id": "zigbee_usb2134",
  "type": "zigbee",
  "vendor": "0424",
  "product": "2134",
  "port": "/dev/ttyUSB1",
  "baud": "115200",
  "enabled": true
}

Returns: { "success": true }

get_adapter_status

Returns real-time health status for all configured adapters.

Parameters: None Returns:

{
  "adapters": [
    {
      "id": "zigbee_cc2531",
      "health": "online",
      "port": "/dev/ttyUSB0",
      "detected": true,
      "last_seen": 1704046800
    }
  ]
}

---

UCI Configuration

Configuration File: /etc/config/mqtt-bridge

Example Configuration

# MQTT Broker Settings
config broker 'broker'
    option host '127.0.0.1'
    option port '1883'
    option username 'secubox'
    option password 'secubox'
    option client_id 'mqtt-bridge-01'

# Bridge Configuration
config bridge 'bridge'
    option base_topic 'secubox/+/state'
    option retention '7'
    option auto_discovery '1'
    option poll_interval '30'

# USB Monitoring
config monitor 'monitor'
    option interval '10'
    option usb_scan_enabled '1'
    option auto_configure '0'

# Zigbee Adapter Example
config adapter 'zigbee_cc2531'
    option enabled '1'
    option type 'zigbee'
    option title 'Texas Instruments CC2531'
    option vendor '0451'
    option product '16a8'
    option port '/dev/ttyUSB0'
    option baud '115200'
    option channel '11'
    option pan_id '0x1A62'
    option permit_join '0'
    option detected '1'
    option health 'online'

# Z-Wave Adapter Example
config adapter 'zwave_aeotec'
    option enabled '1'
    option type 'zwave'
    option title 'Aeotec Z-Stick Gen5'
    option vendor '0658'
    option product '0200'
    option port '/dev/ttyACM0'
    option baud '115200'
    option detected '0'
    option health 'unknown'

# ModBus RTU Adapter Example
config adapter 'modbus_ftdi'
    option enabled '1'
    option type 'modbus'
    option title 'FTDI ModBus Adapter'
    option vendor '0403'
    option product '6001'
    option port '/dev/ttyUSB1'
    option baud '9600'
    option parity 'N'
    option databits '8'
    option stopbits '1'
    option slave_id '1'
    option detected '1'
    option health 'online'

Configuration Options

Broker Section

• host: MQTT broker hostname or IP
• port: MQTT broker port (default: 1883)
• username: Authentication username
• password: Authentication password
• client_id: Unique client identifier

Bridge Section

• base_topic: Base MQTT topic for device messages
• retention: Message retention in days
• auto_discovery: Enable MQTT auto-discovery (0/1)
• poll_interval: Polling interval in seconds

Monitor Section

• interval: USB scan interval in seconds
• usb_scan_enabled: Enable automatic USB scanning (0/1)
• auto_configure: Auto-configure detected adapters (0/1)

Adapter Sections

• enabled: Enable this adapter (0/1)
• type: Adapter type (zigbee/zwave/modbus/serial)
• title: Human-readable name
• vendor: USB vendor ID (VID)
• product: USB product ID (PID)
• port: Serial port device path
• baud: Baud rate (9600, 19200, 38400, 57600, 115200, etc.)
• detected: Adapter currently detected (0/1, auto-updated)
• health: Adapter health status (online/error/missing/unknown, auto-updated)

Zigbee-Specific Options

• channel: Zigbee channel (11-26)
• pan_id: Personal Area Network ID (hex)
• permit_join: Allow new devices to join (0/1)

ModBus-Specific Options

• parity: Parity bit (N/E/O)
• databits: Data bits (7/8)
• stopbits: Stop bits (1/2)
• slave_id: ModBus slave ID

---

USB Detection Library

Location: /usr/share/mqtt-bridge/usb-database.sh

Key Functions

detect_adapter_type(vid, pid)

Matches VID:PID against known device database.

Returns: zigbee, zwave, modbus, serial, or unknown

find_usb_tty(device_path)

Maps USB device path to serial port (/dev/ttyUSB* or /dev/ttyACM*).

Returns: Device path or empty string

test_serial_port(port)

Tests if serial port is accessible.

Returns: 0 (success) or 1 (fail)

get_device_name(vid, pid)

Retrieves human-readable device name from database.

Returns: Device name string

---

Installation

Dependencies

# Required
opkg update
opkg install luci-base rpcd curl mosquitto

# Optional (for specific protocols)
opkg install python3-pyserial  # For serial communication
opkg install socat              # For TCP/serial bridging

Package Installation

# Download from GitHub Releases
wget https://github.com/CyberMind-FR/secubox-openwrt/releases/download/v0.5.0/luci-app-mqtt-bridge_0.5.0-1_all.ipk

# Install
opkg install luci-app-mqtt-bridge_0.5.0-1_all.ipk

# Restart services
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

---

Usage Guide

1. Initial Setup

1. Navigate to SecuBox → Network → MQTT IoT Bridge → Overview
2. Configure MQTT broker settings (host, port, credentials)
3. Click Save & Apply

2. Detecting USB Adapters

1. Plug in your USB IoT adapter (Zigbee, Z-Wave, etc.)
2. Go to Adapters view
3. Click Scan USB Devices
4. Detected devices will appear in the "Detected Devices" section

3. Importing Adapters

1. In the Detected Devices section, find your adapter
2. Click Import button
3. Adapter will be added to configuration automatically
4. Edit adapter settings if needed (channel, baud rate, etc.)

4. Testing Connectivity

1. Select an adapter in the Configured Adapters grid
2. Click Test Connection
3. Check the status indicator (green = success, red = failed)

5. Monitoring Health

• Online (🟢): Adapter is connected and responding
• Error (🔴): Connection failed or communication error
• Missing (🟡): Adapter was detected before but now disconnected
• Unknown (⚪): Status not yet determined

---

Troubleshooting

Common Issues

Adapter Not Detected

Symptoms: USB adapter plugged in but not appearing in "Detected Devices"

Solutions:

1. Check if USB device is recognized by kernel:

   lsusb
   dmesg | grep tty
   

2. Verify device appears in sysfs:

   ls /sys/bus/usb/devices/
   

3. Check if VID:PID is in database:

   cat /usr/share/mqtt-bridge/usb-database.sh | grep <VID>:<PID>
   

Port Permission Errors

Symptoms: "Permission denied" when accessing /dev/ttyUSB*

Solutions:

1. Verify RPCD script permissions:

   chmod 755 /usr/libexec/rpcd/luci.mqtt-bridge
   

2. Check device node permissions:

   ls -l /dev/ttyUSB0
   chmod 666 /dev/ttyUSB0  # Temporary fix
   

Health Status Shows "Missing"

Symptoms: Adapter was working but now shows "missing" status

Solutions:

1. Check if USB device is still connected:

   lsusb
   

2. Verify serial port exists:

   ls -l /dev/ttyUSB*
   

3. Replug the USB adapter
4. Check dmesg for USB errors:

   dmesg | tail -20
   

Debug Commands

# List all USB devices
ubus call luci.mqtt-bridge get_usb_devices

# Detect IoT adapters
ubus call luci.mqtt-bridge detect_iot_adapters

# Get adapter status
ubus call luci.mqtt-bridge get_adapter_status

# Test serial port
ubus call luci.mqtt-bridge test_connection '{"port":"/dev/ttyUSB0"}'

# View MQTT bridge configuration
uci show mqtt-bridge

# Check RPCD logs
logread | grep mqtt-bridge

---

API Reference

JavaScript API Module

Location: htdocs/luci-static/resources/mqtt-bridge/api.js

// Import the API module
'require mqtt-bridge/api as API';

// Get USB devices
API.getUSBDevices().then(function(devices) {
    console.log('USB devices:', devices);
});

// Detect IoT adapters
API.detectIoTAdapters().then(function(adapters) {
    console.log('Zigbee:', adapters.zigbee);
    console.log('Z-Wave:', adapters.zwave);
    console.log('ModBus:', adapters.modbus);
});

// Configure adapter
API.configureAdapter({
    adapter_id: 'zigbee_cc2531',
    type: 'zigbee',
    vendor: '0451',
    product: '16a8',
    port: '/dev/ttyUSB0',
    baud: '115200',
    enabled: true
}).then(function(result) {
    console.log('Configured:', result.success);
});

// Get adapter status
API.getAdapterStatus().then(function(status) {
    console.log('Adapter status:', status.adapters);
});

---

Integration Examples

Home Assistant

# configuration.yaml
mqtt:
  broker: <openwrt-router-ip>
  port: 1883
  username: secubox
  password: secubox
  discovery: true
  discovery_prefix: homeassistant

Zigbee2MQTT

# configuration.yaml
homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://<openwrt-router-ip>
serial:
  port: /dev/ttyUSB0
  adapter: zstack

Node-RED

// MQTT In node configuration
{
    "server": "<openwrt-router-ip>:1883",
    "topic": "secubox/+/state",
    "qos": "0",
    "username": "secubox",
    "password": "secubox"
}

---

Development

Project Structure

luci-app-mqtt-bridge/
├── Makefile
├── README.md
├── htdocs/
│   └── luci-static/
│       └── resources/
│           ├── mqtt-bridge/
│           │   └── api.js          # API module
│           └── view/
│               └── mqtt-bridge/
│                   ├── overview.js  # Overview dashboard
│                   └── adapters.js  # USB adapter management
├── root/
│   ├── etc/
│   │   └── config/
│   │       └── mqtt-bridge         # UCI config
│   ├── usr/
│   │   ├── libexec/
│   │   │   └── rpcd/
│   │   │       └── luci.mqtt-bridge  # RPCD backend
│   │   └── share/
│   │       ├── luci/
│   │       │   └── menu.d/
│   │       │       └── luci-app-mqtt-bridge.json
│   │       ├── rpcd/
│   │       │   └── acl.d/
│   │       │       └── luci-app-mqtt-bridge.json
│   │       └── mqtt-bridge/
│   │           └── usb-database.sh  # USB detection library
│   └── etc/
│       └── init.d/
│           └── mqtt-bridge         # Init script

Adding New USB Devices

To add support for a new USB IoT adapter:

1. Edit /usr/share/mqtt-bridge/usb-database.sh
2. Add VID:PID to appropriate database:

   ZIGBEE_DEVICES="
   ...
   <VID>:<PID>:Your Device Name
   "
   

3. Restart RPCD: /etc/init.d/rpcd restart

---

License

Apache License 2.0

---

Maintainer

CyberMind.fr GitHub: @gkerma Email: contact@cybermind.fr

---

Version History

v0.5.0 (2025-12-30)

• ✅ Complete USB IoT adapter support
• ✅ Added 17 known devices to VID:PID database
• ✅ Created adapters.js view for USB management
• ✅ Enhanced overview.js with adapter statistics
• ✅ Implemented 7 new RPCD methods for USB operations
• ✅ Added real-time health monitoring
• ✅ SecuBox theme integration (dark/light/cyberpunk)

v0.4.0 (2025-11)

• Initial MQTT broker integration
• Basic device management
• Settings configuration

---

Resources

• GitHub Repository: https://github.com/CyberMind-FR/secubox-openwrt
• Documentation: https://gkerma.github.io/secubox-openwrt/
• Issue Tracker: https://github.com/CyberMind-FR/secubox-openwrt/issues
• Live Demo: https://secubox.cybermood.eu

---

Last updated: 2025-12-30