Headers
These header field types are reserved across all message types and usages of the protocol.
For use in code, you can find a code generation section at the bottom of this page.
1: Message ID
Type: uint32
ID identifying the message. Can be used by a receiver to ACK, respond to, deduplicate, resend or otherwise track messages. Some clients and services may require or desire an incrementing message ID for each message sent, acting as a sequence number.
2: Client ID
Type: uint
ID of the client sending the message. May mean different things in different contexts. Must be uint32 or uint64 for Lightbug cloud services, and relate to a Lightbug Device ID.
3: Response to
Type: uint32
ID of the message that is being responded to (Message ID of the request or subscription)
4: Status
Type: int8
If omitted, assume the message is OK 0 indicates OK. A nonpositive value does not necessarily mean the operation is complete; -1 indicates Processing, with further responses expected. Positive values indicate an error or other non-OK result.
| Value | Name | Description |
|---|---|---|
| 0 | OK | Everything appears to be OK |
| 1 | Generic Error | |
| 2 | Missing Parameter | |
| 3 | Method Not Supported | e.g., SETting GPS position |
| 4 | Invalid Parameter | Unsupported values requested (e.g., requesting the GPS data at 100hz) |
| 5 | Invalid State | e.g., requesting GPS data stream before turning GPS on |
| 6 | No Data | e.g., requesting GPS or time data when not yet available |
| 7 | Not Supported | If the receiver does not support the requested action or method |
| 8 | Failed Will Retry | Currently only used for tx now |
| 9 | Failed Permanently | |
| 10 | Abandoned | Status code when an actioned has timed out or been deliberately cancelled by another process |
| 11 | Expired | Status code when a request has expired and has been cancelled, typically subscriptions |
| 12 | Missing Subscription Parameter | Status code when a subscription request is missing required parameters such as Interval or Duration |
| 13 | Invalid Subscription Parameter | Status code when a subscription request has invalid parameters such as Interval or Duration |
| 14 | Bad Encryption | The receiver was expected to be able to decrypt the message, but decryption failed e.g., due to incorrect keys or corrupted data |
| 99 | Unknown Message | The receiver does not recognize the requested message type |
| -127 | Already Responded | |
| -126 | No ACK | |
| -1 | Processing | Processing; further responses are expected. |
5: Method
Type: uint8
Request a service to be perform an action
| Value | Name | Description |
|---|---|---|
| 1 | SET | Set one or more values that are provided in the message payload. |
| 2 | GET | Get values for the associated message type. |
| 3 | SUBSCRIBE | Subscribe to values for the associated message type. Can be used in conjunction with other header fields to define the subscription parameters, such as Interval, Duration, Timeout, Storage Level and Message Level. If no interval is provided, messages will be sent as and when new data is available. Some data, such as GPS position, may require a set interval to be provided. |
| 5 | UNSUBSCRIBE | Unsubscribe from a previous subscription. |
6: Interval
Type: uint32 Unit: ms
To be used with the SUBSCRIBE method. Defines how often messages of the given type should be sent. If no interval is provided, messages will be sent as and when new data is available. Some data, such as GPS position, may require a set interval to be provided. If the interval is less than the period required to acquire the data, or refresh the data, the data may be send less often than requested.
7: Duration
Type: uint32 Unit: ms
To be used with the SUBSCRIBE method, or actions that can be timed. When used with a timed action: This defines how long the action should go on for. When used with the SUBSCRIBE method: This defines a duration to keep the subscription active for. A value of 0 means the subscription is indefinite until explicitly unsubscribed. A message with an EXPIRED status code will be sent if the subscription duration elapses without being renewed with a new subscription request.
8: Timeout
Type: uint32 Unit: ms
When requesting data or services that can take time to acquire (such as a GPS fix), this defines how long to try for before abandoning the action. A message with an ABANDONED status code will be sent in this case. For actions that support it, timeout instead defines how long to wait before performing the action. When used with a SUBSCRIBE method, with a Message Level header field: This defines the time to wait for a message of the given level, before cancelling the subscription. Example: GPS subscribe with Message Level 'Valid' and Timeout 60000ms
10: Forwarded For
🧪 Alpha
Type: uint
Client or local link ID of the sender being forwarded. Repeat this header for each hop, in origin-to-cloud order. Relays append their local sender hop; replies reverse the complete chain into Forward To. Values use length-sized little-endian unsigned integers, as Client ID does; small local IDs remain one byte. Current standardized link IDs are shared with Forward To and command logging: 0 = L1 (Cloud link 1; protocol name Chasm), 1 = ESP32, 2 = L2 (Cloud link 2; protocol name Link2), 3 = P1, 5 = UART link, 7 = USB host. For forwarding destinations, destination 0 is L1, destination 1 is the ESP32 co-processor (not L1), and destination 2 is L2. Forward For Type may add context for non-link forwarding cases such as LoRa, but link forwarding should use these IDs directly.
| Value | Name | Description |
|---|---|---|
| 0 | Chasm | L1 (Cloud link 1); protocol name Chasm |
| 1 | ESP32 | ESP32 co-processor link |
| 2 | Link2 | L2 (Cloud link 2); protocol name Link2 |
| 3 | P1 | P1 link reached from P2 over I2C |
| 5 | UART | UART command link |
| 7 | USB Host | Host computer link, mainly reached from P2 over USB |
14: Forward To
🧪 Alpha
Type: uint
Client or local link ID of the next destination. Repeat this header in delivery order. Each relay consumes only its next hop; [1, 700004] routes through ESP32 to client 700004. Values use length-sized little-endian unsigned integers, as Client ID does; small local IDs remain one byte. Current standardized link IDs are shared with Forwarded For and command logging: 0 = L1 (Cloud link 1; protocol name Chasm), 1 = ESP32, 2 = L2 (Cloud link 2; protocol name Link2), 3 = P1, 5 = UART link, 7 = USB host. For forwarding destinations, destination 0 is L1, destination 1 is the ESP32 co-processor (not L1), and destination 2 is L2. Forwarding To Type may add context for non-link forwarding cases such as LoRa, but link forwarding should use these IDs directly.
| Value | Name | Description |
|---|---|---|
| 0 | Chasm | L1 (Cloud link 1); protocol name Chasm |
| 1 | ESP32 | ESP32 co-processor link |
| 2 | Link2 | L2 (Cloud link 2); protocol name Link2 |
| 3 | P1 | P1 link reached from P2 over I2C |
| 5 | UART Link | UART command link |
| 7 | USB Host | Host computer link reached from P2 over USB |
15: Storage Level
🧪 Alpha
Type: uint8
Defines the behaviour for messages that have not been ACKed. The default is None, i.e. failed messages will not be retried. Devices have limited storage, if using retries and when storage is full, the oldest messages will be overwritten. Future iterations may support "In Order" which will require messages to be sent and ACKed in timestamp order.
| Value | Name | Description |
|---|---|---|
| 0 | None | Do not attempt to resend messages if they are not ACKed |
| 10 | RAM | Keep the messages in RAM until they are ACKed or overwritten. Messages are discarded on reboot |
| 20 | NVM | Keep the messages until they are ACKed or overwritten |
16: Message Level
🧪 Alpha
Type: uint8
Loosely analogous to log levels (trace, debug, info, warning, etc.) in that you must define the lowest level of interest. Message Levels can be used with timeouts on subscriptions - if a message of the requested level is not available within the specified time, the subscription will be abandoned. Currently you may only define one subscription per message type - requesting multiple levels will result in existing subscriptions being modified to the new level. Future iterations will support "Changes Only" and "Critical" and may support multiple concurrent subscriptions with varying levels
| Value | Name | Description |
|---|---|---|
| 1 | Info-Watch | Receive all messages if and when available, without explicitly requesting that the underlying hardware be turned on. |
| 2 | Info-Auto | Receive all messages and explicitly request underlying hardware be activated to provide the requested data where needed |
| 10 | Valid | Activate the relevant hardware but only receive valid data. May be used with subscription timeout feature to request usable data without leaving the hardware on indefinitely |
17: Subscription ID
🧪 Alpha
Type: uint8[]
ID of the subscription being managed, when multiple subscriptions are being used per message type (advanced usage). If not provided, Subscription ID 0 is assumed (the default subscription). Can be used to uniquely identify subscriptions when multiple subscriptions of the same message type exist. Devices may have default subscriptions, and these will use Subscription ID 0. So SUBSCRIBing without a Subscription ID, or with subscription ID 0 will, create or modify the default subscription. When using with the SUBSCRIBE or UNSUBSCRIBE methods, you should optionally provide a single uint8 value. If messages are sent as part of a non 0 Subscription ID, one or more Subscription IDs will be included in the message header to identify which subscription(s) the message relates to.
22: Message Version
Type: uint8
Selects or identifies a message payload format, where supported by the message. Supported values, response/publication usage and the effect of omitting this header are defined by each message.
100: Received time
Type: uint64 Unit: ms since epoch
Time the message was received. Cloud systems may add this to messages they receive. Particularly useful for messages that are further processed, queued or forwarded on.
101: Received sequence
Type: uint
Sequence that messages not associated with a "session" were received in, as an incrementing number. Cloud systems may add this to messages they receive, but should not add it to messages that are part of a session (has session ID, or is session start/end). Should start at 1 and increment by 1 for each message received on a single connection. A sequence number of 1 can thus indicate the start of a new connection, has happened, and the device may want to be resent any commands.