API Reference

This document describes the requests and responses when sending MQTT messages to the Kubios Proxy and the database API.

Kubios Proxy

MQTT topics

Kubios messages use 2 MQTT topics, one for sending requests and another for reading responses.

kubios/request
kubios/response

Users should publish to the kubios/request topic and subscribe to the kubios/response topic.

Requests

Kubios requests are published to the kubios/request topic. The requests must be in JSON format and contain the following four fields, id, type, data and analysis. The type, data and analysis fields must contain the correct information as requested by the Kubios API.

An example of a correctly formatted request:


{
  "mac": "AABBCCDDEEFF",
  "type": "RRI",
  "data": [
    828, 836, 852, 760, 800, 796, 856, 824, 808, 776, 724, 816, 800, 812, 812,
    812, 756, 820, 812, 800
  ],
  "analysis": { "type": "readiness" }
}

The mac field is the MAC address of the sending device. This is used to identify responses when multiple devices are sending simultaneously. The data field contains an array of heart rate intervals. The type and analysis fields are required by the Kubios server and should NOT be modified by the user. NOTE: While the MAC address can be sent in several common formats, the responses will always contain the address in the format specified in the example below.

Responses

Kubios responses are sent back using the MQTT topic kubios/response. Any invalid requests are responded with a JSON string (example below). Responses contain the ID number of the request and the data sent back from the Kubios server.

As an example, this is the received response to the earlier request:


{
  "mac": "AABBCCDDEEFF",
  "data": {
    "analysis": {
      "analysis_segments": {
        "analysis_length": [30],
        "analysis_start": [0],
        "noise_length": [16.099999999999998],
        "noise_start": [0]
      },
      "artefact": 100,
      "artefact_level": "VERY LOW",
      "create_timestamp": "2024-07-08T16:13:45.519759+00:00",
      "effective_prc": 0,
      "effective_time": 0,
      "freq_domain": {
        "HF_peak": 0.19666666666666666,
        "HF_power": 643.8597348835935,
        "HF_power_nu": 78.43759995255542,
        "HF_power_prc": 76.93377727768024,
        "LF_HF_power": 0.2730351722246043,
        "LF_peak": 0.15,
        "LF_power": 175.79635360243,
        "LF_power_nu": 21.416223611930576,
        "LF_power_prc": 21.005627128900766,
        "VLF_peak": 0.04,
        "VLF_power": 16.045252020604902,
        "VLF_power_prc": 1.9172216842238836,
        "tot_power": 836.901238528409
      },
      "mean_hr_bpm": 74.53416149068323,
      "mean_rr_ms": 805,
      "physiological_age": 25,
      "pns_index": -0.3011304704001718,
      "readiness": 62.5,
      "respiratory_rate": null,
      "rmssd_ms": 42.905163398997125,
      "sd1_ms": 31.170430346875026,
      "sd2_ms": 31.704701694991602,
      "sdnn_ms": 30.655320818448132,
      "sns_index": 1.767118595291916,
      "stress_index": 18.454910359256793,
      "version": "1.4.0"
    },
    "status": "ok"
  }
}

Note the MAC address format in the response.

Response to an invalid request:


{
  "data": "Invalid request"
}

NOTE: Invalid request responses contain no identifier (MAC address).

Database API

MQTT Topics

Database API uses multiple topics for requests and a single topic for responses. Users should publish to the request topics and subscribe to the response topic.

Requests
- database/devices/add
- database/patients/add
- database/patients/list
- database/records/add
Responses
- database/response

Add Device Requests

To register a new device, users should publish a request to the database/devices/add topic. The MQTT payload should contain a JSON string with the MAC address of the sending device and the desired name for the device. NOTE: As MAC addresses are unique, adding a device with the same MAC address does nothing.

Example request:


{
  "mac": "AABBCCDDEEFF",
  "device_name": "Example Device"
}

Add Device Responses

The response to a successful request contains the MAC address of the device that sent the request, the message "OK" and the database ID of the new device.

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "OK",
  "data": 2
}

The response to an unsuccessful request contains the MAC address of the device that sent the request and the message "Unable to add device."

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "Unable to add device.",
  "data": ""
}

Add Patient Requests

To register a new patient, users should publish a request to the database/patients/add topic. The MQTT payload should contain a JSON string with the MAC address of the sending device and the desired name for the patient.

Example request:


{
  "mac": "AABBCCDDEEFF",
  "patient_name": "Example Patient"
}

Add Patient Responses

The response to a successful request contains the MAC address of the device that sent the request, the message "OK" and the database ID of the new patient. NOTE: Patient names are NOT unique. Same database can contain multiple patients with the same name. Users should use the returned ID number to refer to a specific patient when making requests.

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "OK",
  "data": 2
}

The response to an unsuccessful request contains the MAC address of the device that sent the request and the message "Unable to add patient."

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "Unable to add patient.",
  "data": ""
}

List Patient Requests

To list all patients in the database, users should publish a request to the database/patients/list topic. The MQTT payload should contain a JSON string with the MAC address of the sending device.

Example request:


{
  "mac": "AABBCCDDEEFF"
}

List Patient Responses

The response to a successful request contains the MAC address of the device that sent the request, the message "OK" and a JSON array containing the patients in the database.

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "OK",
  "data": [
    { "ID": 1, "Name": "Previous Patient", "DeviceID": 2 },
    { "ID": 2, "Name": "Example Patient", "DeviceID": 2 }
  ]
}

If no patients are in the database, the response contains an empty JSON array.

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "OK",
  "data": []
}

Add Record Requests

To add a new record, users should publish a request to the database/records/add topic. The MQTT payload should contain a JSON string with the MAC address of the sending device, timestamp, and mean_hr. NOTE: Any entries without at least the required fields are not stored in the database.

Example request:


{
  "mac": "AABBCCDDEEFF",
  "timestamp": 123456789,
  "mean_hr": 78
}

A record can also optionally contain any of the following fields, mean_ppi, rmssd, sdnn, sns and pns.

Example request:


{
  "mac": "AABBCCDDEEFF",
  "timestamp": 123456789,
  "mean_hr": 78,
  "mean_ppi": 789,
  "rmssd": 23,
  "sdnn": 23,
  "sns": 1.234,
  "pns": -1.234
}

Optionally the record can also contain the patient ID, this saves the record for a specific patient.

Example request:


{
  "mac": "AABBCCDDEEFF",
  "timestamp": 123456789,
  "mean_hr": 78,
  "mean_ppi": 789,
  "rmssd": 23,
  "sdnn": 23,
  "sns": 1.234,
  "pns": -1.234,
  "patient_id": 2
}

Add Record Responses

The response to a successful request contains the MAC address of the device that sent the request, the message "OK" and the database ID of the new record.

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "OK",
  "data": 3
}

The response to an unsuccessful request contains the MAC address of the device that sent the request and the message "Unable to add record."

Example response:


{
  "mac": "AABBCCDDEEFF",
  "message": "Unable to add record.",
  "data": ""
}