Skip to content

WebSocket API Dokumentation

Verbindung zum Server

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

wss://android.cs.hs-rm.de:2001
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 drei Fehlern kommen: Entweder sind die Login-Details nicht korrekt, der User ist bereits mit dem Websocket verbunden oder der User ist noch nicht mit dem Dashboard verbunden.

Server Antwort - Userdetails nicht korrekt

{
    "type": "NOT_AcceptedPW"
}
Felder

Feld Typ Beschreibung
type String Nachrichtentyp

1.1.1 Verbindungsaufbau mit dem Server: User bereits verbunden

Server Antwort - User bereits verbunden

{
    "type": "NOT_AcceptedUserInUse"
}

Felder

Feld Typ Beschreibung
type String Nachrichtentyp

1.1.2 Verbindungsaufbau mit dem Server: User ist nicht mit dem Dashboard verbunden

Server Antwort - User ist nicht dem Dashboard verbunden

{
    "type": "UserNotOnline"
}
Felder

Feld Typ Beschreibung
type String Nachrichtentyp

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": "UserNotOnline",
    "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": "getData",
  "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, 60)

Beispiel: Server will keine Messdaten mehr

{
  "type": "getData",
  "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, 60) |

Beispiel: User loggt sich aus (Dashboard) Szenario: User und Dashboard sind eingeloggt. User loggt sich im Dashboard aus, Uhr ist weiterhin verbunden. Verbindung bleibt erhalten, Uhr wird darüber informiert.

{
    "type": "UserCancelled"
}
Felder

Feld Typ Beschreibung
type String Nachrichtentyp

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": -1.0E30,
      "timestamp": "2025-03-01-11-44-49-301",
      "decibel": 9.030899869919436,
      "magnitude": 2.82842712474619
    }
  ],
  "hertz": 1,
  "type": "liveWatchMotion",
  "user": "7"
}

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 (liveWatchMotion)
user String User-ID

4. Batteriezustand der Uhr

Alle 5 Minuten wird der aktuelle Batteriezustand der Uhr an den Server geschickt.

Beispiel: Batteriezustand

{
    "battery":100,
    "type":"liveWatchBattery",
    "user":"7"
}

Felder:

Feld Typ Beschreibung
type int Nachrichtentyp (liveWatchBattery)
battery String Aufgerundeter Batteriestand der Uhr
user String UserId

Ablauf der Kommunikation - Erfolgreich

sequenceDiagram
    participant Client
    participant Server

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

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

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

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

Ablauf der Kommunikation - Beispiel: Nutzer bereits eingeloggt

sequenceDiagram
    participant Client
    participant Server

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