WebSocket API Documentation

Connecting to the Server

The WebSocket server is accessible via the following URL (as of 23.03.2025):

wss://ios.cs.hs-rm.de:2001/health

The connection to the WebSocket is established using OkHttp3 WebSocket in Kotlin.

---

Message Formats

1. Connection Setup with the Server: Connect to Websocket

The connection is established through the OkHttp3 client and requires authentication parameters that are sent as cookies. The parameters are sent in the header as Key=Value pairs in a cookie.

Cookie

Key	Value	Description
Authorization	userPassword	User's password
user_id	userId	The user's ID
client	watch	Describes the client type, in the case of a watch, it is the watch itself

1.1.0 Connection Setup with the Server: Authentication Failed

The connection with the WebSocket from the server is always established if the URL is correct. However, errors can occur that may prevent the watch from sending data. The following errors may occur: No header was sent, login details are incorrect, the user is not yet connected to the dashboard, or the watch with the same ID is already connected. A wrong client type was sent (for the watch, it must be watch) or the header is incorrectly defined.

Server Response - User Details Incorrect

{
    "type": "ERROR_AUTH_CREDENTIALS_INCORRECT",
    "msg": "string"
}

Fields

Field	Type	Description
type	String	Message type
msg	String	Reason

1.1.1 Connection Setup with the Server: Login Details in Incorrect Format

Server Response - Login Details Cannot Be Read

{
    "type": "ERROR_AUTH_CREDENTIALS_MALFORMED",
    "msg": "string"
}

Fields

Field	Type	Description
type	String	Message type
msg	String	Reason

1.1.2 Connection Setup with the Server: No Login Details in the Header

Server Response - User Did Not Provide Login Details

{
    "type": "ERROR_AUTH_CREDENTIALS_NONE",
    "msg": "string"
}

Fields

Field	Type	Description
type	String	Message type
msg	String	Reason

1.1.3 Connection Setup with the Server: Client Type Unknown or Incorrect Client Used

Server Response - User Did Not Provide Login Details

{
    "type": "ERROR_AUTH_CLIENT_TYPE_UNKNOWN",
    "msg": "string"
}

{
    "type": "ERROR_AUTH_CLIENT_TYPE_MISSMATCHED",
    "msg": "string"
}

Fields

Field	Type	Description
type	String	Message type
msg	String	Reason

1.1.4 Connection Setup with the Server: User Already Logged In

Server Response - User Already Connected

{
    "type": "ERROR_ALREADY_CONNECTED",
    "msg": "string"
}

1.2 Connection Setup with the Server: Authentication Successful

None of the three previous messages are sent back. If the connection is successfully established, the server instead returns a timestamp. Since the watch may not show the correct time, we use our own algorithm to calculate the correct time for the transmitted data based on the server time and local time. This ensures that the sent data packets arrive in the correct order and match the server time.

Server Response - Current Timestamp from the Server

{
    "type": "STATUS_TIMESTAMP",
    "timestamp": "2025-03-01-11-31-20-206",
}

Fields

Field	Type	Description
type	String	Message type
timestamp	String	Current time from the server in the format: yyyy-MM-dd-HH-mm-ss-SSS

---

2. Message from the Server: Request for Measurement Data

In the dashboard, the user can set the Hertz and start requesting measurement data. When measurement data is requested, the client (the watch) receives a message from the server.

Example: Server Requests Measurement Data

{
  "type": "CMD_TOGGLE_GATHER",
  "action": "start",
  "hertz": "1",
}

Fields

Field	Type	Description
type	String	Message type
action	String	Can be start or stop. With start, the watch sends measurement data to the server.
hertz	String	Number of data packets per second (1, 20, 50)

Example: Server No Longer Wants Measurement Data

{
  "type": "CMD_TOGGLE_GATHER",
  "action": "stop",
  "hertz": "1",
}

Fields

Field	Type	Description
type	String	Message type
action	String	Can be start or stop. With stop, the watch no longer sends measurement data to the server.
hertz	String	Number of data packets per second (1, 20, 50)

3. Measurement Data from the Watch

The measurement data is sent to the server every second. The number of data packets varies depending on the Hertz setting. The measurement data always follows a fixed format.

Example: Measurement Data Format

