MQTT.md

Communicating with IoT Analytics with MQTT

An extensive REST API is provided for users to interact with the IoT Analytics server.

Basics

Users must publish to the IoT Analytics broker using a secure connection. Device authentication uses the device's ID and activation token. The CA certificate installed with the iotkit-agent must be used for the TLS connection.

Connection options

• broker: broker.us.enableiot.com
• port: 8883
• username: device-ID of the device to publish from
• password: device-token assigned to the device during initial activation
• Use TLS: yes
• CA certificate(s): /usr/lib/node_modules/iotkit-agent/certs/AddTrust_External_Root.pem (default install location on Galileo/Edison)

Supported Topics

Action	Request Topic (Publish)	Response Topic (Subscribe)	Description
activate	device/{deviceid}/activation	server/devices/{deviceid}/activation	Send activation code and check device activation status
update device metadata	server/devices/{deviceid}/metadata	n/a	Update device metadata (attributes, tags, description, etc.)
submit data	server/metric/{accountid}/{gatewayid}	n/a	Submit data observation
add component	server/devices/{deviceid}/components/add	device/{deviceid}/components	Register a new component (sensor) and verify status
health	server/devices/{deviceid}/health	device/{deviceid}/health	Request health information and build version of Dashboard
component catalog	server/devices/{deviceid}/cmpcatalog	device/{deviceid}/cmpcatalog	Display the account's component-type catalog
control command	n/a	device/{gatewayid}/control	Receive actuations sent from Dashboard

Request Topics

Activate Device

Topic: device/(device id)/activation
Message:
{
    "deviceId": (device id),
    "deviceToken": (device token),
    "activationCode": (activation code),
}

####Update Device Metadata

Topic: server/devices/(device id)/metadata
Message:
{
	"attributes": {
		"agent_version": "1.7.0",
		"hardware_vendor": "Intel(R)Core(TM)i5-2520MCPU@2.50GHz",
		"hardware_model": "win32",
		"ModelName": "x64",
		"FirmwareVersion": "6.1.7601"
	},
	"gatewayId": (gateway ID),
	"deviceToken": (device token)
}

*sample attributes

####Submit Data

Topic: server/metric/(account id)/(gateway id)
Message:
{
	"accountId": (account id),
	"did": (device id),
	"on": (submission timestamp),
	"count": (data count),
	"data": [{
		"on": (data timestamp),
		"value": (data value),
		"cid": (component id)
	}]
}}

####Add Component

Topic: server/devices/(device id)/components/add
Message:
{
	"name": (component name),
	"type": (component type),
	"cid": (component id),
	"deviceToken": (device token)
}

####Test Dashboard Status

Topic: server/devices/(device id)/health
Message:
{
    "detail": "mqtt"
}

####Component Catalog

Topic: server/devices/(device id)/cmpcatalog
Message:
{
	"deviceToken": (device token),
	"deviceId": (device id)
}

Common Parameters

Parameter	Description
device id	unique device name
gateway id	unique gatweway name (usually same as device ID)
account id	account ID for the account the device is activated under
device token	unique token assigned to the device by the Dashboard
component name	local name for the component/sensor
component type	type listed in the account's component catalog
component id	user-defined unique ID for a component (typically is a GUID)

Examples

Python and Node.JS sxample scripts are provided to show how to submit sensor data or request server information via MQTT

mqtt_submit_data - Submits data observation to the Cloud
mqtt_health - Requests Cloud server health status

Note Node.JS samples are broken with mqtt v1.1.2+