Geräteprotokolle über BLE und USB entwerfen

KURZ GESAGT: Schreiben Sie das Geräteprotokoll auf, bevor eine der beiden Seiten gebaut wird: Transport-Mapping, Frame-Format, Nachrichtentypen, Versionierung, Fehlercodes und Timeouts. Halten Sie das Anwendungsprotokoll unabhängig von BLE oder USB, damit es sich über ein serielles Kabel testen lässt. Eine gemeinsame Spezifikation und ein hostseitiges Testwerkzeug lassen Firmware- und App-Team parallel arbeiten und Unstimmigkeiten früh finden.

Schichtendiagramm eines Geräteprotokolls: Die Anwendung auf Smartphone oder PC spricht über eine Protokollbibliothek mit einem Transportadapter für BLE GATT oder USB CDC bzw. HID; dieser erreicht den Transporttreiber des Geräts, einen Frame-Parser, einen Befehlsverteiler und die Geräteanwendung. Ein Host-Testwerkzeug setzt auf der Frame-Schicht an.
Abbildung 1. Protokollschichten. Der Transport wechselt, Frame- und Nachrichtenschicht bleiben.

1.0 Wo Geräteprotokolle schiefgehen

Die meisten Protokollprobleme haben mit BLE oder USB an sich wenig zu tun. Sie entstehen, weil die Schnittstelle nie aufgeschrieben wurde. Der Firmware-Entwickler legt ein Byte-Layout fest, der App-Entwickler liest es aus einem Log ab, und beide Seiten driften auseinander. Spätestens beim zweiten Firmware-Release weiß niemand mehr, welche Seite recht hat, ein Update bricht die App-Version, die schon im Store ist, und die Korrektur verlangt ein abgestimmtes Release auf beiden Seiten.

Die Spezifikation umfasst Transporte, Frame, Nachrichtentabelle, Fehlertabelle und Timeouts. Schreiben Sie sie vor dem ersten Sniffer-Mitschnitt, nicht danach.

2.0 Schichten

Wir teilen das Protokoll in Schichten, damit sich jede einzeln testen lässt:

SchichtAufgabeÄndert sich, wenn
TransportBytes bewegen: BLE-GATT-Characteristics, USB CDC-ACM, USB-HID-Reports, UARTHardware oder Betriebssystem wechseln
FramingNachrichtengrenzen, Länge, Integritätsprüfung, SequenznummerSelten
NachrichtenBefehls- und Antworttypen, Payload-Kodierung, FehlercodesNeue Funktionen
AnwendungWas das Gerät mit einem Befehl tutSich das Produktverhalten ändert

Framing- und Nachrichtenschicht sollten nicht wissen, welcher Transport darunter liegt. Dann läuft dasselbe Protokoll am Messplatz über UART, im Fertigungstest über einen USB-Seriell-Adapter und im Produkt über BLE.

3.0 Den Transport wählen

AnforderungBLEUSB CDC-ACM (virtuelle serielle Schnittstelle)USB HID
Drahtlos zum SmartphonePasst von Haus ausNicht anwendbarNicht anwendbar
Ohne Treiber auf Desktop-BetriebssystemenBraucht den Bluetooth-Stack des BetriebssystemsMitgelieferter Treiber unter Windows 10 und neuer, macOS und LinuxOhne Treiber
Zugriff aus dem BrowserWeb Bluetooth, wo unterstütztWeb Serial, wo unterstütztWebHID, wo unterstützt
DurchsatzBegrenzt durch Connection Interval und MTUHöherBegrenzt durch Report-Größe und Polling
EnergieFür niedrigen Verbrauch ausgelegtGerät kann im verbundenen Zustand Busstrom beziehenWie bei CDC

Die Unterstützung für Web Bluetooth, Web Serial und WebHID unterscheidet sich je nach Browser und Plattform. Prüfen Sie den aktuellen Stand für die Browser Ihrer Nutzer, bevor Sie sich darauf verlassen. Viele Produkte nutzen beides: BLE für die Smartphone-App, USB für Konfiguration, Fertigungstest und Recovery.

3.1 Abbildung auf BLE GATT

