MQTT API

Device Registration

In order for a Gumband Hardware device to become fully registered in the system the following sequence must be followed. The definitions for the endpoints and payloads are defined in the sections below.

API Endpoint Summary

<ID>: componentId of the device
<source>: system, app
endpoint/<CMD> replaced by value referenced "->" e.g. -> set, get

Note: endpoints with <CMD> are sent to the device, the endpoints without are sent from the device.

Info

<ID>/<source>/<CMD> -> get
<ID>/<source>/info
<ID>/<source>/info/<CMD> -> set, get

Log

<ID>/<source>/log

Registration

<ID>/<source>/register/prop
<ID>/<source>/register/prop/<CMD> -> get
<ID>/<source>/register/prop/<CMD>/<property path> -> get

Connections (System only)

<ID>/system/connections
<ID>/system/connections/<CMD> → set, get
<ID>/system/connections/<index>/<CMD> → set, get

Prop

<ID>/<source>/prop/<CMD> → set, get
<ID>/<source>/prop/pub/<array range>/<property path>
<ID>/<source>/prop/<CMD>/<array range>/<property path> -> set, get

Source Information Endpoint

<ID>/<source>/get This endpoint will request information from several child endpoints

See individual source docs for specific payloads & sequences

Information Endpoint

<ID>/<source>/info

Each info message will be published to a connection once it is available, and can be requested anytime.

See individual source docs for specific payloads & sequences

Request Information

<ID>/<source>/info/get

Information can be requested by publishing an empty payload to the get endpoint. The hardware will publish the information to the base <ID>/<source>/info endpoint in response.

Edit Information

<ID>/<source>/info/set

Some information can be changed by publishing to the set endpoint. The hardware will publish the updated information to the base <ID>/<source>/info endpoint as confirmation.

Log Endpoint

<ID>/<source>/log

Logs will be published as they occur, and include both severity and text fields.

severity: debug, error, warning

{
  "severity": "debug",
  "text": "<log text>"
}

Property Registration Endpoint

<ID>/<source>/register/prop

Properties are dynamic endpoints that can be interacted with. Property registration is sent after the information message (<ID>/<source>/info). Each property will publish to this prop endpoint in succession. The number of property registration payloads published should equal that listed in the "num_props" field in listed the information message (<ID>/<source>/info). The property registration can be requested anytime by requesting the information message; the property registration will be republished with it.

{
  "path": "power", // Can be "Group Name/Prop Name" like "motor/power".
  "desc": "More about what the property is", // Description that can be used for hover-over text. Blank if not used.
  "index": ##, // Index of the property, can be used to validate expected count listed in information registration
  "type": "gmbnd_primitive",
  "format": "i", // Packed data format via pickling, predefined types have a set format.
  "length": 1, // Length is 0 for gmbnd_trigger
  "settable": true,
  "gettable": true,
  "min": 0, // (Optional) range. We don't provide this for string, color, trigger, and LED types.
  "max": 100, // (Optional) ^^
  "step": 10, // (Optional) Step for range. Can be used for setting intervals for a slider in the UI.
  "ui_hidden": true // (Optional) UI-specific stuff
}

Property paths cannot be empty/blank. They cannot start or end with a forward-slash '/'. They cannot include wildcard symbols '$', '#', or '+'. They cannot include non-printable characters.

Ex: The property "" is invalid The properties "/position" and "position/" are invalid The property "x+y corrdinates" is invalid

Request Property Registration

<ID>/<source>/register/prop/get

Gets all of the registered properties for the source. This is equivalent to what gets sent during property registration.

Request Individual Property Registration

<ID>/<source>/register/prop/get/<property path>

Get a property registration based on its property path.

Property Endpoints

<ID>/<source>/prop/<action>/<array range>/<property path>

Once a property's information has been registered with the register/prop endpoint, it can be interacted through its unique property endpoint. A property's "path" field from from its registration is appended onto the base prop/<action>/<array range> endpoint to build its unique property endpoint.

