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 Values <= 0 indicate OK status. Values > 0 indicate an error or non-OK status.
| 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 |
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. An ACK with 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. An ACK with 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
ID of the client sending the original message that is being forwarded. Forward for type alters the meaning of this field
14: Forward To
🧪 Alpha
Type: uint8
ID of the client to forward the message to. Forwarding to type alters the meaning of this field.
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.
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: uint32
Sequence the message was received in, as an incrementing number. Cloud systems may add this to messages they receive. Should start at 1 and increments by 1 for each message received on a single connection or during a single session. A sequence number of 1 can thus indicate the start of a new session or connection.