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>
         }
      }
   }
}

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.