Ex: The "temperature" property has the endpoint <ID>/<source>/prop/<action>/<array range>/temperature

note

Currently, the only syntax that is supported for the array range is ":", meaning "the whole array"

The hardware can publish to the property pub endpoint either when the value changes, on a pre-determined interval, or on-demand though logic in the user application code. The source of truth for these values lives on the hardware, but they can be edited or requested anytime using the set and get endpoints (see below).

A property's "path" field can be multi-level, separated by forward-slashes "/". This can be helpful for organizing properties into features or hardware components. The last level of the hierarchy is considered the property’s name and each level before it are considered groups.

Property Types

Property data payloads are packed according to the format and length listed in its property information, based on Python struct packing.

Anything that can be described solely from the format considered gmbnd_primitive type.

Ex: gmbnd_int in user code is registered as a gmbnd_primitive type with format "i". It represents a signed integer value. gmbnd_text in user code is registered as a gmbnd_primitive type with format "s". It represents a UTF-8 encoded string.

Note that the trigger type has an empty format. It sends and receives only empty payload messages so it can trigger events.

Ex: gmbnd_trigger in user code is registered as a gmbnd_primitive type with empty format "".

Special-cases will be given a pre-determined type where extra context is needed.

Ex: gmbnd_color in user code is registered as a gmbnd_color type with format “4B”. It represents 4 values: white, red, green, and blue. (It’s a hex color code! 0xRRGGBB)

Property Types: Payload Formats

Trigger gmbnd_primitive

Format: ""
Bytes: 0
Array Support: No (array length is always 0)
Min/Max/Step Support: No

The trigger type is a data-less type that "triggers" the property, similar to an interrupt or event. There is no data payload format associated with the trigger type because it does not use one. The payload message body should be empty.

Note: if the payload isn't empty, it should just be ignored (and not ocnsidered an error).

Bool gmbnd_primitive

Format: "?"
Bytes: 1
Array Support: Yes
Min/Max/Step Support: No

The bool type is a Boolean type with two states: true or false.

Example Payloads:

  Single: [0x01]    ->    [True]
  Array:  [0x01,
           0x00,
           0x01]    ->    [True, False, True]

Byte gmbnd_primitive

Format: "B"
Bytes: 1
Array Support: Yes
Min/Max/Step Support: Yes

The byte type is an 8-bit number, ranging from 0 to 255.

Example Payloads:

  Single: [0xFF]    ->    [255]
  Array:  [0x0B,
           0x0A,
           0x0D]    ->    [11, 10, 13]

Integer gmbnd_primitive

Format: "i"
Bytes: 4
Array Support: Yes
Min/Max/Step Support: Yes

The integer type is a 32-bit integer type that support signed numbers.

Example Payloads:

  Single: [0xFF, 0xFF 0xFF 0xFF]      ->    [-1]
  Array:  [0x00, 0x00, 0x0B, 0xB8,
           0xFF, 0xFF, 0xF4, 0x48]    ->    [3000, -3000]

Floating Point gmbnd_primitive

Format: "d"
Bytes: 8
Array Support: Yes
Min/Max/Step Support: Yes

The floating point type is a 64-bit IEEE 754 double-precision floating-point formatted type that supports decimal and exponential numbers.

Example Payloads:

  Single: [0x40, 0x09, 0x1E, 0xB8, 0x51, 0xEB, 0x85, 0x1F]    ->    [3.14]
  Array:  [0xBF, 0xBF, 0x97, 0x24, 0x74, 0x53, 0x8E, 0xF3,
           0x40, 0x09, 0x1E, 0xB8, 0x51, 0xEB, 0x85, 0x1F]    ->    [-0.1234, 3.14]

Text gmbnd_primitive

Format: "s"
Bytes: Uses the array length for max text length
Array Support: No
Min/Max/Step Support: No

The text type is a string (UTF-8 encoded). The maximum number of characters the property supports is the array length sent during registration.

