Link Search Menu Expand Document

Byteflies Cloud API

Convenience

The Byteflies Cloud API is developed using a serverless infrastructure and documented using an OpenAPI 3.0 specification. This API is optimized for the purpose of retrieving health data in a structured and readable format.

Table of contents
  1. Overview
    1. Recording
    2. Docking Station
  2. Getting Started
    1. Breaking down a curl HTTP request
    2. Breaking down a JSON Response
    3. Byteflies Cloud RESTful API
    4. Authentication
      1. Retrieving an Authentication Token IdToken
      2. Making requests to the API Endpoints
      3. Token Expiration
  3. Exploring the API Endpoints
    1. The /groups Endpoint
    2. The /groups/{groupId}/recordings Endpoint
    3. The /groups/{groupId}/recordings/{recordingId} Endpoint
    4. Available Signals in a Recording
      1. Units of measurement
    5. The /groups/{groupId}/recordings/{recordingId}/algorithms/{algorithmId} Endpoint
    6. The /docks/{dockName}/config Endpoint

Overview

The Byteflies Cloud gathers sample-level Recordings from Sensor Dots via the Docking Station, which are associated with a User Account. For more information, consult the Byteflies Kit IFU.

Signal
A physiologic or motion signal, as recorded by a Sensor Dot (e.g. ECG).
Channel
A Sensor Dot can record two biopotential Signals simultaneously and has two pairs of electrode connectors that each form a Channel.
Recording
The combination of all data recorded by a single Sensor Dot is grouped in a Recording.
Group
A Group combines one or more Docking Stations that are assigned to a specific study.
Patient ID
A unique string used to identify a study subject.
Patient Record
A list of pre-configured Patient IDs and the hardware they are associated with.
User Account
A Byteflies Cloud account that can contain one or more Groups and can only be accessed with a specific username and password.

Recording

Whenever a Sensor Dot is configured to start a Recording, the device initializes its sensors to start gathering data on all specified channels. At this specific point in time, the Sensor Dot captures the Recording timestamp, also known as startDate. The specifics of a Recording are discussed further.

Docking Station

The Docking Station can be thought as a relay of Recordings to the Byteflies Cloud. It reads a Recording from the Sensor Dot’s memory, and uploads it. It’s also used to calibrate and configure the Sensor Dot, and charge its batteries.

Getting Started

In this manual, we introduce curl commands for interacting with the API. To execute curl commands, the MacOS terminal, Linux console, or Windows Command Prompt can be used. This software enables a User Account to send HTTP requests or data to web servers using HTTP methods, like GET or POST.

Breaking down a curl HTTP request

curl -X GET \
  -H 'Authorization: <id token>' \
  https://api.cloud.byteflies.net/{endpoint}

-X specifies the HTTP Request method to use when sending, in this case it is the GET HTTP method.

-H specifies an HTTP Request header to be used when sending the request, in this case it is a header named Authorization. More information can be found on curl’s official documentation.

The last parameter is the URL endpoint where the HTTP request will be sent, in this case https://api.cloud.byteflies.net/{endpoint}.

Breaking down a JSON Response

{
    "AuthenticationResult": {
        "AccessToken": "eyJ..",
        "ExpiresIn": 3600,
        "IdToken": "eyJ..",
        "RefreshToken": "eyJ...",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

This response specifies a JSON object that contains the following name/value pairs:

  • AuthenticationResult
  • ChallengeParameters

Within the AuthenticationResult the following name/value pairs appear:

  • AccessToken
  • ExpiresIn
  • IdToken
  • RefreshToken
  • TokenType

A name/value pair is separated by a colon :, where the name is to the left of the colon and the value to the right. A more in-depth explanation can be found here.

Byteflies Cloud RESTful API

The sandbox API is available at the following URI:

https://api.cloud.byteflies.net

and currently has the following endpoints:

HTTP Method Endpoint Description
GET /groups Retrieve all Groups connected to your account
GET /groups/{groupId}/recordings Returns all Recordings of a specific Group
GET /groups/{groupId}/recordings/{recordingId} Retrieve the Recording details
GET /groups/{groupId}/recordings/{recordingId}/algorithms/{algorithmId} Retrieve algorithm details
PUT /docks/{dockName}/config Switch a Docking Station to configuration mode

Authentication

The access to the API is secured by authentication tokens generated by Amazon Cognito. This means that when someone makes a request without an authentication token, our API will refuse the request with a 403 Forbidden response. Valid requests can be sent to the API using these tokens on the HTTP Header Authentication, ensuring the restricted access to the resources on the Byteflies Cloud.

Retrieving an Authentication Token IdToken

In order to retrieve an authentication token, specifically the IdToken, the User Account has to log in the API with a username and password. For demonstration purposes we have created a demo account with the following credentials:

username: demo@byteflies.com
password: 16yV&dXP

To login into our API, the following curl command can be executed:

curl -X POST \
  --data '{
    "ClientId": "5kgqk7n83evq9cbqnam1biqnbr",
    "AuthFlow": "USER_PASSWORD_AUTH",
    "AuthParameters": {"USERNAME": "demo@byteflies.com", "PASSWORD": "16yV&dXP"}}' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
  -H 'Content-Type: application/x-amz-json-1.1' \
   https://cognito-idp.eu-west-1.amazonaws.com

The curl command sends a POST request to the https://cognito-idp.eu-west-1.amazonaws.com endpoint. This endpoint is part of the Amazon Cognito service from AWS, which handles the authentication of Byteflies Cloud users. To authenticate a User Account, the endpoint requires some parameters to be sent on the POST request data. Such parameters can be seen in the --data section of the request.

Noteworthy, on this line:

"AuthParameters": {"USERNAME": "demo@byteflies.com", "PASSWORD": "16yV&dXP"}}' \

