flatbuffer base

flatbuffers/control/config_ctrl.fbs

@@ -0,0 +1,8 @@
+// Config change control — WIP.
+// Schema stub; content will be defined when the config-change sub-protocol
+// is specified (requires device-loading control in the protocol first).
+namespace hmmmm.ctrl.config_ctrl;
+
+table ConfigCtrlMessage {
+    // TODO
+}

flatbuffers/control/config_notif.fbs

@@ -0,0 +1,37 @@
+namespace hmmmm.ctrl.config_notif;
+
+// Notification subtype 0001 — a device's configuration was updated.
+// Carries the path of the affected device; client should re-request full config.
+table DeviceConfigUpdateNotif {
+    device_path: [string];   // hierarchical path, e.g. ["core"] or ["gpio_a"]
+}
+
+// Numeric ID assigned to one named segment within a device.
+table SegIdEntry {
+    name: string;
+    id:   uint32;
+}
+
+// Maps a hierarchical device path to a compact numeric device_id + segment IDs.
+// Clients use these IDs in stream and mem packets instead of string paths.
+table DeviceIdEntry {
+    path:    [string];       // hierarchical device id, e.g. ["core"]
+    device_id: uint32;
+    seg_ids: [SegIdEntry];
+}
+
+// Notification subtype 0010 — full device-id / segment-id mapping table.
+// Sent after auth and after any config change that affects the device tree.
+table DeviceIdMappingNotif {
+    entries: [DeviceIdEntry];
+}
+
+union ConfigNotifPayload {
+    DeviceConfigUpdateNotif,
+    DeviceIdMappingNotif,
+}
+
+table ConfigNotifMessage {
+    tclk:    uint64;
+    payload: ConfigNotifPayload;
+}

flatbuffers/control/control.fbs

@@ -0,0 +1,39 @@
+include "exec_ctrl.fbs";
+include "exec_notif.fbs";
+include "config_ctrl.fbs";
+include "config_notif.fbs";
+include "lost.fbs";
+include "orphaned.fbs";
+include "setup_buf.fbs";
+include "qos.fbs";
+
+namespace hmmmm.ctrl;
+
+// ── Client → Server ──────────────────────────────────────────────────────────
+
+union CtrlClientPayload {
+    hmmmm.ctrl.exec.ExecCtrlMessage,
+    hmmmm.ctrl.config_ctrl.ConfigCtrlMessage,
+    hmmmm.ctrl.lost.LostMessagesRequest,
+    hmmmm.ctrl.orphaned.OrphanedRequest,
+    hmmmm.ctrl.setup_buf.SetupBuf,
+}
+
+table CtrlClientMessage {
+    payload: CtrlClientPayload;
+}
+
+// ── Server → Client ──────────────────────────────────────────────────────────
+
+union CtrlServerPayload {
+    hmmmm.ctrl.exec_notif.ExecNotifyMessage,
+    hmmmm.ctrl.config_notif.ConfigNotifMessage,
+    hmmmm.ctrl.lost.LostMessagesResponse,
+    hmmmm.ctrl.orphaned.OrphanedResponse,
+    hmmmm.ctrl.setup_buf.SetupBuf,
+    hmmmm.ctrl.qos.QosReport,
+}
+
+table CtrlServerMessage {
+    payload: CtrlServerPayload;
+}

flatbuffers/control/exec_ctrl.fbs

@@ -0,0 +1,14 @@
+namespace hmmmm.ctrl.exec;
+
+enum ExecPrompt: byte {
+    _invalid = 0,
+    start    = 1,
+    pause    = 2,
+    resume   = 3,
+    stop     = 4,
+    reset    = 5,
+}
+
+table ExecCtrlMessage {
+    prompt: ExecPrompt;
+}

flatbuffers/control/exec_notif.fbs

@@ -0,0 +1,13 @@
+namespace hmmmm.ctrl.exec_notif;
+
+enum ExecState: byte {
+    still      = 0,
+    executing  = 1,
+    paused     = 2,
+    stopped    = 3,
+}
+
+table ExecNotifyMessage {
+    tclk:  uint64;
+    state: ExecState;
+}

flatbuffers/control/lost.fbs

@@ -0,0 +1,19 @@
+namespace hmmmm.ctrl.lost;
+
+// Client → Server: request buffered (undelivered) messages for a seat.
+table LostMessagesRequest {
+    seat_id: uint64;
+    clear:   bool = false;   // if true, drop the buffer after reading
+}
+
+// One buffered message that was not delivered before the seat disconnected.
+table LostMessage {
+    original_nonce: uint64;
+    data: [ubyte];           // raw FlatBuffer bytes of the original ServerMessage
+}
+
+// Server → Client: buffered messages for the requested seat.
+table LostMessagesResponse {
+    seat_id:  uint64;
+    messages: [LostMessage];
+}

flatbuffers/control/orphaned.fbs

@@ -0,0 +1,16 @@
+namespace hmmmm.ctrl.orphaned;
+
+// Client → Server: enumerate disconnected seats that still have buffered messages.
+// No body — request is the signal itself.
+table OrphanedRequest {}
+
+table OrphanedEntry {
+    seat_id:         uint64;
+    disconnect_tclk: uint64;   // virtual clock tick at time of disconnect
+    lost_count:      uint32;   // number of buffered messages waiting
+}
+
+// Server → Client: list of orphaned seats with pending buffers.
+table OrphanedResponse {
+    entries: [OrphanedEntry];
+}

flatbuffers/control/qos.fbs

@@ -0,0 +1,10 @@
+namespace hmmmm.ctrl.qos;
+
+// Server → Client: connection quality snapshot.
+// Sent periodically or on request (TBD).
+table QosReport {
+    rtt_us:          uint64;   // measured round-trip time, microseconds
+    packets_sent:    uint64;
+    packets_lost:    uint32;
+    buf_pressure:    float;    // outgoing buffer fill level, 0.0 .. 1.0
+}

flatbuffers/control/setup_buf.fbs

@@ -0,0 +1,8 @@
+namespace hmmmm.ctrl.setup_buf;
+
+// Client → Server: configure the lost-message buffer for this seat.
+// Server → Client: echoes back the confirmed (possibly clamped) settings.
+table SetupBuf {
+    lost_buf_size:         uint32;   // max buffered messages per seat
+    client_lifetime_ticks: uint64;   // virtual ticks to keep buffer after disconnect
+}