Example Payloads:

  Single: [0x67]                                  ->    ["g"]
  Array:  [0x48, 0x65, 0x6C, 0x6C, 0x6F]          ->    ["Hello"]
  UTF8:   [0xE4, 0xBD, 0xA0, 0xE5, 0xA5, 0xBD]    ->    ["你好"]

Color gmbnd_color

Format: "4B" or "BBBB"
Bytes: 4
Array Support: Yes
Min/Max/Step Support: No

The color type is an RGB hex color code with ARGB32 byte ordering. While compatible with 3 and 6 length RGB CSS color codes, it is NOT compatible with 8 length RGBA codes because of the position of the alpha value.

Example Payloads:

  Single: [0x12, 0x34, 0x56, 0x78]    ->    {
                                              alpha: 0x12, (or white)
                                              red: 0x34,
                                              green: 0x56,
                                              blue: 0x78
                                            }
  Array:  [0x12, 0x34, 0x56, 0x78,
           0x9A, 0xBC, 0xDE, 0xF0]    ->    [
                                              {
                                                alpha: 0x12, (or white)
                                                ret: 0x34,
                                                green: 0x56,
                                                blue: 0x78
                                              },
                                              {
                                                alpha: 0x9A, (or white)
                                                ret: 0xBC,
                                                green: 0xDE,
                                                blue: 0xF0
                                              }
                                            ]

Publish Property Value

<ID>/<source>/prop/pub/<array range>/<property path>

The base property endpoint where properties are published.

Get Property Value

<ID>/<source>/prop/get/<array range>/<property path>

The current value of a property can be requested by publishing an empty payload to its get endpoint. The hardware will publish the value to its base <ID>/<source>/prop/pub/<property path> endpoint in response.

Set Property Value

<ID>/<source>/prop/set/<array range>/<property path>

Some properties can be written to by publishing a formatted payload to its set endpoint. The hardware won’t publish any response.

System

System can be treated as the “operating system” layer of the hardware. Its information and interactions should happen regardless of whether there is a user application loaded or not.

System Get

<ID>/system/get

Gets the same response as if the following commands were called one after another:

<ID>/system/info/get
<ID>/system/register/prop/get
<ID>/system/connections/get

System Information

<ID>/system/info

This is sent immediately as the first message of registration. It contains the device name, capabilities, and most importantly the API version it’s using to communicate.

See general info endpoint

{
  // Gumband-Library Information
  "api_ver": ##, // Gumband HW Message API version
  "gb_lib_ver": "##.##.##", // (Optional) Gumband Library version. Just for displaying in the UI.
  // Hardware-Component Information
  "name": "My Device", // Device HW name
  "type": "presence", // generic, presence, temp, etc.
  "capabilites": [ "OTA", "filesystem" ], // Device capabilties
  "num_props": ##, // Number of system props (heartbeat, temperature, voltage, etc.)
  "platform": // Physical board/platform information (Not currently used. Just for display purposed in the UI. Can be used for OTA fw update file type hinting)
  {
    "name": "PSoC", // Clipboard, Bundle, EPS32, PicoW, etc.
    "variant": "module", // (Optional) Module, breakout, or ESP32-S2-SOLO, etc.
    "ver": "0.0", // (Optional) Some board version, etc.
    "gb_pkg_ver": "##.##.##", // (Optional) Gumband Library Support Package version. Just for displaying in the UI.
    "bootloader_ver": "##.##", // (Optional) Bootloader version if device supports it
  },
  // Network info
  "mac": "MAC_ADDRESS",
  "ip": "IP_ADDR"
}

Example: Editing the Device Name

Publish a message to the <ID>/system/info/set endpoint with the edit to the device name. The value will be the new device name. If successful, the hardware should re-send its system info to all active connections to inform them of the name change.

Note: if the name provided is too long, it will be truncated. The length limit on the names is platform/hardware dependent.
{
  // Hardware-Component Information
  "name": "My hardware device", // new device name
}

