Skip to content

WebSocket API Dokumentation

Verbindung zum Server

Der WebSocket-Server ist unter folgender URL erreichbar (stand 23.03.2025): 

wss://ios.cs.hs-rm.de:2001/health
Die Verbindung zum Websocket wird durch OkHttp3 WebSocket in Kotlin hergestellt.

Nachrichtenformate

1. Verbindungsaufbau mit dem Server: Websocket connect

Der Verbindungsaufbau erfolgt über den OkHttp3 Client und benötigt für die Authentifizierung Parameter, die als Cookie mitgeschickt werden. Die Parameter werden im Header als Cookie mit Key=Value Paaren mitgeschickt.

Cookie

Key Value Beschreibung
Authorization userPassword Passwort des Nutzers
user_id userId Die Userid des Nutzers
client watch Beschreibt den Clienttypen, im Falle der Uhr, die Uhr selbst

1.1.0 Verbindungsaufbau mit dem Server: Authentifizierung fehlgeschlagen

Die Verbindung mit dem Websocket vom Server erfolgt, insofern die URL korrekt ist, immer. Jedoch kann es zu Fehlern kommen, die die Uhr davon abhalten können, Daten verschicken zu können. Es kann zu diesen Fehlern kommen: Entweder wurde kein Header mitgeschickt, die Login-Details sind nicht korrekt, der User ist noch nicht mit dem Dashboard verbunden oder die Uhr mit derselben ID ist bereits verbunden. Es wurde ein falscher client-typ mitgeschickt (bei der Uhr muss es watch sein) oder der Header ist falsch definiert.

Server Antwort - Userdetails nicht korrekt

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

Feld Typ Beschreibung
type String Nachrichtentyp
msg String Grund

1.1.1 Verbindungsaufbau mit dem Server: Login Details liegen im falschen Format vor

Server Antwort - Login Details können nicht ausgelesen werden

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

Felder

Feld Typ Beschreibung
type String Nachrichtentyp
msg String Grund

1.1.2 Verbindungsaufbau mit dem Server: Im Header sind keine Login Details vorhanden

Server Antwort - User hat keine Login Details mitgeliefert

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

Feld Typ Beschreibung
type String Nachrichtentyp
msg String Grund

1.1.3 Verbindungsaufbau mit dem Server: Client-typ ist nicht bekannt oder es wurde der falsche benutzt

Server Antwort - User hat keine Login Details mitgeliefert

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


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

Feld Typ Beschreibung
type String Nachrichtentyp
msg String Grund

1.1.4 Verbindungsaufbau mit dem Server: User ist bereits angemeldet

Server Antwort - User ist bereits verbunden

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

1.2 Verbindungsaufbau mit dem Server: Authentifizierung erfolgreich

Keine der drei vorherigen Nachrichten wird zurückgesendet. Wenn die Verbindung erfolgreich hergestellt wurde, erhält man stattdessen einen Zeitstempel vom Server. Da die Uhr möglicherweise nicht die korrekte Zeit anzeigt, nutzen wir einen eigenen Algorithmus, der auf Basis der Serverzeit und der lokalen Uhrzeit eine präzise Zeit für die übermittelten Daten berechnet. So stellen wir sicher, dass die gesendeten Datenpakete in der richtigen Reihenfolge ankommen und zur Serverzeit passen.

Server Antwort - Aktueller Zeitstempel vom Server

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

Felder

Feld Typ Beschreibung
type String Nachrichtentyp
timestamp String Aktuelle Uhrzeit vom Server im Format: yyyy-MM-dd-HH-mm-ss-SSS

2. Nachricht vom Server: Messdaten sollen gesendet werden

Im Dashboard kann der Nutzer die Hertz einstellen und das Anfordern von Messdaten starten. Werden Messdaten angefordert, erhält der Client (die Uhr) eine Nachricht vom Server.

Beispiel: Server fordert Messdaten an

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

Felder

Feld Typ Beschreibung
type String Nachrichtentyp
action String Es wird unterschieden zwischen start und stop. Bei start schickt die Uhr Messdaten an den Server.
hertz String Anzahl der Datenpakete pro Sekunde (1, 20, 50)

Beispiel: Server will keine Messdaten mehr

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

Felder

Feld Typ Beschreibung
type String Nachrichtentyp
action String Es wird unterschieden zwischen start und stop. Bei stop schickt die Uhr keine Messdaten mehr an den Server.
hertz String Anzahl der Datenpakete pro Sekunde (1, 20, 50)

3. Messdaten der Uhr

Die Messdaten werden jede Sekunde an den Server geschickt. Die Anzahl der Datenpakete variiert je nach Hertz-Einstellung. Die Messdaten haben immer ein festes Format.

Beispiel: Messdaten-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"
}

Felder

Feld Typ Beschreibung
data Array Enthält Sensordaten als Objekte
attitudePitch Float Neigungswinkel in Pitch-Richtung
attitudeRoll Float Neigungswinkel in Roll-Richtung
attitudeYaw Float Neigungswinkel in Yaw-Richtung
gravityX Float Gravitationskraft auf X-Achse
gravityY Float Gravitationskraft auf Y-Achse
gravityZ Float Gravitationskraft auf Z-Achse
accelUserX Float Beschleunigung ohne Gravitation auf X-Achse
accelUserY Float Beschleunigung ohne Gravitation auf Y-Achse
accelUserZ Float Beschleunigung ohne Gravitation auf Z-Achse
gyroX Float Rotationsgeschwindigkeit um X-Achse
gyroY Float Rotationsgeschwindigkeit um Y-Achse
gyroZ Float Rotationsgeschwindigkeit um Z-Achse
heartrate Float Herzfrequenz (bpm)
temperature Float Temperaturwert
timestamp String Zeitstempel im Format yyyy-MM-dd-HH-mm-ss-SSS
decibel Float Lautstärke in Dezibel (dB)
magnitude Float Bewegungsintensität
hertz String Hertz
type String Nachrichtentyp (DATA_LIVE_MOTION)

4. PPG-Sensor Daten der Uhr

In den Einstellungen der App kann der Nutzer PPG-Daten der Uhr mitschicken.

Beispiel: Batteriezustand

{
    "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"
}

Felder

Feld Typ Beschreibung
data Array Enthält Sensordaten als Objekte
PPG0 Number PPG0-Wert
PPG1 Number PPG1-Wert
PPG2 Number PPG2-Wert
PPG3 Number PPG3-Wert
PPG4 Number PPG4-Wert
PPG5 Number PPG5-Wert
PPG6 Number PPG6-Wert
PPG7 Number PPG7-Wert
PPG8 Number PPG8-Wert
PPG9 Number PPG9-Wert
PPG10 Number PPG10-Wert
PPG11 Number PPG11-Wert
PPG12 Number PPG12-Wert
PPG13 Number PPG13-Wert
PPG14 Number PPG14-Wert
PPG15 Number PPG15-Wert
hertz number Hertz
type String Nachrichtentyp (DATA_LIVE_PPG)

5. Batteriezustand

Alle 5 Minuten wird der aktuelle Batteriezustand der Uhr mitgeschickt.

Beispiel: Batteriezustand

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

Felder

Feld Typ Beschreibung
type int Nachrichtentyp (STATUS_BATTERY)
battery String Aufgerundeter Batteriestand der Uhr

Ablauf der Kommunikation - Erfolgreich

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" }

Ablauf der Kommunikation - Beispiel: Nutzer bereits eingeloggt

sequenceDiagram
    participant Client
    participant Server

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