Guide d'utilisation

Vérification du bon fonctionnement

Une fois le routage mis en place, vérifiez que les données sont bien transmises en vous rendant sur l'application Administration de IoT magic Builder.

Portail IoT magic Builder — Application Administration

Cliquer pour ouvrir

Accédez à la section Équipements et sélectionnez l'équipement concerné. Dans l'onglet État de l'équipement, les dernières données transmises seront disponibles.

---

Comprendre le template Mustache

Structure des données source

Voici un exemple de structure de données émise par un objet connecté dans Live Objects :

{
  "value": {
    "temperature": {
      "0": {
        "sensorValue": 22.61
      }
    },
    "humidity": {
      "0": {
        "sensorValue": 45.55
      }
    },
    "genericSensor": {
      "0": {
        "sensorValue": 320
      },
      "1": {
        "sensorValue": 71
      }
    }
  }
}

Extraction des valeurs

Pour extraire une valeur depuis la structure source :

{{value.NOM_CAPTEUR.INDEX.sensorValue}}

Élément	Description
value	L'objet racine contenant toutes les valeurs
NOM_CAPTEUR	Le nom du capteur (ex: temperature, humidity)
INDEX	L'index du capteur (généralement 0 pour les capteurs uniques)
sensorValue	La propriété contenant la valeur mesurée

Exemples concrets

Capteur	Chemin Mustache	Valeur extraite
Température	{{value.temperature.0.sensorValue}}	22.61
Humidité	{{value.humidity.0.sensorValue}}	45.55
CO2	{{value.genericSensor.0.sensorValue}}	320
COV	{{value.genericSensor.1.sensorValue}}	71

Champs principaux du template

Champ	Description
protocol	Version du protocole (fixe : "v2")
device	ID de l'appareil récupéré via {{extra.deviceId}}
at	Horodatage de la mesure via {{timestamp}}
data	Contient toutes les données des capteurs formatées

attention

{{extra.deviceId}} récupère le deviceId configuré dans le profil identitaire de l'objet sur Live Objects. Il doit être configuré en amont.

Propriété deviceId dans l'identité de l'objet Live Objects

Cliquer pour ouvrir

Personnaliser le template

• Ajouter un capteur : ajoutez un objet dans le tableau values :

{
  "s": "NOM_DU_CAPTEUR",
  "v": "{{value.CHEMIN.VERS.LA.VALEUR}}"
}

• Supprimer un capteur : retirez simplement l'objet correspondant du tableau values.

---

API Live Objects (avancé)

Pour les déploiements à grande échelle, Live Objects propose une API REST permettant d'automatiser la configuration.

Host : https://liveobjects.orange-business.com

Obtenir une clé API

1. Connectez-vous à votre compte sur Live Objects
2. Accédez au menu Administration > Clés d'API
3. Créez une nouvelle clé API avec le profil Personnalisé et activez les rôles nécessaires (notamment Équipement en lecture/écriture)

Page Clés d'API sur Live Objects

Cliquer pour ouvrir

Formulaire d'ajout d'une clé d'API avec les rôles

Cliquer pour ouvrir

Clé d'API créée avec succès

Cliquer pour ouvrir

Endpoints principaux

Méthode	Endpoint	Description
GET	/api/v1/deviceMgt/devices	Lister tous les devices
POST	/api/v1/deviceMgt/devices	Créer un device
POST	/api/v1/deviceMgt/devices/{deviceId}/interfaces	Créer une interface
PATCH	/api/v1/deviceMgt/devices/{deviceId}/interfaces/{interfaceId}	Assigner un décodeur
GET	/api/v0/decoders	Lister les décodeurs propriétaires
GET	/api/v0/decoders/public	Lister les décodeurs publics
GET	/api/v1/deviceMgt/connectors/lora/profiles	Lister les profils LoRa
POST	/api/v1/event2action/actionPolicies	Appliquer un template Mustache

Créer un device via API

POST /api/v1/deviceMgt/devices
Header: X-API-Key: <votre_clé_api>
Header: Content-Type: application/json

{
  "id": "urn:lo:nsid:<namespace_id>:<device_id>",
  "name": "mon_device",
  "properties": {
    "manufacturer": "Adeunis",
    "deviceID": "<device_uuid_iotmagicbuilder>"
  },
  "profile": "default"
}

Élément	Description
urn:lo:nsid	Préfixe fixe pour tous les appareils Live Objects
<namespace_id>	Votre espace de noms
<device_id>	Identifiant de l'appareil

Appliquer un template Mustache via API

POST /api/v1/event2action/actionPolicies
Header: X-API-Key: <votre_clé_api>
Header: Content-Type: application/json

{
  "name": "Routing_to_IoTMagicBuilder",
  "enabled": true,
  "triggers": {
    "dataMessage": {
      "version": 1
    }
  },
  "actions": {
    "httpPush": [
      {
        "webhookUrl": "https://streams-api.magicbuilder.io/streams",
        "headers": {
          "ApiKey": ["<votre_api_key_iotmagicbuilder>"]
        },
        "retryOnFailure": true,
        "content": "{\"protocol\": \"v2\", \"device\": \"{{extra.deviceId}}\", \"at\": \"{{timestamp}}\", \"data\": {\"ver\": \"1\", \"index\": \"0\", \"itemType\": \"Global\", \"type\": \"Measure\", \"values\": [{\"s\": \"temperature\", \"v\": \"{{value.temperature.0.sensorValue}}\"}, {\"s\": \"humidity\", \"v\": \"{{value.humidity.0.sensorValue}}\"}]}}"
      }
    ]
  }
}

---

Dépannage

Si vos données n'arrivent pas correctement dans Magic Builder :

1. Vérifiez que le deviceId est correctement configuré dans l'identité de l'objet sur Live Objects
2. Contrôlez le chemin d'accès aux valeurs des capteurs dans le template Mustache
3. Assurez-vous que la structure JSON est valide (pas de virgules superflues)
4. Vérifiez que la règle de routage est bien Activée dans Live Objects
5. Consultez la colonne Supervision dans la page Routage pour détecter d'éventuelles erreurs