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
Possible values: SESSION_ACTIVE / SESSION_IDLE

_requiredMeasurementIntervalMilliseconds

The minimal time between measurements in milliseconds.

Integer

UsageCustomAttributes

Other custom attributes defined in BioT console for this usage session type.

key: value
Example:
"algo1": true,
"feature1": false

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.


Did this page help you?