System Connections Endpoint

note

The API definition has room in it for connections to be for any source, but currently only system connections are implemented

<ID>/system/connections

List of current connections that the hardware publishes at registration, as well as any time the connections list is modified. Can be requested anytime.

[
  {
    "type": "MQTT",
    "name": "Cloud Dashboard",
    "address": "app.gbtt.gumband.com",
    "port": 1884,
    "enabled": true,                     // Connection is enabled/disabled
    "secure": true,                      // TLS or not
    "modifiable": false,                 // Can be edited/deleted remotely or not
    "prop_interact": true,               // Connection can interact with property messages (needs better name)
    "status": 1,                         // 0 -- not connected, 1 -- connected
    "uptime": ######                     // Connection uptime in minutes
  },
  {
    "type": "MQTT",
    "name": "My local application",
    "address": "10.0.0.1",
    "port": 1883,
    "enabled": true,
    "secure": false,
    "modifiable": false,
    "prop_interact": true,
    "status": 1,
    "uptime": ######
  }
]

System Request Connections List

<ID>/system/connections/get

The connections list can be requested by publishing an empty payload to the get endpoint. The hardware will publish the information to the base <ID>/system/connections endpoint in response.

System Edit Connections List

<ID>/system/connections/set

Some connection information can be changed by publishing to the set endpoint. The hardware will publish the updated information to the base <ID>/system/connections endpoint as confirmation. Partial updates to the connection are permitted. However, the following entries are not settable:

status
uptime

Example Payloads:

[
  {
    "type": "MQTT",
    "name": "Cloud Dashboard",
    "address": "app.gbtt.gumband.com",
    "port": 1884,
    "enabled": true,
    "secure": true,
    "modifiable": false,
    "prop_interact": true
  },
  {
    "type": "MQTT",
    "name": "My local application",
    "address": "10.0.0.1",
    "port": 1883,
  }
]

[
  {
    // Note that a placeholder is used for the connections that aren't edited
  },
  {
    "name": "Cloud Dashboard" // If you just wanted to update the name of this connection
  }
]

warning

Currently the connection type cannot be changed. "MQTT" must ALWAYS be used.

System Individual Connection Endpoint

<ID>/system/connections/<index>

Individual connections can also be interacted with. Since the Connections List is an array, you can refer to the connection by its position. The First connection in the list is connection 0, the second is connection 1, etc.

  "type": "MQTT",
  "name": "Cloud Dashboard",
  "address": "app.gbtt.gumband.com",
  "port": 1884,
  "enabled": true, // Connection is enabled/disabled
  "secure": true, // TLS or not
  "modifiable": false, // Can be edited/deleted remotely or not
  "prop_interact": true, // Connection can interact with property messages (needs better name)
  "status": 1, // 0 -- not connected, 1 -- connected, -1 -- can't find, -2 -- bad auth, etc.
  "uptime": ###### // Connection uptime in minutes

note

This payload is identical to a single connection's information contained in the connections list array payload.

System Request Individual Connection

<ID>/system/connections/<index>/get

An individual connection in the list can be requested by publishing an empty payload to the get endpoint. The hardware will publish the information to the base <ID>/system/connections/<index> endpoint in response.

System Edit Individual Connection

<ID>/system/connections/<index>/set

Some connection information can be changed by publishing to the set endpoint. The hardware will publish the updated information to the base <ID>/<source>/connections/<index> endpoint as confirmation.

The payload will be the a single connection’s information.

warning

The payload follows the same restrictions as the base connections endpoint i.e status and uptime are not settable and the type must always be "MQTT".

Example Payloads:

{
  "type": "MQTT",
  "name": "Cloud Dashboard",
  "address": "app.gbtt.gumband.com",
  "port": 1884,
  "enabled": true,
  "secure": true,
  "modifiable": false,
  "prop_interact": true
}

{
  "name": "Cloud Dashboard" // If you just wanted to update the name
}

System Properties

