Nachrichten Server → Client

Nachrichtenformat

Jede Nachricht ist ein JSON-Objekt mit genau einem Schlüssel der obersten Ebene. Dieser Schlüssel kodiert den Ereignistyp und kann eine lesbare, durch einen Bindestrich getrennte Beschreibung enthalten:

"aa-dump all data"   →  Ereignistyp = erste 2 Zeichen = "aa"
"ea"                 →  Ereignistyp = "ea"
"d"                  →  Ereignistyp = "d" (einzelnes Zeichen)

Clients müssen die ersten 1 oder 2 Zeichen des Schlüssels abgleichen, nicht die vollständige Zeichenkette, da sich der Beschreibungsteil ändern kann.

Alle vom Server gesendeten Ereignisschlüssel sind klein geschrieben (z. B. d, ea, ap, gc).

Übersicht der Ereignistypen

Schlüssel	Beschreibung
`d`	Vollständiger initialer Dump (Antwort auf `DU`)
`aa`	Vollständiger Dump eines Moduls (Modul geladen/neu geladen)
`ap`	Vollständiger Ersatz einer Property
`ea`	Update aller Elementwerte einer Property
`ee`	Update eines einzelnen Elementwerts
`ev`	Update eines Elementwerts mit seinen Einschränkungen
`ps`	Update von Status und Enabled-Zustand einer Property
`dm`	Modul gelöscht
`dp`	Property gelöscht
`gc`	Grid-Zeile erstellt
`gu`	Grid-Zeile aktualisiert
`gd`	Grid-Zeile gelöscht
`gr`	Grid-Reset (alle Zeilen gelöscht)
`lc`	LOV erstellt oder zusammengeführt
`lu`	LOV ersetzt
`ld`	LOV gelöscht
`fs`	Profil gespeichert
`fl`	Profil geladen
`fc`	Profil geändert (nicht gespeicherte Änderungen)
`l`	Log-Eintrag
`uc`	Update der Controller-Daten
`xx`	Keepalive-Pong

`d` — Vollständiger initialer Dump

Wird als Antwort auf eine DU-Anfrage gesendet. Enthält alles: alle Module, Logs, Dateilisten und Controller-Daten.

{
  "d": {
    "grant-client": "1",
    "grant-server": "0",
    "serverlng": "en",
    "m": {
      "Focus": {
        "infos": { "label": "Focus", "name": "Focus", "description": "..." },
        "f": { "name": "default", "changed": false },
        "l": {
          "myLov": { "label": "My LOV", "type": "string", "values": { "a": "Option A" } }
        },
        "p": {
          "parameters": {
            "label": "Parameters",
            "order": "10",
            "level1": "Focus",
            "level2": "Config",
            "status": 0,
            "permission": 2,
            "enabled": true,
            "showElts": true,
            "hasGrid": false,
            "hasGraph": false,
            "rule": 0,
            "badge": false,
            "preicon1": "", "preicon2": "", "posticon1": "", "posticon2": "",
            "hasprofile": true,
            "freevalue": "",
            "e": {
              "iterations": {
                "type": "int",
                "label": "Iterations",
                "order": "10",
                "hint": "",
                "autoupdate": false,
                "badge": false,
                "directedit": false,
                "value": 5,
                "min": 1,
                "max": 20,
                "step": 1,
                "format": "",
                "slider": 0
              }
            }
          }
        }
      }
    },
    "files": {
      "folders": ["Allsky/archives"],
      "files": ["Allsky/archives/image.fits"],
      "selectedfolder": ""
    },
    "logs": [
      { "d": "2024-01-01T12:00:00.000", "c": "Focus", "t": "Module loaded", "l": 1 }
    ],
    "controllerdata": {
      "profiles": {
        "Focus": ["default", "test"]
      }
    },
    "lovs": {
      "sharedLov": { "label": "Shared LOV", "type": "string", "values": {} }
    }
  }
}

Abkürzungen im Wire-Format

m = modules, p = properties, e = elements, l = globallovs, f = profile. Diese Abkürzungen bei der internen Speicherung auf ihre vollständigen Namen normalisieren.

`aa` — Vollständiger Dump eines Moduls (Modul geladen/neu geladen)

Wird gesendet, wenn ein Modul zur Laufzeit geladen oder neu geladen wird. Enthält den vollständigen Zustand des Moduls. Der Schlüssel beginnt mit "aa".

