Vous aimeriez un devis?

Documentation de RVCP: API REST pour capteurs VCP sur SensGate

1. Introduction

La plupart des instruments Dracal peuvent être munis de l'option VCP (Virtual COM Port). L'un des principaux avantages d'opter pour un instrument muni de cette option est la possibilité d'en intégrer les données sans dépendre d'une applications tiers, comme par exemple notre outil en ligne-de-commande dracal-usb-get. Notre API REST nommée RVCP, installée nativement sur le SensGate, permet désormais aux détenteurs d'instruments munis de l'option VCP de les connecter à leur SensGate et d'accéder à leurs données à distance sans dépendre d'un logiciel tiers propriétaire. RVCP vous permet donc de jouir simultanément des avantages de la communication COM offerte mode VCP et de la connectivité sans-fil offerte par le SensGate, sans compormis.

1.1. À propos de cette documentation

Cette documentation est construite depuis un ordinateur dont le système d'exploitation est Windows 11. L'ordinateur accède au SensGate de numéro de série unique G00033 configuré en mode AP (Access Point)  via une communication Wi-Fi établie sur ce sous-réseau.

Dans les exemples, L'API RVCP est appelé sur un terminal via l'exécutable curl, disponible sur tous les systèmes d'exploitations les plus populaires. Noter qu'il est aussi possible d'effectuer les appels directement via votre fureteur web. Par exemple, si la commande curl http://192.168.40.1:8080/sensgate/rvcp/devices est appelée dans un terminal, la même commande sans le curl (soit http://192.168.40.1:8080/sensgate/rvcp/devices) peut être invoquée dans votre fureteur comme ceci:

1.2. Restrictions et sécurité

Que l'accès à l'interface web de votre SensGate soit sécurisé par mot de passe ou non, les données des instruments y étant connectés peuvent être écoutées par nos outils, incluant l'API REST RVCP. Il vous revient d'évaluer les risques associés à la possibilité d'accéder aux données que vous produisez, même si c'est sans leur contexte d'utilisation.

1.3. Compatibilité avec les formats de sortie du mode VCP

Toujours dans un objectif d'optimiser le temps déjà investi dans vos projets pour intégrer les données de vos instruments Dracal, l'API RVCP pour SensGate reproduit à l'identique le format des données telles que retournées par vos instruments communiquant en mode VCP. Cependant, afin de se conformer aux meilleurs pratiques d'architectures REST, le résultat des commandes est enveloppé dans un tableau JSON simple.

2. Prérequis

1. Détenir des instruments munis de l'option VCP (ex. VCP-PTH450-CAL, VCP-RTD300, VCP-...)

2. Détenir un SensGate et avoir pris connaissance de la documentation pour démarrer rapidement avec le SensGate

3. S'assurer que la version de votre SensGate est 1.1.1 ou plus récente:

 

Si votre version est antérieure, ou si vous hésitez, effectuez une mise à jour du micrologiciel (firmware update) en téléchargeant ici la dernière version disponible et suivez les étapes suivantes:

3. Point d'accès aux ressources

Une API REST (REpresentational State Transfer) est un style d'architecture logicielle qui définit un ensemble de contraintes pour la création de services web. L'architecture REST repose sur plusieurs principes fondamentaux bien établis. L'un de ces principes demande que les ressources (qui peuvent être des objets ou des services) d'une API REST soient identifiées par des URIs (Uniform Resource Identifiers).

Les URI de l'API RVCP pour SensGate sont des URLs dont le format est le suivant: 

http://[adresse IP du SensGate]:8080/sensgate/rvcp/[commandes]

où

    • http://: Que l'interface web du SensGate soit protégée par mot de passe (https) ou non (http), la communication pour RVCP passe par http
    • [adresse IP du SensGate] : L'adresse IP du SensGate, qui peut être repérée dans votre navigateur web
      ainsi que dans l'onglet Network de DracalView

  • :8080 : Port d'accès pour la communication REST avec le SensGate. Il a été fixé par Dracal Technologies et est identique pour l'ensemble des utilisateurs.
  • /sensgate/rvcp : Chaîne de caractères, constante également, qui constitue le point d'accès de l'API RVCP et ses commandes
  • [commandes] : Commandes supportées par l'API et décrites ci-après