System-related information that changes over time and needs to be broadcasted on an interval will be registered as a system system property. If the device does not register a system property, then the device does not have that system information.

Known System Properties

Gumband devices do not have to implement all or any of these, but if they do we encourage following the same property names and types.

The Gumband team will try to keep this list up-to-date, but in the future there might be a system property not captured by this list; for this reason we ask all system properties should be registered with a description for it’s purpose and use.

Note: Boards can also implement their own, unique, system properties in the future that may not be caputred by this list.

Runtime gmbnd_float | gettable

<ID>/system/prop/<action>/:/Runtime
Description: Time device has been powered on in minutes

Temperature gmbnd_float | gettable

<ID>/system/prop/<action>/:/Temperature
Description: Device temperature in °C

Voltage gmbnd_float | gettable

<ID>/system/prop/<action>/:/Voltage
Description: Board voltage in V

Reboot gmbnd_trigger | settable

<ID>/system/prop/<action>/:/Reboot
Description: Reboot the device

Identify gmbnd_trigger | settable

<ID>/system/prop/<action>/:/Identify
Description: Identify the device by flashing the on-board LED

Clock Time gmbnd_text | gettable settable

<ID>/system/prop/<action>/:/Clock/Time
Description: Current device time in YYYY-MM-DDTHH:mm:ss.sssZ format

Clock Set gmbnd_bool | gettable

<ID>/system/prop/<action>/:/Clock/Set
Description: Indicates whether or not the RTC(Real Time Clock) has been set

App Status gmbnd_text | gettable

<ID>/system/prop/<action>/:/App status
Description: Current detected runtime status of the app
- Unable to Verify – Application image doesn’t exist or invalid
- Not compatible (<app’s GSP version>) – Gumband support package for the app core is incompatible with the main, system core
- Initialization timeout – Unable to initialize shared memory queue
- Running – App is running in a normal, non-error state
- Running (slow) – App core is running slower than the main, system core and messages are getting dropped. This can be from large bursts of incoming messages or long delays in the app.

Application

This is the user-application layer of the hardware. Its information and interactions should happen only when a user application has successfully loaded.

Application Get

<ID>/app/get

Gets the same response as if the following commands were called one after another:

<ID>/app/info/get
<ID>/app/register/prop/get

Application Information

<ID>/app/info

This is sent once the user application is loaded and finished its setup procedure. It contains the application file name, version, and number of user-defined properties. If the user application fails to load or does not complete its setup routine, the application information will never be sent.

See general info endpoint

{
  // Gumband-Specific Info
  "file_name": "my_sketch.gbm4" // (Optional) Application FW image name
  "ver": "##.##", // (Optional) Application FW version
  "gb_pkg_ver": "##.##", // (Optional) Gumband Library Support Package version. Just for displaying in the UI.}
  "num_props": ##
}

note

The application information is not editable; attempts to publish to its set endpoint will not do anything.

Device Registration​

Source Information Endpoint​

Information Endpoint​

Request Information​

Edit Information​

Log Endpoint​

Property Registration Endpoint​

Request Property Registration​

Request Individual Property Registration​

Property Endpoints​

Property Types​

Publish Property Value​

Get Property Value​

Set Property Value​

System​

System Get​

System Information​

System Connections Endpoint​

System Request Connections List​

System Edit Connections List​

System Individual Connection Endpoint​

System Request Individual Connection​

System Edit Individual Connection​

System Properties​

Application​

Application Get​

Application Information​

Device Registration

Source Information Endpoint

Information Endpoint

Request Information

Edit Information

Log Endpoint

Property Registration Endpoint

Request Property Registration

Request Individual Property Registration

Property Endpoints

Property Types

Publish Property Value

Get Property Value

Set Property Value

System

System Get

System Information

System Connections Endpoint

System Request Connections List

System Edit Connections List

System Individual Connection Endpoint

System Request Individual Connection

System Edit Individual Connection

System Properties

Application

Application Get

Application Information