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.

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.

ParameterDescriptionFormat
contextA unique string representing the session. The context is passed back to BioT with every measurement message.String
stateIndicates if the session should start or stop.String
Possible values: SESSION_ACTIVE / SESSION_IDLE
_requiredMeasurementIntervalMillisecondsThe minimal time between measurements in milliseconds.Integer
UsageCustomAttributesOther 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": "ACTIVE"
   	   },
          "data": {
               "_requiredMeasurementIntervalMilliseconds": 1000,
               <UsageCustomAttributes>
         }
      }
   }
}

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