Skip to content

mqtt_api.adoc

Latest commit

 

History

History
339 lines (251 loc) · 10.8 KB

mqtt_api.adoc

File metadata and controls

339 lines (251 loc) · 10.8 KB

MQTT API Reference

1. Einführung

Die MQTT-Schnittstelle ermöglicht die Steuerung des PySignalduino-Gateways und den Empfang von dekodierten Nachrichten. Alle Befehle und Antworten verwenden das JSON-Format.

1.1. Topics und Struktur

Der Standard-Topic für alle MQTT-Operationen ist signalduino/v1. Dieser Wert kann über die Umgebungsvariable MQTT_TOPIC oder den CLI-Parameter --mqtt-topic angepasst werden. Wenn nur der Basis-Topic (z.B. foo) gesetzt wird, ist der finale Topic immer versionsspezifisch: foo/v1. Alle nachfolgenden Beispiele verwenden signalduino/v1 als Basis.

Zweck Topic-Format Anmerkungen

Befehl senden (Request)

signalduino/v1/commands/<command_path>

Senden Sie hier die JSON-Payload, um einen Befehl auszuführen.

Befehlsantwort (Success)

signalduino/v1/responses

Erfolgreiche Antworten von get/ und set/ Befehlen.

Befehlsfehler (Error)

signalduino/v1/errors

Fehler (z.B. Validierung oder Timeout).

Empfangene Nachrichten

signalduino/v1/state/messages

Dekodierte Funknachrichten.

1.2. Request- und Response-Format

Alle Requests verwenden das folgende JSON-Format. Für einfache Befehle (meiste GETs) kann die Payload einfach {} sein.

Feld Beschreibung

req_id

(Optional) Eine Korrelations-ID (string) zur Zuordnung von Request und Response.

value

(Nur für einfache SET-Befehle) Der Wert, der gesetzt werden soll. Typ variiert (Zahl, String).

parameters

(Nur für komplexe Befehle) Ein Objekt für Befehle mit mehreren Argumenten (z.B. command/send/msg).

Eine erfolgreiche Response auf signalduino/v1/responses hat folgende Struktur:

{
  "command": "der/ausgeführte/befehl",
  "success": true,
  "req_id": "F001",
  "payload": {
    // Die tatsächlichen Daten, z.B. Frequenz-Wert, Versionsstring, etc.
  }
}

2. CLI Tool zur Steuerung (tools/sd_mqtt_cli.py)

Das Skript tools/sd_mqtt_cli.py dient als einfaches Python-Kommandozeilen-Tool, um Befehle an das PySignalduino MQTT-Gateway zu senden und die Antworten zu empfangen.

2.1. Installation und Ausführung

Das Tool benötigt die paho-mqtt Abhängigkeit, die in der requirements-dev.txt enthalten ist.

pip install paho-mqtt
python3 tools/sd_mqtt_cli.py --help

2.2. Verfügbare Kommandos

Kommando Beschreibung Beispiel

reset

Führt einen Factory Reset durch (set/factory_reset).

python3 tools/sd_mqtt_cli.py reset

get all-settings

Fragt alle wichtigen CC1101-Einstellungen in einer aggregierten Nachricht ab.

python3 tools/sd_mqtt_cli.py get all-settings

get hardware-status --parameter <param>

Fragt einen spezifischen CC1101-Parameter ab. Parameter: frequency, bandwidth, rampl, sensitivity, datarate.

python3 tools/sd_mqtt_cli.py get hardware-status --parameter frequency

get system-status --parameter <param>

NEU: Fragt einen spezifischen System-Parameter ab. Parameter: version, freeram, uptime.

python3 tools/sd_mqtt_cli.py get system-status --parameter freeram

poll

NEU: Fragt nacheinander alle verfügbaren System- und CC1101-Parameter ab. Nützlich zur Diagnose des aktuellen Gerätezustands.

python3 tools/sd_mqtt_cli.py poll

3. GET Commands (Status und Konfiguration abrufen)

GET-Befehle benötigen eine leere Payload ({}) oder nur eine req_id.

Befehlspfad Antwort-Payload (Beispiel payload) Beschreibung

get/system/version

"V 3.3.1-dev…​"

Firmware-Version.

get/system/freeram

1234

Verfügbarer RAM-Speicher (int).

get/system/uptime

56789

System-Laufzeit (int).

get/config/decoder

