MQTT Overview

Each Gumband Hardware Device maintains two MQTT broker connections: one to handle global gumband events (Cloud), and one to handle exhibit events (Exhibit). The purpose is to keep exhibit events on the lowest latency and most reliable connection to ensure super responsive performance and improve up time (especially when the Cloud server is remote). The hardware can also be run without a connection to the Cloud server but maintaining the Gumband messaging protocol. When a Gumband device registers through the cloud and is attached to an active exhibit, the Exhibit server IP/hostname will be returned. Note: this could be the same IP/hostname as the Cloud server in the case of an on-premises Cloud server (but it can't be the same port).

• Cloud Server

  • Firmware updates

  • Device Registration

  • Heartbeat

  • Error/Warnings

  • Logs

  • Lifecycle commands (restart, shutdown, etc)

  • When in Debug Mode supports all control events (for test and debug) 

• Exhibit Server

  • Device Registration

  • Heartbeats

  • All peripheral/property events specific to exhibits

Hardware Authentication

• The user creates a hardware auth token from the "Auth" tab for that hardware within the Gumband UI.

• That token needs to be written to the hardware either through the serial interface or the firmware API.

• On boot the hardware will subscribe to the topic: <hardware_id>/authenticate

• At this point no other subscribe or publish is allowed by the Cloud until authentication has completed

• When an unknown hardware device attempts to open a socket with the GBTT server and subscribe to the authenticate topic (Note: The Cloud must wait for the HW to subscribe to this), the Cloud will issue a request event to this topic: <hardware_id>/authenticate

{
  "text": "request" 
}

• The HW responds to a request with it's authentication token in the following format:

  • Topic = <hardware_id>/authenticate

{
  "token": 32 char alphanumeric 
}

• If the token and hardwareId are valid, the server will respond on the authenticate topic with “true”.

  • Topic = <hardware_id>/authenticate

{
  "text": "true"
}

• If the token is not valid, the server will respond on the authenticate topic with “false”.

• Topic = <hardware_id>/authenticate

{
  "text": "false" 
}

• If the hardwareId is not valid, the server will respond on the authenticate topic with “id”.

• Topic = <hardware_id>/authenticate

{
  "text": "id" 
}

• If the authentication fails or the HW fails to respond to the authentication request then the GBTT server ignores all data on this socket (but does not explicitly close it).

• Any events/topics published without first authenticating will be responded with an error event on the info topic (see INFO). Note no other subscribe or publish is allowed during the authentication handshake or the auth will fail, so it’s important not to send anything else until this is completed.

• All topic subscriptions (other than authenticate) will be rejected until the auth sequence is completed.

Hardware Registration

This occurs whenever the initial connection is made to the MQTT cloud server after authentication, this contains the device capabilities only. To obtain actual property states readable topics can be polled.

Registration can also occur when a registration request is received from the server (the INFO topic “register” command).

• Once authenticated, the HW sends Gumband registration event to the Cloud Server and Exhibit Server at the topic: <hardware_id>/registration

• Registration events should be logged on the server side

• Registration events have an initial JSON message body identifying the device and the total number of peripherals, followed by individual registration messages for each property of every peripheral. Outline below:

Topic = <hardware_id>/registration

{
  "hardwareId": ##, // globally unique hardwareId from Gumband
  "mac": "MAC_ADDRESS",
  "gumband_fw": ##,
  "user_fw": ##,
  "hw_ver": ##,
  "ip": "IP_ADDR",
  "numPeripherals": ## 
  "exhibitIP": "IP_ADDR" 
  "exhibitState": 1/0 
}

Topic = <hardware_id>/registration/property

{
  "hardwareId": ##,
  "peripheral": "lamp", 
  "property": "power",
  "numProperties": ##,
  "type": "xxxxx",
  "length": 1,
  "settable": true,
  "hide": true,
  "info":"Mouse Over Text"
}

Registration Flow

Cloud Registration

Note:

1. For Debug only

2. Should be implemented on every connection but only required if the hardware does not already have a saved exhibit server address or if the address has changed

3. If the hardware already holds an exhibit address this will happen in parallel with the master connection

Exhibit Registration

SYNC Messages

DEPRECATED - See “info” topic, “register” command

Gumband needs some way to make sure its knowledge of peripheral properties are up to date if the Gumband server or MQTT go down at any point and publication messages are missed. In these cases, a SYNC request will be made to each out of date board as soon as the server comes back up. 

• Sync topic: <hardware_id>/sync

• Immediately after registration every Gumband Hardware device subscribes to this sync topic so should always be ready to receive it.

• In response to a sync topic the hardware will issue a registration and resubscribe to all topics.

• If the cloud wants read the status of specific peripheral properties it can then poll all readable properties: <hardware_id>/{peripheral_name}/{property_name}/get

INFO Messages

Gumband Cloud Server needs a way to signal each hardware device to send simple control commands. In this case, the information is published to the device INFO topic to which each device subscribes first (before publishing its initial authentication/registration). The INFO topic is also used during the initial handshake to share the exhibit broker host details.

• Every Gumband hardware device should be subscribed to the topic: <hardware_id>/info

• This subscription occurs prior to every registration

• The contents of the info topic is a 2 parameter JSON structure:

{
  "command": "xxxx",
  "text": "xxxx"
}

Heartbeats

Heartbeats are sent from the Gumband Hardware every 16 seconds and are published to the topic: <hardware_id>/heartbeat

• With the payload:

{
  "hardwareId": "<ID>""
  "uptime": "######",
  "exhibitIP": "<IP_ADDR>" 
  "exhibitState": "1/0/-1"
  "temp": "##.##"
  "voltage": "##.##"
}

• Board metrics

  • Uptime - Time in minutes since last reboot

  • Exhibit IP - The exhibit server IP currently saved on the hardware

  • Exhibit State - The state of the connection from the exhibit hardware to the exhibit server (0 = No connection, 1 = Connection, -1 = Not Set)

  • Temperature - Hardware temperature in degrees C (this is actually the Die temp for most current hardware)

  • Voltage - System supply voltage in V

• The time of last heartbeat should be logged

Logs

• Gumband debug, error and log messages are published to the Cloud Server at the topic:

  • <hardware_id>/log/debug

  • <hardware_id>/log/error

  • And should have the message body:

{
  "text": "<event message text>",
}

Notifications

• Gumband notification messages are immediately sent to any user subscribed to hardware notifications in the main are published to the Cloud Server at the topic:

  • <hardware_id>/log/notify

  • And should have the message body:

{
  "text": "<notification message text>",
}

Events

• Gumband events can be viewed on the “Reports” tab and are published to the Cloud Server at the topic:

  • <hardware_id>/log/event

  • And should have the message body:

{
  "text": "<event message text>",
  "value": <event value>
}

Properties

• Properties are user defined endpoints that control individual aspects of the application (motor speed, light color, power on/off etc.).

• Properties are grouped into a specific “Peripherals” which serves only as a hierarchical organizational structure.

Writing Properties

• Any property with write permissions is a “settable” property.

• For every "settable" property, gumband hardware is subscribed to:

  • <hardware_id>/{peripheralName}/{propertyName}/set

• Data sent to this endpoint will be received by the gumband hardware and routed to the appropriate callback.

• The message body is a raw data byte packet (not ASCII or JSON encoded)

Reading Properties

• Every property is readable or “gettable” however a Publish can be triggered at any time by the user code so this does not need to be polled in normal operation.

• Gumband hardware will publish property data to the following topic, therefore the GBTT Broker should be subscribed to this topic for every property exposed in the capabilities registration:

  • <hardware_id>/{peripheralName}/{propertyName}

• For every property the gumband hardware is subscribed to the following topic and the value of a property can be actively requested by publishing to it:

  • <hardware_id>/{peripheralName}/{propertyName}/get

• See more SDK-Hardware Interface Notes

Property Data Packet

Dynamic Hardware ID

FUTURE SPEC- Note: This is future specification possibility and is not currently implemented.

If Hardware boots and no hardwareId exists in memory but an auth token exists, Hardware will attempt to assign itself directly to an Exhibit using this process. This can be used to mass-assign Hardware to an Exhibit.

Overview

• Hardware listens to <mac_address>/new-hardware-id on Cloud Server

• Hardware publishes hardwareId request to Cloud Server at topic new-hardware-id

• Gumband uses auth token to lookup Exhibit and generate new Hardware assigned to that Exhibit

• Gumband publishes hardwareId over Cloud Server at topic <mac_address>/new-hardware-id

• Hardware can proceed with normal registration flow

Message Outline

• Data flow = Hardware -> Cloud Server -> Gumband

• Topic = new-hardware-id

{
  "mac": "MAC_ADDRESS",
  "auth": "AUTH_TOKEN"
}

• Data flow = Gumband -> Cloud Server -> Hardware

• Topic = <mac_address>/new-hardware-id

{
  "hardwareId": "HARDWARE_ID"
}