Respond to Remote Control Commands
A Usage Type is the device's intended use from the perspective of BioT. It is defined in the device template in the BioT console. If your device supports remote control - i.e. remote activation of its intended use - such activation can be triggered from the Organization portal.
A Usage Session is a single activation of the Usage Type.
BioT sends Start and Stop messages to the device to indicate that a user has requested remote control usage of the device. During the session, the device is expected to send measurements and optionally perform other additional tasks.
Each Usage Type has a unique name that appears in the topic name used to communicate with the device about this type of usage.
Note
The clientId in the following topics is configured in the device during the activation stage. See Direct IoT Device Integration.
Start Session
To start a session, the device needs to listen to the following topic:
$aws/things/<clientId>/shadow/name/<usageName>/update/delta
Note
To subscribe to a topic, enter the unique device ID and environment in the topic path. The environment was supplied to the device during device pairing.
Message body:
{
“state”: {
“delta” {
"metadata": {
“context”: “VVVJRHMgb2YgcGFpZW5kSWQgYW5kIHNlc3Npb25JZA==”,
“state”: “SESSION_ACTIVE”
},
"data": {
“_requiredMeasurementIntervalMilliseconds“: 1000,
<UsageCustomAttributes>
}
}
}
}
Parameter | Description | Format |
---|---|---|
context | A unique string representing the session. This context needs to be passed back to BioT with every measurement message. | String |
state | Indicates if the session should start or stop. | String |
_requiredMeasurementIntervalMilliseconds | The minimal time between measurements in milliseconds. | Integer |
UsageCustomAttributes | Other custom attributes defined in BioT console for this usage session type. | key: value |
To acknowledge, send an ACK message to the following topic:
$aws/things/<clientId>/shadow/name/<usageName>/update
ACK Message structure: (Note the “reported” section)
{
“state”: {
“reported” {
"metadata": {
“context”: “VVVJRHMgb2YgcGFpZW5kSWQgYW5kIHNlc3Npb25JZA==”,
“state”: “SESSION_ACTIVE”
},
"data": {
“_requiredMeasurementIntervalMilliseconds“: 1000,
<UsageCustomAttributes>
}
}
}
}
The ACK message will include all the parameters sent in the start session message.
Stop Session
To stop a session, BioT will send a stop session message to the same topic as the start message:
$aws/things/<clientId>/shadow/name/<usageName>/update/delta
Message body:
{
“state”: {
“delta” {
"metadata": {
“context”: “VVVJRHMgb2YgcGFpZW5kSWQgYW5kIHNlc3Npb25JZA==”,
“state”: “SESSION_IDLE”,
“stopReason”: null
},
"data": null
}
}
}
The device will acknowledge a stop message using the same ACK topic used in the start session message with all the configuration received in the start session message.
ACK Message structure: (Note the “reported” section)
{
“state”: {
“reported” {
"metadata": {
“context”: “VVVJRHMgb2YgcGFpZW5kSWQgYW5kIHNlc3Npb25JZA==”,
“state”: “SESSION_IDLE”,
“stopReason”: null
},
"data": null
}
}
}
Session Failure
If the session fails mid-session, the device will update the reported “stopReason” field with the reason it was not able to start/continue the session.
Note
The device should not change the reported “state” in a session failure and is expected to try resuming its session as long as the desired “state” is SESSION_ACTIVE.
Updated about 2 months ago