1. Everactive
  2. Edge Developers
  3. Documentation

MQTT subscription for real time data

Updated
Keal Harter
Have more questions? Submit a request

 

Everactive’s Managed Network ensures connectivity, uptime, and reliable & secure data transfer into our Platform. We understand that you need a steady stream of new data to transform it into high-value insights to package as innovative, hyper-scale IoT applications to your end users. The Everactive Edge Platform gives you direct programmatic access to the data returned by the Eversensors. The data is made available via different channels: RESTful APIs, Webhooks, or MQTT Subscriptions.

 

mceclip0.png

 

The MQTT Subscriptions service is particularly useful to obtain the data as a steady stream, and as fast as possible. Everactive’s outbound subscriptions are designed to deliver the sensor data as soon as we have it ready for consumption. Once a sensor reading has been properly decoded and enriched, it is sent to an MQTT client for delivery to your Broker.

 

mceclip1.png

Integration with AWS IoT Core

1. Create API Keys

The MQTT Subscriptions are created via the Everactive Platform API. Before we can make any request, we have to prepare a set of Keys that will grant us access to the API. If you haven’t already, use this guide to create your first set of API Credentials. Make sure you have included the privileges for User and Developer in the scope. Retrieve the Client ID and the Client Secret and keep them handy, we’ll need them for our exercise.

2. Authenticate to get an Access Token

Everactive API follows the OAuth2 security flow. To test your credentials you need to make an authentication request using the Client ID and Secret you just created:

 

\ 1 curl --request POST 
\ 2 --url https://api.data.everactive.com/auth/token 
\ 3 --header 'Content-Type: application/json' 
\ 4 --data '{ 
\ 5 "client_id": "{your API client id}", 
\ 6 "client_secret": "{your API secret }", 
\ 7 "grant_type": "client_credentials" 
\ 8} 
\ 9'

This will return a response with a valid access_token, you will use this token for the next requests.

 

mceclip2.png

 

3. Retrieve your List of Sensors and Customer ID

Let’s give this access token a try by getting the list of active sensors in your account and your own Customer ID — You will need this ID in the next steps.

\ 1curl --request GET 
\ 2 --url 'https://api.data.everactive.com/ds/v1/eversensors?page=1' 
\ 3 --header 'Authorization: Bearer {the token goes here}'

 

The response is an array of Eversensor data that includes, for every sensor, its last reading and the associated customer account. Take note of the customer id, (we will use 4d323690-6b81-45a1-8000-000000000000 for this example) we will use it in our MQTT subscription.

 

Prepare your AWS IoT Core settings

We are going to use AWS IoT Core as the target MQTT Broker for this exercise. Before creating the subscription we need to set the service to accept our connection and data. There is some useful documentation in the AWS IoT Core website.

Before we set things up, we need to understand how the Everactive Platform MQTT Client will behave.

 

mceclip3.png

 

The Everactive MQTT Client will establish a connection with AWS IoT Core using X.509 client certificates and a unique MQTT Client ID provided by the user or one that is generated with a random string. For example, in our case we can designate a Client ID Prefix as iotcoretest

Once the connection has been successfully established, the MQTT Client will begin publishing messages — as they arrive from the edge— to a particular set of topics that include the Customer ID, the type of message, schema information, and the device identification. Optionally, an MQTT Topic prefix can be set in order to organize the Everactive topics within an existing topics tree. The topic structure will follow this pattern:

{prefix}/{Customer ID}/sensor_reading/{schema}/{version}/reading/{mac}

In our case, a topic with vibration readings could look like this:

4d323690-6b81-45a1-8000-000000000000/sensor_reading/vibration-electrical/v1/reading/bc:5e:a1:ff:fe:00:56:fb

  • Customer ID: 4d323690-6b81-45a1-8000-000000000000

  • Message Type: sensor_reading

  • Message Schema: vibration-electrical/v1/reading

  • Device Identification: bc:5e:a1:ff:fe:00:56:fb

    More details can be found at the Everactive MQTT Async API docs.

    Now let’s set up AWS IoT Core to receive your data:

    1. Create a new “Thing”. We are going to call it “dev_everactive_mqtt_subscription”.

    2. Attach a Certificate to the device as the means of authentication.

