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 or (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 COMODO root certificate. Comodo is a common SSL provider and is usually included by default in most SSL implementations (OS X, Windows and Linux). If the certificate is not available, you can download the Comodo root certificate off of their website. In most Unix environments, you need to provide the path to your ssl certificates which is often here:

--capath /etc/ssl/certs

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 using this command line parameter:

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

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/devices/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.

Transducer Prefix

Within your endpoint, we have the convention of placing transducers in the /openchirp/devices/TRANSDUCER_ID/transducer directory. This is where services like the Time-series Data Store looks for new data.

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/devices/5a19bb88f76abe01c57abfa6/#'
• The default server is mqtt.openchirp.io

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/devices/5a19bb88f76abe01c57abfa6/#'
openchirp/devices/5a19bb88f76abe01c57abfa6/transducer/motor 10000
openchirp/devices/5a19bb88f76abe01c57abfa6/transducer/motor 5000
openchirp/devices/5a19bb88f76abe01c57abfa6/transducer/motor 60
openchirp/devices/5a19bb88f76abe01c57abfa6/transducer/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/devices/5a19bb88f76abe01c57abfa6/transducer/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/devices/5a19bb88f76abe01c57abfa6/transducer/motor' -m 1000