4. Commandes disponibles: à partir des ports

Attention: L'allocation des ports est effectuée à l'alimentation d'un SensGate. Ainsi, interchanger les capteurs sur un SensGate déjà en fonction ne devrait pas affecter les ports assignés à chacun d'entre eux tant et aussi longtemps que le SensGate demeure en marche. Cependant, lors du prochain arrêt/réalimentation du SensGate, le SensGate assignera à nouveau des ports à chaque capteurs et cette réassignation pourrait être différente de l'allocation précédente si ceux-ci ne sont plus connectés dans la même configuration. Ainsi, un port ne devrait pas être utilisé comme identificateur unique d'un instrument, et c'est la raison pour laquelle nous vous offrons également la possibilité d'interroger vos capteurs directement par leur numéro de série dans la section 5 de cette documentation.

Si malgré tout l'appel par le port est ce qui vous convient le mieux, cette section vous est toute indiquée.

4.1. Lister les ports: commande /ports

La commande /ports permet de lister les ports sur lesquels sont connectés des instruments communiquant en mode VCP.

L'exemple ci-dessous nous indique que 2 instruments communiquant en mode VCP sont actuellement connectés sur le SensGate utilisé pour construire la présente documentation:

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports
["ttyACM0","ttyACM1"]

4.2. Obtenir tous les détails d'un instrument: commande /ports/[port]

Maintenant que la liste des ports disponibles a été obtenue, il est possible, port par port, d'aller chercher les détails correspondant à chacun. Dans l'exemple ci-dessous, les deux informations des appareils associés aux ports ttyACM0 et ttyACM1 sont obtenues:

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM0
{
"port": "ttyACM0",
"time": "2023-12-21T18:44:16+00:00",
"data": "D,VCP-PTH450-CAL,E21833,,103371,Pa,25.616844,C,16.220341,%,*6a04",
"info": "I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,SHT31 Temperature,C,SHT31 Relative Humidity,%,*bbdd"
}

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM1
{
"port": "ttyACM1",
"time": "2023-12-21T18:45:32+00:00",
"data": "D,VCP-TMC200k-CAL,E24616,,25.1601,C,28.0092,C,*2e2f",
"info": "I,Product ID,Serial Number,Message,Type-K Thermocouple,C,Thermocouple cold junction temperature,C,*12d9D"
}

4.3. Obtenir les informations d'un instrument (résultat de la commande VCP INFO): commande /ports/[port]/info