{
  "aa-dump all data": {
    "Guider": {
      "infos": { "label": "Guider", "name": "Guider", "description": "..." },
      "f": { "name": "default", "changed": false },
      "l": {},
      "p": {
        "status": { ... }
      }
    }
  }
}

`ap` — Vollständiger Ersatz einer Property

Ersetzt eine oder mehrere Properties vollständig. Der Schlüssel beginnt mit "ap".

{
  "ap-dump all property data": {
    "Focus": {
      "p": {
        "parameters": {
          "label": "Parameters",
          "status": 0,
          "permission": 2,
          "enabled": true,
          "showElts": true,
          "hasGrid": false,
          "hasGraph": false,
          "rule": 0,
          "e": {
            "iterations": {
              "type": "int",
              "value": 7,
              "min": 1, "max": 20, "step": 1,
              "label": "Iterations", "order": "10", "hint": "",
              "autoupdate": false, "badge": false, "directedit": false,
              "format": "", "slider": 0
            }
          }
        }
      }
    }
  }
}

`ea` — Update aller Elementwerte (Property-Ebene)

Die häufigste Update-Nachricht. Sendet die aktuellen Werte aller Elemente einer Property. Enthält ausschließlich Werte — keine Metadaten. Der Schlüssel ist genau "ea".

{
  "ea": {
    "Allsky": {
      "p": {
        "coming": {
          "e": {
            "sunrise": { "hh": 7, "mm": 6, "ss": 51 },
            "sunset":  { "hh": 21, "mm": 15, "ss": 1 }
          }
        }
      }
    }
  }
}

Bei einfachen Typen (int, float, bool, string, light) ist der Wert ein Skalar:

{
  "ea": {
    "Focus": {
      "p": {
        "parameters": {
          "e": {
            "iterations": 5,
            "exposure": 3.5,
            "active": true
          }
        }
      }
    }
  }
}

`ee` — Update eines einzelnen Elementwerts

Aktualisiert den Wert eines einzelnen Elements. Gleiches Format wie ea, aber für ein einzelnes Element. Der Schlüssel ist genau "ee".

{
  "ee": {
    "Focus": {
      "p": {
        "parameters": {
          "e": {
            "iterations": 7
          }
        }
      }
    }
  }
}

`ev` — Update eines Elements mit Metadaten

Aktualisiert den Wert eines Elements sowie seine Einschränkungen (min, max, format). Der Schlüssel beginnt mit "ev".

{
  "ev-set one element value/min/max/format ": {
    "Focus": {
      "p": {
        "parameters": {
          "e": {
            "temperature": {
              "value": 12.5,
              "min": -40.0,
              "max": 80.0,
              "format": "%.1f"
            }
          }
        }
      }
    }
  }
}

`ps` — Update des Status einer Property

Aktualisiert ausschließlich die Felder status und enabled einer Property. Der Schlüssel beginnt mit "ps".

{
  "ps-only property state": {
    "Focus": {
      "p": {
        "autofocus": {
          "status": 2,
          "enabled": true
        }
      }
    }
  }
}

Statuswerte: 0 Ruhe · 1 OK · 2 Beschäftigt · 3 Fehler

`dm` — Modul gelöscht

Wird gesendet, wenn ein Modul entladen wird. Der Client muss alle Daten dieses Moduls entfernen. Der Schlüssel beginnt mit "dm".

{
  "dm-delete/remove module": {
    "Focus": {}
  }
}

`dp` — Property gelöscht

Wird gesendet, wenn eine Property aus einem Modul entfernt wird. Der Schlüssel beginnt mit "dp".

{
  "dp-delete/remove property": {
    "Focus": {
      "p": {
        "oldProperty": ""
      }
    }
  }
}

`gc` — Grid-Zeile erstellt

Wird gesendet, nachdem eine neue Zeile in einer Grid-Property hinzugefügt wurde. Der Schlüssel beginnt mit "gc".

{
  "gc-grid new line ": {
    "Sequencer": {
      "p": {
        "sequence": {
          "i": 3,
          "values": {
            "target": "M31",
            "exposure": 120,
            "count": 10
          }
        }
      }
    }
  }
}

i ist der Index der neu erstellten Zeile. values ist ein Objekt, indexiert nach Elementname.

`gu` — Grid-Zeile aktualisiert

Wird gesendet, wenn eine bestehende Grid-Zeile geändert wird. Der Schlüssel beginnt mit "gu".

