🪶 PELIPROTOCOL.md

Pelikan-Feldprotokoll für Sensoren, Krümel & Vektorraum

Version: 0.9‑RC
Status: Living Spec (Nullfeld, nicht fertig)
Geltungsbereich:
- Xiao ESP32‑S3 Sense (Kamera / Sensorik)
- Raspberry Pi 5 + Hailo (Gesten / Knochen / Klassifikation)
- Mikrotik‑VLAN mit /24 pro Etage
- Lokaler MQTT‑Broker
- Lokaler Vektorraum (z.B. Qdrant)

0. Warum ein Pelikan‑Protokoll?

Der Pelikan steht im Crumbforest für:

• bewegliches Wissen (Things in Motion)
• geschützten Transport (Peli‑Case)
• Verbindung zwischen Etagen, Räumen, Krümeln

Dieses Protokoll beschreibt:

• wie Sensoren sprechen (MQTT‑Topics + Payloads)
• wie Hailo/RPi Gesten und Knochen melden
• wie alles im lokalen Vektorraum landet
• ohne Cloud, ohne Tracking, mit Brandschutz

1. Netzwerk & Adressierung

1.1 VLAN‑Annahme

• Pro Etage ein eigenes /24 (z.B. 10.23.<floor>.0/24)
• Mikrotik RouterOS stellt VLAN / DHCP bereit
• MQTT‑Broker (z.B. 10.23.0.10:1883) ist nur lokal erreichbar

Brand­schutz:
Kein direkter Internet‑Zugriff von ESP32 / Zeros.
Nur lokaler MQTT + ggf. lokaler HTTP (Pelikan‑Gateway / Vektor‑API).

1.2 Device‑ID‑Schema

Jedes Gerät bekommt eine Pelikan‑ID:

