# Buzzer-Kommunikationsprotokoll (vNext Entwurf)

Diese Datei beschreibt den geplanten Neuentwurf des Protokolls. Ziel ist ein klar strukturiertes Binärprotokoll mit stabilen Typen, expliziter Endianness und sauberem Streaming für große Daten.

## 1) Grundregeln

- Transport: USB CDC (Byte-Stream)
- Multi-Byte-Integer: **Little Endian**
- Integer-Typen im Protokoll: nur feste Breiten (`uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`)
- `bool`: als `uint8_t` (`0` = false, `1` = true)
- Strings: immer `len + bytes`, ohne implizites `\0`
- `unsigned long` wird im Protokoll **nicht** verwendet (plattformabhängig)

> Hinweis: Obwohl nRF52 und STM32G0 beide Little Endian sind, bleibt Endianness explizit Teil der Spezifikation.

## 2) Frame-Struktur

Alle Requests und Responses nutzen denselben Header.

### 2.1 Header

| Feld | Typ | Beschreibung |
|---|---|---|
| `sync` | 4 Byte | Immer `BUZZ` (`0x42 0x55 0x5A 0x5A`) |
| `frame_type` | `uint8_t` | Typ des Frames (siehe unten) |
| `command_id` | `uint8_t` | Kommando-ID |
| `sequence` | `uint16_t` | Anfrage-/Antwort-Korrelation |
| `payload_len` | `uint32_t` | Länge von `payload` in Bytes |
| `header_crc16` | `uint16_t` | CRC16 über Header ohne `sync` und ohne `header_crc16` |

Danach folgen:

| Feld | Typ | Beschreibung |
|---|---|---|
| `payload` | `byte[payload_len]` | Kommandoabhängige Nutzdaten |
| `payload_crc32` | `uint32_t` | CRC32 über `payload` |

### 2.2 `frame_type`

| Wert | Name | Bedeutung |
|---:|---|---|
| `0x01` | `REQ` | Host → Device Anfrage |
| `0x10` | `RESP_ACK` | Erfolgreich, ohne Nutzdaten |
| `0x11` | `RESP_DATA` | Erfolgreich, mit Nutzdaten |
| `0x12` | `RESP_STREAM_START` | Start eines Datenstroms |
| `0x13` | `RESP_STREAM_CHUNK` | Chunk eines Datenstroms |
| `0x14` | `RESP_STREAM_END` | Ende eines Datenstroms |
| `0x7F` | `RESP_ERROR` | Fehlerantwort |

## 3) Antwortmodell (ACK vs DATA)

Ja, wir unterscheiden explizit:

- **`RESP_ACK`**: „OK ohne Payload“ (Host muss nur Erfolg verbuchen)
- **`RESP_DATA`**: „OK mit Payload“
- **`RESP_ERROR`**: Fehlercode + optionaler Detailtext

Damit ist Parsing eindeutig und ohne Sonderfälle wie „OK aber vielleicht mit Daten“.

## 4) Fehlercodes

Fehlercodes bleiben wie bisher inhaltlich erhalten (`P_ERR_*`), werden aber als Binärwert in `RESP_ERROR` übertragen.

### 4.1 Fehler-Payload (`RESP_ERROR`)

| Feld | Typ | Beschreibung |
|---|---|---|
| `error_code` | `uint8_t` | Protokollfehlercode |
| `detail_len` | `uint8_t` | Länge von `detail` |
| `detail` | `byte[detail_len]` | Optionaler Kurztext (ASCII/UTF-8) |

## 5) Kommandos (erste Aufteilung)

## 5.1 `0x00` `GET_PROTOCOL_VERSION`

**Request-Payload:** keine

**Response:** `RESP_DATA`

| Feld | Typ | Beschreibung |
|---|---|---|
| `protocol_version` | `uint16_t` | Versionsnummer des Protokolls |

## 5.2 `0x01` `GET_FIRMWARE_STATUS`

**Request-Payload:** keine

**Response:** `RESP_DATA`