{"MS": 1, "MU": 1, "MC": 1, "MN": 1}

Aktuelle Decoder-Konfiguration (aktivierte Protokollfamilien) als geparstes Dictionary.

get/cc1101/config

{"cc1101_config_string": "C0D11=0F"}

CC1101 Konfigurationsregister-Dump als gekapselter String.

get/cc1101/patable

{"pa_table_hex": "C3E = C0 C1 C2 C3 C4 C5 C6 C7"}

CC1101 PA-Tabelle.

get/cc1101/register

{"register_name": "IOCFG2", "address_hex": "00", "register_value": "C00 = 29"}

Liest den Wert eines einzelnen CC1101-Registers. Erfordert den Registernamen im value-Feld der Payload (z.B. {"value": "IOCFG2"}).

get/cc1101/frequency

{"frequency": 868.3500}

Aktuelle RF-Frequenz in MHz.

get/cc1101/bandwidth

{"bandwidth": 102.0}

Aktuelle IF-Bandbreite in kHz.

get/cc1101/rampl

{"rampl": 30}

Aktuelle Empfängerverstärkung (LNA Gain) in dB. Mögliche Werte: 24, 27, 30, 33, 36, 38, 40, 42.

get/cc1101/sensitivity

{"sensitivity": 12}

Aktuelle Empfindlichkeit in dB. Mögliche Werte: 4, 8, 12, 16.

get/cc1101/datarate

{"datarate": 4.8}

Aktuelle Datenrate in kBaud.

get/cc1101/settings

{"frequency": 868.35, "bandwidth": 102.0, "rampl": 30, "sensitivity": 12, "datarate": 4.8}

Aggregierte Abfrage aller CC1101-Haupteinstellungen.

4. SET Commands (Konfigurationsänderungen)

SET-Befehle, die einen Wert setzen, verwenden das value-Feld. Befehle, die nur eine Aktion auslösen, benötigen eine leere Payload. Nach allen CC1101-SET-Befehlen wird automatisch eine Re-Initialisierung des Chips durchgeführt.

4.1. Einfache SET-Befehle (Aktionen)

Diese Befehle benötigen nur eine leere Payload ({}) oder eine req_id.

Befehlspfad Beschreibung Beispiel mosquitto_pub

set/factory_reset

Setzt EEPROM-Defaults zurück und startet das Gerät neu.

mosquitto_pub -t signalduino/v1/commands/set/factory_reset -m '{}'

set/config/decoder_ms_enable

Aktiviert den "Synced Message (MS)" Decoder (CE S).

mosquitto_pub -t signalduino/v1/commands/set/config/decoder_ms_enable -m '{"req_id": "DECODER01"}'

set/config/decoder_ms_disable

Deaktiviert den "Synced Message (MS)" Decoder (CD S).

mosquitto_pub -t signalduino/v1/commands/set/config/decoder_ms_disable -m '{}'

set/config/decoder_mu_enable

Aktiviert den "Unsynced Message (MU)" Decoder (CE U).

mosquitto_pub -t signalduino/v1/commands/set/config/decoder_mu_enable -m '{}'

set/config/decoder_mu_disable

Deaktiviert den "Unsynced Message (MU)" Decoder (CD U).

mosquitto_pub -t signalduino/v1/commands/set/config/decoder_mu_disable -m '{}'

set/config/decoder_mc_enable

Aktiviert den "Manchester Coded Message (MC)" Decoder (CE C).

mosquitto_pub -t signalduino/v1/commands/set/config/decoder_mc_enable -m '{}'

set/config/decoder_mc_disable

Deaktiviert den "Manchester Coded Message (MC)" Decoder (CD C).

mosquitto_pub -t signalduino/v1/commands/set/config/decoder_mc_disable -m '{}'

4.2. CC1101 Parameter SET-Befehle

Diese Befehle benötigen das Feld value im Payload, das gegen ein definiertes JSON-Schema validiert wird.

Befehlspfad Wert (value) Erlaubte Werte Beispiel mosquitto_pub

set/cc1101/frequency

RF-Frequenz in MHz (float)

315.0 bis 915.0

mosquitto_pub -t signalduino/v1/commands/set/cc1101/frequency -m '{"value": 433.92}'

set/cc1101/rampl

Empfängerverstärkung in dB (int)

24, 27, 30, 33, 36, 38, 40, 42