Zwei verbreitete Ansätze:

  • Ein Attribut pro Wert. Jede Einstellung und jeder Messwert ist eine eigene Characteristic. Mit generischen BLE-Tools leicht einzusehen, aber neue Funktionen bedeuten Änderungen an der GATT-Tabelle, und Aktualisierungen mehrerer Felder sind nicht atomar.
  • Message Pipe. Eine Characteristic für Schreibzugriffe vom Host zum Gerät, eine für Notifications vom Gerät zum Host, beide transportieren gerahmte Nachrichten. Ein Protokoll für alle Funktionen; die GATT-Tabelle bleibt stabil.

Sobald das Gerät mehr als eine Handvoll Werte bereitstellt, nehmen wir eine Message Pipe und behalten Standard-Services (Device Information, Battery) als Attribute, damit generische Tools weiter funktionieren. Eigene Services brauchen 128-Bit-UUIDs; die Standard-UUIDs stehen in der Assigned-Numbers-Liste der Bluetooth SIG.

Durchsatz und Latenz hängen von den Verbindungsparametern und der ausgehandelten ATT-MTU ab, und die bestimmt eher das Smartphone als das Gerät. Legen Sie das Protokoll so an, dass eine Nachricht über mehrere Notifications verteilt und wieder zusammengesetzt werden kann, und gehen Sie von keiner bestimmten MTU aus.

3.2 Abbildung auf USB

CDC-ACM erscheint dem Host als serielle Schnittstelle und passt zu einem Byte-Stream-Protokoll mit Framing. HID liefert Reports fester Größe und funktioniert ohne Treiber, was bei abgeschotteten Firmen-PCs hilft; die Framing-Schicht verteilt Nachrichten dann auf mehrere Reports. Beide Klassenspezifikationen veröffentlicht das USB-IF.

4.0 Der Frame

Das Frame-Format, von dem wir ausgehen:

FeldGrößeHinweise
Startmarke oder Längenpräfix1–2 ByteLängenpräfix bei BLE/HID; Begrenzung nach COBS- oder SLIP-Art bei Byte-Streams
Protokollversion1 ByteMajor-Version des Frame-Formats
Sequenznummer1–2 ByteOrdnet Antworten den Anfragen zu; erkennt verlorene Frames
Nachrichtentyp1–2 ByteBefehl, Antwort, Ereignis, Fehler
Payload-Länge2 ByteExplizit, auch wenn der Transport selbst eine Länge kennt
PayloadvariabelKodierung je Projekt (feste Structs, TLV, CBOR, Protobuf)
Integritätsprüfung2–4 ByteCRC bei Byte-Streams; kann entfallen, wo der Transport bereits prüft

Die Payload-Kodierung ist ein Abwägen zwischen Codegröße auf dem Gerät und Flexibilität. Feste Little-Endian-Structs sind am kleinsten und am schwersten weiterzuentwickeln. Mit TLV oder CBOR lassen sich optionale Felder ergänzen, ohne alte Leser zu brechen.

5.0 Versionierung und Kompatibilität

Schreiben Sie die Kompatibilitätsregel auf. Unsere:

  1. Das Gerät meldet Protokollversion und Feature-Flags als Antwort auf einen „hello“- oder „get info“-Befehl, dessen Aufbau sich nie ändert.
  2. Neue Felder kommen optional hinzu. Leser ignorieren Felder, die sie nicht kennen.
  3. Ein Feld zu entfernen oder seine Bedeutung zu ändern erfordert eine neue Major-Version, und die App unterstützt die vorherige Major-Version für einen dokumentierten Zeitraum weiter.
  4. Die Release Notes von Firmware und App nennen die unterstützten Protokollversionen.

6.0 Fehler, Timeouts und Zustand

Jeder Befehl bekommt genau eine Antwort: Erfolg mit Daten oder einen Fehlercode aus einer dokumentierten Tabelle. Typische Fehlerklassen sind fehlerhafter Frame, unbekannter Befehl, ungültiger Parameter, beschäftigt, im aktuellen Zustand nicht erlaubt und interner Fehler. Die Tabelle gehört in die Spezifikation, nicht nur in den Code.

