Start a Remote Session

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 Device Connection.

📘

Device Shadow

BioT uses the device's IoT shadow to send messages. To learn how to communicate with the shadow first, click here.

Start Session

To start a session, the device needs to listen to the following topic:

$aws/things/<clientId>/shadow/name/<usageName>/update/delta

Message body:

{
   "version":9,
   "timestamp":1682256097,
   "state":{
      "metadata":{
         "context":"eyJwYXRpZW50SWQiOiJmNzNiYWUxNS0yNmNhLTRkMzEtYWVjMS0wOTMyZDFkZDYwMmMiLCJzZXNzaW9uSWQiOiI3ZWI2YWU3Yi05YzU5LTQ1NTUtOTE2Yy04ZjY5NDA3YmZhNDkiLCJvd25lck9yZ2FuaXphdGlvbklkIjoiYWUwNmI1MWYtOTEyOS00NDg3LThiODgtN2MwNWIwMDcxMmRhIn0=",
         "state":"ACTIVE"
      },
      "data":{
         "_requiredMeasurementIntervalMilliseconds":1000,
         <UsageCustomAttributes>
      }
   },
   "metadata":{
      "metadata":{
         "context":{
            "timestamp":1682256097
         },
         "state":{
            "timestamp":1682256097
         }
      },
      "data":{
         "_requiredMeasurementIntervalMilliseconds":{
            "timestamp":1682256097
         }
      }
   }
}

📘

Note

The part is related to the session is inside the first state JSON object. The rest is a JSON wrapper added by AWS.
Also there might be some differences in the way you receive this message from the example, depending if this this is the first time this device receives the message or not.

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": "ACTIVE"
   	   },
          "data": {
               "_requiredMeasurementIntervalMilliseconds": 1000,
               <UsageCustomAttributes>
         }
      }
   }
}

The ACK message will include all the parameters sent in the start session message.