The login credentials are included. To login as a different user, the USERNAME and PASSWORD fields need to be changed accordingly. To login to a different environment, the ClientId field needs to be changed. The 2 most common values:

  • 5npk57fmnt946m07lagee2q9dp (test environment)
  • 5kgqk7n83evq9cbqnam1biqnbr (production environment)

As a response, this command gets the following JSON Response:

{
    "AuthenticationResult": {
        "AccessToken": "eyJ..",
        "ExpiresIn": 3600,
        "IdToken": "eyJ..",
        "RefreshToken": "eyJ...",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

This response includes the parameter "IdToken": "eyJ..",, this value is required to make further requests to the API.

Making requests to the API Endpoints

Once the IdToken parameter is retrieved using the authentication steps above, the User Account can start making HTTP requests to the API endpoints.

For example, to request the list of Docking Stations associated with a User Account, the following command can be executed replacing <id token> with the value eyJ... retrieved in the "IdToken": "eyJ..", parameter from the previous response:

curl -X GET \
  -H 'Authorization: <id token>' \
  https://api.cloud.byteflies.net/groups/

This command sends a HTTP GET request to the https://api.cloud.byteflies.net/groups/ endpoint, which returns the list of Docking Stations associated with the User Account.

Token Expiration

Authentication Tokens are valid for the amount of time specified in the JSON response when authenticating. For instance, if the authentication responded with the following JSON response:

{
    "AuthenticationResult": {
        "AccessToken": "eyJ..",
        "ExpiresIn": 3600,
        "IdToken": "eyJ..",
        "RefreshToken": "eyJ...",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

The response includes the "ExpiresIn": 3600 name/value pair. The value 3600 specifies the amount of time in seconds that the authentication tokens are valid from the time of authentication. If the tokens have expired, the API will respond with:

{
    "message": "The incoming token has expired"
}

If that is the case, re-authenticating and retrieving a new token will be necessary.

Exploring the API Endpoints

The /groups Endpoint

The list of Groups associated with a User Account

When sending a GET request to the /groups endpoint:

curl -X GET \
  https://api.cloud.byteflies.net/groups/ \
  -H 'Authorization: <id token>'

The endpoint responds with a JSON response:

[
    {
        "id": "1234",
        "name": "TestGroup",
        "description": "Description of group"
    }
]

This response includes a list of JSON Objects that include the Group associated with your User Account. In this particular response, there is only one Group named TestGroup associated with the User Account.

The /groups/{groupId}/recordings Endpoint

The list of Recordings associated to a Group

When sending a GET request to the /groups/{groupId}/recordings endpoint, the path parameter groupId needs to be swapped with the ID of a Group. Using the Group ID retrieved above with the /groups endpoint, the following command can be executed:

curl -X GET \
  -H 'Authorization: <id token>' \
  https://api.cloud.byteflies.net/groups/1234/recordings

The endpoint will respond with a list of recordings, for example:

[
    {
        "id": "33d8951c-999f-11e9-a2a3-2a2ae2dbcce4",
        "dotId": "24:de:b6:f2:e3:60",
        "dockName": "Dock-1234",
        "patient": "patient-ID",
        "signals": [
            {
                "type":"EEG",
                "quality":"FAIL"
            },
            {
                "type":"ACC"
            }
        ],
        "startDate": 1526919822.1422584,
        "uploadDate": 1526939822.453,
        "duration": 99.384483839
    }
]

This response includes a list of one Recording with the following values:

Name Description
id A unique identifier of the Recording
dotId A unique identifier of the Sensor Dot that performed the Recording
dockName A unique identifier of the Docking Station that was used to upload the Recording
patient A patient identifier
signals A list of Signal objects available in the Recording
signals.type The type of Signal
signals.quality The quality of the Signal. Can be PASS, CHECK or FAIL*
startDate A UNIX timestamp in (fractional) seconds indicating the start of the Recording
uploadDate A UNIX timestamp in (fractional) seconds indicating the time of data upload
duration Total duration of a Recording in (fractional) seconds

*Refer to the Clinical Insights section for more information.

The /groups/{groupId}/recordings/{recordingId} Endpoint

The details of a particular Recording

When sending a GET request to the /groups/{groupId}/recordings/{recordingId}, the path parameter {recordingId} needs to be swapped with the id of a Recording. The parameter {groupId} needs to be swapped with the id of the group in which this Recording was uploaded. Taking the recordingId 33d8951c-999f-11e9-a2a3-2a2ae2dbcce4 of the previous endpoint, the following command can be executed:

curl -X GET \
  -H 'Authorization: <id token>' \
  https://api.cloud.byteflies.net/groups/1234/recordings/33d8951c-999f-11e9-a2a3-2a2ae2dbcce4

The endpoint sends back a JSON response:

{
    "id": "33d8951c-999f-11e9-a2a3-2a2ae2dbcce4",
    "dockName": "DemoDock-8e6bde5ac7e7191caaf7e3c9",
    "dotId": "24:de:b6:f2:e3:60",
    "patient": "patient-ID",
    "startDate": 1526919822.1422584,
    "uploadDate": 1526939822.453,
    "signals": [...]
}

This response includes the following:

Name Description
id A unique identifier of the Recording
dotId A unique identifier of the Sensor Dot that performed the Recording
dockName A unique identifier of the Docking Station that was used to upload the Recording
patient A patient identifier
signals A list of Signal objects available in the Recording
startDate A UNIX timestamp in (fractional) seconds indicating the start of the Recording
uploadDate A UNIX timestamp in (fractional) seconds indicating the time of data upload
duration Total duration of a Recording in (fractional) seconds
firmwareVersion The version of the firmware that was on the Sensor Dot at the time of the Recording

The specifics of signals will be explained in detail in the next section.

Update the patient identifier

You can associate a Patient Identifier with your recording with this endpoint. To do so, make a PUTrequest to the /groups/{groupId}/recordings/{recordingId} endpoint.

The payload of the body should look like this :

{
    "patient": "Patient Identifier"
}

Rerun algorithms for all signals in a recording

You can rerun algorithms for all Signals in a specific Recording. This might be useful in case a new version of the algorithm was deployed or if for some reason, the algorithm was never triggered. You cannot choose which algorithm to run, this is linked to the Signal type. To (re)run the algorithms, make a PUT request to the /groups/{groupId}/recordings/{recordingId} endpoint.

The payload of the body should look like this :

{
    "triggerAlgorithms": true
}

Available Signals in a Recording

For each Recording, a list of signals is included in the response:

{
    ...
    "signals": [
      {
            "type": "ACC",
            "rawData": "https://...",
            "samplingRate": "25",
            "conversionFactor":0.000244140625
        },
        {
            "type": "EEG",
            "channel": 1,
            "rawData": "https://...",
            "samplingRate": "250",
            "conversionFactor":0.4808108585052719,
            "algorithms":[
                {"type":"EEG_ARTFCTS",
                    "col":1,
                    "id":"09cdf800-7268-11ea-a8d6-a7682dc8f48c"}
                ]
        },
        {
            "type": "ECG",
            "channel": 2,
            "rawData": "https://...",
            "samplingRate": "250",
            "conversionFactor":1.4424325755158156
        },
        {
            "type": "GYR",
            "rawData": "https://...",
            "samplingRate": "200",
            "conversionFactor":0.030517578125
        }
    ]
}

This signals list includes an entry for each of the Signals available in a Recording. In this particular example, there is an ACC, EEG, ECG, and a GYR signal available.

The response includes the following information:

Name Description
type The type of Signal
channel The Channel number as described in the Byteflies Kit IFU
rawData A URL for the sample-level (raw) data
samplingRate The number of samples per second for the Signal
algorithms a list of available algorithm outputs containing the type of algorithm, the column in the sample-level data for which the algorithm applies and the algorithmId
conversionFactor a value to convert the sample-level data to physical units through multiplication

With this information, we know that the recording 33d8951c-999f-11e9-a2a3-2a2ae2dbcce4 has sample-level data in CSV format of Signal type ACC, which can be downloaded using the URL available in rawData. For example using the wget command:

wget \
-O 33d8951c-999f-11e9-a2a3-2a2ae2dbcce4.csv \
'https://bc-iot-platform-parseduploadsbucket-khbvk362f8kf.s3.eu-west-1.amazonaws.com/2018/05/21/33d8951c-999f-11e9-a2a3-2a2ae2dbcce4/719a0254-99a1-11e9-a2a3-2a2ae2dbcce4?AWSAccessKeyId=ASIA4GCJNCPO6RIVNIRY&Expires=1567770981&Signature=PwbiPzjeziQ9DGUQaGG504Kwoi0%3D&x-amz-security-token=AgoJb3JpZ2luX2VjEKT%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJIMEYCIQCgUhSo3YP6MaUsdHvKJwLAzNiHQvOVwsWJ1ngWlE9XrQIhAOz1Ja%2FcthQA7Wfc0Wnqx0XLfv%2FSbQtyynKMdlmsclXdKq4CCF0QABoMODM3NjcyNTcxODY5IgyWMiRcTX04GhdA4HIqiwKA4d2yKrQrzA2%2F4Sw%2FnevDMsXL1%2FCmzvszLpCha7pctguogMZ5RgMGtI8yc6jFAG900halbX8dtqwVI6Jfa3chE17pwJgAEQ%2BJ%2F%2BAkapORxcJ5sdxHY3cTzZo4KNezwbWEYpyUa5GlTbRLmqQNaarbKNqol1AA%2BtD3%2BbwUdNBUMeq5Ph16D4bZvC23a52bb4S8iSFUUdFvxfFng4jouPpssbnIIJixxzXNmQvNMLhEz9zVPTpuvqBe8VMGd22BeT%2F4kin9YyLqrU3d8lEemW8jY9EtX5CKe3hO3l6Wg079DGyMkIhg1nN22LEbDK0zp68Y8ANMUaUdoC6up02o%2FNbHGfDJmuEqDqPn02Awio7J6wU6swET3qHT342B1zNlp0kDKySNJch4iAADF1TzEVSZCzhC3p6RCMrPP8eLjaeUMECwxqSgfNeXVxXqqwK4UvNiof1%2F7QcX3a%2BWlSSJZbzbPsy0fppjMP1lB6GfBCv7qlROWhwN59NzRc7v7n2foFjGzRPh90pUmraGHPXWuaFUrzo2LqurLitNrSdcz1kdGtwNTvuW%2FcvOz4mCGKTbVKYghmUCaEY1YnUTzrIGzg0aJLiXFjgRmg%3D%3D'

This will download the file using the name 33d8951c-999f-11e9-a2a3-2a2ae2dbcce4.csv. Please note that this URL includes temporary credentials for downloading, which are only valid for 10 minutes.

Units of measurement

The units of measurements depend on the signal type.

Type SI Unit Description
ExG nV nanovolt
ACC g g-force
GYR °/s degrees per second
BAT % % of total battery capacity

The /groups/{groupId}/recordings/{recordingId}/algorithms/{algorithmId} Endpoint

The details of a particular Algorithm

When sending a GET request to the /groups/{groupId}/recordings/{recordingId}/algorithms/{algorithmId}, the path parameter {recordingId} needs to be swapped with the id of a recording. The parameter {groupId} needs to be swapped with the id of the group in which this recording was uploaded. The parameter {algorithmId} needs to be swapped with the id of the algorithm.

Taking the recordingId 33d8951c-999f-11e9-a2a3-2a2ae2dbcce4 of the previous endpoint, and the algorithmId 09cdf800-7268-11ea-a8d6-a7682dc8f48c the following command can be executed:

curl -X GET \
  -H 'Authorization: <id token>' \
  https://api.cloud.byteflies.net/groups/1234/recordings/33d8951c-999f-11e9-a2a3-2a2ae2dbcce4/algorithms/09cdf800-7268-11ea-a8d6-a7682dc8f48c

This will download the file using the name 09cdf800-7268-11ea-a8d6-a7682dc8f48c-EEG_ARTFCTS.csv. Please note that this URL includes temporary credentials for downloading, which are only valid for 10 minutes.

The /docks/{dockName}/config Endpoint

You can set a Docking Station in one of your groups to CONFIGURATION or NORMAL mode. To do so, make a PUT request to the /docks/{dockName}/config endpoint.

The payload of the body should look like this to enter CONFIGURATION mode:

{
    "mode": "configuration",
    "configSignals": [
        {"type": "ECG", "fs": 250, "channel": 1},
        {"type": "EEG", "fs": 250, "channel": 2},
        {"type": "ACC", "fs": 25},
        {"type": "GYR", "fs": 25},
    ]
}
  • In case you do not want to measure a certain Signal, simple omit it.
  • Allowed signal types are: EEG, ECG, EOG, EMG, ACC, or GYR.
  • For any biopotential (ExG) Signal, you should define a Channel number (1 or 2) and the sampling frequency should be 250 Hz.
  • For ACC or GYR Signals, no Channel needs to be specified and the sampling frequency can be 25, 50, 100 or 200 Hz.

To revert the Docking Station to NORMAL mode, set the payload as follows:

{
    "mode" : "normal"
}

Copyright © 2020 Byteflies