| Feld | Typ | Beschreibung |
|---|---|---|
| `status` | `uint8_t` | `0` = pending, `1` = confirmed |
| `version_len` | `uint8_t` | Länge des Versionsstrings |
| `version` | `byte[version_len]` | Firmware-Version |

## 5.3 `0x02` `GET_FLASH_STATUS`

**Request-Payload:** keine

**Response:** `RESP_DATA`

| Feld | Typ | Beschreibung |
|---|---|---|
| `block_size` | `uint32_t` | Bytes pro Block |
| `total_blocks` | `uint32_t` | Gesamtblöcke |
| `free_blocks` | `uint32_t` | Freie Blöcke |
| `path_max_len` | `uint32_t` | Maximale erlaubte Pfadlänge in Bytes |

## 5.4 `0x10` `LIST_DIR`

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `path_len` | `uint8_t` | Länge von `path` |
| `path` | `byte[path_len]` | Zielverzeichnis, z. B. `/` oder `/lfs/a` |

`path_len` darf den in `GET_FLASH_STATUS.path_max_len` gemeldeten Wert nicht überschreiten.

**Response:** `RESP_DATA`

`LIST_DIR` liefert Einträge als Stream:

1. `RESP_STREAM_START`
2. `RESP_STREAM_CHUNK` pro Verzeichniseintrag
3. `RESP_STREAM_END`

### `RESP_STREAM_START` Payload

| Feld | Typ | Beschreibung |
|---|---|---|
| `entry_count` | `uint32_t` | Anzahl Einträge, `0xFFFFFFFF` = unbekannt |

### `RESP_STREAM_CHUNK` Payload (ein Eintrag)

| Feld | Typ | Beschreibung |
|---|---|---|
| `entry_type` | `uint8_t` | `0` = Datei, `1` = Verzeichnis |
| `name_len` | `uint8_t` | Länge von `name` |
| `size` | `uint32_t` | Dateigröße in Bytes (`0` für Verzeichnisse) |
| `name` | `byte[name_len]` | Name ohne führenden Pfad |

### `RESP_STREAM_END` Payload

- leer

**Hinweis:** Rekursion bleibt Host-seitig. Der Host setzt aus angefragtem Basispfad + `name` den vollständigen Pfad zusammen.

## 5.5 `0x11` `CHECK_FILE_CRC`

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `path_len` | `uint8_t` | Länge von `path` |
| `path` | `byte[path_len]` | Pfad zur Datei |

`path_len` darf den in `GET_FLASH_STATUS.path_max_len` gemeldeten Wert nicht überschreiten.

**Response:** `RESP_DATA`

| Feld | Typ | Beschreibung |
|---|---|---|
| `crc32` | `uint32_t` | CRC32 (Little Endian) über den Audio-Inhalt |

**Hinweis:** Die CRC-Berechnung folgt der aktuellen Firmware-Logik für Audio-Dateien (ohne angehängte Tag-Daten).

## 5.6 `0x12` `MKDIR`

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `path_len` | `uint8_t` | Länge von `path` |
| `path` | `byte[path_len]` | Zielpfad für neues Verzeichnis |

`path_len` darf den in `GET_FLASH_STATUS.path_max_len` gemeldeten Wert nicht überschreiten.

**Response:** `RESP_ACK`

Bei Erfolg wird eine leere ACK-Antwort gesendet. Bei Fehlern `RESP_ERROR` mit passendem `P_ERR_*`.

## 5.7 `0x13` `RM`

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `path_len` | `uint8_t` | Länge von `path` |
| `path` | `byte[path_len]` | Pfad zu Datei oder leerem Verzeichnis |

`path_len` darf den in `GET_FLASH_STATUS.path_max_len` gemeldeten Wert nicht überschreiten.

**Response:** `RESP_ACK`

Bei Erfolg wird eine leere ACK-Antwort gesendet. Bei Fehlern `RESP_ERROR` mit passendem `P_ERR_*`.

**Hinweis:** Rekursives Löschen bleibt Host-seitig (mehrere `LIST_DIR` + `RM` Aufrufe).

