Sensmos API & Protokolle — Node-HTTP-API, MQTT, Software-Nodes, LoRa-Frame-Format

Node-HTTP-API (LAN, Port 80)

Authentifizierung: Authorization: Bearer <PIN> (die PIN, die du beim Hinzufügen des Nodes gesetzt hast). GET /info ist offen.

Endpunkt	Zweck
`GET /info`	ID, Firmware, Alias, Uptime, `lora{board,role,rx_key,open}` wenn ein Funkmodul vorhanden ist
`GET /data/status`	aktuelle Entitäten (eigene / öffentliche / abonnierte / Diagnostik)
`POST /data` `{entity_id,value,unit}`	eine Entität schreiben (own. / native pub.)
`GET /data/native`	Katalog der nativen Entitäten, die die Firmware kennt
`GET/POST /node/mqtt`	Konfiguration des lokalen Brokers
`GET/POST /node/lora_emerg`	Satz der Emergency-Entitäten + Befehls-Webhook
`GET/POST /node/lora_rx` `{key,open}`	LoRa-Empfangs-Schlüsselphrase (wird nie zurückgegeben) und Klartext-Frame-Opt-in
`POST /node/lorasend` `{dst,sub,payload,aes,via?}`	einen LoRa-DATA-Frame senden (eigener Sensor: Funk; anderer Node: über das Netzwerk)
`GET /lora/inbox`	LoRa-Inbox: `cmds` (Emergency-Befehle) und `frames` (Sensor-Frames, `via` rf/ws/tx)
`GET /lora/last`	Funkzustand inkl. TX-Diagnostik (`link`)
`POST /node/alias`	Node-Bezeichnung (angezeigt in /info)
`POST /node/pair` / `DELETE`	Pairing-Schlüssel für Fernzugriff (nur LAN, mit Absicht)

MQTT

Topic-Root sensmos/<id8>/. Status, Diagnostik und Entitäten werden mit Home-Assistant-Discovery veröffentlicht. Nachrichten kommen auf sensmos/<id8>/msg als {from, eid, p} an — z. B. {"from":"lora","eid":"lora_frame.3","p":"21.5"} für einen LoRa-Frame von Sensor 3, {"from":"owner","eid":"lora_cmd","p":"water_off"} für einen Emergency-Befehl.

Software-Nodes — Daten ohne Hardware

POST https://api.sensmos.com/v1/ingest mit {key, entities:[{entity_id,value,unit}], lat?, lon?, label?} bringt deine Daten als Software-Node auf die Live-Karte (Home Assistant, ESPHome, ein Skript — was auch immer). Ein Key mit ≥ 32 Zeichen ist deine Identität. Software-Nodes sind reine Datenlieferanten: Sie verdienen nicht und sind keine Probenziele.

LoRa-DATA-Frame (für Sensorbauer)

plain:      [0xE0][0x02][flags][dst 4B][sub 1B][payload 1..128 B][CRC32 LE]
encrypted:  [0xE0][0x02][flags][dst 4B][sub 1B][nonce 4B][AES-256-CTR(payload+CRC32)]

dst = die ersten 4 Bytes der ID des Ziel-Nodes (die 8-Hex-ID aus der App); sub = die Nummer deines Sensors hinter diesem Node (1–255).
flags Bit0 = AES; Bit1 = „letzter Hop" — nur vom Node gesetzt, wenn er an einen Sensor sendet. Ein Sensor akzeptiert einen Frame nur, wenn Bit1 gesetzt ist, dst sein Node ist und sub seine eigene; seine eigenen Uplinks sendet er mit Bit1 = 0.
CRC32 (zlib) der Payload, Little-Endian, innerhalb des verschlüsselten Blocks — ein falscher Schlüssel lässt die CRC scheitern.
AES-256-CTR, Schlüssel = SHA-256(Schlüsselphrase), Zählerblock [nonce 4B][dst 4B][sub][0…], zufällige Nonce pro Frame.
Funk: EU 868.1 MHz / US 903.9 MHz, BW 125 kHz, SF11, CR 4/5, Sync-Word 0x34, LoRa-CRC an, normales IQ. Listen before talk; den 1% Duty Cycle einhalten (≈25 Frames/Stunde bei 30 Bytes).
Nur ein Funk-Hop. Uplinks werden von jedem Node oder Gateway gehört und über das Netzwerk an den Ziel-Node geliefert; Downlinks an einen Sensor sendet nur der eigene Node dieses Sensors.

Ein Aktor, der nie sendet, ist für das Netzwerk unsichtbar — schick einmal pro Stunde ein kurzes „hello", damit das Netzwerk lernt, wer ihn hört. Der vollständige Engineering-Vertrag liegt im Firmware-Repository (DOCS/dev/LORA-MESSAGING.md).

Gateways als Hörer

Ein LoRaWAN-Gateway, den du betreibst (Semtech Packet Forwarder), kann für das ganze Netzwerk hören: Ein passiver Agent leitet jeden empfangenen Frame unter der Identität deines Nodes ans Backend weiter — Einrichtung unter LoRaWAN-Gateway, der Vertrag (Pairing, Tokens, Formate) unter Attachments & die EXT-API. Frames für Sensmos-Nodes werden weitergeleitet; fremder LoRaWAN-Verkehr zählt nur als Spektrumstatistik.