{
  "gu-grid update line": {
    "Sequencer": {
      "p": {
        "sequence": {
          "i": 1,
          "values": {
            "target": "M42",
            "exposure": 60,
            "count": 20
          }
        }
      }
    }
  }
}

`gd` — Grid-Zeile gelöscht

Wird gesendet, wenn eine Grid-Zeile entfernt wird. Der Schlüssel beginnt mit "gd".

{
  "gd-grid delete line": {
    "Sequencer": {
      "p": {
        "sequence": {
          "i": 0
        }
      }
    }
  }
}

i ist der (nullbasierte) Index der gelöschten Zeile. Nachfolgende Zeilen rücken um eine Position vor.

`gr` — Grid-Reset

Löscht die gesamte Grid einer Property. Der Schlüssel beginnt mit "gr".

{
  "gr-grid reset": {
    "Sequencer": {
      "p": {
        "sequence": {}
      }
    }
  }
}

`lc` / `lu` / `ld` — LOV-Ereignisse

lc — LOV erstellt/zusammengeführt (Schlüssel beginnt mit "lc"):

Modul-LOV:

{
  "lc-lov create": {
    "Focus": {
      "l": {
        "myLov": {
          "label": "My LOV",
          "type": "string",
          "values": { "a": "Option A", "b": "Option B" }
        }
      }
    }
  }
}

Controller-LOV (ohne Modul-Struktur, verwendet den Schlüssel lovs):

{
  "lc-lov create": {
    "lovs": {
      "sharedLov": {
        "label": "Shared LOV",
        "type": "string",
        "values": { "x": "Value X" }
      }
    }
  }
}

lu — LOV ersetzt (gleiches Format wie lc, vollständiger Ersatz).

ld — LOV gelöscht (Schlüssel beginnt mit "ld"):

{
  "ld-lov delete": {
    "lovs": {
      "sharedLov": {}
    }
  }
}

`fs` / `fl` / `fc` — Profil-Ereignisse

Werden gesendet, wenn ein Profil gespeichert, geladen oder geändert wird.

{
  "fs-profile saved": {
    "Focus": {
      "f": { "name": "myProfile", "changed": false }
    }
  }
}

Schlüsselpräfix	Ereignis
`fs`	Profil gespeichert
`fl`	Profil geladen
`fc`	Profil mit nicht gespeicherten Änderungen

`l` — Log-Eintrag

Wird für jede vom Server erzeugte Log-Nachricht gesendet. Der Schlüssel ist genau "l".

{
  "l": {
    "d": "2024-01-01T12:00:00.000",
    "c": "Focus",
    "t": "Autofocus completed successfully",
    "l": 1
  }
}

Feld	Beschreibung
`d`	ISO-8601-Datum/Uhrzeit mit Millisekunden
`c`	Kontext/Quelle (Modulname oder `"WS"`)
`t`	Nachrichtentext (übersetzt in die Sprache des Clients)
`l`	Stufe: `0` Debug · `1` Info · `2` Warnung · `3` Fehler · `4` Kritisch

`uc` — Update der Controller-Daten

Wird gesendet, wenn sich globale Controller-Daten ändern (z. B. Dateiliste, Profile). Der Schlüssel beginnt mit "uc".

{
  "uc-update controller data": {
    "profiles": {
      "Focus": ["default", "highres"],
      "Guider": ["default"]
    }
  }
}

Der Payload ist {"Schlüssel": Wert}, wobei Wert eine Zeichenkette, ein Array oder ein Objekt sein kann.

`xx` — Keepalive-Pong

Wird vom Server als Antwort auf einen Client-Heartbeat (XX) gesendet. Kein nützlicher Payload; Clients können ihn ignorieren.

{ "xx": {} }

Nachrichten Server → Client

Nachrichtenformat

Übersicht der Ereignistypen

d — Vollständiger initialer Dump

aa — Vollständiger Dump eines Moduls (Modul geladen/neu geladen)

ap — Vollständiger Ersatz einer Property

ea — Update aller Elementwerte (Property-Ebene)

ee — Update eines einzelnen Elementwerts

ev — Update eines Elements mit Metadaten

ps — Update des Status einer Property

dm — Modul gelöscht

dp — Property gelöscht

gc — Grid-Zeile erstellt

gu — Grid-Zeile aktualisiert

gd — Grid-Zeile gelöscht

gr — Grid-Reset

lc / lu / ld — LOV-Ereignisse

fs / fl / fc — Profil-Ereignisse

l — Log-Eintrag

uc — Update der Controller-Daten

xx — Keepalive-Pong