PubSub Overview

Each device that is created in OpenChirp has an MQTT end-point and can be provisioned with login credentials allowing programs or gateway devices to produce and consume real-time data. This is most useful if you are writing a program (like a gateway device) that is producing sensor data or if you are writing something like a stream-processing service.

Security

The MQTT server has TLS enabled so that all traffic is encrypted. There are two ways to connect to the broker:

1. as a user with a user token
2. as a device with a device token.

A user has the same read and write access in MQTT as the same user account would have in the web portal or REST. A device has scoped write access to just the device's end point. This is useful for programs that produce data for a single device. For gateways that produce data for many devices, it might be easier to use the user credentials.

To begin, you should install:

1. OpenSSL
2. Mosquitto (a common MQTT library).

You need to make sure to select a CA credential file or path that has the IdentTrust - TrustID X3 root certificate. IdentTrust is a common SSL provider and is usually included by default in most SSL CA certs libraries (OS X, Windows and Linux). If the certificate is not available, you can download the TrustID X3 root certificate from their website using the below instructions.

Standard GNU/Linux Environment

In most Unix environments, you need to provide the path to your ssl certificates which is often /etc/ssl/certs.

Include the following in you mosquitto_sub command arguments list.

--capath /etc/ssl/certs

OSX Environment

In OS X, for many clients like Mosquitto, we found that you need to point directly to the CA file. You can find the path by running:

$ openssl version -d
OPENSSLDIR: "/Users/USER_NAME/anaconda/ssl"

With mosquitto, you can point to the cafile directly by using this command line parameter:

--cafile /Users/USER_NAME/anaconda/ssl/cacert.pem

Other Environemnt

Although we use Let's Encrypt to issue certificates for our services, Let's Encrypt's own root certificate authority, ISRG Root X1, is still quite new and not commonly trusted. To get around this issue, Let's Encrypt's intermediate has be graciously cross-signed by IdentTrust's root certificate authority DST Root CA X3, which is commonly trusted by clients.

What this means for you is that you need to provide the IdentTrust's root CA cert for verification. To obtain the DST Root CA X3 cert, issue the following commands:

wget https://www.identrust.com/node/935 -O trustidrootx3_chain.p7b
openssl pkcs7 -inform DER -in trustidrootx3_chain.p7b -print_certs -outform PEM -out trustidrootx3_chain.pem

You can then use the resulting trustidrootx3_chain.pem as the --cafile agrument.

Observe Endpoint

Any device you create will be given an MQTT endpoint that can be found on the properties page of the web portal. The endpoint will be /openchirp/device/TRANSDUCER_ID. You can generate a device token if you go to the Security tab. For a user ID and token, go to the "My Profile" page. Your user ID may not be your email address, so please double check on the web portal.

Endpoint Hierarchy

Topic names that occur immediately following your endpoint are considered transducers. Transducers are visible from the web interface and can be recorded by the time series service. For example /openchirp/device/DEVICE_ID/jetpack_thrust represents the jetpack_thrust transducer, which corresponds to the jetpack_thrust transducer on the website.

Any topic that is nested deeper than the first level of your endpoint is considered a hidden topic. For example /openchirp/device/DEVICE_ID/metric/jetpack_temp_degc represents a hidden topic jetpack_temp_degc because it is under the subpath metric. We may then use the Math-Evaluate service to pickup this value, convert it to degrees F, and republish it to the real transducer /openchirp/device/DEVICE_ID/jetpack_temp. This can be useful as a scratch space for values to be converted, as in this example, or as a place where excess data is published that should not be logged.

Subscribe Example

Below is an example of subscribing to a device using the built-in Mosquitto tool with the following attributes:

• user is set to Device ID: 5a19bb88f76abe01c57abfa6
• password is set to Device Token: 0U3dAX3SBrSTc99yNLgeFF0AALq1Rez
• subscribing to end all activity on its endpoint: 'openchirp/device/5a19bb88f76abe01c57abfa6/#'
• The default server is mqtt.openchirp.io on port 8883

Make sure to set the -i identifier flag to something unique or Mosquitto will silently fail.

$ mosquitto_sub -v -i monitor2369 -h mqtt.openchirp.io --cafile /Users/USER_NAME/anaconda/ssl/cacert.pem -u 5a19bb88f76abe01c57abfa6 -P 0U3dAX3SBrSTc99yNLgeFF0AALq1Rez -t 'openchirp/device/5a19bb88f76abe01c57abfa6/#'
openchirp/device/5a19bb88f76abe01c57abfa6/motor 10000
openchirp/device/5a19bb88f76abe01c57abfa6/motor 5000
openchirp/device/5a19bb88f76abe01c57abfa6/motor 60
openchirp/device/5a19bb88f76abe01c57abfa6/motor 5000

You should see values update using the "Command" buttons online or if you publish values manually as shown below.

Publish Example

Below is an example of publishing to a device using the built-in Mosquitto tool with the following attributes:

• user is set to Device ID: 5a19bb88f76abe01c57abfa6
• password is set to Device Token: 0U3dAX3SBrSTc99yNLgeFF0AALq1Rez
• setting the 'motor' transducer: 'openchirp/device/5a19bb88f76abe01c57abfa6/motor' to 1000
• The default server is mqtt.openchirp.io

Make sure to set the -i identifier flag to something different from your subscriber or Mosquitto will silently fail.

$ mosquitto_pub -i randomID123 -h mqtt.openchirp.io --cafile /Users/USER_NAME/anaconda/ssl/cacert.pem -u 5a19bb88f76abe01c57abfa6 -P 0U3dAX3SBrSTc99yNLgeFF0AALq1Rez -t 'openchirp/device/5a19bb88f76abe01c57abfa6/motor' -m 1000