From d89fb6a96d63f80288b29af40536b6c32ff890d5 Mon Sep 17 00:00:00 2001
From: Eric FELIXINE <eric@digitribe.fr>
Date: Mon, 4 May 2026 20:41:17 -0400
Subject: [PATCH] OpenRemote: MQTT Agent setup guide (UI procedure)

---
 openremote_mqtt_agent_setup.md | 75 ++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 openremote_mqtt_agent_setup.md

diff --git a/openremote_mqtt_agent_setup.md b/openremote_mqtt_agent_setup.md
new file mode 100644
index 00000000..fdaae112
--- /dev/null
+++ b/openremote_mqtt_agent_setup.md
@@ -0,0 +1,75 @@
+# OpenRemote MQTT Agent - Configuration
+
+## Date : 04 Mai 2026
+
+## 🎯 Objectif
+Configurer un agent MQTT dans OpenRemote pour recevoir les données IoT depuis les brokers (EMQX, Mosquitto, BunkerM) et peupler le realm Smart City.
+
+## 🔧 Procédure (via Manager UI)
+
+### Prérequis
+- OpenRemote accessible : https://openremote.digitribe.fr/manager/
+- Realm : `smartcity`
+- Login : `admin` / `Digitribe972`
+- Keycloak configuré avec `KC_HOSTNAME: openremote.digitribe.fr`
+- `KC_COOKIE_SAME_SITE: "None"` (requis pour same-domain)
+
+### Étapes de création de l'agent MQTT
+
+1. **Accéder à l'interface Manager**
+   - Ouvrir https://openremote.digitribe.fr/manager/
+   - Sélectionner le realm `Smart City` (si pas déjà sélectionné)
+
+2. **Créer un nouvel Asset de type Agent**
+   - Cliquer sur **Assets** dans le menu gauche
+   - Bouton **+ Add Asset**
+   - Choisir **Agent** → **MQTT Agent**
+
+3. **Configuration pour EMQX (Broker principal)**
+   ```
+   Name: EMQX MQTT Agent
+   Broker URL: tcp://mqtt.digitribe.fr:1900
+   (ou interne: tcp://docker-emqx-1:1883)
+   Username: bunker
+   Password: bunker
+   Client ID: openremote-emqx-agent
+   Clean Session: true
+   Topics: smartcity/# (subscribe)
+   QoS: 0 ou 1
+   ```
+
+4. **Configuration pour Mosquitto (Traefik)**
+   ```
+   Name: Mosquitto MQTT Agent
+   Broker URL: tcp://mosquitto.digitribe.fr:1883
+   Username: (si configuré)
+   Password: (si configuré)
+   Topics: smartcity/#
+   ```
+
+5. **Mapping des données (après connexion)**
+   - L'agent va recevoir les messages MQTT
+   - Créer des **Attributes** sur les Assets IoT existants (33 assets)
+   - Lier les topics MQTT aux attributs (ex: `smartcity/airquality/temperature` → `Attribute: temperature`)
+
+## ⚠️ Notes importantes
+
+1. **API Service Account bloquée** : L'API OpenRemote donne 403 (Service Account non configuré correctement)
+2. **Contournement** : Utiliser uniquement l'interface Manager UI
+3. **Keycloak** : Client `openremote` avec secret `QVTnyObwXdpQ0Vuc60kFSonidK49FiXb`
+4. **Cookies** : Après modification Keycloak, faire logout + clear cookies + reconnect
+
+## 🔗 Références
+- OpenRemote MQTT Agent docs : https://docs.openremote.io/docs/connect-to-things/mqtt
+- Realm Smart City : 33 assets IoT déjà configurés
+- Simulateur : Envoie sur EMQX (port 11883) et Mosquitto (port 1883)
+
+## 📋 TODO
+- [ ] Créer EMQX MQTT Agent (via UI)
+- [ ] Créer Mosquitto MQTT Agent (via UI)
+- [ ] Tester réception données (simulateur → broker → OpenRemote)
+- [ ] Configurer mapping des attributs sur les 33 assets
+
+---
+**Statut** : 📋 À faire (via Manager UI)
+**Dernière mise à jour** : 04 Mai 2026