mceclip4.png
  1. Certificate

  2. Create a Policy in that certificate to allow access for message publication and subscription. Our policy name is “dev_everactive_mqtt_subscription-PolicyInfo”, and the access rules we need are:

    1. Allow Connect actions to a client id with the prefix iotcretest.

    2. Allow Subscribe actions to topics with a filter that includes our Customer ID and the sensor_reading message type: 4d323690-6b81-45a1-8000-000000000000/sensor_reading*

    3. Allow Publish and Receive actions to topics with the same filter: 4d323690-6b81-45a1-8000-000000000000/sensor_reading*

 {
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:*************:client/iotcoretest-*"
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1::*************::topicfilter/4d323690-6b81-45a1-8000-000000000000/sensor_reading*"
},
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Receive"
],
"Resource": "arn:aws:iot:us-east-1::*************::topic/4d323690-6b81-45a1-8000-000000000000/sensor_reading*"
}

 

These rules should allow the publication in a topic like in our example:

4d323690-6b81-45a1-8000-000000000000/sensor_reading/vibration-electrical/v1/reading/bc:5e:a1:ff:fe:00:56:fb

mceclip5.png

 

 

Create an MQTT Subscription via the Everactive API

Now that we have set up the AWS IoT Core broker, we can proceed to create an MQTT Subscription to connect and deliver the data. We do this by calling the Everactive API MQTT endpoints:

 

 

1 curl --request POST \
2  --url https://api.data.everactive.com/ds/v1/mqtt-subscriptions \
3  --header 'Authorization: Bearer {your access token goes here}' \
4  --header 'Content-Type: application/json' \
5  --data '{
6  "enabled": true,
7  "customerId": "4d323690-6b81-45a1-8000-000000000000",
8  "mqttConfig": {
9    "mqttUrl": "ssl://a3onduf381ngr3-ats.iot.us-east-1.amazonaws.com:8883",
10    "mqttClientPrefix": "iotcoretest",
11    "mqttQos": 0,
12    "mqttAuth": "tls",
13    "mqttKey": "-----BEGIN RSA PRIVATE KEY-----the pem content\nof the private key\n----END RSA PRIVATE KEY-----",
14    "mqttCert": "-----BEGIN CERTIFICATE-----the pem content\nof the public key\n-----END CERTIFICATE-----",
15    "mqttCA": "-----BEGIN CERTIFICATE-----the pem content\nof the CA cert\n-----END CERTIFICATE-----"
16  }
17}'

Let’s take a closer look at the request body:

  • "enabled": true so that the MQTT Client starts the connection immediately.

  • "customerId": "4d323690-6b81-45a1-8000-000000000000", This is our Customer ID

  • "mqttUrl": "ssl://a3onduf381ngr3-ats.iot.us-east-1.amazonaws.com:8883" This is the AWS IoT Core endpoint.

  • "mqttClientPrefix": "iotcoretest", The Client ID Prefix we set up in the CONNECT security policy.

  • "mqttKey", "mqttCert", and "mqttCA" are the PEM content of the X.509 Certificates provided by AWS IoT Core.

 $ mosquitto_sub --cert dev_everactive_mqtt_subscription.cert.pem \
--key dev_everactive_mqtt_subscription.private.key \
--cafile root-CA.crt -h a3onduf381ngr3-ats.iot.us-east-1.amazonaws.com \
-v -i iotcoretest-mosquitto-2 -d -v -t '4d323690-6b81-45a1-8000-000000000000/sensor_reading/#'

Validate the data flow

After a few seconds, once the subscription has been deployed you will see the data flowing — based on the sensors update rate— to the MQTT Broker. We can use a mosquitto.org client to peak at the data flow. Using the same TLS credentials we can establish a subscription connection:

mceclip0.png

Support

If you run into any issue, please contact us at success@everactive.com for support; we will gladly help you.

 

Reference Documentation

Articles in this section

See more
Was this article helpful?
0 out of 0 found this helpful
Share

Comments

0 comments

Please sign in to leave a comment.