Skip to content
English - United Kingdom
Verv Portal
  • There are no suggestions because the search field is empty.

Verv Device Live Data API Guide

The below guide details the Verv Live Data API that can be utilised by users.

Overview

The live data is published all the time the device is on and the API provides the user with a way to subscribe to this data feed. Verv uses the MQTT protocol and is backed by the industry standard AWS MQTT broker in the Cloud. The MQTT protocol has become a standard for IoT data transmission because it delivers the following benefits:

Reliable - Many IoT devices connect over unreliable cellular networks with low bandwidth and high latency. MQTT has built-in features that reduce the time the IoT device takes to reconnect with the cloud. It also defines three different quality-of-service levels to ensure reliability for IoT use cases— at most once (0), at least once (1), and exactly once (2).

Secure - MQTT makes it easy for developers to authenticate devices and users using modern authentication protocols, such as OAuth, TLS1.3, Customer Managed Certificates, and more.

Lightweight and efficient - MQTT implementations require minimal resources. For example, a minimal MQTT control message can be as little as two data bytes. MQTT message headers are also small so that you can optimise network bandwidth.

Scalable - MQTT implementation requires a minimal amount of code that consumes very little power in operations. The protocol also has built-in features to support communication with a large number of IoT devices. Hence, you can implement the MQTT protocol to connect with millions of these devices.

Well-supported - Several languages like Python have extensive support for MQTT protocol implementation. Hence, developers can quickly implement it with minimal coding in any type of application.

How to connect to the live feed

You need an MQTT client to be able to connect to Verv Live Data API. The client will require 4 key bits of information in order to connect and subscribe to your live data feed

  1. The broker endpoint address of Verv’s AWS MQTT broker

  2. The MQTT client id, which must start with the company name and a dash

  3. The topic name that you wish to subscribe to

  4. Security certificates/credentials

Verv (Green Running Limited)

Sustainable Workspaces County Hall, 5th Floor Belvedere Road London, SE1 7PB

Verv (Green Running Limited) , Sustainable Workspaces, Riverside Building, County Hall, 3rd, Westminster Bridge Rd, London, SE1 7PB

Once you have been assigned API capability, the Verv team will provide an API pack that will contain all 4 items above.

The broker endpoint will be of the form:
"xxxxxxxx-ats.iot.eu-west-2.amazonaws.com", where xxxxxxxx is replaced by a specific

string
The client id must start with the company name (or short version agree with Verv) and a

dash, of the form:

"<company-name>-xxx” e.g. “acme-007”

The topic name will be provided and will be of the form: “api/<company_name>” e.g. “api/acme/+”

You must include “/+” at the end of topic, in order to subscribe to anything on that topic

The security documents are 3 separate files, the root CA certificate (trusted certificate authority), the customer specific certificate and your private key. These must be kept secure and are the only way to access the Live API. These 3 files together are used to form the TLS security context required to access the live feed.

Example Code

We have created a simple easy to follow example of how to connect to the live feed using the popular Python MQTT library Paho.

The following code is from the main section:

# Create a Paho MQTT client object and pass in company name
mqttc = mqtt.Client(client_id="<company_name>-XXX")
# Create and add security context
ssl_context= ssl_alpn()
mqttc.tls_set_context(context=ssl_context)
# Attach callbacks to on_message and on_subscribe events
mqttc.on_message=on_message
mqttc.on_subscribe=on_subscribe
logger.info("start connect")
# Connect to AWS IOT
mqttc.connect(aws_iot_endpoint, port=443)
logger.info("connect success")
# Subscribe to topic
mqttc.subscribe("api/<compnay_name>/+")
mqttc.loop_start()

The following code demonstrates how to decode the MQTT payload:

Verv (Green Running Limited) , Sustainable Workspaces, Riverside Building, County Hall, 3rd, Westminster Bridge Rd, London, SE1 7PB

def on_message(client, userdata, message):
    # Example decoding of the live feed in the on_message callback
    live_feed = json.loads(str(message.payload.decode("utf-8")))
    logger.info(f"topic: {message.topic} qos: {str(message.qos)}")
    logger.info(f"device: {live_feed['Device']}, real power: {live_feed['RealPower']}")

A full working example will be included in the API pack.

We would expect the terminal to show an output to be similar to that shown below:

2023-07-20 13:49:45,872 - root - INFO - open ssl version:OpenSSL 1.1.1k  25 Mar
2021
2023-07-20 13:49:45,907 - root - INFO - start connect
2023-07-20 13:49:46,059 - root - INFO - connect success
2023-07-20 13:49:46,149 - root - INFO - on_subscribe id: 1 granted qos: (0,)
2023-07-20 13:49:46,206 - root - INFO - topic: api/acme/VCP20000101 qos: 0
2023-07-20 13:49:46,206 - root - INFO - device: VCP20000101, real power: 872.13W
2023-07-20 13:49:47,244 - root - INFO - topic: api/acme/VCP20000101 qos: 0
2023-07-20 13:49:47,245 - root - INFO - device: VCP20000101, real power: 1032.45W
2023-07-20 13:49:48,294 - root - INFO - topic: api/acme/VCP20000101 qos: 0
2023-07-20 13:49:48,295 - root - INFO - device: VCP20000101, real power: 894.76W

Note: This particular feed is published ~every second your feeds may be set up differently.

Frequently Asked Questions

What topics can we subscribe to?

As above the API provides access to your devices on an “api/<company_name>/” topic. All devices owned by your company that have been designated to have an API associated with them, will publish to this topic, with a specific topic name per device. You can choose to subscribe to the generic topic using “api/<company_name>/+”,or an individual specific device’s topic e.g. “api/<company_name>/<device_serial>”

What is an MQTT broker?

MQTT is a server-client base message protocol that requires a broker to act as the server and acts as a central point for clients to connect to. It distributes messages as required and is able to police security, quality of service and other integral parts of the service.

Do we have to use Python and Paho?

No this is just an example code, there are many available examples of client MQTT implementations in multiple languages. You also don’t have to use Paho even if you are using Python, there are other great MQTT frameworks available.