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

SecuBox MQTT IoT Bridge

Version : 0.5.0-1 Statut : Pret pour Production Categorie : IoT & Integration Mainteneur : CyberMind contact@cybermind.fr

Pont MQTT IoT avec support complet des peripheriques USB pour les routeurs SecuBox. Detecte et configure automatiquement les adaptateurs USB IoT (Zigbee, Z-Wave, ModBus, Serie) et les relie a un broker MQTT pour la domotique et les applications IoT industrielles.

---

Fonctionnalites

Fonctionnalites de Base

• Integration Broker MQTT : Connexion aux brokers MQTT locaux ou distants
• Detection Adaptateurs USB IoT : Detection automatique de 17 peripheriques USB connus
• Support Multi-Protocoles : Zigbee, Z-Wave, ModBus RTU et USB Serie generique
• Surveillance Sante en Temps Reel : Suivi du statut des adaptateurs (en ligne/erreur/manquant/inconnu)
• Gestion de Configuration : Configuration persistante basee sur UCI
• Integration Theme SecuBox : Interface coherente avec les themes sombre/clair/cyberpunk

Adaptateurs USB IoT Supportes

Adaptateurs Zigbee (6 peripheriques)

• 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) - Zigbee Generique
• SMSC USB2134B (VID:PID 0424:2134)
• CH340 (VID:PID 1a86:7523) - Sonoff Zigbee 3.0

Cles USB Z-Wave (3 peripheriques)

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

Adaptateurs ModBus RTU (4 peripheriques)

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

Adaptateurs USB Serie Generiques

• Tout adaptateur USB vers serie detecte via /dev/ttyUSB* ou /dev/ttyACM*

---

Vues

1. Vue d'Ensemble (overview.js)

• Statut de connexion au broker MQTT
• Nombre total de peripheriques connectes
• Statistiques des adaptateurs USB par type (Zigbee/Z-Wave/ModBus/Serie)
• Resume du statut de sante (en ligne/erreur/manquant/inconnu)
• Messages et topics MQTT recents
• Actions rapides (scanner USB, reconnecter broker)

2. Adaptateurs (adapters.js)

• Grille des Adaptateurs Configures : Tous les adaptateurs configures via UCI avec statut
• Section Peripheriques Detectes : Resultats du scan USB en temps reel
• Assistant d'Import : Import en un clic depuis les peripheriques detectes vers la configuration
• Gestion des Adaptateurs : Actions tester connexion, configurer, supprimer
• Indicateurs de Sante : Statut code par couleur (vert=en ligne, rouge=erreur, jaune=manquant, gris=inconnu)

---

Methodes RPC (7 au total)

Detection & Gestion USB

get_usb_devices

Liste tous les peripheriques USB connectes au systeme avec infos vendeur/produit.

Parametres : Aucun Retourne :

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

detect_iot_adapters

Identifie les adaptateurs IoT par correspondance VID:PID avec la base de peripheriques connus.

Parametres : Aucun Retourne :

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

get_serial_ports

Liste tous les ports serie (/dev/ttyUSB*, /dev/ttyACM*) avec attributs.

Parametres : Aucun Retourne :

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

get_adapter_info

Retourne les informations detaillees pour un adaptateur specifique par ID.

Parametres : { "adapter": "zigbee_cc2531" } Retourne :

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

test_connection

Teste l'accessibilite et la lisibilite du port serie.

Parametres : { "port": "/dev/ttyUSB0" } Retourne :

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

configure_adapter

Cree ou met a jour une configuration d'adaptateur UCI.

Parametres :

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

Retourne : { "success": true }

get_adapter_status

Retourne le statut de sante en temps reel pour tous les adaptateurs configures.

Parametres : Aucun Retourne :

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

---

Configuration UCI

Fichier de Configuration : /etc/config/mqtt-bridge

Exemple de Configuration

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

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

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

# Exemple Adaptateur Zigbee
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'

# Exemple Adaptateur Z-Wave
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'

# Exemple Adaptateur ModBus RTU
config adapter 'modbus_ftdi'
    option enabled '1'
    option type 'modbus'
    option title 'Adaptateur ModBus FTDI'
    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'

Options de Configuration

Section Broker

