Coldwave Yuki Module (YMOD) — Integrations- & Betriebshandbuch

Produkt

Coldwave Yuki Module

Modell

YMOD — ein Source-Tree, zwei Modem-Varianten über den Build-Flag YUKI_MODEM: eg912 (Default) / bg77

Produktklasse

Zellulares Connectivity-Modul (Einbaukomponente für einen Host-MCU)

Hersteller

ImagineOn GmbH, Neusser Str. 27–29, 50670 Köln, Deutschland

Firmware-Version

1.0.0

HW-Plattform

Silicon Labs EFR32MG26 (ARM Cortex-M33), coldwave-os 2.2.0

Service-UUID

00000000-0000-1000-8002-006D0099AB53

Dokumentversion

1.0 — 2026-07-13

Sprachen

Deutsch (Original), Englisch, Französisch

1. Über dieses Dokument

Dieses Handbuch beschreibt Integration und Betrieb des Coldwave Yuki Module (YMOD) der ImagineOn GmbH — eines zellularen Connectivity-Moduls, das eine Trägerplatine bzw. einen Host-MCU über ein lokales UART-Protokoll an das Coldwave-Backend anbindet. Zielgruppe sind Integratoren (Entwicklung der Trägerplatine und der Host-Firmware) sowie Anlagenbetreiber.

Das YMOD ist eine Einbaukomponente. Bestimmte konformitäts- und sicherheitsrelevante Schritte (RF-Layout, Antennenpfad, Schlüssel-Provisioning, Secure-Boot-/Anti-Rollback-Konfiguration, Watchdog-Aktivierung, Endprodukt-Zertifizierung) liegen in der Verantwortung des Integrators bzw. des Endprodukt-Herstellers — siehe §16 und den Modul-Integrationsnachweis in der technischen Dokumentation.

2. Hersteller, CE, vereinfachte EU-Konformitätserklärung

2.1 Hersteller

ImagineOn GmbH
Neusser Str. 27–29
50670 Köln, Deutschland
Web: https://www.imagineon.de
Compliance: compliance@imagineon.de · PSIRT: security@coldwave.io

2.2 CE-Kennzeichnung & angewandte Rechtsvorschriften

Die Konformitätsbewertung erfolgt nach Modul A (interne Fertigungskontrolle). Angewandte EU-Rechtsakte:

• Funkanlagenrichtlinie 2014/53/EU (RED), inkl. Delegierte Verordnung (EU) 2022/30 zu RED Art. 3(3)(d)+(e)+(f)
• Cyber Resilience Act (EU) 2024/2847 (vorbereitend angewandt; voll anwendbar ab 2027-12-11)
• EMV-Richtlinie 2014/30/EU (implizit über die EN-301-489-Familie)

2.3 Vereinfachte EU-Konformitätserklärung (Art. 10 (9) RED)

2.4 Angewandte harmonisierte Normen

Hinweis: Das EFR32MG26-SoC enthält ein BLE-/802.15.4-Funkteil, das in beiden YMOD-Varianten per Firmware nicht verlinkt ist (kein Stack im Build). Es ist ein plattformbezogener Vorhalt für künftige Varianten. Frequenz, Modulation und Sendeleistung des Mobilfunkteils sind vollständig durch das jeweils bestückte, vorzertifizierte Quectel-Modul (EG912 bzw. BG77) spezifiziert; YMOD enthält kein eigenes Funkdesign.

3. Bestimmungsgemäße Verwendung

Das YMOD ist ein zellulares Connectivity-Modul zur Einbettung auf einer kundenseitigen Trägerplatine. Es übernimmt für einen Host-MCU die Mobilfunkanbindung (LTE), die DTLS-gesicherte Backend-Kommunikation (Telemetrie/Property-Sync, Remote-Konfiguration, OTA-Trigger), die Geräteidentität sowie — in der bg77-Variante — die GNSS-Positionsbestimmung, und stellt diese Dienste über ein TLV-basiertes UART-Protokoll bereit.

Typischer Einsatz: als bestücktes Funkmodul in Industrie-/Gewerbeumgebungen. Die Versorgung erfolgt über die Trägerplatine (SELV/PELV).

