Skip to content

sademardotde/onair4hermes

v0.2.0GPL-3.0-or-later

OnAir (SDR receiver, 170+ decoder modes) as Hermes devices: status, devices, modes, telemetry, spectrum, start/stop, mode and frequency changes via the local remote-control HTTP API, plus the 'hermes onair' CLI, a dashboard proxy backend and a desktop pane.

onair4hermes

Hermes-Plugin für OnAir (SDR / Funküberwachung). Es bindet den OnAir-Receiver über die lokale Remote-Control-HTTP-API als Hermes-Geräte ein: Status, Geräte, Modi, Telemetrie, Spektrum, Start/Stop, Modus- und Frequenzwechsel – als Tools, als hermes onair-CLI, als Dashboard-Backend und als Desktop-Seite mit Status-Chip und Live-Spektrum.

Aufbau analog zu iwfcam4hermes:

DateiZweck
plugin.yamlHermes-Manifest (v2) mit Tools, CLI und Konfigurationsschema
plugin.jsonportables Manifest (agent-plugins.org)
__init__.pyregister(ctx): Tools + CLI registrieren (schlank, ohne Netzwerk)
hermes_plugin.pyFassade, Settings-Auflösung und hermes onair-CLI
onair_client.pyHTTP-Client für die OnAir-API (nur Standardbibliothek)
dashboard/plugin_api.pyProxy-Backend unter /api/plugins/onair4hermes/
desktop/plugin.jsHermes-Desktop-Pane + Status-Chip (nutzt ctx.rest)
onair_devices.jsonstatischer Geräte-Fallback, wenn die API nicht läuft

Voraussetzungen

  • OnAir läuft und die Remote-Control-API ist aktiv: Ansicht → Datenfeeds → Remote-Control-API, Standard-Port 8765.
  • Optional Token: Wenn in OnAir „Programs on this computer need the token too“ aktiv ist, den Token unter Ansicht → Datenfeeds → Remote-Control-API → „Token kopieren“ holen und im Plugin hinterlegen (siehe unten).

Installation

# Verzeichnis-Plugin in den Hermes-Plugin-Root kopieren
cp -r /home/fm/ziot/onair4hermes ~/.hermes/plugins/onair4hermes
hermes plugins enable onair4hermes
hermes plugins doctor onair4hermes   # optional: Runtime-Checks

Für die Desktop-Seite zusätzlich die Desktop-Hälfte kopieren (das Dashboard-Backend liefert die Daten, deshalb kein direkter API-Zugriff aus dem Renderer):

mkdir -p ~/.hermes/desktop-plugins/onair4hermes
cp desktop/plugin.js ~/.hermes/desktop-plugins/onair4hermes/plugin.js

Danach in Hermes die Desktop-Plugins neu laden (⌘K/Ctrl+K → „Reload desktop plugins“). Das Dashboard-Backend wird beim ersten Request automatisch nachgeladen (Hot-Mount), ein Neustart des Gateways ist nur nötig, wenn das Plugin erst nach dem Start aktiviert wurde.

Das Dashboard ist ein maschinenweiter Server und liest die plugins.enabled-Liste des Default-Profils (~/.hermes/config.yaml). Damit /api/plugins/onair4hermes/ auch dort antwortet, das Plugin zusätzlich in diesem Profil aktivieren (bei profilgebundenen Installationen genügt der Eintrag in der jeweiligen Profil-Config nicht).

Konfiguration

Einstellungen liegen unter plugins.entries.onair4hermes.settings in ~/.hermes/config.yaml bzw. in der Hermes-Oberfläche:

SchlüsselTypStandardBedeutung
configstrleerPfad zur JSON-Gerätekonfiguration (Fallback)
base_urlstrhttp://127.0.0.1:8765Basis-URL der OnAir-API
tokensecretleerOnAir-API-Token, landet in ~/.hermes/.env als ONAIR_API_TOKEN
timeoutfloat5.0Timeout je Anfrage (0,5–60 s)

Der Token wird zur Laufzeit in dieser Reihenfolge aufgelöst: Plugin-Setting → Umgebungsvariable ONAIR_API_TOKEN → leer. Die Basis-URL analog über ONAIR_BASE_URL.