{
  "data": [
    {
      "attitudePitch": 0.0005531197,
      "attitudeRoll": 0.0005453013,
      "attitudeYaw": -1.568391,
      "gravityX": -0.005347578,
      "gravityY": 0.0054242513,
      "gravityZ": 9.806647,
      "accelUserX": 0.005347578,
      "accelUserY": -0.0054242513,
      "accelUserZ": 0.0033416748,
      "gyroX": 0.0,
      "gyroY": 0.0,
      "gyroZ": 0.0,
      "heartrate": 0.0,
      "temperature": 37,
      "timestamp": "2025-03-01-11-44-49-301",
      "decibel": 9.030899869919436,
      "magnitude": 2.82842712474619
    }
  ],
  "hertz": 1,
  "type": "DATA_LIVE_MOTION"
}

Fields

Field	Type	Description
data	Array	Contains sensor data as objects
attitudePitch	Float	Pitch angle
attitudeRoll	Float	Roll angle
attitudeYaw	Float	Yaw angle
gravityX	Float	Gravitational force on the X-axis
gravityY	Float	Gravitational force on the Y-axis
gravityZ	Float	Gravitational force on the Z-axis
accelUserX	Float	Acceleration without gravity on the X-axis
accelUserY	Float	Acceleration without gravity on the Y-axis
accelUserZ	Float	Acceleration without gravity on the Z-axis
gyroX	Float	Rotation speed around the X-axis
gyroY	Float	Rotation speed around the Y-axis
gyroZ	Float	Rotation speed around the Z-axis
heartrate	Float	Heart rate (bpm)
temperature	Float	Temperature value
timestamp	String	Timestamp in the format yyyy-MM-dd-HH-mm-ss-SSS
decibel	Float	Loudness in decibels (dB)
magnitude	Float	Motion intensity
hertz	String	Hertz
type	String	Message type (DATA_LIVE_MOTION)

---

4. PPG Sensor Data from the Watch

In the app's settings, the user can choose to send PPG data from the watch.

Example: Battery Status

{
    "data": [
      {
        "PPG0": 0.0521312312,
        "PPG1": 0.0521312312,
        "PPG2": 0.0521312312,
        "PPG3": -0.3521312312,
        "PPG4": 0.0521312312,
        "PPG5": 0.0521312312,
        "PPG6": 0.005347578,
        "PPG7": -0.0054242513,
        "PPG8": 0.0033416748,
        "PPG9": 0.0521312312,
        "PPG10": 0.0521312312,
        "PPG11": 0.0521312312,
        "PPG12": 0.0521312312,
        "PPG13": 0.0521312312,
        "PPG14": 0.0521312312,
        "PPG15": 0.0521312312,
        "timestamp": "2025-03-23-11-44-49-301",
      }
    ],
    "hertz": 1,
    "type": "DATA_LIVE_MOTION"
}

Fields

Field	Type	Description
data	Array	Contains sensor data as objects
PPG0	Number	PPG0 value
PPG1	Number	PPG1 value
PPG2	Number	PPG2 value
PPG3	Number	PPG3 value
PPG4	Number	PPG4 value
PPG5	Number	PPG5 value
PPG6	Number	PPG6 value
PPG7	Number	PPG7 value
PPG8	Number	PPG8 value
PPG9	Number	PPG9 value
PPG10	Number	PPG10 value
PPG11	Number	PPG11 value
PPG12	Number	PPG12 value
PPG13	Number	PPG13 value
PPG14	Number	PPG14 value
PPG15	Number	PPG15 value
hertz	number	Hertz
type	String	Message type (DATA_LIVE_PPG)

---

5. Battery Status

Every 5 minutes, the current battery status of the watch is sent.

Example: Battery Status

{
    "battery":100,
    "type":"STATUS_BATTERY",
}

Fields

Field	Type	Description
type	int	Message type (STATUS_BATTERY)
battery	String	Rounded battery status of the watch

Communication Flow - Successful

sequenceDiagram
    participant Client
    participant Server

    Server->>Client: { "type": "STATUS_TIMESTAMP", "timestamp": "2025-02-25T12:34:56Z" }

    Server->>Client: { "type": "CMD_TOGGLE_GATHER", "action": "start", "hertz": "1" }

    Client->>Server: { "data": [{...}], "hertz": 1, "type": "DATA_LIVE_MOTION", "user": "7" }

    Server->>Client: { "type": "CMD_TOGGLE_GATHER", "action": "stop", "hertz": "1" }

Communication Flow - Example: User Already Logged In

sequenceDiagram
    participant Client
    participant Server

    Server->>Client: { "type": "ERROR_ALREADY_CONNECTED" }