YMOD führt kein Modbus-/BACnet-Feldbus-Gateway, kein Scripting/Script-VM, keine Supercaps/Power-Fail-Pufferung, kein batteriegepuffertes RTC und kein Datenbudget. Diese in den yukiblock-Schwesterprodukten vorhandenen Funktionen sind für YMOD ersatzlos entfallen.

4. Modul-Identifikation & Varianten

4.1 Firmware-Identität

4.2 Modem-Varianten (ein Source-Tree, Build-Flag YUKI_MODEM)

Beide Varianten sind funktional identisch, abgesehen vom Modem, dem GNSS-Pfad und dem LTE-Quality-Modell. Der Modem-Host-Link-Baud bezeichnet die modul-interne Verbindung zwischen YMOD und dem Quectel-Modem — nicht die Baudrate der Host-UART-Schnittstelle zum Kunden-MCU (siehe §7/§9).

4.3 Kennzeichnung

Die technische Geräte-ID ist die IMEI; sie wird beim ersten Boot aus dem Modem ausgelesen, plausibilisiert und persistiert. HW-Revision, Modul-Labeling und Seriennummern-Vergabe sind im Hardware-Datensatz definiert: [zu bestätigen].

5. Sicherheit

5.1 Sicherheitshinweise

• Versorgung ausschließlich aus einer SELV/PELV-Quelle über die Trägerplatine. Genaue elektrische Grenzwerte (Versorgungsspannung, Strombedarf, TX-Strompulse): [zu bestätigen] (Hardware-Datenblatt/Modul-Datenblatt).
• Das Modul enthält keine vom Anwender wartbaren Teile.
• Betrieb nur in trockener, sauberer Umgebung im Rahmen der spezifizierten Umgebungsbedingungen ([zu bestätigen]).
• Der RF-Pfad und der Antennenanschluss sind gemäß den Quectel-Integrationsvorgaben (Hardware Design / RF Application Notes) auszuführen; keine Modifikation außerhalb des zugelassenen Bereichs.

5.2 HF-Expositionsschutz

Die Sendeleistung des Mobilfunkteils wird durch das jeweils bestückte Quectel-Modul bestimmt. Die HF-Expositionsbewertung nach EN 50665 erfolgt auf Endprodukt-Ebene durch den Integrator, einschließlich der Festlegung des erforderlichen Mindestabstands. Der GNSS-Empfänger der bg77-Variante ist reiner Empfänger (keine Sendeeigenschaft).

6. Modul-Übersicht & Architektur

Das YMOD läuft als einzige Software auf einem EFR32MG26 (Cortex-M33) auf coldwave-os 2.2.0. Die Firmware ist bewusst schlank aufgebaut:

┌───────────────────────────────────────────────────────────────┐
│  Applikation (firmware/src/)                                   │
│  ├─ main.cpp        Identität (product_id="YMOD",              │
│  │                  hw_id="EFR32MG26"), Modem-Init-Blob         │
│  ├─ app.cpp         yuki_app_init(): Board + Connectivity-      │
│  │                  Supervisor + Coldwave-Service + Backend     │
│  ├─ app/app_main.cpp UART-Server, GNSS (nur bg77),             │
│  │                   GPIO0/1-Tags, SYNC, Status-LEDs, Sync-Loop │
│  ├─ app/app_status.cpp  Status-LED-Zustandsmaschine           │
│  ├─ app/mcc_timezone.c  MCC → POSIX-TZ                         │
│  ├─ uart_protocol/  TLV-Server + CRC-16 + Handler + IO         │
│  └─ cli/cli.c       Serielle Diagnose-CLI                      │
├───────────────────────────────────────────────────────────────┤
│  coldwave-yuki-core 1.0.0 (In-House, gepinnt):             │
│  Connectivity-Supervisor + Recovery + LTE-Quality.             │
│  Power-Fail / Budget auskompiliert (YUKI_CORE_WITH_*=OFF).     │
├───────────────────────────────────────────────────────────────┤
│  coldwave-os 2.2.0: Kernel (FreeRTOS), lwIP, mbedTLS/PSA,      │
│  DTLS, OTA, KV-FS, AT-Modem-Treiber, MCUboot-Bootloader        │
└───────────────────────────────────────────────────────────────┘

