Sending Mesurements From Gateway

The following article will got over a complete flow of a gateway sending observations to BioT.

Steps covered here are:

• Login to BioT
• Start a session from the gateway
• Get temporary credentials and connect to IoT
• Send continuous data
• Stop the session and send session summary

Login to BioT

To login to BioT use the user (patient/caregiver) credentials with the following API:

https://example.com/ums/v2/users/login

For more information click here.

From the response save the user ID. It will be used in the next steps.

Start a session from the gateway

To start a session make a request to the following API:

https://example.com/device/v1/devices/{deviceId}/usage-sessions/usage-type/{usageType}

With the following request body:

{
  "_startTime": "{{current_timestamp}}",
  "_state": "ACTIVE",  
  "_patient": {
    "id": "{{PATIENT_ID}}"
  }
}

• deviceId is the ID of device that was used to take the measurements.
• usageType is the session type that you would like to used by the device. The usage type is defined in the device template and directs the device to what kind of measurements it should take.
• _startTime is the start time of the session and should be passed in ISO8601 format, for example: 2023-11-06T07:53:37.618Z
• _patient.id is the id of patient that the measurements are taken from. The ID of the patient is obtained from the login API.

From the response save the session context and the session ID.

Get temporary credentials and connect to IoT

To connect to the IoT service you will need credentials that will be used to authenticate against the AWS IoT broker. Use the following API:

https://example.com/ums/v1/temp-credentials/organization

Use the credentials returned to login to AWS IoT. It is recommended to use any of the AWS provided IoT SDKs.

Send continuous data

Once connected to IoT the gateway can send measurements to BioT using the MQTT protocol.

To do so gateway needs to send MQTT formatted messages to the following MQTT topic:

<clientId>/from-device/measurement

The clientId in the following topics is configured in the device during the activation stage. See Direct Device Connection for more information.

An example of a measurement message:

{
   "metadata":{
      "timestamp":1641985478161,
      "context":"ewogICJwYXRpZW50SWQiOiAiZDU3MzhkZjYtMGRlZS00YTY1LTk0MzktODg5ZTE3YTM2MjM3IiwKICAic2Vzc2lvbklkIjogIjBhYWVjYTRmLTMxOGUtNDg5MS1hOWY1LWY3YTBiNzkyMjVkNCIsCiAgIm93bmVyT3JnYW5pemF0aW9uSWQiOiAiYWUwNmI1MWYtOTEyOS00NDg3LThiODgtN2MwNWIwMDcxMmRhIgp9"
   },
   "data":{
      "hr":"97",
      "spo2":"92"
   }
}

Note that the "hr" and "spo2" are just examples of observation attributes that need to be defined in the patient template.

For more information about sending measurements via MQTT click here.

Stop the session and send session summary

Once all measurements are sent the gateway can close the session by calling the following API:

https://example.com/device/v1/devices/{deviceId}/usage-sessions/{id}

with the following body:

{
  "_endTime": "{{current_timestamp}}",
  "_state": "DONE",
  "_summary": {
    "_stopReason": "Manual Stop",
    "_stopReasonCode": "COMPLETION"
  }
}

• deviceId is the ID of device that was used to take the measurements.
• _state is the current state of the session. You can set it to "DONE"
• _endTime is the end time of the session and should be passed in ISO8601 format, for example: 2023-11-06T07:53:37.618Z
• _stopReason is a free text reason for stopping the session
• _stopReasonCode is used to indicate if the session was successful or failed. Use "COMPLETION" for successful completion.

For more information about stopping a session click here.