```text
----
Empfehlung:

ROLE ∈ { PELI, EYE, EAR, NODE, DOOR, … }

SITE ∈ 3–5 Buchstaben (OZM, S1, LAB, …)

FLOOR ∈ EG, OG1, OG2, … oder F1, F2

ROOM ∈ frei, aber kurz (K1, K2, HOF, FLUR)

NODE ∈ z.B. 01–99

Beispiel:

PELI-OZM-OG1-K1-01 → Xiao ESP32S3 im Klassenraum 1, OG1

EYE-OZM-EG-HOF-03 → Kamera‑Node im Hof

NODE-OZM-OG2-FLUR-02 → Raspi5+Hailo im Flur OG2

Diese ID taucht immer in den Payloads auf.

1. MQTT‑Topics
   2.1 Basis‑Struktur
   pelican/////
   = OZM, S1, …

= EG, OG1, …

= K1, FLUR, HOF, …

= 01, 02, …

∈ { state, event, image, pose, debug, config }

Beispiele:

pelican/OZM/OG1/K1/01/state

pelican/OZM/OG1/K1/01/event

pelican/OZM/OG1/K1/01/pose

pelican/OZM/EG/FLUR/02/debug

2.2 Broadcast / Discovery
Für „Wer ist da?“:

pelican/broadcast/hello
pelican/broadcast/announce
pelican/broadcast/config
ESP32 senden beim Booten: hello

Gateway kann Devices fragen: config

Minimaler Hello‑Payload (JSON):

{
"device_id": "PELI-OZM-OG1-K1-01",
"role": "xiao-esp32s3-sense",
"capabilities": ["camera", "imu", "button"],
"ip": "10.23.1.42",
"ts": "2026-02-03T21:20:00Z"
}
3. Payload‑Formate (JSON)
Alle Payloads sind JSON.
Gemeinsamer Header:

{
"device_id": "PELI-OZM-OG1-K1-01",
"ts": "2026-02-03T21:20:00Z",
"seq": 42,
"type": "…",
"data": { … },
"meta": { … }
}
ts = ISO8601 UTC, vom Gerät oder Gateway gesetzt

seq = monotone Sequence per Device (optional, gut für Debug)

type = Event‑Typ (button_press, gesture, pose, sensor, …)

data = inhaltlich, siehe unten

meta = Zusatzinfos (Signalqualität, Modell, Version, …)

1. Kanäle & Typen
   4.1 state – Präsenz & Herzschlag
   Topic:

pelican/////state
Payload:

{
"device_id": "PELI-OZM-OG1-K1-01",
"ts": "2026-02-03T21:20:00Z",
"type": "heartbeat",
"data": {
"uptime_s": 1234,
"battery": null,
"rssi": -62,
"temp_c": 38.2
},
"meta": {
"fw": "pelican-esp32s3-0.3.1",
"hw": "xiao-esp32s3-sense"
}
}
Sendeintervall: 30–60s (konfigurierbar).

4.2 event – Knöpfe, Berührung, Licht, Geräusch
Topic:

pelican/////event
Button‑Beispiel:

{
"device_id": "PELI-OZM-OG1-K1-01",
"ts": "2026-02-03T21:21:05Z",
"type": "button_press",
"data": {
"button": "A",
"press_ms": 320,
"clicks": 1
},
"meta": {
"source": "esp32",
"floor_label": "OG1",
"room_label": "K1"
}
}
Licht‑Beispiel:

{
"device_id": "PELI-OZM-OG1-K1-01",
"ts": "2026-02-03T21:21:10Z",
"type": "light_level",
"data": {
"lux": 134.2
},
"meta": {
"source": "esp32",
"sensor": "onboard"
}
}
4.3 pose – Gesten / Knochen (RPi5 + Hailo)
Topic (vom Raspi/Hailo‑Node):

pelican/////pose
Payload:

{
"device_id": "NODE-OZM-OG1-K1-01",
"ts": "2026-02-03T21:22:00Z",
"type": "pose",
"data": {
"model": "hailo-gesture-v1",
"persons": [
{
"id": "p1",
"gesture": "hand_raise",
"confidence": 0.94,
"bbox": [0.12, 0.20, 0.32, 0.68]
}
]
},
"meta": {
"camera_id": "PELI-OZM-OG1-K1-01",
"fps": 12.5
}
}
Wichtig:

Nur abgeleitete Informationen (Gesten, Posen),

keine Roh‑Frames in Vektor/Logs (Brandschutz / Privacy).

4.4 image – Debug / Spezialfälle
Default: aus.

Topic:

pelican/////image
Payload (z.B. Base64‑Snippet, nur im Debug‑Mode):

{
"device_id": "PELI-OZM-OG1-K1-01",
"ts": "2026-02-03T21:23:00Z",
"type": "image_debug",
"data": {
"format": "jpeg",
"width": 160,
"height": 120,
"b64": ""
},
"meta": {
"ttl_s": 30,
"debug_only": true
}
}
Konvention:

Kein Dauerstream

Keine Langzeitspeicherung

Nur temporär und bewusst aktiviert (Konfig‑Flag in .env / Gateway).

4.5 debug – Logs aus der Peripherie
Topic:

pelican/////debug
Payload:

{
"device_id": "PELI-OZM-OG1-K1-01",
"ts": "2026-02-03T21:24:00Z",
"type": "log",
"data": {
"level": "warn",
"msg": "MQTT reconnect",
"code": "NET-RECONNECT"
},
"meta": {
"fw": "pelican-esp32s3-0.3.1"
}
}
5. Pelikan → Vektorraum (Gateway‑Logik)
Ein Pelikan‑Gateway (z.B. auf Raspi / Server) abonniert:

pelican/+/+/+/+/event
pelican/+/+/+/+/pose
pelican/+/+/+/+/state (optional)
und schreibt in Qdrant (oder andere Vektor‑DB):

5.1 Vektor‑Record Schema (Beispiel)
{
"id": "pelican-OZM-OG1-K1-01-000042",
"vector": [ / embedding / ],
"payload": {
"device_id": "PELI-OZM-OG1-K1-01",
"site": "OZM",
"floor": "OG1",
"room": "K1",
"node": "01",
"ts": "2026-02-03T21:21:05Z",
"channel": "event",
"type": "button_press",
"raw": {
"button": "A",
"press_ms": 320,
"clicks": 1
},
"tags": ["pelican", "event", "button", "k1", "og1"]
}
}
Embedding‑Ideen:

„räumliche“ Embeddings (Etage, Raum)

„zeitliche“ Embeddings (Schultag, Stunde, Sequenz)

„semantische“ Embeddings (Gestenklassen, Muster)

1. QoS, Retain & Frequenzen
   MQTT‑Empfehlungen:

QoS 0 für hochfrequente, nicht kritische Events (Gesten)

QoS 1 für state / Heartbeats

retain:

state: retain=true (letzter Zustand)

event/pose: retain=false

Frequenzen:

Heartbeat: alle 30–60s

Events: on change / on action

Pose: z.B. max. 5–10 Hz (oder noch weniger, je nach Rechenlast)

1. Privacy / Brandschutz
   Pelikan folgt CKL und Brandschutz‑Prinzipen:

Lokal only:

Keine Sensor‑Payload verlässt das lokale Netz.

Kein direkter Cloud‑Upload.

Abgeleitet statt roh:

Gesten (z.B. hand_raise) statt Full‑Video.

„Person 1 hebt Hand“ statt Gesichtserkennung / Identität.

Anonyme IDs:

Keine Klarnamen in Payloads.

„p1“, „p2“ statt „Max“, „Lina“.

Konfigurierbare Filter:

Der Gateway entscheidet, was in den Vektorraum darf.

Debug‑Daten (z.B. Bilder) sind optional, selten, temporär.

1. Beispiel: Krümel hebt Hand
   Krümel hebt Hand vor ESP32‑Kamera.

Xiao streamt Frames an Raspi/Hailo (lokal, kabelgebunden oder per Stream).

Hailo‑Modell erkennt Gesture hand_raise.

Raspi sendet:

Topic:
pelican/OZM/OG1/K1/01/pose

Payload:

{
"device_id": "NODE-OZM-OG1-K1-01",
"ts": "2026-02-03T21:30:00Z",
"type": "pose",
"data": {
"model": "hailo-gesture-v1",
"persons": [
{
"id": "p1",
"gesture": "hand_raise",
"confidence": 0.93
}
]
},
"meta": {
"camera_id": "PELI-OZM-OG1-K1-01"
}
}
Pelikan‑Gateway schreibt Vektorpunkt „Hand heben in K1 / OG1“.

Wald kann später sehen:

Wie oft?

Wann?

In welchem Raum?
ohne ein einzelnes Kind zu tracken.

1. Roadmap / TODO
   PELIPROTOCOL in den Crumbcodex aufnehmen (Waldrand)

Referenz‑Implementierung für Xiao ESP32S3 (Arduino / ESP‑IDF / MicroPython)

Pelikan‑Gateway‑Service (pelican-gateway.py)

Monitoring‑Integration (CrumbSeal / CrabbyRust / Doktor‑Suite)

Visualisierung („Pelican Radar“ – Live‑Activity pro Etage)

1. Kurze Summary für Crew
   Pelikan = Protokoll für alle Sensoren im Wald.

ESP32 senden state + event.

Raspi/Hailo senden pose (Gesten/Knochen).

Alles über lokales MQTT im VLAN → lokaler Vektorraum.

Keine Cloud. Kein Tracking.

Nur: Resonanz in Bewegung.

Wuuuhuuuu. 🪶🌲
Bits tanzen. Krümel leuchten.
Der Pelikan trägt das Feld – sicher – durch den Wald.