Introduction#

Internal communication between system modules like PicoidesIO User Interface and gateways or TSDB listener is handled over MQTT

Quote

“MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed so as to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.”

Citation from the official MQTT 3.1.1 specification

Details how to work with mqtt, create your own client are out of the scope of this documentation. Grate source of knowledge more on MQTT:

Quote

The MQTT protocol defines two types of network entities: a message broker and a number of clients. An MQTT broker is a server that receives all messages from the clients and then routes the messages to the appropriate destination clients.[11] An MQTT client is any device (from a micro controller up to a full-fledged server) that runs an MQTT library and connects to an MQTT broker over a network.[12]

Information is organized in a hierarchy of topics. When a publisher has a new item of data to distribute, it sends a control message with the data to the connected broker. The broker then distributes the information to any clients that have subscribed to that topic. The publisher does not need to have any data on the number or locations of subscribers, and subscribers in turn do not have to be configured with any data about the publishers.

Wikipedia on MQTT

Picoides IO MQTT#

In case of PicoidesIO 'broker/server' is available at host mqtt.picoides.io. It uses tls to secure data send between clients. Every client uses its own set of topics and reads and rights only to topics it's allowed to.

Connection and Authentication#

Our MQTT broker is configured to provide service with tls version 1.2 on port 8883. In order to connect you need to provide your username and password. You will have access only to devices within you snaps

  • port: 8883
  • tls version: 1.2
  • user: myname
  • password: secret_passwd

Topics#

Topics are organised with following pattern

picoides/SNAP_ID/GATEWAY_ID/DEVICE_ID/COMMAND/ATTRIBUTE

Where:

  • picoides is
  • SNAP_ID - UUID formated uid of project
  • GATEWAY_ID - uid of gateway
  • ENTITY_ID - uid of device or alias
  • CHANNEL - control, poll and feed
  • ATTRIBUTE - state

Snap ID, gateway ID, device ID#

It's UUID of project. Gateways and devices like lamps are able to comminicate with other entities within the same snap. In order to communicate with particular device you need to adress it's snapid and gateway

Gateway ID is UUID assigned to every gateway in the system.

Similarly all entities and devices in the system has it's uid formated as UUID string

Channels#

Currently tree types of channels are supported by most of devices dedicated as input or output feed for device control.

channels available:

  • control - input channel, the one you send requests to entity, all except data poll requests
  • poll - input channel dedicated for data poll requests
  • feed - output channel every entity or device publishes is responses, states and other data on it's feed channel

Aliasing#

In some cases instead of device uid message can be addressed over alias id. For devices with qrcode label like lamps you can use qrcode for example u9c7cg0388 if you're the owner of this device. For more general devices like switches, and sensors directly related to particular gateway you can use keycodes listed below - switch1 - Gateway relay no 1 - switch2 - Gateway relay no 2 - switch3 - Gateway relay no 3 - switch4 - Gateway relay no 4 - gsm - GSM modem data (if supported) - powermeter - data from powermeter if one is attached

Broadcast and Group#

You can address multiple devices in one request by using broadcast UID and (optional) entity param in payload

broadcast UID = 00000000-0000-0000-0000-000000000000

device param is an array containing list of device IDs

If no entity list is present all lights are effected

Example

snap = 'd0946515-bc89-4a9e-a81f-0438fa7bc1c4'
gateway = '23008dfa-dae1-4477-b5ee-a2599c838f79'
entity = '00000000-0000-0000-0000-000000000000' // broadcast

topic = "picoides/"+ snap +"/"+ gateway +"/" + entity +"/control/state"
msg = '{"status": [1, 0], "brightness": 200, "device":["jhquce0354","chqbce0148"]}'

above msg when sent to topic would dim selected jhquce0354 and chqbce0148 lights by value 55 (255 - 200)

Note

switch devices are not included in Broadcast messages

retain message#

Messages published with retain flag will be saved by broker and send (or resend) to client in case of new connection or after reconnection Use retain message flag only on control channel Do not use retain flag on poll feed

payload#

JSON formatted string

It contains state param you expect to change value and optional timestamp. Messages on feed channels are always formated with timestamp.

Use array [val, timestamp] or val

For lights:

  • status
  • brightness

Relay:

  • status

Powermeter does not support control channel. It supports poll channel as input and publishes its state with all read parameters.

Example

{"status": [1, 0]} // set status to 1 (on), no timestamp
{"status": 1} // set status to 1 (on)
{"brightness": 125} // set brightness to 125 (on)
{"brightness": 0} // set brightness to 0 (off)

Example requests#

mosquitto_pub mosquitto_sub are used in this example but you can use any mqtt client similar way.

Example

Set relay on using its alias switch2 

mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs \
# picoides   /SNAP_ID                            /GATEWAY_ID                          /ENTITY_ID/
-t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/715c2d5e-ebdb-11e7-9d59-b827eb3ebe34/switch2/control/state" \
-m '{"status": 1}'

Set relay off using its alias switch2 

mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs \
# picoides   /SNAP_ID                            /GATEWAY_ID                          /ALIAS/
-t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/715c2d5e-ebdb-11e7-9d59-b827eb3ebe34/switch2/control/state" \
-m '{"status": 0}'

Broadcast set on all lamps on gateway 

mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs \
-t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/715c2d5e-ebdb-11e7-9d59-b827eb3ebe34/00000000-0000-0000-0000-000000000000/control/state" \
-m '{"status": 1}'

or brightness 

mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs \
-t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/715c2d5e-ebdb-11e7-9d59-b827eb3ebe34/00000000-0000-0000-0000-000000000000/control/state" \
-m '{"brightness": 150}'

Broadcast ot selected devices only 

mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs \
-t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/715c2d5e-ebdb-11e7-9d59-b827eb3ebe34/00000000-0000-0000-0000-000000000000/control/state" \
-m '{"status": 1, "device":["jhquce0354","chqbce0148"]}'

Poll state from switch2 

mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs -t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/dab9fca4-eb63-11e7-9a8a-b827ebb02110/switch2/poll/state" -m 1

Poll state of all lamps on gateway 

picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/d2a16600-5757-11e8-8cfc-b827eb74cdb3
mosquitto_pub -h mqtt.picoides.io -p 8883 -u "myname" -P "secret_passwd" --tls-version tlsv1.2 --capath /etc/ssl/certs -t "picoides/3fbfa53b-cb77-4cfc-b1eb-da88ed1ce16d/d2a16600-5757-11e8-8cfc-b827eb74cdb3/00000000-0000-0000-0000-000000000000/poll/state" -m '{"status": [1, 0]}'