Output

Intro

This section describes how to get data out of Vision 42. Manually, this can be done by the press of a button:

• Download a project

• Download plot data

Under the IO tab, automatic output can be configured by administrators. The standard URL syntax is used to describe output locations. A password or other secret goes into the dedicated secret field. Transient errors will be indicated by a clickable exclamation mark. They will be cleared automatically, once solved.

A network protocol method can either pull or push data. Let's have a closer look at both. Live examples can be found in the demo app.

Note: all TLS connections (Transport Layer Security) use a certificate that is signed by a universal trusted CA (certificate authority), domain validated (DV) and valid for 90 days.

Pull data

Vision 42 can serve real-time data to polling clients, using the following protocol methods.

HTTP GET

Hypertext Transfer Protocol

The many endpoints are part of the REST API and serve both metadata and data. Administrators can grant access in the output table, based on:

• User-password: URL http:{user} and secret password

• Token: URL http:token and secret token

• Fixed address: URL http:ip and secret IPv6 or IPv4

The first two require a standard Authorization header, respectively Basic and Bearer. For access to all projects, use: http:{user}*

OPC-UA

Vision 42 comes with an integrated server, which provides data, alerts, and outages to SCADA clients (Supervisory control and data acquisition):

• Address: vision42.net

• Port 4843 (default): production

• Port 4844: quality assurance

• Port 4845: development

• Anonymous access: not allowed

Administrators can grant access in the output table; URL opc.tcp:{user} and secret password.

The shared namespace is populated dynamically so new projects, devices, and channels appear instantly.

A channel alert indicates its level, corresponding to the four thresholds: -2,-1,0,1,2. Aggregations per device and per project equal the maximum absolute level: 0,1,2.

A channel outage is a simple boolean: false,true. Aggregations per device and project indicate the outage percentage.

Push data

Data and events can be forwarded in real-time, using these efficient protocol methods. To avoid message loss while offline, Vision 42 will retry with an exponential back-off. The payload is described below.

HTTP POST

Vision 42 can post data and events to an endpoint. Destination URLs have the following base forms, depending:

• https://user@server/endpoint for Basic authentication (secret password)

• https://server/endpoint for Bearer authentication (secret token)

• https://server/endpoint?key=SECRET for parameter authentication (secret value)

The first two will send a standard Authorization header, respectively Basic and Bearer. Available variants, including TLS: HTTP and HTTPS.

MQTT publish

Message Queuing Telemetry Transport

Vision 42 can publish a data stream on a broker. URLs will typically look like this:

• mqtts://user@broker#topic

• wss://user@broker/path#topic

Available variants, including TLS and WebSocket: MQTT, MQTTS, WS, and WSS. The QoS (Quality of Service) level is 1 for data and 2 for events. Standard version 5 will be used. If needed, exceptions can be made for versions 3.1.1 and 3.1. The topic will be suffixed by a device name.

Extension:

• Microsoft Azure Event Grid can authorize our certificate.

MQTT subscribe

Vision 42 has an integrated broker, which allows subscribing to a data stream:

• Protocol: MQTTS

• Address: vision42.net

• Port 8883 (default): production

• Port 8884: quality assurance

• Port 8885: development

• Offline persistence: 1 week, including QoS 0 messages

• Credentials and topic: to be requested by ticket

In the output table, a URL mqtt:{topic} will publish the given project under that topic.

AMQP publish

Vision 42 can publish a data stream on a broker queue. A typical URL will have this form: amqps://user@broker/vhost#queue

Available variants, including TLS: AMQP and AMQPS. Standard 0-9-1 is supported.

SFTP PUT

A JSON Lines file can be appended with real-time data and events. The URL looks like this: sftp://user@server/directory/file

While a password may be used, it is recommended to authorize our public key:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0skCWi+E3HMQgeuINQPYnO24K96JIGMVrca9xUzrtnbws31DeDkec0y+DH4ilUpZbEb2I+6krcQYEZnn92/IHBADJj7+iRBtmZJhPvguloaNygyBLF4E0yk6YB2PBdGXuoY/trGWj4h3h9NPKXpbkQwZtfmj8v4cQ7QGxbatmn62/piHfgY9tnL7ZpN9oxO4AQdSUisU4knPZViS7Go4Rj2bPDSVssqI+vCeNONjnvdSHXibwlIb/AiHMXJfSLEZytCnC1Ran9z9fPUWP0xCh+pHVKVv7hVwW6jc0R6081e4amBZOWsMiskoY/0CQGAfek9E6ON8yz7d+k7dKu2QZ Vision 42

FTP PUT

Similar to SFTP, a JSON Lines file can be appended with real-time data and events. The URL looks like this: ftps://user@server/directory/file

Available variants, including TLS: FTP and FTPS. The former is insecure and thus not recommended. Only extended passive mode is supported (EPSV and EPRT).

S3 PUT

Real-time data and events can be written as prefixed JSON objects in a bucket, using a URL of this form: s3://{access_key_ID}@{endpoint}/{bucket}/{prefix}/#region

The secret access key goes into the secret field. The prefix is optional. For Amazon S3, the endpoint s3.amazonaws.com may be used. Other providers, like Cloudflare R2 or MinIO, will specify the endpoint.

Warning: commercial S3 providers will charge the request costs.

FILE append

A file:{app}/{file} URL may be used internally to forward real-time data to another Vision 42 instance.

Payload

The data payload looks like this and has generic and channel properties:

{

  "device": "Indoor air quality",

  "id": "58A0CB000011D9C3",

  "latitude": 50.964592,

  "longitude": 3.72257827,

  "altitude": 21,

  "epsg": 31370,

  "easting": 104607.24027609851,

  "northing": 184011.27231100108,

  "time": "2024-06-16T15:49:23.785Z",

  "CO₂ [ppm]": 792,

  "Indoor air quality": 69,

  "Relative humidity [%]": 74,

  "Temperature [°C]": 20,

  "Volatile organic compounds [ppm]": 1

}

• Format: JavaScript Object Notation (JSON), implying UTF-8 character encoding

• Coordinates: World Geodetic System (WGS 84) and local EPSG easting and northing

• Date/time: ISO 8601 / RFC 3339 / RFC 9557 with milliseconds in Coordinated Universal Time (UTC)

• Values: not invalid and relative to their instrument datum, if any

For profile data, a convenient structure will be added:

"profile": [

 {

  "A [mm]": 24.04,

  "B [mm]": 4.6,

  "z [mASL]": 64.25

 },

 {

  "A [mm]": 23.67,

  "B [mm]": 4.54,

  "z [mASL]": 63.75

 },

 {

  "A [mm]": 24.03,

  "B [mm]": 5.06,

  "z [mASL]": 63.25

 },

 ...

]

The event payload is similar:

{

  "device": "Indoor air quality",

  "id": "58A0CB000011D9C3",

  "latitude": 50.964592,

  "longitude": 3.72257827,

  "altitude": 21,

  "epsg": 31370,

  "easting": 104607.24027609851,

  "northing": 184011.27231100108,

  "time": "2023-11-13T12:31:39.588Z",

  "channel": "CO₂ [ppm]",

  "type": "!",

  "event": "1005 > 994 ppm"

}