...

• 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: {hardwareId}<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: {hardwareId}<hardware_id>/authenticate

{
  "text": "request" 
}

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

  • {hardwareId}Topic = <hardware_id>/authenticate

{
  "token": 32 char alphanumeric 
}

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

  • Topic = {hardwareId}<hardware_id>/authenticate

{
  "text": "true"
}

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

• Topic = {hardwareId}<hardware_id>/authenticate

{
  "text": "false" 
}

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

• Topic = {hardwareId}<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 errorevent 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 sync INFO topic “register” command).

• Once authenticated, the HW sends Gumband registration event to the Cloud Server and Exhibit Server at the topic: {hardwareId}<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 = {hardwareId}<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 = {hardwareId}<hardware_id>/registration/property

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

...

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

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: {hardwareId}/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.

...

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: {hardwareId}<hardware_id>/info

• This subscription occurs prior to every registration

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

...

...

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

• With the payload:

{
  "texthardwareId": "Heartbeat<ID>""
  "uptime": "######",
  "exhibitIP": "IP<IP_ADDRADDR>" 
  "exhibitState": "1/0/-1"
  "Temptemp": "##.##"
  "Voltagevoltage": #####"##.##"
}

• 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 - Connected= 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 mVV

• The time of the last heartbeat should be loggedis displayed on the “Overview” page under “Last Updated”

Logs

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

  • {hardwareId}<hardware_id>/log/debug

  • {hardwareId}<hardware_id>/log/error

  • And should have the message body:

...

• 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:

  • {hardwareId}<hardware_id>/log/notify

  • And should have the message body:

...

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

  • {hardwareId}<hardware_id>/log/event

  • And should have the message body:

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

Exhibit Events

...

...

Controllable exhibit events are structured as "settable" properties

...

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:

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

  Reading/Polling properties

  For every property

• Data sent to this endpoint will be received by the gumband hardware

  is subscribed to:

• {hardwareId}/{peripheralName}/{propertyName}/get

• Note that this callback is intended to initiate a publish to the associated property but ultimately this is handled in user code so implementation is not guaranteed.

The Exhibit 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

  {hardwareId}

  :

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

Dynamic Hardware ID

Note: This is a suggested method to address a potential issue - this 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"
}

• 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

...