Die primäre lokale Angriffsfläche ist der UART-Protokoll-Server (§9). Die Backend-Anbindung (DTLS/LTE), OTA, das KV-FS und die PSA-Kryptografie sind an coldwave-os delegiert; die Connectivity- und Recovery-Logik sowie das LTE-Quality-Modell stammen aus coldwave-yuki-core.

7. Host-Schnittstelle: Signale & Belegung

Das YMOD stellt dem Host-MCU die folgenden logischen Signale bereit. Die physische Zuordnung zum Modul-Footprint (Pin-/Pad-Nummern) ist im Hardware-Integrationsdatenblatt festgelegt: [zu bestätigen].

Reservierte/plattformseitige Pins: ein BLE-Eingang und ein POWER-GOOD-Eingang sind im Board-Bring-up konfiguriert, aber im aktuellen Funktionsumfang nicht produktiv verwendet.

8. Integration (Einbau, Antenne, Versorgung)

• Bestückung: Das YMOD wird als Funkmodul auf der Trägerplatine bestückt. Reflow-/Löthinweise und der Modul-Footprint: [zu bestätigen] (Hardware-Datenblatt).
• Versorgung: SELV/PELV über die Trägerplatine; ausreichende Strompuls-Reserve für die TX-Bursts des Modems gemäß Quectel-Hardware-Design vorsehen.
• Antenne: Mobilfunkantenne (50 Ω) gemäß Quectel-RF-Application-Note anschließen; bei bg77 zusätzlich die GNSS-Antenne. Keine Modifikation des RF-Pfades gegenüber dem Modul-Referenzdesign.
• Host-Verdrahtung: Host-UART (TXD/RXD, optional RTS/CTS) zum Host-MCU führen; SYNC, SLEEP, NW_ERR und GPIO0/1 nach Bedarf. Status-LEDs auf der Trägerplatine platzieren.
• SIM: SIM/eSIM gemäß Hardware-Datensatz bestücken. Das Netzprofil ist per Firmware voreingestellt (§17).

9. UART-Host-Protokoll (TLV + CRC-16)

Der UART-Protokoll-Server (src/uart_protocol/yuki_module_server.c) ist die lokale Schnittstelle des Moduls zum Host-MCU und zugleich seine primäre Angriffsfläche. Er wird über strikte Frame-, Längen- und CRC-Validierung abgesichert (Fuzzing-getestet). Es findet keine Authentifizierung statt — die Strecke gilt als baugruppen-/modulintern (vertrauenswürdiger Host-Link).

9.1 Frame-Format

┌──────────── Header (2 Byte) ────────────┬── Payload (0..511) ──┬── CRC (2 Byte) ──┐
│ Byte0 = (Type << 1) | (Len-Bit8)          │  V[0..Len-1]          │ CRC-16 (Big-Endian)│
│ Byte1 =  Len & 0xFF                       │                      │                   │
└──────────────────────────────────────────┴──────────────────────┴───────────────────┘

• Type (Kommando): 7 Bit (0x00–0x7F).
• Len: 9 Bit, max. 511 Byte (YUKI_MODULE_MAX_TLV_LENGTH). Überlängen werden mit EPROTO abgewiesen.
• CRC: CRC-16/CCITT-FALSE (Polynom 0x1021, Init 0xFFFF, kein XOR-Out), berechnet über Header + Payload, Big-Endian übertragen.

9.2 Antwortformat

Auf jedes Request-Frame antwortet der Server mit demselben Type. Die Payload beginnt mit einem Fehler-/Statusbyte, gefolgt von den Nutzdaten:

Response.Payload = [ ErrByte ] [ Daten … ]

9.3 Kommandosatz

9.4 SET-Payload & Datentypen

Das SET-Kommando setzt eine Property auf dem Kunden-Service. Payload-Aufbau:

[0..1] id (Big-Endian)   [2] Flags (Bit4 = read-only)   [3] Typ   dann Wert
  Typ STRING/BIN:  [4..5] Länge (BE)   [6..] Bytes
  sonst (Skalar):  [4..]  Wert (feste Länge je Typ)

* DOUBLE, UINT64 und INT64 werden im aktuellen Firmware-Stand angenommen, aber noch nicht verarbeitet (Antwort ERR_INTERNAL).

