Connecteur node-red

Introduction

La palette node-red-contrib-scorp-io permet de connecter Node-RED au broker public SCorp-io via MQTTS (MQTT over TLS). Elle gère automatiquement la publication des messages DBIRTH (déclaration des métriques) et DDATA (valeurs des métriques) dans le format attendu par la plateforme SCorp-io.

Cette palette est compatible avec Node-RED ≥ 3.0.0 et Node.js ≥ 18.0.0, en installation locale ou sur FlowFuse.

---

Prérequis

Avant de commencer, munissez-vous des éléments fournis par SCorp-io lors de la mise en place de votre projet :

• Client ID — identifiant unique du client MQTTS

• Login — nom d'utilisateur MQTTS

• Mot de passe — mot de passe MQTTS

• Project ID — identifiant du projet SCorp-io

• Node ID — identifiant du nœud MQTT dans votre infrastructure

---

Installation

1

Extraire la palette

Décompresser le fichier node-red-contrib-scorp-io.zip dans un dossier dédié sur votre machine :

node-red-contrib-scorp-io/
├── nodes/
│   ├── scorp-io-config.js
│   ├── scorp-io-config.html
│   ├── scorp-io-device.js
│   └── scorp-io-device.html
├── locales/
├── test/
└── package.json

2

Installer les dépendances

Ouvrir un terminal dans le dossier de la palette et exécuter :

cd node-red-contrib-scorp-io
npm install

Cette étape est obligatoire à chaque mise à jour de la palette. Elle installe notamment la librairie mqtt nécessaire à la connexion MQTTS.

3

Démarrer Node-RED

node-red

Vérifier dans les logs que la palette est bien chargée :

[info] Loading palette nodes
[info] Started flows

Si le message Waiting for missing types: scorp-io-device apparaît brièvement au démarrage, c'est normal — Node-RED attend que le nœud de configuration soit enregistré avant de finaliser le nœud device. Il disparaît automatiquement après quelques secondes.

---

Adresse et port du broker

Paramètre	Valeur
URL	broker-public-prod.scorp-io.com
Port	8883
Protocole	MQTTS — MQTT over TLS 1.2

Le certificat TLS est porté par le broker SCorp-io. Aucun certificat client n'est requis de votre côté.

---

Nœud de configuration — scorp-io-config

Ce nœud centralise les paramètres de connexion MQTT. Il est partagé par tous les nœuds device de votre flow.

Accès

Dans la palette Node-RED, glisser un nœud SCorp-io Device dans le flow, puis double-cliquer. Cliquer sur l'icône ✏️ à côté du champ Config pour créer ou éditer la configuration.

Paramètres

Champ	Description	Exemple
Nom	Nom libre pour identifier la configuration	SCorp-io Production
Mode	🧪 Test (simulation) ou 🟢 Production (envoi réel)	Production
Client ID	Identifiant unique du client MQTT	my-edge-client-01
Login	Nom d'utilisateur fourni par SCorp-io	[e-mail]
Mot de passe	Mot de passe MQTT fourni par SCorp-io	(masqué)
Project ID	Identifiant du projet SCorp-io	8a3bbfb2-0a47-4a05-98d2-64807bc4ca27
Node ID	Identifiant unique du nœud MQTT dans l'infrastructure	automate-s7

En mode Production, les messages MQTT sont transmis en temps réel au broker SCorp-io. Un bandeau d'avertissement orange s'affiche dans l'interface pour le rappeler.

---

Nœud device — scorp-io-device

Ce nœud gère la publication des messages DBIRTH et DDATA pour un ou plusieurs équipements.

Section — Devices

Chaque device représente un équipement physique (automate, capteur, pompe…). Un seul nœud peut gérer plusieurs devices simultanément.

Ajouter un device

Cliquer sur "Ajouter un device" et renseigner le Device ID — identifiant unique de l'équipement dans le projet.

Exemples : pompe-1 · automate-z3-1 · capteur-temp-01

Dans une infrastructure avec plusieurs publishers MQTT, le Device ID doit être un identifiant unique dans le projet SCorp-io.

Ajouter des métriques

Chaque device contient une liste de métriques. Cliquer sur "Ajouter une métrique" dans le bloc du device correspondant.

Colonne	Description	Exemple
Nom métrique	Nom de la variable publiée sur SCorp-io	pompe-1/etats
Type	Type de donnée de la métrique	Integer
Chemin (depuis msg)	Chemin vers la valeur dans le message Node-RED	msg.payload.pompe1.etats

Types de données disponibles :

Int8 · Int16 · Int32 · Int64 · UInt8 · UInt16 · UInt32 · UInt64 · Float · Double · Boolean · String · DateTime

Notation des chemins :

Les chemins partent de la racine msg :

msg.payload.pompe1.etats   →  accès à msg.payload.pompe1.etats
msg.pompe.etat             →  accès à msg.pompe.etat

Si le chemin ne commence pas par msg., le nœud effectue un fallback automatique sur msg.payload.<chemin>.

---

Section — Émission DBIRTH

Le DBIRTH est le message de configuration envoyé à SCorp-io pour déclarer les métriques disponibles sur un device. Il doit être émis avant toute publication de données.

Option	Description
☑ Après déploiement / redémarrage	Envoie automatiquement un DBIRTH dès que la connexion MQTT est établie. Activé par défaut.
☐ Périodiquement	Réémet un DBIRTH à intervalle régulier : 1h · 6h · 12h · 24h · 48h

---

Section — Actions

