Looking for a quote?

Documentation of RVCP: REST API for VCP sensors on SensGate

1. Introduction

Most Dracal instruments can be equipped with the VCP option (Virtual COM Port). One of the main advantages of opting for an instrument with this option is integrating its data without relying on third-party applications, such as our dracal-usb-get command-line tool. Our REST API named RVCP, natively installed on the SensGate, now enables owners of instruments with the VCP option to connect them to their SensGate and access their data remotely without relying on proprietary third-party software. RVCP lets you simultaneously enjoy the benefits of COM communication offered in VCP mode and the wireless connectivity offered by the SensGate without compromise.

1.1. About this documentation

This documentation is built from a computer running Windows 11. The computer accesses the SensGate with a unique serial number G00033 configured in AP (Access Point) mode via a Wi-Fi connection established on this subnetwork.

In the examples, the RVCP API is called on a terminal via the curl executable, available on all popular operating systems. Note that making calls directly via your web browser is also possible. For example, if the command curl http://192.168.40.1:8080/sensgate/rvcp/devices is called in a terminal, the same command without the curl (i.e. http://192.168.40.1:8080/sensgate/rvcp/devices) can be invoked in your browser like this:

 

1.2. Restrictions and safety

Whether access to your SensGate web interface is password-protected or not, data from instruments connected to it can be listened to by our tools, including the RVCP REST API. It's up to you to assess the risks associated with accessing the data you produce, even without the context in which it's used.

1.3. Compatibility with VCP mode output formats

Always intending to optimize the time already invested in your projects to integrate data from your Dracal instruments, the RVCP API for SensGate identically reproduces the data format as returned by your instruments communicating in VCP mode. However, to comply with best practices in REST architectures, the results of commands are wrapped in a simple JSON array.

2. Prerequisites

1. Own instruments with VCP option (e.g. VCP-PTH450-CAL, VCP-RTD300, VCP-...)

2. Own a SensGate and have read the documentation to quickly get started with the SensGate

3. Make sure your SensGate version is 1.1.1 or newer:

 

If your version is older, or if you're not sure, download the latest firmware update here and follow the 4 steps below:

3. Resource access point

A REST (REpresentational State Transfer) API is a style of software architecture that defines a set of constraints for creating web services. REST architecture is based on several well-established fundamental principles. One of these is that resources (objects or services) in a REST API must be identified by URIs (Uniform Resource Identifiers).

 

URIs in the RVCP API for SensGate are URLs in the following format:

http://[SensGate IP address]:8080/sensgate/rvcp/[commands]

where

    • http://: Whether the SensGate web interface is password-protected (https) or not (http), communication for RVCP uses http
    • [SensGate IP address] : The SensGate's IP address, which can be tracked in your web browser
      and in the Network tab of DracalView

  • :8080 : Access port for REST communication with the SensGate. It has been set by Dracal Technologies and is identical for all users.
  • /sensgate/rvcp : Character string, also a constant, which is the access point for the RVCP API and its commands
  • [commands] : Commands supported by the API and described below

4. Available commands: from ports

Important: Ports are allocated when a SensGate is powered up. So, swapping sensors on a SensGate that is already in operation should not affect the ports assigned to each as long as the SensGate remains on. However, the next time the SensGate is switched off/re-powered, it will reassign ports to each sensor, and this reassignment may be different from the previous allocation if they are no longer connected in the same configuration. Thus, a port should not be used as a unique identifier for an instrument. We also offer you the possibility of querying your sensors directly by their serial number in section 5 of this documentation.

If, despite this, querying by port is what you need, then this section is for you.

4.1. List ports: command /ports 

The /ports command lists the ports to which instruments communicating in VCP mode are connected.

The example below shows that 2 instruments communicating in VCP mode are currently connected to the SensGate used to build this documentation:

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

4.2. Get all instrument details: command /ports/[port]

Now that the list of available ports has been obtained, it is possible, port by port, to fetch the details corresponding to each one. In the example below, both the device information associated with ports ttyACM0 and ttyACM1 are obtained:

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. Get instrument information (the result of VCP INFO command): command /ports/[port]/info

The /ports/[port]/info command returns the result of the INFO command in VCP mode, wrapped in JSON format. In the example below, ports ttyACM0 to ttyACM1 are queried one after the other:

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. Read data from an instrument: command /ports/[port]/data

The /ports/[port]/data command is used to obtain a line of data measured by the queried instrument in real-time, in a format identical to that of VCP mode (wrapped in a JSON array). So, to obtain an uninterrupted stream of data, simply invoke this command in a loop at the desired frequency. Should data not be updated as quickly as required, set your instrument to a higher POLL rate. The default rate is 1 measurement per second.

In the following example, we successively invoke the /ports/ttyACM0/data and /ports/ttyACM1/data commands to obtain data from our 2 instruments in succession:

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. Available commands: from unique serial numbers

The commands presented in section 4 above are also available from the “devices” rather than “ports” root, allowing you to query sensors by their unique serial number rather than the port to which they are connected. The same remarks made in section 4 apply to each of these commands.

5.1 List devices: command /devices

The /devices command lists the serial numbers of Dracal instruments connected to the SensGate and communicating in VCP mode.

The example below shows that 2 instruments communicating in VCP mode are currently connected to the SensGate used to build this documentation:

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

5.2 Get all the details of a device: command /devices/[serial_number]

Now that the list of available ports has been obtained, it is possible, device by device, to fetch the details corresponding to each one. In the example below, both the device information associated with instruments with serial number E21833 and E24616 are obtained:

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 Obtain instrument information (result of VCP INFO command): command /devices/[serial_number]/info

The /devices/[serial number]/info command returns the result of the INFO command in VCP mode, wrapped in JSON format. In the example below, sensors with serial number E21833 and E24616 are queried one after the other:

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. Read data from an instrument: command /devices/[serial_number]/data

The /devices/[serial number]/data command is used to obtain a line of data measured by the queried instrument in real-time, in a format identical to that of VCP mode (wrapped in a JSON array). So, to obtain an uninterrupted stream of data, simply invoke this command in a loop at the desired frequency. Should data not be updated as quickly as required, set your instrument to a higher POLL rate. The default rate is 1 measurement per second.

In the following example, we successively invoke the /devices/E21833/data and /ports/E24616/data commands to obtain data from our 2 instruments in succession:

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

The Dracal REST API offered with SensGate allows you to rapidly deploy a precision instrument infrastructure across your entire network and access data without the intervention of any third-party software. Along with enjoying the benefits of COM communication, it also frees you from dependence on arbitrary port assignment, thanks to the ability to interrogate sensors directly by their unique serial number. If you're unsure whether these features offer a real advantage, perhaps our dracal-sensgate-get command-line tool might be more suitable.