This add-on is operated by LogMeIn, Inc
Xively IoT Platform Connector for Heroku
Last updated 11 May 2016
Table of Contents
The Xively add-on for Heroku provides resources needed to begin using the Xively IOT platform.
The Xively IOT platform is a collection of services for building IOT applications. The Xively add-on allows you to use the platform’s messaging service, so you can see how an Internet-connected product would use the messaging service with an IOT application.
Provisioning the add-on
The Xively add-on can be attached to a Heroku application via the CLI:
$ heroku addons:create xively
After installing the Xively add-on, the Heroku application can use Xively’s messaging service to send and receive messages using an MQTT library.
The UUID of the Xively account the resources are provisioned under. The account ID is used on the MQTT topic names.
The fully-qualified DNS domain name for the Xively MQTT broker.
The standard TCP port for the Xively MQTT broker.
The websockets TCP port for the Xively MQTT broker, when used from a browser-based MQTT client.
The name of the control channel provisioned for the Xively account. The purpose of the control channel is to send commands to a device from an IOT application. In a production Xively implementation, you can configure as many channels as you want and use them as you see fit.
The name of the data channel provisioned for the Xively account. The purpose of the data channel is to send information (such as telemetry) from a device to an IOT application. In a production Xively implementation, you can configure as many channels as you want and use them as you see fit.
The UUID for the device. The UUID provides device identity, it is a unique identifier (name) for the device. The add-on provisions one device. In a production Xively implementation, there would be many devices, one for each connected product or unit.
The password for the device. The password provides device authentication, it is a uniquely assigned to the device. In a production Xively implementation, every device would have a unique password.
The UUID for the device user. The UUID provides user identity, it is a unique identifier (name) for the user of a device. The add-on provisions one user. In a production Xively implementation, there would be many users, who can be associated with devices in multiple ways.
The password for the user. The password provides user authentication, it is uniquely assigned to the user. In a production Xively implementation, every user would have a unique password.
MQTT topic names
MQTT topic names are derived from the environment variables as follows:
For example, given the following output from
XIVELY_ACCOUNT_ID: c4ce07f5-683c-4f0a-8bbb-518bd6239543 XIVELY_BROKER_HOST: broker.demo.xively.com XIVELY_BROKER_PORT: 8883 XIVELY_BROKER_WS_PORT: 443 XIVELY_CHANNEL_CONTROL: control XIVELY_CHANNEL_DATA: data XIVELY_DEVICE_ID: c02c3f93-9f7f-4a4c-b5e1-a8bdfa90158a XIVELY_DEVICE_PWD: T5CmBSrG/1BHod2XVLI58giOSomTSUYACIENQBQOw/8= XIVELY_USER_ID: 4f371229-1a8b-4ab3-9dcc-5d941ca53134 XIVELY_USER_PWD: wr+DsJ6VBTRQnabBuM4tg7kdtFjsXphL8l8FUmHtIkU=
The MQTT topic for the device’s data channel is:
The credentials above are examples and are not usable within an application.
MQTT client example
Here is an example of mapping the env vars to publish/subscribe calls in the mosquitto MQTT client. Mapping of the env vars to other MQTT libraries (e.g., mqtt.js) is straightforward.
mosquitto_pub \ -d \ -q 0 \ -p $XIVELY_BROKER_PORT \ -h $XIVELY_BROKER_HOST \ -i $XIVELY_DEVICE_ID \ -u $XIVELY_DEVICE_ID \ -P $XIVELY_DEVICE_PWD \ -t xi/blue/v1/$XIVELY_ACCOUNT_ID/d/$XIVELY_DEVICE_ID/$XIVELY_CHANNEL_DATA \ -m "Hello world" \ --cafile gsroot.pem
mosquitto_sub \ -d \ -q 0 \ -p $XIVELY_BROKER_PORT \ -h $XIVELY_BROKER_HOST \ -i $XIVELY_USER_ID \ -u $XIVELY_USER_ID \ -P $XIVELY_USER_PWD \ -t xi/blue/v1/$XIVELY_ACCOUNT_ID/d/$XIVELY_DEVICE_ID/$XIVELY_CHANNEL_DATA \ --cafile gsroot.pem
Removing the add-on
The Xively add-on can be removed via the CLI.
$ heroku addons:destroy xively