Documentation DevIO – Interface d’Échanges HTTP REST

1. Introduction

L’interface DevIOIEHttpRest permet l’intégration d’équipements et de systèmes tiers via le protocole HTTP REST. Elle facilite la collecte, la supervision et le pilotage de données en s’appuyant sur des échanges de fichiers texte ou JSON, adaptés à l’IoT, la GTB et l’interopérabilité industrielle.

Cas d’usage typiques : - Intégration de capteurs connectés - Remontée de données vers des plateformes cloud - Commande à distance d’équipements via API

2. Compatibilité et prérequis

Versions supportées : DevIO v6.0 et supérieures
Environnements : Windows (toutes versions compatibles DevIO)
Dépendances : Accès réseau HTTP, configuration des ports sur le pare-feu

3. Fonctionnalités supportées

Push de données : Fichiers texte (CSV) ou JSON
Sécurité : Gestion de secrets, filtrage IP, logs
Callbacks : Acquittement et retour d’état via HTTP
Historique et polling : Gestion des historiques, activation du polling
Mode -ATLANTIC : Mode spécifique pour compatibilité avec certains équipements (voir section dédiée)
Options avancées : Mapping flexible des clés JSON, gestion fine des timeouts, logs détaillés

4. Configuration de l’interface HTTP REST

Création de l’interface

Ouvrir votre projet dans DevIO Studio
Clic-droit sur Interfaces d’échanges > Nouvelle Interface d’échange
Renseigner les champs principaux :
Mnémonique : Nom logique de l’interface (ex : HTTPREST1)
Description : (ex : Interface HTTP REST pour capteurs connectés)
Exécutable : DevIOIEHttpRest.exe

Options générales et avancées

Option	Description	Valeur par défaut / Exemple
-SERVER	Nom du serveur DevIO
-NAME	Nom de l’interface d’échange
-LISTEN	URL d’écoute HTTP de l’interface	-LISTEN http://0.0.0.0:8080
-BACKURL	URL de callback pour les retours d’état
-VERBOSE	Active les logs détaillés
-LOG	Active la journalisation des échanges
-IHDC	Création de points dédiés aux historiques
-IT	Timeout d’inactivité en secondes	60
-PROXY	Utilisation d’un proxy HTTP
-E	Clé de l’identifiant équipement dans le JSON (deviceId par défaut)	-E deviceId
-D	Clé de l’identifiant de la donnée dans le JSON (sensorId par défaut)	-D sensorId
-V	Clé de la valeur dans le JSON (value par défaut)	-V value
-T	Clé de l’horodatage dans le JSON (updateTime par défaut)	-T updateTime
-MODE	Mode de fonctionnement (ex : ATLANTIC, ATLANTICV2)
-BASEURL	URL de base pour certains modes (ex : Atlantic)	https://apigamtest.groupe-atlantic.com:8243/
-AUTH	Fichier d’autorisation (utilisé pour certains modes)
-SECRET	Fichier de secret pour sécuriser les pushs
-NOIP	Ignore la vérification de l’adresse IP des clients
-CACHED	Active la mise en cache des données
-STR	Utilisation de données de type string

Exemples d’utilisation des options avancées

-PROXY :
Permet de passer par un proxy HTTP pour les communications sortantes.
Exemple : -PROXY http://proxy.mondomaine.local:3128
-BACKURL :
Permet de spécifier une URL de callback pour recevoir des retours d’état ou des notifications.
Exemple : -BACKURL http://monserveur/callback
-IHDC :
Active la création de points dédiés aux historiques dans DevIO.
Utile pour la traçabilité et l’archivage des données reçues.
-CACHED :
Active la mise en cache des données reçues pour optimiser les performances ou la résilience réseau.
-STR :
Permet de traiter des données de type chaîne de caractères (string) dans les échanges JSON.

Options spécifiques aux équipements

Option	Description
-CNXGETFILE	Demande automatique du fichier texte des données horodatées à la connexion sortante

4.1 Modes spécifiques : ATLANTIC / ATLANTICv2

Les modes -ATLANTIC et -ATLANTICV2 activent une compatibilité avancée avec certains équipements ou plateformes (ex : Groupe Atlantic). Ils modifient la structure des échanges JSON, la gestion des secrets et peuvent nécessiter des options supplémentaires.

Options et paramètres spécifiques

Option	Description	Exemple
-MODE ATLANTIC	Active le mode ATLANTIC	-MODE ATLANTIC
-MODE ATLANTICV2	Active le mode ATLANTIC version 2	-MODE ATLANTICV2
-BASEURL	URL de base pour les appels sortants (souvent imposée par la plateforme Atlantic)	-BASEURL https://apigamtest.groupe-atlantic.com:8243/
-AUTH	Fichier d’autorisation spécifique pour la connexion à la plateforme	-AUTH monfichierauth.txt

Structure JSON attendue en mode ATLANTIC

Clés : DeviceId, CapabilityId, CapabilityValue, DModif
Voir exemples dans la section "Utilisation et supervision"

Particularités

Gestion spécifique des secrets et de l’authentification
Possibilité de mapping avancé des clés JSON via les options -D, -E, -V, -T
Utilisation obligatoire de -BASEURL et -AUTH dans certains cas

Exemple de ligne de commande complète (ATLANTIC)