Statischer Geräte-Fallback

Wenn die OnAir-API nicht erreichbar ist, listet das Plugin die Geräte aus onair_devices.json (oder dem unter config gesetzten Pfad):

{
  "devices": [
    {"id": "rig1", "name": "IC-7300", "host": "127.0.0.1", "port": 8765}
  ]
}

Tools

ToolZweck
onair_list_devicesRadios/Quellen auflisten
onair_list_modesverfügbare Decoder-Modi auflisten
onair_statusReceiver-Status (Gerät, Modus, Frequenz, Laufzeit)
onair_telemetryTelemetrie des aktiven Modus (SNR, Lock, Qualität, RDS …)
onair_spectrumSpektrum als dBFS-Bins (bins 16–4096)
onair_startReceiver starten (optional device_index)
onair_stopReceiver stoppen
onair_set_modeModus wechseln (family, optional sub)
onair_set_frequencyFrequenz setzen (hz oder mhz)

Alle Tools liefern JSON-Strings mit ok, bei Fehlern zusätzlich error und – falls die API geantwortet hat – status (HTTP-Code).

CLI

hermes onair status
hermes onair devices
hermes onair modes
hermes onair device onair-device-0
hermes onair telemetry
hermes onair spectrum --bins 128
hermes onair start --device 0
hermes onair stop
hermes onair mode 7 --sub ft8
hermes onair freq --mhz 100
hermes onair freq --hz 100000000

--config PFAD und --base-url URL überschreiben die Plugin-Settings pro Aufruf.

Dashboard und Desktop

  • dashboard/plugin_api.py wird unter /api/plugins/onair4hermes/ gemountet und proxyt status, devices, modes, telemetry, spectrum, start, stop, mode, frequency, config.
  • desktop/plugin.js registriert eine eigene Seite (/onair, Sidebar-Eintrag „OnAir“ und Befehlspalette), ein Pane (panes, rechts, 360 px) und einen Status-Chip (statusBar.right). Alles pollt über ctx.rest; der Renderer spricht nie direkt mit OnAir (die API sendet keine CORS-Header).

Wichtig – Desktop-Hälfte ist opt-in: Als Teil eines einheitlichen Agent+Desktop-Pakets wird die Desktop-Hälfte standardmäßig deaktiviert ausgeliefert (.hermes-package.json → defaultEnabled: false). Nach der Installation einmal unter Fähigkeiten → Plugins den Schalter onair4hermes aktivieren (oder in der Plugins-Liste „Enable“). Ohne diesen Schalter erscheint kein OnAir-Button, und es gibt bewusst keine Fehlermeldung im Log.

Tests

# Plugin-Tests (Mock-OnAir, ohne laufendes OnAir)
python3 -m pytest -p no:syrupy -q tests/test_plugin.py

# oder ohne pytest
python3 tests/test_plugin.py

# Dashboard-Backend (braucht FastAPI + httpx, z. B. im Dashboard-Venv)
/home/fm/ziot/.venv-dashboard-test/bin/python tests/test_dashboard_api.py

Fehlersuche

  • HTTP 401 / 403 – Token fehlt oder ist falsch. Token in OnAir kopieren und als Plugin-Setting token eintragen (oder ONAIR_API_TOKEN in ~/.hermes/.env). Der Fehlertext nennt den Pfad.
  • OnAir API nicht erreichbar – läuft OnAir, ist die Remote-Control-API aktiviert, stimmt base_url? hermes onair status zeigt die verwendete URL.
  • Desktop-Pane bleibt offline – ist das Plugin in Hermes aktiviert (hermes plugins list), und wurde das Desktop-Plugin neu geladen? Das Backend antwortet unter /api/plugins/onair4hermes/config.
  • CORS – direkte fetch-Aufrufe aus dem Electron-Renderer zur OnAir-API schlagen fehl; deshalb der Proxy. Nicht auf Direktzugriff zurückbauen.

Lizenz

GPL-3.0-or-later (basiert auf OnAir, siehe OnAir-Lizenz).