Auch Timeouts sind Teil des Protokolls. Legen Sie die maximale Antwortzeit je Befehlsklasse fest, was der Host bei einem Timeout tut (Wiederholung mit derselben Sequenznummer oder Abbruch) und wie lange das Gerät auf den Rest einer mehrteiligen Nachricht wartet, bevor es sie verwirft.

Lange Vorgänge wie ein Firmware-Update oder ein Kalibrierlauf sollten sofort mit „angenommen“ antworten und den Fortschritt als Ereignisse melden, statt die Antwort zu blockieren.

7.0 Sicherheit

BLE-Pairing und -Bonding schützen die Verbindung, entscheiden aber nicht, was eine authentifizierte Gegenstelle tun darf. Listen Sie auf, welche Befehle den Zustand ändern, welche eine autorisierte Sitzung brauchen und welche jedem verbundenen Host offenstehen dürfen. Fertigungs- und Debug-Befehle sollten in der Serienfirmware deaktiviert oder gesperrt sein, und die Spezifikation sollte festhalten, wie.

8.0 Testwerkzeug

Wir schreiben ein kleines hostseitiges Tool, in Python, sofern das Projekt nichts anderes vorgibt, das das Protokoll über eine serielle Schnittstelle spricht. Es erfüllt drei Aufgaben: Der Firmware-Entwickler kann Befehle ausprobieren, bevor es eine App gibt; in der CI laufen skriptgesteuerte Regressionstests gegen ein Board am Messplatz; und das App-Team hat eine Referenzimplementierung zum Vergleich. Wer den Frame-Parser mit demselben Tool per Fuzzing mit fehlerhaften Eingaben füttert, findet eine Klasse von Abstürzen, die im normalen Betrieb nie auftritt.

9.0 Übergabe

  • Protokollspezifikation: Transporte, Frame, Nachrichtentabelle, Fehlertabelle, Timeouts, Versionsregeln.
  • GATT-Tabelle oder USB-Deskriptoren.
  • Host-Testwerkzeug und seine Skripte.
  • Für jeden Befehl eine aufgezeichnete Beispielsitzung.

Die Seite Embedded-Firmware beschreibt die Geräteseite dieser Arbeit, Web, Cloud und Geräteverwaltung behandelt Apps und Backends, die mit Geräten sprechen. Für ein Review eines bestehenden Protokolls nutzen Sie das Formular Projekt besprechen.

Quellen

Häufige Fragen

Standard-BLE-Profil oder eigener Service?

Wo ein Standard-Service zu den Daten passt, etwa Battery oder Device Information, nehmen Sie ihn, denn generische Tools und Betriebssysteme verstehen ihn. Produktspezifische Funktionen brauchen einen eigenen Service. Ein einzelner Message-Pipe-Service hält diesen eigenen Teil stabil, auch wenn Funktionen hinzukommen.

Welche Payload-Kodierung sollten wir wählen?

Entscheiden Sie nach Flash- und RAM-Budget des Geräts und danach, wie oft sich das Protokoll voraussichtlich ändert. Feste Structs passen zu kleinen, stabilen Befehlssätzen. TLV oder CBOR kosten mehr Code, erlauben aber neue Felder, ohne ältere Apps zu brechen.

Wie bleiben alte Apps nach einem Firmware-Update funktionsfähig?

Der Befehl zur Versionsabfrage bleibt dauerhaft gleich, neue Felder kommen optional hinzu, und Leser ignorieren unbekannte Felder. Inkompatible Änderungen gehen in eine neue Major-Version; die alte wird für einen Zeitraum weiter unterstützt, der in beiden Release Notes steht.

Kann dasselbe Protokoll über BLE und USB laufen?

Genau deshalb bleiben Framing und Nachrichten unabhängig vom Transport. Nur der Transportadapter ändert sich. So können Fertigungstest- und Recovery-Tools ein Kabel nutzen, während die Produkt-App über BLE spricht.

Wann sollte das Protokoll geschrieben werden?

Bevor die Arbeit an Firmware und App richtig beginnt. Ein erster Entwurf darf kurz sein: Transporte, Frame, fünf oder sechs Befehle und die Fehlertabelle. Danach ändert er sich durch Reviews, nicht durch Debugging.