-LISTEN http://0.0.0.0:8080 -SECRET mysecretfile -MODE ATLANTIC -BASEURL https://apigamtest.groupe-atlantic.com:8243/ -AUTH monfichierauth.txt -LOG -VERBOSE

5. Déclaration et configuration des équipements

Modèle d’équipement HTTP REST

Utiliser le modèle d’équipement dédié dans DevIO Studio (ex : Model_HTTPREST)
Paramètres spécifiques :
-CNXGETFILE : Demande automatique du fichier texte des données horodatées à la connexion sortante

Exemple de configuration d’un équipement

Nom : CAPTEUR_TEMP_1
Modèle : Model_HTTPREST
Paramètres : -CNXGETFILE

6. Utilisation et supervision

Exemples de push de données

Mode standard (par défaut)

Clés JSON attendues : deviceId, sensorId, value, updateTime

Exemple de push temps réel :

{
  "deviceId": "EQUI1",
  "sensorId": "001",
  "value": 23.5,
  "updateTime": "2024-06-20T14:30:00"
}

Exemple d’historique (tableau) :

[
  {
    "deviceId": "EQUI1",
    "sensorId": "001",
    "value": 23.5,
    "updateTime": "2024-06-20T14:30:00"
  },
  {
    "deviceId": "EQUI1",
    "sensorId": "002",
    "value": 19.8,
    "updateTime": "2024-06-20T14:35:00"
  }
]

Mode ATLANTIC

Clés JSON attendues : DeviceId, CapabilityId, CapabilityValue, DModif

Exemple de push temps réel :

{
  "DeviceId": 23,
  "CapabilityId": 2,
  "CapabilityValue": "Value2",
  "DModif": "2024-06-20T14:30:00"
}

Exemple d’historique (tableau) :

[
  {
    "DeviceId": 23,
    "CapabilityId": 2,
    "CapabilityValue": "Value2",
    "DModif": "2024-06-20T14:30:00"
  },
  {
    "DeviceId": 23,
    "CapabilityId": 3,
    "CapabilityValue": "Value3",
    "DModif": "2024-06-20T14:35:00"
  }
]

Push de fichier texte (CSV)

URL : http://<serveur_devio>:<port>/DevIO/api/v1/devices/<id_device>/pushdata
Méthode : POST
Headers :
accept: application/json
content-type: application/x-www-form-urlencoded
X-DevIO-Secret: <clé secrète> (si utilisé)
Données :
content=<CONTENU_DU_FICHIER_EN_BASE64>

Important : Le contenu du fichier texte doit obligatoirement être encodé en base64. Si ce n'est pas le cas, la requête sera rejetée avec une erreur 400 ("file not encoded in base64").

Exemple de contenu CSV :

EQUI1;001;0;2017-12-20T01:20:00.100
EQUI1;002;12;2017-12-20T01:30:00.100
EQUI1;003;13;2017-12-20T01:40:00.100

Gestion des callbacks et acquittements

Callback :
Permet à DevIO de notifier l’équipement d’un traitement ou d’une consigne

Exemple de callback JSON :

{
  "url": "http://<adresse_device>:<port>/writecallback",
  "httpMethod": "POST",
  "contentType": "application/json",
  "bodytemplate": "{name:{sensor}, value:{value}}"
}

Acquittement :
Code 202 : Fichier accepté, traitement en cours
Code 400 : Fichier ou requête incorrecte
Code 404 : Aucun callback enregistré pour l’équipement

Surveillance, logs et diagnostic

Utiliser les options -LOG et -VERBOSE pour activer les journaux détaillés
Vérifier les logs pour diagnostiquer les erreurs de communication ou d’authentification

7. FAQ et dépannage

Q : Je reçois une erreur 400 ou 404 lors d’un push ? - Vérifier le format du fichier envoyé (CSV ou JSON) - Vérifier la présence et la validité du secret - S’assurer que l’équipement est bien déclaré côté DevIO

Q : Le push n’est pas accepté malgré un secret correct ? - Vérifier l’adresse IP source (sauf si -NOIP) - Vérifier le format du fichier secret

Q : Comment activer le mode ATLANTIC ? - Ajouter l’option -ATLANTIC dans la configuration de l’interface - Ce mode adapte le parsing et la gestion des données pour les équipements Atlantic (voir documentation technique spécifique) - Les clés JSON attendues changent (voir exemples ci-dessus)

Q : Comment diagnostiquer un problème de callback ? - Vérifier l’URL et la méthode HTTP configurées - Activer -VERBOSE pour plus de détails dans les logs

8. Annexes

Tableau récapitulatif des options

Option	Description courte
-LISTEN	URL d’écoute HTTP
-SECRET	Fichier de secret
-NOIP	Ignore la vérification IP
-D, -E, -V, -T	Mapping flexible des clés JSON
-LOG	Active les logs
-IT	Timeout d’inactivité
-VERBOSE	Logs détaillés
-ATLANTIC	Mode spécifique équipements Atlantic

Exemples de fichiers d’import (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ImportRequest>
  <Device Name="EQUI1" Pin="-p1 -p2 " Model="Model_HTTPREST">
    <DeviceParameters Address="EQUI1" />
    <DeviceCall>
      ...
    </DeviceCall>
  </Device>
</ImportRequest>

Références utiles

Pour toute question ou demande d’assistance, contacter le support DevIO.