9.5 Diagnose-CLI

Über die serielle Diagnose-CLI (nur Debug/Service) stehen u. a. die Kommandos info, imei, iccid, pubkey, quality, connected, cloud_connected und exit zur Verfügung.

10. Erstinbetriebnahme, Identität & Claim-Code

10.1 Boot-Sequenz

1. Power-on/Reboot → main → yuki_app_init(): Board-Bring-up, Status-LED-Thread, FS-Init.
2. Connectivity-Supervisor (coldwave-yuki-core) startet das Modem; die IMEI wird gelesen, auf Plausibilität geprüft (15 Ziffern) und im KV-FS persistiert. Eine leere/unplausible IMEI wird nicht gespeichert; das Modul rebootet kontrolliert und versucht es erneut.
3. Coldwave-Service (cwClient) wird registriert; Backend-Attach über LTE/DTLS gegen das Coldwave-Backend.
4. Der UART-Protokoll-Server startet (und exportiert dabei den Geräte-Public-Key).
5. app_main()-Loop: bedient den Host, treibt die Status-LEDs und den periodischen Sync.

10.2 Identität & Onboarding

• Geräte-ID: die IMEI (15 Ziffern) dient als device_id am Backend.
• Geräteschlüssel: ED25519, non-exportable im PSA-Keystore. Der Public-Key wird über GET_PUBKEY exportiert.
• Claim-Code (Cloud-Onboarding): base58(SHA-256(pubkey ‖ imei ‖ iccid)), auf die ersten 8 Byte des Hashes gekürzt → 12-stelliger Base58-Code. Abruf über GET_CLAIMCODE. Der Claim-Code verknüpft das Gerät im Coldwave-Portal mit dem Eigentümer-Account.

11. Betrieb & Konfiguration

Im Normalbetrieb läuft das Modul autonom. Der app_main()-Loop (Periode 2 s):

• bedient das UART-Protokoll (ein Frame je Durchlauf),
• führt periodische Backend-Syncs aus (Default-Intervall 60 s, desired_sync_interval_s) sowie ereignisgetriggerte Syncs über den SYNC-Pin,
• aktualisiert alle 5 min die aus dem Netzbetreiber-MCC abgeleitete Zeitzone,
• spiegelt den Verbindungszustand auf die Status-LEDs und den NW_ERR-Pin,
• registriert nach dem Attach den Kunden-Service (aus der per SET_UUID gesetzten UUID).

Die vom Supervisor veröffentlichten Diagnose-Properties (read-only) umfassen:

Sicherheitsrelevante Betriebsparameter (Backend-FQDN, APN, MNO, Modem-Variante, Modem-Baud) stammen ausschließlich aus Build-Konstanten und sind zur Laufzeit nicht über externe Eingaben veränderbar. Es gibt keine Werks-Default-Passwörter und keine lokale Konfigurationskonsole.

12. GNSS-Positionsbestimmung (nur bg77)

In der bg77-Variante wird das GNSS-Gerät (gnss0) geöffnet. Der Host aktiviert die Positionsbestimmung über GEO_ENA (Type 0x08). Das Modul pollt anschließend den GNSS-Empfänger und sendet bei gültigem Fix einen Geo-Report (GEO_RPT, Type 0x09) als Push an den Host — ein festes 22-Byte-Payload:

Der GNSS-Empfänger ist reiner Empfänger (keine Sendeeigenschaft). Während aktiver GNSS-Fixe signalisiert die grüne LED das GPS-Muster (§14). Auf der eg912-Variante ist der GNSS-Pfad nicht verlinkt; GEO_ENA beantwortet der Server mit ERR_CMD.

13. Firmware-Updates (OTA) & Secure Boot

1. Das Backend triggert ein Update über den DTLS-authentifizierten Property-Kanal.
2. Das Image wird geladen und im OTA-Slot abgelegt.
3. Die kryptographische Signatur wird geprüft (ECDSA-P256 / SHA-256).
4. Bei gültiger Signatur führt der MCUboot-artige coldwave-os-Bootloader den Swap durch und startet neu; bei ungültiger/fehlender Signatur wird das Update verworfen und in das vorherige gültige Image zurückgefallen.

