Guides API de Reduxi
Connectez vos propres systèmes à Reduxi : l'External API fournit les données du cloud via HTTPS, l'API MQTT vous donne un accès direct à un Reduxi Controller via votre broker MQTT.
1 De quel guide API avez-vous besoin ?
Reduxi propose deux guides API. Utilisez l'External API pour récupérer depuis le cloud Reduxi les données de vos contrôleurs, appareils, prévisions et prix. Utilisez l'API MQTT pour lire les valeurs d'un Reduxi Controller et lui envoyer des consignes et des commandes via votre propre broker MQTT.
| External API | MQTT API | |
|---|---|---|
| Type | API REST via HTTPS (OpenAPI 3.0) | Messages MQTT (version 3.x) sur votre broker MQTT |
| Origine des données | Cloud Reduxi | Reduxi Controller |
| Accès | Jeton Bearer | Hôte, port, nom d'utilisateur et mot de passe du broker MQTT, définis dans le Reduxi Configurator |
| Sens | Récupère des données | Lit des données, envoie des consignes et des commandes |
| Cas d'usage | Tableaux de bord, rapports et intégrations avec des données de contrôleurs, d'appareils, de prévisions et de prix | Surveillance et pilotage d'un contrôleur en temps réel |
2 External API (REST)
L'External API vous donne accès aux données de vos contrôleurs dans le cloud Reduxi. Toutes les valeurs de puissance et d'énergie sont fournies en unités de base : W et Wh. Les requêtes sont autorisées par un jeton Bearer.
- Contrôleurs : liste des contrôleurs, détails d'un contrôleur et dernier état connu de ses appareils
- Alarmes : alarmes actives d'un contrôleur
- Données des appareils : mesures par appareil, mesures agrégées par catégorie d'appareils et requêtes portant sur plusieurs appareils
- Types de données : types de données disponibles pour un appareil
- Prévisions : données de prévision par site ou par contrôleur
- Prix : prix du marché spot day-ahead, régions du marché spot et listes de prix par site
3 MQTT API
L'API MQTT relie un Reduxi Controller à votre broker MQTT. Le contrôleur publie ses relevés ainsi que les informations sur les appareils et les stratégies dans des topics, et vous lui renvoyez consignes, commandes et paramètres via d'autres topics. La spécification actuelle est la version 1.5 ; elle nécessite la version logicielle du contrôleur 20260421084600.
- Contrôleur : identifiant, keep-alive, intervalles de relevé et de keep-alive, paramètres réseau
- Appareils : liste des appareils, informations sur l'appareil, relevés et consignes
- Stratégies : liste des stratégies, informations, relevés, paramètres, état actif et paramètres de l'EMS externe
- Commandes : actualiser les métadonnées et redémarrer
La documentation MQTT est rédigée du point de vue du Reduxi Controller.
Lorsque vous lisez des données depuis Reduxi MQTT, vous voyez le terme « PUB ». Pourquoi PUB ? Parce que nous publions les données du Reduxi Controller sur le topic.
Lorsque vous définissez des valeurs sur le Reduxi Controller via MQTT, vous voyez le terme « SUB ». Pourquoi SUB ? Parce que nous nous abonnons au topic et y lisons les données, ce qui applique au Reduxi Controller les valeurs que vous avez envoyées.
Les sections 4 à 8 montrent comment configurer le Reduxi Configurator pour que le contrôleur envoie ses données à votre broker MQTT. Elles se terminent par un exemple de lecture d'un appareil et de réglage de ses consignes.
4 Prise en charge des versions MQTT
Nous prenons en charge la version 3. x. En revanche, nous ne prenons pas en charge la version 5. x.
5 Configuration de l'interface MQTT de Reduxi
Connectez-vous à l'appareil Reduxi Controler et accédez aux paramètres système (System settings). Sous System settings, sélectionnez MQTT v3 et définissez les données du broker MQTT :
- Hôte (uniquement le domaine/l'IP, sans mqtts://)
- Port
- Nom d'utilisateur
- Mot de passe
Description textuelle de cette image
Capture d'écran de la page MQTT v3 connection du Reduxi Configurator. Menu de gauche sous le logo reduxi CONFIGURATOR : Users ; Devices ; Strategies ; System (déplié, signe moins) ; Identifier ; Network ; Open VPN ; Connector (déplié) ; Cloud ; MQTT v3 (sélectionné, en gras) ; iFlex ; Configuration (replié, signe plus) ; Distribution System Operators ; Time. En-tête de page : MQTT v3 connection, icône de lien verte à droite. Tableau d'état : Client: vide ; Host: vide ; Connected: coche verte. Section de formulaire Mqtt connection : Host: mqtt.example.com (gris, style d'exemple) ; Port: 1883 (gris) ; Username: vide ; Password: vide ; Server CA chain (PEM format): Choose File, No file chosen ; Client public certificate (PEM format): Choose File, No file chosen ; Client private key (PEM format): Choose File, No file chosen ; Readout interval: 5 sec. Boutons : Clear, Save.
6 Client Windows (MQTT Explorer)
Vous pouvez essayer de collecter des données avec MQTT Explorer en vous connectant au broker MQTT avec les paramètres suivants :
Vous pouvez vous connecter au broker MQTT en lançant une application MQTT Explorer.
Description textuelle de cette image
Capture d'écran de MQTT Explorer (barre supérieure : DISCONNECT, champ de recherche) avec la boîte de dialogue MQTT Connection ouverte au-dessus de la fenêtre principale assombrie. Liste de gauche : bouton plus jaune avec le libellé Connections ; une entrée enregistrée mqtt.example.com avec le petit texte mqtt://mqtt.example.com:1883/ (sélectionnée). Titre de la boîte de dialogue : MQTT Connection, avec mqtt://mqtt.example.com:1883/ à côté. Champs : Name: mqtt.example.com ; Validate certificate: bascule désactivée ; Encryption (tls): bascule désactivée ; Protocol: mqtt:// (liste déroulante) ; Host: mqtt.example.com ; Port: 1883 ; Username: vide ; Password: masqué par des points, avec une icône d'œil afficher/masquer. Boutons : DELETE, ADVANCED, SAVE (jaune), CONNECT (sombre). À l'arrière-plan assombri, une partie du panneau Topic et une valeur JSON avec les entrées type POWER_ACTIVE, target FIXED, phaseType null sont visibles.
7 Commandes
7.1. Actualiser les métadonnées
Demandez à Reduxi de republier sur MQTT toutes les métadonnées du système, des appareils et des stratégies. Sinon, seuls les relevés et les consignes sont publiés périodiquement.
Topic: controllers/controller_unit_id/commands/refresh
Description textuelle de cette image
Capture d'écran de MQTT Explorer (statut DISCONNECT, champ de recherche en haut) utilisé pour envoyer la commande refresh. Arborescence des topics à gauche : e8c1fe29.ala.eu-central-1.emqxsl.com ; controllers ; ZGFE avec keepAlive = 1734965285703 ; commands avec l'entrée refresh ; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(coupé) ; settings ; interval: readout = 15000, keepAlive = 60000 ; devices : 2 avec info = {"id":2,"name":"Tesla Wall Connector Gen 3","typeId":59,"type":{"id":59,"categoryId":3,"category":{"id":3,"name":"EV charger","enumeration":"EV_CHARGER"} ; 4 (1 topic, 2 messages) ; 12 avec info = {"id":12,"name":"Iskraemeco AM550","typeId":16,"type":{"id":16,"categoryId":1,"category":{"id":1,"name":"Energy meter","enumeration":"ENERGY_METER"} ; 17 (1 topic, 2 messages) ; 18 (1 topic, 2 messages) ; strategies : 8 avec info = {"id":8,"typeId":7,"type":{"id":7,"name":"1-phase current based ON/OFF regulation","enumeration":"DISCRETE_CURRENT_PHASE_1"} ; parameters (3 topics, 12 messages) ; 20 (2 topics, 8 messages) ; 27 (sélectionné) avec info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"} ; parameters (1 topic, 4 messages) ; list = [{"id":8,"typeId":7. Côté droit : panneau Topic (badge 2) avec le chemin controllers / ZGFE / strategies / 27 ; panneau Value avec History ; panneau Publish avec Topic: controllers/ZGFE/commands/refresh ; formats raw, xml, json avec json sélectionné ; corps du message vide ; bouton PUBLISH avec une flèche rouge qui le désigne.
7.2. Redémarrage
Redémarre le Reduxi Controller.
Topic: controllers/controller_unit_id/commands/reboot
Description textuelle de cette image
Capture d'écran de l'application MQTT Explorer (statut DISCONNECT, champ de recherche en haut) utilisée pour envoyer la commande reboot. Arborescence des topics à gauche : $SYS (48 topics, 406 messages) ; controllers ; devices (29 topics, 865 messages) ; strategies (38 topics, 884 messages) ; commands (0 topics, 1 message) ; identifier = {"unitId","unitIdFormatted","CPUSerial":.} (ligne sélectionnée) ; settings (2 topics, 2 messages) ; keepAlive = 1675762462861. Côté droit : un aperçu de message JSON en haut avec softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.} ; History : 1. Panneau Publish avec Topic: /controllers/ … /commands/reboot, avec un crochet rouge à la fin du champ de topic. Options de format raw, xml, json : json est sélectionné. Le corps du message est vide. Le bouton PUBLISH est entouré en rouge. QoS: 0 ; retain : case non cochée.
8 Consignes
Les consignes pilotent la puissance ou le courant d'un appareil. Le Reduxi Controller publie les consignes actives de chaque appareil, et vous en définissez de nouvelles via le topic /set correspondant.
8.1. Afficher toutes les consignes actives de l'appareil
Topic: controllers/controller_unit_id/devices/device_id/setpoint
Description textuelle de cette image
Capture d'écran de MQTT Explorer (statut DISCONNECT, champ de recherche en haut) affichant la consigne de l'appareil 15. Arborescence des topics à gauche : $SYS (48 topics, 862 messages) ; controllers ; devices ; 13 (3 topics, 235 messages) ; 14 (3 topics, 235 messages) ; 15 déplié avec les entrées readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1" ; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (ligne sélectionnée, marquée d'un crochet rouge) ; info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE ; puis 18, 8, 9, 10, 11, 12 (3 topics, 233 messages chacun) ; list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge","enumeration":"SOLAR_SOLARE ; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB" ; strategies (38 topics, 2104 messages) ; commands (0 topics, 1 message) ; identifier = {"unitId","unitIdFormatted","CPUSerial" ; settings (2 topics, 2 messages) ; keepAlive = 1675762644772. Côté droit, Topic / controllers / / devices / 15 / setpoint. Panneau Value, QoS: 0, 02/07/2023 10:37:53 AM, avec le bouton de vue formatée entouré en rouge et la valeur JSON encadrée par un crochet rouge : { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (suite). History : 20.
8.2. Définir les consignes de l'appareil
Topic: controllers/controller_unit_id/devices/device_id/setpoint/set
Description textuelle de cette image
Capture d'écran de MQTT Explorer (statut DISCONNECT, champ de recherche en haut) utilisé pour publier une consigne pour l'appareil 15. Arborescence des topics à gauche : $SYS (48 topics, 1192 messages) ; controllers ; devices (surligné) ; 13 (3 topics, 341 messages) ; 14 (3 topics, 341 messages) ; 15 déplié avec readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1" ; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (ligne sélectionnée) ; info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE ; 18 (3 topics, 339 messages) ; 8 (3 topics, 340 messages, surligné) ; 9, 10, 11, 12 (3 topics, 339 messages chacun) ; list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge" ; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB" ; strategies (38 topics, 3062 messages) ; commands (0 topics, 1 message) ; identifier = {"unitId","unitIdFormatted","CPUSerial": ; settings (2 topics, 2 messages) ; keepAlive = 1675762764833. Côté droit : badge History 20, puis panneau Publish. Topic: /controllers/ … /devices/15/setpoint/set ; le champ de topic est marqué par des crochets rouges et le mot set est souligné en rouge. Format raw, xml, json : json sélectionné. Corps du message, encadré par un crochet rouge : { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Bouton PUBLISH entouré en rouge. QoS: 0 ; retain non coché. Une section History se trouve en dessous.
8.2.1. Exemple 1
Régler la puissance active sur -1 kW (export) sur toutes les phases pendant 15 secondes.
{
"values": [
{
"action": "SET",
"type": "POWER_ACTIVE",
"target": "FIXED",
"phaseType": null,
"value": 1000,
"priority": 10000,
"validForTime": 15000
}
]
}
8.2.2. Exemple 2
Limiter le courant maximal à 10 A sur la phase L2 pendant 30 secondes.
{
"values": [
{
"action": "SET",
"type": "CURRENT",
"target": "MAX",
"phaseType": "L2",
"value": 10,
"priority": 10000,
"validForTime": 30000
}
]
}