RVCP : une 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é 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 de bénéficier exactement du même avantage: accéder aux données de leurs instruments connectés à leur SensGate 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 communiation Wi-Fi établie sur ce sous-réseau.

L'API RVCP est appelé sur un terminal via l'exécutable curl, disponible sur tous systèmes d'exploitations les plus populaires.

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. 

1.3. Compatibilité avec les format du mode VCP

Toujours dans un objectif d'otimiser 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. À un détail près... 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 (Ari refaire le screenshot ci-dessous) :

 

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 mettre à jour le lien et refaire le screenshot :

 

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]

  • 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 peut être repérée dans votre navigateur erb ainsi que dans l'onglet Network de DracalView Mettre des screenshot
  • :8080 : Port d'accès pour la communication REST avec le SensGate
  • /sensgate/rvcp : Chaîne de caractère fixe 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

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.

Attention: L'allocation des ports est effectuée à l'alimentation d'un SensGate. Ainsi, interchanger les capteurs sur un SensGate déjà en fonction n'affectera pas 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 de 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 peut être utilisé comme identificateur unique d'un instrument dans la limite d'une même session d'alimentation uniquement.

L'exemple ci-dessous nous indique que 4 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","ttyACM2","ttyACM3"]

 

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

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"
}

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM2
{
"port": "ttyACM2",
"time": "2023-12-21T18:46:10+00:00",
"data": "D,VCP-BAR20-CAL,E24253,,103433,Pa,33.07,C,*e4ed",
"info": "I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,MS5611 Temperature,C,*d77e"
}

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM3
{
"port": "ttyACM3",
"time": "2023-12-21T18:46:23+00:00",
"data": "D,VCP-RTD300-CAL,E22156,,25.4744,C,*524e",
"info": "I,Product ID,Serial Number,Message,3-Wire PT100 Temperature sensor,C,*cf04"
}

 

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 à ttyACM3 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"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM2/info
["I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,MS5611 Temperature,C,*d77e"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM3/info
["I,Product ID,Serial Number,Message,3-Wire PT100 Temperature sensor,C,*cf04"]

 

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.

Dans l'exemple suivant, on invoque successivement les commandes /ports/ttyACM0/data/ports/ttyACM1/data, /ports/ttyACM2/data et /ports/ttyACM3/data pour obtenir les données de nos 4 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"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM2/data
["D,VCP-BAR20-CAL,E24253,,103432,Pa,33.48,C,*fc66"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/ports/ttyACM3/data
["D,VCP-RTD300-CAL,E22156,,25.5109,C,*d74e"]

 

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

5.1 Lister les instruments: commande /devices

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

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

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/E22156
{
"device": "E22156",
"time": "2023-12-21T18:59:54+00:00",
"data": "D,VCP-RTD300-CAL,E22156,,25.5089,C,*90c3",
"info": "I,Product ID,Serial Number,Message,3-Wire PT100 Temperature sensor,C,*cf04"
}

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E24253
{
"device": "E24253",
"time": "2023-12-21T19:00:24+00:00",
"data": "D,VCP-BAR20-CAL,E24253,,103427,Pa,33.6,C,*3fdc",
"info": "I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,MS5611 Temperature,C,*d77e"
}

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 /ports/[devices]/info

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/E22156/info
["I,Product ID,Serial Number,Message,3-Wire PT100 Temperature sensor,C,*cf04"]

C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E24253/info
["I,Product ID,Serial Number,Message,MS5611 Pressure,Pa,MS5611 Temperature,C,*d77e"]
C:\Users\MyUser> curl http://192.168.40.1:8080/sensgate/rvcp/devices/E24616/info
{
"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"
}