14. Status-LEDs & NW_ERR-Signal

Das Modul treibt eine grüne und eine rote LED. Der Status-Thread arbeitet mit 100-ms-Takt; die Muster ergeben sich aus dem vom Hauptloop gesetzten Zustand:

Zusätzlich signalisiert der NW_ERR-Ausgangspin den Backend-Link-Zustand hardwareseitig: High bei Mobilfunk-/Backend-Fehler, Low sobald das Backend angebunden ist. Der Host-MCU kann dieses Signal ohne UART-Abfrage auswerten.

15. Reset & Factory-Reset

Das YMOD hat keinen physischen Reset-Taster. Zurücksetzen erfolgt über den Host:

• Ereignis-Sync: eine steigende Flanke am SYNC-Pin (oder SYNC über UART, Type 0x05) stößt eine sofortige Backend-Synchronisation an.
• Factory-Reset: das UART-Kommando FACTORY_RESET (Type 0x11) löscht den lokal gecachten IMEI-/ICCID-/Script-Speicher und startet das Modul neu, sodass der nächste Boot die IMEI/ICCID frisch aus dem Modem liest. Das Modul antwortet nicht — der Host erkennt den Reset am Neustart des Moduls. Da der Host-Link als vertrauenswürdig gilt, erfolgt keine zusätzliche Bestätigung.

16. Cybersicherheit (EN 18031-1) — Hinweise für Integratoren/Betreiber

16.1 Was das Modul selbst tut

• Backend-Kommunikation ausschließlich über DTLS (LTE/UDP) mit Server-Zertifikatsprüfung gegen eine build-time eingebettete Coldwave-PKI-Root-CA.
• Secure Boot und signierte OTA-Updates (ECDSA-P256/SHA-256) verhindern das Einspielen unautorisierter Firmware.
• Keine offene Netzwerkschnittstelle — kein lokaler TLS-Server (cwClient, kein cwServer), kein Telnet/SSH/HTTP. Einzige lokale Schnittstelle ist der UART-Protokoll-Server.
• Keine Default-Passwörter, keine hartkodierten Geheimnisse im Image. Schlüssel liegen im PSA-Keystore (ED25519, non-exportable).
• Der UART-Parser ist gegen fehlerhafte/abgeschnittene Frames gehärtet (Frame-/Längen-/CRC-Validierung, libFuzzer-getestet).
• Release-Builds geben keine Debug-Interna preis (Log-Level gegated).
• Es werden keine personenbezogenen Daten verarbeitet.

16.2 Verantwortung des Integrators / Betreibers

• Backend-Root-CA provisionieren: die produktive Coldwave-PKI-Root-CA muss im Release-Build eingebettet sein (CI-Secret BACKEND_CA_CERT_PEM), damit die DTLS-Server-Cert-Prüfung greift.
• Geräteschlüssel-Custody: den PSA-Keystore-Slot in der Produktion als non-exportable setzen und den ED25519-Key sicher injizieren (Werks-Provisioning).
• Secure Boot / Anti-Rollback in der Produktions-Bootloader-Konfiguration aktivieren; den produktiven OTA-Signaturschlüssel (ein cloud-gehostetes Hardware-Sicherheitsmodul (HSM)) bereitstellen.
• Hardware-Watchdog im Release-Build aktivieren/bestätigen (RR-002).
• Physischer Schutz: das Endprodukt so gestalten, dass der Debug-Zugang (JTAG/SWD) gesperrt bleibt (Gecko-Security-Element-Debug-Lock) und das Modul physisch geschützt eingebaut ist.
• Bei Verdacht auf Manipulation: Gerät außer Betrieb nehmen und Hersteller informieren (§23).

16.3 Sicherheits-Support-Zeitraum

ImagineOn stellt für dieses Produkt sicherheitsrelevante Firmware-Updates über einen definierten Support-Zeitraum bereit und folgt einem koordinierten Offenlegungsprozess (CVD) nach IEC 62443-4-1 (§23). Die kalendarische Dauer des Support-Zeitraums für das YMOD-Endprodukt: [zu bestätigen].

17. Mobilfunk-Konnektivität & Recovery