## 5.8 `0x20` `GET_TAG_BLOB`

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `path_len` | `uint8_t` | Länge von `path` |
| `path` | `byte[path_len]` | Pfad zur Datei |

`path_len` darf den in `GET_FLASH_STATUS.path_max_len` gemeldeten Wert nicht überschreiten.

**Response:** Stream

1. `RESP_STREAM_START` mit `total_len:uint32_t`
2. `RESP_STREAM_CHUNK` mit rohen Tag-Blob-Bytes
3. `RESP_STREAM_END` (leer)

Der Blob-Inhalt ist die TLV-Metadatenstruktur aus `Tags.md` (ohne Footer `version+len+TAG!`).

## 5.9 `0x21` `SET_TAG_BLOB_START`

Startet eine Tag-Blob-Übertragung.

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `path_len` | `uint8_t` | Länge von `path` |
| `path` | `byte[path_len]` | Pfad zur Datei |
| `total_len` | `uint16_t` | Gesamtlänge des folgenden Blobs |

**Response:** `RESP_ACK`

## 5.10 `0x22` `SET_TAG_BLOB_CHUNK`

Sendet einen weiteren Chunk des Blobs.

**Request-Payload:**

| Feld | Typ | Beschreibung |
|---|---|---|
| `data` | `byte[]` | Chunk-Daten |

**Response:** `RESP_ACK`

## 5.11 `0x23` `SET_TAG_BLOB_END`

Schließt den Upload ab und schreibt den Blob in die Datei (ersetzt bestehende Tags).

**Request-Payload:** leer

**Response:** `RESP_ACK`

Hinweis: Ein leerer Blob (`total_len=0`) ist erlaubt und entspricht "Tags leeren".

## 6) Große Daten (Dateien, Audio, Firmware)

Für mehrere MB nicht als einzelnes `RESP_DATA` senden, sondern streamen.

### 6.1 Warum nicht ein riesiges `payload_len`?

- Höheres Risiko bei Paketverlust/Timeout
- Mehr RAM-/Pufferdruck auf MCU
- Schlechtere Wiederanlaufstrategie bei Fehlern

### 6.2 Streaming-Ablauf

1. `RESP_STREAM_START` mit Metadaten
2. `RESP_STREAM_CHUNK` (mehrfach)
3. `RESP_STREAM_END` mit Gesamt-CRC/Abschlussstatus

### 6.3 Stream-Metadaten (`RESP_STREAM_START`)

| Feld | Typ | Beschreibung |
|---|---|---|
| `stream_id` | `uint16_t` | ID des Streams |
| `total_len` | `uint32_t` | Gesamtlänge in Bytes |
| `chunk_size` | `uint16_t` | Ziel-Chunkgröße |

### 6.4 Chunk-Payload (`RESP_STREAM_CHUNK`)

| Feld | Typ | Beschreibung |
|---|---|---|
| `stream_id` | `uint16_t` | Zuordnung zum Stream |
| `offset` | `uint32_t` | Byte-Offset im Gesamtstrom |
| `data_len` | `uint16_t` | Länge von `data` |
| `data` | `byte[data_len]` | Nutzdaten |

`total_len` ist `uint32_t`, damit sind bis 4 GiB abbildbar. Für euer Gerät ist das mehr als ausreichend und trotzdem standardisiert.

## 7) Offene Punkte für die Implementierung

- Fixe maximale `chunk_size` (z. B. 256/512/1024 Bytes)
- ACK/NACK auf Chunk-Ebene nötig oder „best effort + Retry auf Kommando-Ebene“?
- Timeout-/Retry-Policy pro Kommando
- Welche Kommandos zuerst in `protocol.c` migriert werden

## 8) Kurzfazit für den nächsten Schritt

- Ja, getrennte Kommandos sind sinnvoll.
- Ja, Endianness muss explizit definiert sein (Little Endian).
- Ja, `ACK` und `DATA` sollten als unterschiedliche Frame-Typen geführt werden.
- Für große Dateien: `uint32_t total_len` + Chunk-Streaming statt Einmal-Payload.