Guide d'utilisation

Vérifier le bon fonctionnement

Après le déploiement, chaque message reçu de votre source déclenche une publication vers dDruid.

1. Dans Node-RED, le nœud debug affiche le résultat : en HTTPS, la réponse {"response":"OK"} ; en MQTTS, le stream publié.
2. Sur IoT magic Builder, ouvrez l'application Administration → Équipements, sélectionnez l'équipement, puis la variable concernée et son onglet Données : les derniers points de données y apparaissent.

Dernières données reçues sur la variable dans IoT magic Builder

Cliquer pour ouvrir

---

Le stream produit

Le nœud Build dDruid stream construit, pour chaque message, un stream au format v2 contenant un dataset S1 :

{
  "protocol": "v2",
  "device": "DEVICE_DEVELOPER_ID",
  "at": 1554884039,
  "data": {
    "ver": "S1",
    "dataset": [
      { "at": 1554884039, "ref": "Global|0|temperature", "value": 22.61 },
      { "at": 1554884039, "ref": "Global|0|humidity", "value": 45.55 }
    ]
  }
}

Ce message est identique quel que soit le transport :

• en HTTPS, il est envoyé via POST https://streams-api.magicbuilder.io/streams, avec le header apikey ;
• en MQTTS, il est publié sur le topic {API_KEY}/streams du broker streams-mqtt.magicbuilder.io:8883.

Champ	Description
device	Device developer ID de l'équipement dDruid
at	Horodatage Unix (secondes) du stream
data.ver	Version du dataset, toujours "S1"
dataset[].ref	Référence de la variable, itemType|itemIndex|serviceId
dataset[].value	La valeur transmise

info

Une variable est créée automatiquement côté dDruid la première fois qu'une référence inconnue est reçue.

---

Adapter le template à votre source

Le seul bloc à modifier est le Mapping du nœud Build dDruid stream : il fait le lien entre la structure de votre msg.payload et les variables dDruid.

Exemple : payload plat

Si votre source émet { "temperature": 22.6, "humidity": 45.5 }, le mapping par défaut convient tel quel.

Exemple : payload imbriqué

Si votre source émet une structure imbriquée, ajustez les chemins :

const src = msg.payload || {};
const dataset = [];
if (src.sensor?.temp != null)
  dataset.push({ at, ref: 'Global|0|temperature', value: src.sensor.temp });
if (src.sensor?.hum != null) dataset.push({ at, ref: 'Global|0|humidity', value: src.sensor.hum });

Exemple : payload = valeur simple

Si votre source émet directement une valeur (un nombre ou une chaîne dans msg.payload) plutôt qu'un objet :

const dataset = [{ at, ref: 'Global|0|temperature', value: Number(msg.payload) }];

---

Personnaliser

Ajouter une variable

Ajoutez une ligne dans le tableau dataset, avec la référence dDruid souhaitée :

if (src.co2 != null) dataset.push({ at, ref: 'Global|0|co2', value: src.co2 });

Utiliser des items indexés

La référence suit la syntaxe itemType|itemIndex|serviceId. Utilisez l'itemIndex pour regrouper plusieurs mesures d'un même équipement :

dataset.push({ at, ref: 'Salle|1|temperature', value: t1 });
dataset.push({ at, ref: 'Salle|2|temperature', value: t2 });

Alimenter plusieurs équipements

Pour envoyer vers plusieurs équipements dDruid depuis un même flow, dupliquez le nœud Build dDruid stream (un DEVICE par équipement) ou construisez la valeur device dynamiquement à partir de msg.

---

Dépannage

Symptôme	Piste
HTTPS — réponse 401 / 403	Clé API absente ou incorrecte dans le header apikey (vérifier msg.headers dans Build dDruid stream)
HTTPS — réponse vide / erreur de format	Vérifier que le nœud json précède http request et que content-type: application/json est présent
MQTTS — le nœud reste sur connecting	Connectivité sortante vers streams-mqtt.magicbuilder.io:8883 (pare-feu), ou certificat TLS non vérifié
MQTTS — nœud « Connecté » mais rien ne remonte	Username = clé API manquant dans l'onglet Sécurité du broker (non importé par Node-RED)
Aucune donnée ne remonte	Le mapping correspond-il bien à la structure de votre msg.payload ? Le dataset n'est-il pas vide ?
Données reçues mais pas de variable dans dDruid	Vérifier la référence produite (ref) et que le device correspond bien au Device developer ID

astuce

Ajoutez un nœud debug juste après Build dDruid stream pour inspecter le contenu exact du stream avant publication, et un autre en sortie du nœud d'envoi (http request ou mqtt out) pour contrôler le résultat.