17.1 Netzprofil

• APN: Private, von Coldwave verwaltete APN auf dem Mobilfunknetz der Deutschen Telekom; APN-Auth CHAP, Benutzer/Passwort leer / SIM-managed).
• MNO-Voreinstellung: Deutsche Telekom. Scan-Reihenfolge {'0','3'}, Default-Band LTE_B8 (900 MHz). Tatsächlich unterstützte Bänder ergeben sich aus dem jeweiligen Quectel-Datenblatt.
• Backend-FQDN: das Coldwave-Backend (feste Build-Konstante). Zeitbezug über NTP — es gibt kein RTC.

17.2 Recovery-Ladder

Der Connectivity-Supervisor (coldwave-yuki-core) überwacht die Verbindung (Periode 5 s) und durchläuft bei Verlust eine deterministische Recovery-Ladder: Reconnect → Modem-Reset → Reboot. Der Reboot greift erst nach maximal 3 erfolglosen Resets (max_resets_before_reboot=3) und einer Mindestlaufzeit von 30 min. Rund 5 fehlgeschlagene Syncs ohne Backend-Round-Trip werten als „attached-but-dead" und lösen ebenfalls einen Modem-Reset aus. Eine Raten-Obergrenze (ltemq_rate_cap_kbit_s) begrenzt den Durchsatz; ein monatliches Datenbudget gibt es nicht.

18. Wartung

Das Modul ist wartungsfrei. Es enthält keine RTC-Pufferbatterie und keine vom Anwender wartbaren Teile (die Uhrzeit kommt aus NTP). Endprodukt-seitige Pflege (Reinigung, Prüfung des Antennenanschlusses) obliegt dem Betreiber gemäß der Dokumentation des Endprodukts.

19. Funkparameter

Der Integrationsnachweis (RED Art. 3(2)) stützt sich für beide Module auf das jeweilige Quectel-CE-Zertifikat (GCF/PTCRB) und geräteseitige Prüfungen nach EN 301 489-1/-52 und EN 301 908-1/-13 auf Endprodukt-Ebene.

20. Technische Daten (Übersicht)

21. Troubleshooting

22. Außerbetriebnahme & Entsorgung

1. Versorgung der Trägerplatine abschalten.
2. Gerät im Coldwave-Portal ggf. als außer Betrieb markieren.
3. Modul bzw. Endprodukt fachgerecht entsorgen.

23. Support, Schwachstellen-Meldung, Sicherheits-Support

Bitte keine öffentlichen GitHub-Issues für Schwachstellen. Bei der Meldung Firmware-Version (Release-Tag/Commit) und Modem-Variante (eg912/bg77) angeben; für UART-Protokoll-Themen ist eine minimale Byte-Sequenz ideal. Empfangsbestätigung binnen 2 Arbeitstagen; Triage binnen 5 Arbeitstagen; Fix für Critical/High (CVSS ≥ 7) binnen 90 Tagen, für Medium/Low binnen 180 Tagen (gebündelt ins nächste Minor-Release). Koordinierte Offenlegung nach Verfügbarkeit des Fixes und einem angemessenen Rollout-Fenster (typ. 30 Tage). Details: SECURITY.md.

24. Software-Komponenten & Lizenzen

Der YMOD-Applikationscode (src/) ist vollständig ImagineOn-authored; es gibt keinen vendored Drittanbieter-Quellcode im Image außer dem coldwave-os-SDK. Die vollständige SBOM (CycloneDX) liegt unter firmware/compliance/sbom/ymod-v1.0.0.cdx.json. Vertrieb durch die ImagineOn GmbH unter den ImagineOn-Softwarelizenzbedingungen (imagineon.de/de/info/licensing-terms) — keine Open-Source-Lizenz; Weiterverbreitung nur mit schriftlicher Vereinbarung.

25. Glossar

26. Änderungshistorie

© 2026 ImagineOn GmbH. Alle Rechte vorbehalten. Dieses Handbuch darf ohne ausdrückliche Genehmigung der ImagineOn GmbH nicht vervielfältigt oder Dritten zugänglich gemacht werden, ausgenommen die Weitergabe im Rahmen der Lieferkette des Produkts Coldwave Yuki Module (YMOD).