mosquitto_pub -t signalduino/v1/commands/set/cc1101/rampl -m '{"value": 38}'

set/cc1101/sensitivity

Empfindlichkeit in dB (int)

4, 8, 12, 16

mosquitto_pub -t signalduino/v1/commands/set/cc1101/sensitivity -m '{"value": 12}'

set/cc1101/patable

PA-Power-Level (string)

-30_dBm, -20_dBm, -15_dBm, -10_dBm, -5_dBm, 0_dBm, 5_dBm, 7_dBm, 10_dBm

mosquitto_pub -t signalduino/v1/commands/set/cc1101/patable -m '{"value": "5_dBm"}'

set/cc1101/bandwidth

IF-Bandbreite in kHz (float)

Bestimmte Enum-Werte (z.B. 58, 102, 203, 406). Es wird der nächstgelegene unterstützte Wert gesetzt.

mosquitto_pub -t signalduino/v1/commands/set/cc1101/bandwidth -m '{"value": 102.0}'

set/cc1101/datarate

Datenrate in kBaud (float)

0.0247955 bis 1621.83

mosquitto_pub -t signalduino/v1/commands/set/cc1101/datarate -m '{"value": 4.8}'

set/cc1101/deviation

Frequenzabweichung in kHz (float)

1.586914 bis 380.859375

mosquitto_pub -t signalduino/v1/commands/set/cc1101/deviation -m '{"value": 50.0}'

5. Komplexe Befehle

Komplexe Befehle verwenden das parameters-Feld im Payload.

5.1. command/send/msg

Dieser Befehl sendet eine vorab encodierte Nachricht an das Signalduino-Gerät, die direkt an die Firmware übergeben wird.

{
  "req_id": "SEND007",
  "parameters": {
    "protocol_id": 1,
    "data": "AABBCC",
    "repeats": 3,
    "clock_us": 350,
    "frequency_mhz": 433.92
  }
}
Parameter Typ Erforderlich Beschreibung

protocol_id

int

Ja

Die ID des zu verwendenden Protokolls (z.B. P1).

data

string

Ja

Die zu sendenden Daten als Hex- oder Binär-String.

repeats

int

Nein (Standard: 1)

Die Anzahl der Wiederholungen (R<n>).

clock_us

int

Nein

Optionale Taktfrequenz in Mikrosekunden (C<n>).

frequency_mhz

float

Nein

Optionale Frequenz in MHz (F<val>).

6. FHEM Integration

PySignalduino lässt sich nahtlos in FHEM integrieren, indem ein MQTT-Broker als Vermittler genutzt wird. Die empfohlene Methode ist die Verwendung des FHEM-Moduls MQTT2_CLIENT zur Verbindung mit dem Broker und MQTT2_DEVICE zur Repräsentation des Signalduino.

6.1. Beispielkonfiguration

Eine vollständige Beispielkonfiguration finden Sie in der Datei .devcontainer/fhem-data/fhem_signalduino_example.cfg. Im DevContainer wird diese Datei automatisch als FHEM-Konfiguration geladen, sodass PySignalDuino sofort verfügbar ist.

# 1. Verbindung zum Broker herstellen (falls noch nicht vorhanden)
define mqtt_broker MQTT2_CLIENT mqtt:1883
attr mqtt_broker autocreate simple

# 2. PySignalduino Device definieren
define PySignalDuino MQTT2_DEVICE
attr PySignalDuino IODev mqtt_broker

# 3. Readings für empfangene Nachrichten extrahieren
# Wandelt JSON-Payload automatisch in Readings um
attr PySignalDuino readingList signalduino/v1/state/messages:.* { json2nameValue($EVENT, '', $JSONMAP) }

# 4. Senden von Befehlen ermöglichen
attr PySignalDuino setList raw:textField signalduino/v1/commands/set/raw $EVTPART1 \
cc1101_reg:textField signalduino/v1/commands/set/cc1101_reg $EVTPART1 \
version:noArg signalduino/v1/commands/get/system/version

6.2. Wichtige Hinweise

  • Topics: Stellen Sie sicher, dass das readingList Attribut dem in PySignalduino konfigurierten MQTT_TOPIC entspricht (Standard: signalduino/v1/state/messages).

  • JSON Parsing: Die Funktion json2nameValue in FHEM ist ideal, um die flachen JSON-Objekte von PySignalduino direkt in FHEM Readings umzuwandeln.