User GuideAPI Reference
ProductUse CasesResource CenterFAQAbout UsBook a DemoSign Up - It's Free
User Guide

Sending Statuses

A status attribute is a device attribute that is updated by the device. It can be seen through the BioT Manufacturer Portal and/or Organization Portal.
The device is expected to update its status to BioT whenever it is requested to do so (e.g. BioT asks the device for its status after disconnect-reconnect events), and can also update when it determines necessary - i.e. status changes.
For example: the device updates the cloud about its boot time (a built-in status field in the Device’s template using BioT Console), or its battery level (a custom field that can be added manually).

Status Update Requests

To listen to status update requests, the device needs to register to STATUS.subscribe topic read from the environmentData shadow. BioT will send an empty JSON message when it requires an update, usually after the device connects to IoT.

Built-in Status Attributes

BioT includes a list of predefined attributes for every device. It is possible to configure custom device attributes in a device template (see Device Template documentation for more info).
BioT has the below default device attributes (see BioT documentation for more details about each attribute):

📘

Note

None of the attributes are mandatory.

Attribute JSON NamePurposeType
_operational._statusAlert status of the device.Single select - CRITICAL, MAJOR, MINOR, OK.
_operational._messageDetails about the alert.String
_fwVersionFirmware version.String
Free text, e.g. 1.0.2 or myfw.1.8
_hwVersionHardware version / model.String
Free text, e.g. 1.0.2 or myhw.1.8
_timezoneTimezone where the device is usually located.UTC taken from here.
Example: America/Toronto
_bootTimeBoot time of the device.Date & Time in ISO 8601 format
Example: 2021-10-18T06:17:23Z

Sending Statuses

When a device's status changes, it needs to send an MQTT message to BioT. This message should describe the new values of the relevant status attributes.
The MQTT topic for publishing the message can be found in the STATUS.publish
attribute retrieved from the environmentData shadow.

Status Message Body Structure

The device status message body is JSON in the following format:

ParameterDescriptionFormat
metadataGeneral metadata about the message.
timestampEvent time, in milliseconds, in UTC.
Mandatory.
Epoch time in milliseconds
Example: 1641985478161
dataStatus fields with values.key-value JSON

Status message example:

{
  "metadata": {
	"timestamp": 1641985478161
  },
  "data": {
       "_operational": {
          "_status": "MINOR",
          "_message": "sensor 8 malfunction"
        },
	"batteryLevel": 0.63,
  "_fwVersion": "0.73"
  }
}

🚧

Note

The name of the attributes in the “data” section should match the attributes configured in the Status Fields tab of the Device Template in the BioT Console.

The "_status" prefix that appears in the console should be omitted here
for example to send _fwVersion you will need to send:
"_fwVersion": "0.73"

Attributes that do not match are ignored.

Supporting BioT Requests for Device Status

A device needs to subscribe to the topic described in Sending Statuses & Measurements, in order to receive a request to update its status, from the BioT cloud.

The device will subscribe to messages received from this topic, and once a message arrives, it will need to publish its status to the publishing status topic.