Lightbug Documentation

Appearance

34: Device Status ​

Read battery, network and firmware status, or subscribe to later status updates. The fields returned depend on the target device and available readings; a response may contain only firmware information. Do not treat an omitted field as a zero value.

Message fields

Fields specific to Device Status. Operation sections below explain when each field is used.

FieldTypeDescriptionExample
BatteryField 1uint8

Battery level as a percentage.

88%Example
Signal StrengthField 2uint8

Signal strength as a percentage.

64%Example
ModeField 3uint8

Device mode.

  • 0 · Sleep
  • 1 · Awake
0 · SleepExample
Network typeField 4uint8

Current network.

  • 0 · No network
  • 2 · GSM (2G)
  • 3 · WCDMA (3G)
  • 4 · LTE (4G)
0 · No networkExample
Network MNCField 5uint16

MNC of the currently connected network. Can be 0 if not connected. Network code reference: https://mcc-mnc.net/

0Example
Network MCCField 6uint16

MCC of the currently connected network. Can be 0 if not connected. Network code reference: https://mcc-mnc.net/

0Example
Firmware VersionField 7uint32

Firmware version Can be a literal integer, or an encoded version number. Lightbug devices use a single integer for firmware version, e.g. 2287. ESP devices encode a semver version into an int, MAJOR*10000 + MINOR*100 + PATCH. 0.18.0 becomes 1800 and 1.1.1 becomes 10101.

2287Example
Device TypeField 10uint8

Type of device, relates to the SN prefix. For devices released from 2025 onwards, this is documented on the device specification page.

48Example

Examples are observed values from the linked captures, not defaults.

GETMessage 34

Read device status

Request the currently available status fields.

Request

No payload fields are required. Method must be included; this message does not default to GET.

Request headers

MethodHeader 5
uint8required

Value 2 · GET

Request a service to be perform an action

Message IDHeader 1
uint32optional

Include a nonzero Message ID to correlate the reply.

Expected response (MT34)

Device status

A successful GET returns Device Status directly, without a separate success ACK. Returned fields vary by target and available readings. Response To and Status may be omitted when the request has no nonzero Message ID.

Correlation, status and acknowledgment rules

Response data fields

BatteryField 1
uint8optional

Battery level as a percentage.

Signal StrengthField 2
uint8optional

Signal strength as a percentage.

ModeField 3
uint8optional

Device mode.

  • 0 · Sleep
  • 1 · Awake
Network typeField 4
uint8optional

Current network.

  • 0 · No network
  • 2 · GSM (2G)
  • 3 · WCDMA (3G)
  • 4 · LTE (4G)
Network MNCField 5
uint16optional

MNC of the currently connected network. Can be 0 if not connected. Network code reference: https://mcc-mnc.net/

Network MCCField 6
uint16optional

MCC of the currently connected network. Can be 0 if not connected. Network code reference: https://mcc-mnc.net/

Firmware VersionField 7
uint32optional

Firmware version Can be a literal integer, or an encoded version number. Lightbug devices use a single integer for firmware version, e.g. 2287. ESP devices encode a semver version into an int, MAJOR*10000 + MINOR*100 + PATCH. 0.18.0 becomes 1800 and 1.1.1 becomes 10101.

Device TypeField 10
uint8optional

Type of device, relates to the SN prefix. For devices released from 2025 onwards, this is documented on the device specification page.

SUBSCRIBEMessage 34

Subscribe to status updates

Create or update the default Device Status subscription. Setup acknowledgment and later status publications are separate; subscribing does not itself request an immediate status snapshot. Use GET when you need the current status.

Request

No payload fields are required. Omit Subscription ID (header 17), or use 0, for the default subscription documented here. Updates are subject to the selected interval and message level.

Request headers

MethodHeader 5
uint8required

Value 3 · SUBSCRIBE

Request a service to be perform an action

Message IDHeader 1
uint32optional

Include a nonzero Message ID if you need a setup acknowledgment.

IntervalHeader 6
uint32optional

Publication interval in milliseconds. Omitted or 0 allows updates as new status data becomes available.

DurationHeader 7
uint32optional

Subscription duration in milliseconds. Omitted or 0 keeps the subscription active until unsubscribed.

TimeoutHeader 8
uint32optional

Time in milliseconds to wait for the first matching status update. Omitted or 0 does not set a timeout.

Storage LevelHeader 15
uint8optional

Storage/retry policy for publications. Defaults to None (0).

  • 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
Message LevelHeader 16
uint8optional

Minimum publication level. The default Info-Auto (2) receives normal status updates; no explicit level is required.

  • 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
Subscription IDHeader 17
uint8[]optional

Value 0

Default subscription. Omit this header or use 0 so UNSUBSCRIBE can cancel it.

Expected response (MT5 - ACK)

A successful setup returns an MT5 acknowledgment with Status 0 when the request includes a nonzero Message ID. This acknowledges the request, not delivery of a status update. No acknowledgment is sent for an omitted or zero Message ID.

Correlation, status and acknowledgment rules · MT5 packet format

Later publication (MT34)

Status update

Later status updates produce Device Status messages, filtered by the subscription interval and level. They are not replies to the original SUBSCRIBE request and do not carry its Response To. Available payload fields vary by target and readings.

Publication headers

Response toHeader 3
uint32omitted

A later publication is not correlated to the subscription request.

StatusHeader 4
int8omitted

Status updates carry status data, not a command-result envelope.

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

Publication data fields

BatteryField 1
uint8optional

Battery level as a percentage.

Signal StrengthField 2
uint8optional

Signal strength as a percentage.

ModeField 3
uint8optional

Device mode.

  • 0 · Sleep
  • 1 · Awake
Network typeField 4
uint8optional

Current network.

  • 0 · No network
  • 2 · GSM (2G)
  • 3 · WCDMA (3G)
  • 4 · LTE (4G)
Network MNCField 5
uint16optional

MNC of the currently connected network. Can be 0 if not connected. Network code reference: https://mcc-mnc.net/

Network MCCField 6
uint16optional

MCC of the currently connected network. Can be 0 if not connected. Network code reference: https://mcc-mnc.net/

Firmware VersionField 7
uint32optional

Firmware version Can be a literal integer, or an encoded version number. Lightbug devices use a single integer for firmware version, e.g. 2287. ESP devices encode a semver version into an int, MAJOR*10000 + MINOR*100 + PATCH. 0.18.0 becomes 1800 and 1.1.1 becomes 10101.

Device TypeField 10
uint8optional

Type of device, relates to the SN prefix. For devices released from 2025 onwards, this is documented on the device specification page.

UNSUBSCRIBEMessage 34

Stop the default status subscription

Stop the default Device Status subscription (ID 0). This operation does not select a named subscription; supplying another Subscription ID does not cancel that named subscription.

Request

No payload fields are required. Omit Subscription ID; this operation removes the default subscription only.

Request headers

MethodHeader 5
uint8required

Value 5 · UNSUBSCRIBE

Request a service to be perform an action

Message IDHeader 1
uint32optional

Include a nonzero Message ID if you need an acknowledgment.

Expected response (MT5 - ACK)

A successful cancellation returns an MT5 acknowledgment with Status 0 when the request includes a nonzero Message ID. No acknowledgment is sent for an omitted or zero Message ID.

Correlation, status and acknowledgment rules · MT5 packet format

Message and field constants

Identifiers for this message type and its fields. See the operation sections above for rules and limits.