Le bouton "Forcer DBIRTH maintenant" déclenche manuellement un DBIRTH pour tous les devices du nœud, directement depuis le panneau de configuration, sans modifier le flow.

Un retour visuel indique le résultat :

• ✅ DBIRTH envoyé : pompe-1, pompe-2

• ❌ Erreur : ... en cas de problème de connexion

Ce bouton n'est actif que si le nœud a déjà été déployé au moins une fois.

---

Entrée et sortie du nœud

Entrée

Le nœud dispose d'une seule entrée. Le comportement dépend du contenu du message reçu :

Condition	Action
msg.topic === "birth"	Force l'émission d'un DBIRTH pour tous les devices
Tout autre message	Routage automatique DDATA

Routage automatique DDATA

Le nœud analyse le message et publie un DDATA pour chaque device dont au moins une métrique est résolvable dans le message. Plusieurs devices peuvent être publiés en parallèle depuis un seul message.

// Publie DDATA pour pompe-1 ET pompe-2 simultanément
msg.payload = {
    pompe1: { etats: 1, defaut: false, status: 3.14 },
    pompe2: { etats: 0, status: 1.5 }
}

Forcer un DBIRTH depuis le flow

Utiliser un nœud inject configuré ainsi :

msg.topic   = "birth"
msg.payload = {}

Sortie — debug

La sortie unique émet chaque trame publiée. Connecter un nœud debug pour inspecter les messages en temps réel.

Champ	Description
msg.topic	Topic MQTT publié
msg.payload	Trame JSON publiée (métriques)
msg._scorp.type	DBIRTH ou DDATA
msg._scorp.device	Device ID concerné
msg._scorp.mode	test ou production
msg._scorp.simulated	true en mode test

---

Format des messages

DBIRTH — Déclaration des métriques

Topic

mqtts/{PROJECT_ID}/DBIRTH/{EDGE_NODE_ID}/{DEVICE_ID}

QoS : 1 · Retained : oui

Payload

{
  "metrics": [
    {
      "name": "pompe-1/etats",
      "dataType": "Integer"
    },
    {
      "name": "pompe-1/defaut",
      "dataType": "Boolean"
    },
    {
      "name": "pompe-1/status",
      "dataType": "Float"
    }
  ]
}

---

DDATA — Publication des valeurs

Topic

mqtts/{PROJECT_ID}/DDATA/{EDGE_NODE_ID}/{DEVICE_ID}

Exemple

mqtts/8a3bbfb2-0a47-4a05-98d2-64807bc4ca27/DDATA/automate-s7/pompe-1

QoS : 1 · Retained : non

Payload

{
  "metrics": [
    {
      "name": "pompe-1/etats",
      "timestamp": 1486144502122,
      "dataType": "Integer",
      "value": 1
    },
    {
      "name": "pompe-1/defaut",
      "timestamp": 1486144502122,
      "dataType": "Boolean",
      "value": false
    },
    {
      "name": "pompe-1/status",
      "timestamp": 1486144502122,
      "dataType": "Float",
      "value": 3.14
    }
  ]
}

Le champ timestamp est généré automatiquement par le nœud au moment de la publication (Date.now()). Il représente le nombre de millisecondes depuis le 1er janvier 1970 (epoch UTC).

---

Exemple de flow complet

Objectif

Publier les données de deux pompes vers SCorp-io toutes les 5 secondes.

Architecture du flow

[Inject — 5s]   ──→  [Function]  ──→  [SCorp-io Device]  ──→  [Debug]
[Inject — birth] ─────────────────────────────────────────↗

Nœud Function — préparer les données

msg.payload = {
    pompe1: {
        etats:  1,
        defaut: false,
        status: 3.14
    },
    pompe2: {
        etats:  0,
        status: 1.5
    }
};
return msg;

Configuration du nœud SCorp-io Device

Device pompe-1

Nom métrique	Type	Chemin
pompe-1/etats	Integer	msg.payload.pompe1.etats
pompe-1/defaut	Boolean	msg.payload.pompe1.defaut
pompe-1/status	Float	msg.payload.pompe1.status

Device pompe-2

Nom métrique	Type	Chemin
pompe-2/etats	Integer	msg.payload.pompe2.etats
pompe-2/status	Float	msg.payload.pompe2.status

---

Mode Test vs Production

	Mode Test 🧪	Mode Production 🟢
Connexion MQTT	❌ Non établie	✅ Établie
Messages publiés	❌ Simulés	✅ Envoyés au broker
Sortie debug	✅ Alimentée	✅ Alimentée
Badge nœud	Bleu	Vert / Rouge / Jaune

Utilisez toujours le mode Test pour valider vos chemins de métriques et la structure de vos messages avant de basculer en Production.

---

Dépannage

Symptôme	Cause probable	Solution
Cannot find module 'mqtt'	node_modules absent	Exécuter npm install dans le dossier palette
Waiting for missing types: scorp-io-device	Ordre de chargement	Normal et transitoire — attendre quelques secondes
Badge rouge "Config manquante"	Nœud config non associé	Double-cliquer et sélectionner une configuration
Aucun device ne correspond au msg	Chemins de métriques incorrects	Vérifier les chemins msg.payload.* dans la configuration
Badge jaune "Connexion..." permanent	Mauvais identifiants ou réseau	Vérifier Client ID / Login / Mot de passe et la connectivité vers le broker
DBIRTH non visible dans SCorp-io	Nœud pas encore déployé ou retained non reçu	Vérifier que le mode Production est actif et utiliser le bouton "Forcer DBIRTH"