La commande /ports/[port]/info retourne le résultat de la commande INFO du mode VCP enveloppé dans un format JSON. Dans l'exemple ci-dessous, les ports ttyACM0 à ttyACM1 sont interrogés l'un après l'autre:

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM0/info
["I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,SHT31 Temperature,C,SHT31 Relative Humidity,%,*bbdd"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM1/info
["I,Product ID,Serial Number,Message,Type-K Thermocouple,C,Thermocouple cold junction temperature,C,*12d9"]

4.4. Lire les données d'un instrument: commande /ports/[port]/data

La commande /ports/[port]/data permet d'obtenir une ligne des données mesurées par l'instrument interrogé en temps réel, dans un format identique à celui du mode VCP (enveloppé dans un tableau JSON). Ainsi, pour obtenir un flot ininterrompu de données, il suffit d'invoquer cette commande en boucle, à la fréquence désirée. Si les données ne sont pas mises à jour aussi rapidement que nécessaire, configurez votre instrument à une fréquence d'interrogation (POLL rate) plus élevé. La fréquence par défaut est de une mesure par seconde.

Dans l'exemple suivant, on invoque successivement les commandes /ports/ttyACM0/data et /ports/ttyACM1/data pour obtenir les données de nos 2 instruments successivement:

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM0/data
["D,VCP-PTH450-CAL,E21833,,103364,Pa,25.632866,C,15.953307,%,*ef96"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM1/data
["D,VCP-TMC200k-CAL,E24616,,25.1954,C,28.3487,C,*2c88"]

5. Commandes disponibles: à partir des numéros de séries uniques

Les commandes présentées dans la section 4 ci-dessus sont également disponibles depuis la racine "devices" plutôt que "ports", permettant d'interroger les capteurs par leur numéro de série unique plutôt que le port auquel ils sont connectés. Pour chacune des commandes, les mêmes remarques émises dans la section 4 s'appliquent ici.

5.1 Lister les instruments: commande /devices

La commande /devices liste les numéros de série des instruments Dracal connectés au SensGate et communiquant en mode VCP.

L'exemple ci-dessous montre que 2 instruments communiquant en mode VCP sont actuellement connectés au SensGate utilisé pour élaborer cette documentation :

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices
["E21833","E24616"]

5.2 Obtenir tous les détails d'un instrument: commande /devices/[serial_number]

Maintenant que la liste des instruments disponibles a été obtenue, il est possible, appareil par appareil, de récupérer les détails correspondant à chacun d'entre eux. Dans l'exemple ci-dessous, on obtient à la fois les informations sur les dispositifs associés aux instruments portant le numéro de série E21833 et E24616 :

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E21833
{
"device": "E21833",
"time": "2023-12-21T18:59:19+00:00",
"data": "D,VCP-PTH450-CAL,E21833,,103362,Pa,25.590141,C,15.834287,%,*845f",
"info": "I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,SHT31 Temperature,C,SHT31 Relative Humidity,%,*bbdd"
}

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E24616
{
"device": "E24616",
"time": "2023-12-21T19:00:58+00:00",
"data": "D,VCP-TMC200k-CAL,E24616,,25.1655,C,28.4131,C,*bfd0",
"info": "I,Product ID,Serial Number,Message,Type-K Thermocouple,C,Thermocouple cold junction temperature,C,*12d9D"
}

5.3 Obtenir les informations d'un instrument (résultat de la commande VCP INFO): commande /devices/[serial_number]/info

La commande /devices/[serial number]/info renvoie le résultat de la commande INFO en mode VCP, au format JSON. Dans l'exemple ci-dessous, les capteurs portant les numéros de série E21833 et E24616 sont interrogés l'un après l'autre :

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E21833/info
["I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,SHT31 Temperature,C,SHT31 Relative Humidity,%,*bbdd"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E24616/info
["I,Product ID,Serial Number,Message,Type-K Thermocouple,C,Thermocouple cold junction temperature,C,*12d9"]

5.4. Lire les données d'un instrument: commande /devices/[serial_number]/data

La commande /devices/[serial number]/data permet d'obtenir une ligne de données mesurées par l'instrument interrogé en temps réel, dans un format identique à celui du mode VCP (enveloppé dans un tableau JSON). Ainsi, pour obtenir un flux ininterrompu de données, il suffit d'invoquer cette commande en boucle, à la fréquence souhaitée. Si les données ne sont pas mises à jour aussi rapidement que souhaité, réglez votre instrument sur un taux de d'interrogation (POLL rate) plus élevé. La fréquence par défaut est de 1 mesure par seconde.

Dans l'exemple suivant, nous invoquons successivement les commandes /devices/E21833/data et /ports/E24616/data pour obtenir successivement les données de nos 2 instruments :

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E21833/data
["D,VCP-PTH450-CAL,E21833,,103364,Pa,25.632866,C,15.953307,%,*ef96"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E24616/data
["D,VCP-TMC200k-CAL,E24616,,25.1954,C,28.3487,C,*2c88"]

Conclusion

L'API REST de Dracal offerte avec le SensGate vous offre la possibilité de déployer rapidement une infrastructure d'instruments de précision sur tout votre réseau et d'accéder aux données sans l'intervention d'un quelconque logiciel tiers. Tout en vous permettant de bénéficier des avantages de la communication COM, il vous permet également de vous affranchir de la dépendance à l'assignement arbitraire des ports grâce à la possibilité d'interroger les capteurs directement par leur numéro de série unique. Si vous n'êtes pas certains que ces caractéristiques offrent un réel avantage pour vous, peut-être que notre outil en ligne-de-commande dracal-sensgate-get pourrait d'avantage vous convenir.