• host : Nom d'hote ou IP du broker MQTT
• port : Port du broker MQTT (defaut : 1883)
• username : Nom d'utilisateur d'authentification
• password : Mot de passe d'authentification
• client_id : Identifiant client unique

Section Bridge

• base_topic : Topic MQTT de base pour les messages des peripheriques
• retention : Retention des messages en jours
• auto_discovery : Activer l'auto-decouverte MQTT (0/1)
• poll_interval : Intervalle de polling en secondes

Section Monitor

• interval : Intervalle de scan USB en secondes
• usb_scan_enabled : Activer le scan USB automatique (0/1)
• auto_configure : Auto-configurer les adaptateurs detectes (0/1)

Sections Adapter

• enabled : Activer cet adaptateur (0/1)
• type : Type d'adaptateur (zigbee/zwave/modbus/serial)
• title : Nom lisible par l'humain
• vendor : ID vendeur USB (VID)
• product : ID produit USB (PID)
• port : Chemin du port serie
• baud : Vitesse en bauds (9600, 19200, 38400, 57600, 115200, etc.)
• detected : Adaptateur actuellement detecte (0/1, mis a jour automatiquement)
• health : Statut de sante de l'adaptateur (online/error/missing/unknown, mis a jour automatiquement)

Options Specifiques Zigbee

• channel : Canal Zigbee (11-26)
• pan_id : ID Personal Area Network (hex)
• permit_join : Autoriser nouveaux peripheriques a rejoindre (0/1)

Options Specifiques ModBus

• parity : Bit de parite (N/E/O)
• databits : Bits de donnees (7/8)
• stopbits : Bits d'arret (1/2)
• slave_id : ID esclave ModBus

---

Bibliotheque de Detection USB

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

Fonctions Cles

detect_adapter_type(vid, pid)

Fait correspondre VID:PID avec la base de peripheriques connus.

Retourne : zigbee, zwave, modbus, serial, ou unknown

find_usb_tty(device_path)

Mappe le chemin de peripherique USB vers le port serie (/dev/ttyUSB* ou /dev/ttyACM*).

Retourne : Chemin du peripherique ou chaine vide

test_serial_port(port)

Teste si le port serie est accessible.

Retourne : 0 (succes) ou 1 (echec)

get_device_name(vid, pid)

Recupere le nom lisible du peripherique depuis la base de donnees.

Retourne : Chaine du nom du peripherique

---

Installation

Dependances

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

# Optionnel (pour protocoles specifiques)
opkg install python3-pyserial  # Pour communication serie
opkg install socat              # Pour pont TCP/serie

Installation du Paquet

# Telecharger depuis 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

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

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

---

Guide d'Utilisation

1. Configuration Initiale

1. Naviguer vers SecuBox -> Reseau -> MQTT IoT Bridge -> Vue d'Ensemble
2. Configurer les parametres du broker MQTT (hote, port, identifiants)
3. Cliquer sur Sauvegarder & Appliquer

2. Detection des Adaptateurs USB

1. Brancher votre adaptateur USB IoT (Zigbee, Z-Wave, etc.)
2. Aller a la vue Adaptateurs
3. Cliquer sur Scanner Peripheriques USB
4. Les peripheriques detectes apparaitront dans la section "Peripheriques Detectes"

3. Import des Adaptateurs

1. Dans la section Peripheriques Detectes, trouver votre adaptateur
2. Cliquer sur le bouton Importer
3. L'adaptateur sera ajoute a la configuration automatiquement
4. Modifier les parametres de l'adaptateur si necessaire (canal, vitesse en bauds, etc.)

4. Test de Connectivite

1. Selectionner un adaptateur dans la grille Adaptateurs Configures
2. Cliquer sur Tester Connexion
3. Verifier l'indicateur de statut (vert = succes, rouge = echec)

5. Surveillance de la Sante

• En Ligne : Adaptateur connecte et repond
• Erreur : Connexion echouee ou erreur de communication
• Manquant : Adaptateur detecte avant mais maintenant deconnecte
• Inconnu : Statut pas encore determine

---

Depannage

Problemes Courants

Adaptateur Non Detecte

Symptomes : Adaptateur USB branche mais n'apparait pas dans "Peripheriques Detectes"

Solutions :

1. Verifier si le peripherique USB est reconnu par le kernel :

   lsusb
   dmesg | grep tty
   

2. Verifier que le peripherique apparait dans sysfs :

   ls /sys/bus/usb/devices/
   

3. Verifier si VID:PID est dans la base de donnees :

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

Erreurs de Permission Port

Symptomes : "Permission denied" lors de l'acces a /dev/ttyUSB*

Solutions :

1. Verifier les permissions du script RPCD :

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

2. Verifier les permissions du noeud de peripherique :

   ls -l /dev/ttyUSB0
   chmod 666 /dev/ttyUSB0  # Correction temporaire
   

Statut de Sante Affiche "Manquant"

Symptomes : L'adaptateur fonctionnait mais affiche maintenant le statut "missing"

Solutions :

1. Verifier si le peripherique USB est toujours connecte :

   lsusb
   

2. Verifier que le port serie existe :

   ls -l /dev/ttyUSB*
   

3. Rebrancher l'adaptateur USB
4. Verifier dmesg pour les erreurs USB :

   dmesg | tail -20
   

Commandes de Debug

# Lister tous les peripheriques USB
ubus call luci.mqtt-bridge get_usb_devices

# Detecter adaptateurs IoT
ubus call luci.mqtt-bridge detect_iot_adapters

# Obtenir statut adaptateurs
ubus call luci.mqtt-bridge get_adapter_status

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

# Voir configuration pont MQTT
uci show mqtt-bridge

# Verifier logs RPCD
logread | grep mqtt-bridge

---

Reference API

Module API JavaScript

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

// Importer le module API
'require mqtt-bridge/api as API';

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

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

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

// Obtenir statut adaptateurs
API.getAdapterStatus().then(function(status) {
    console.log('Statut adaptateurs:', status.adapters);
});

---

Exemples d'Integration

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

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

---

Developpement

Structure du Projet

luci-app-mqtt-bridge/
|-- Makefile
|-- README.md
|-- htdocs/
|   +-- luci-static/
|       +-- resources/
|           |-- mqtt-bridge/
|           |   +-- api.js          # Module API
|           +-- view/
|               +-- mqtt-bridge/
|                   |-- overview.js  # Tableau de bord Vue d'Ensemble
|                   +-- adapters.js  # Gestion adaptateurs USB
|-- root/
    |-- etc/
    |   +-- config/
    |       +-- mqtt-bridge         # Config UCI
    +-- usr/
        |-- libexec/
        |   +-- rpcd/
        |       +-- luci.mqtt-bridge  # Backend RPCD
        +-- share/
            |-- luci/
            |   +-- menu.d/
            |       +-- luci-app-mqtt-bridge.json
            |-- rpcd/
            |   +-- acl.d/
            |       +-- luci-app-mqtt-bridge.json
            +-- mqtt-bridge/
                +-- usb-database.sh  # Bibliotheque detection USB

Ajout de Nouveaux Peripheriques USB

Pour ajouter le support d'un nouvel adaptateur USB IoT :

1. Editer /usr/share/mqtt-bridge/usb-database.sh
2. Ajouter VID:PID a la base de donnees appropriee :

   ZIGBEE_DEVICES="
   ...
   <VID>:<PID>:Nom de Votre Peripherique
   "
   

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

---

Licence

Apache License 2.0

---

Mainteneur

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

---

Historique des Versions

v0.5.0 (2025-12-30)

• Support complet adaptateurs USB IoT
• Ajout de 17 peripheriques connus a la base VID:PID
• Creation de la vue adapters.js pour gestion USB
• Overview.js ameliore avec statistiques adaptateurs
• Implementation de 7 nouvelles methodes RPCD pour operations USB
• Ajout surveillance sante en temps reel
• Integration theme SecuBox (sombre/clair/cyberpunk)

v0.4.0 (2025-11)

• Integration broker MQTT initiale
• Gestion basique des peripheriques
• Configuration des parametres

---

Ressources

• Depot GitHub : https://github.com/CyberMind-FR/secubox-openwrt
• Documentation : https://gkerma.github.io/secubox-openwrt/
• Suivi des Issues : https://github.com/CyberMind-FR/secubox-openwrt/issues
• Demo Live : https://secubox.cybermood.eu

---

Derniere mise a jour : 2025-12-30