add per-hardware plugin operation guides in docs

docs/hardware-microham-guide.md

@@ -0,0 +1,84 @@
+# microHAM U3 (PTT + TX Audio)
+
+Diese Anleitung beschreibt Betrieb, Einstellung und Basis-Kalibrierung der microHAM-Anbindung ueber das Plugin `rms.microham`.
+
+## Quick Start
+
+```bash
+ls -l /dev/rms-microham-u3
+arecord -l
+ffmpeg -version
+
+grep -E '^(MICROHAM_DEVICE|MICROHAM_PTT_COMMANDS_ENABLED|MICROHAM_AUDIO_ALSA_DEVICE|MICROHAM_AUDIO_INPUT_MIME)=' /etc/remotestation-arcg/remotestation-arcg.env
+sudo systemctl restart remotestation-arcg
+curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8080/v1/openwebrx/tx/status
+```
+
+## 1) Hardware und Voraussetzungen
+
+- Device: typischerweise `/dev/rms-microham-u3`
+- Audio-Backend: `ffmpeg` + gueltiges ALSA Capture-Device (`MICROHAM_AUDIO_ALSA_DEVICE`)
+- Optional fuer Batch-PTT-Down mit Frequenz/Mode: `rigctl`
+
+## 2) Relevante ENV-Keys
+
+```env
+MICROHAM_DEVICE=/dev/rms-microham-u3
+
+MICROHAM_PTT_COMMANDS_ENABLED=true
+MICROHAM_PTT_DOWN_CMD=
+MICROHAM_PTT_UP_CMD=
+MICROHAM_PTT_TIMEOUT_MS=5000
+
+MICROHAM_PTT_APPLY_BAND_STATE=true
+MICROHAM_PTT_RIGCTL_MODEL=3023
+MICROHAM_PTT_RIGCTL_BAUD=19200
+MICROHAM_PTT_RIGCTL_SETCONF=rts_state=OFF,dtr_state=OFF
+
+MICROHAM_AUDIO_ENABLED=true
+MICROHAM_AUDIO_ALSA_DEVICE=plughw:CARD=CODEC,DEV=0
+MICROHAM_AUDIO_INPUT_MIME=webm
+MICROHAM_AUDIO_CHUNK_MS=100
+MICROHAM_AUDIO_STOP_ON_DISCONNECT=true
+MICROHAM_AUDIO_SESSION_TIMEOUT_MS=120000
+MICROHAM_AUDIO_FFMPEG_PATH=/usr/bin/ffmpeg
+MICROHAM_AUDIO_FFMPEG_EXTRA_ARGS=
+```
+
+## 3) Bedienung (Runtime)
+
+- PTT down: `POST /v1/openwebrx/ptt/down`
+- PTT up: `POST /v1/openwebrx/ptt/up`
+- TX Status inkl. PTT-Konfiguration: `GET /v1/openwebrx/tx/status`
+- Audio-WS (Plugin-Pfad): `/v1/openwebrx/plugin/audio/ws`
+
+Hinweis: PTT und TX-Power sind getrennt. TX-Power kommt aus `tx.control`, PTT aus `rms.microham`.
+
+## 4) Einstellen und Kalibrieren
+
+### PTT
+
+1. Erst sichere `pttUp`/`pttDown` Kommandos setzen.
+2. `MICROHAM_PTT_COMMANDS_ENABLED=true` aktivieren.
+3. Falls Band-/Mode-konsistentes PTT gewuenscht: `MICROHAM_PTT_APPLY_BAND_STATE=true`.
+4. Bei Instabilitaet `MICROHAM_PTT_TIMEOUT_MS` moderat erhoehen (nicht exzessiv).
+
+### Audio
+
+1. `MICROHAM_AUDIO_ALSA_DEVICE` mit `arecord -l` auf reales Capture-Device setzen.
+2. `MICROHAM_AUDIO_INPUT_MIME` auf den Client abstimmen (`webm` oder `ogg`).
+3. Bei Dropouts/Artefakten:
+   - `MICROHAM_AUDIO_CHUNK_MS` leicht erhoehen (z. B. 100 -> 120/140)
+   - zusaetzliche ffmpeg-Args nur kontrolliert setzen.
+
+## 5) Typische Fehlerbilder
+
+- `MICROHAM_PTT_COMMANDS_ENABLED must be true`: PTT nicht aktiviert.
+- `MICROHAM_PTT_DOWN_CMD missing`/`UP_CMD missing`: Kommandos fehlen (wenn kein Batch-Pfad genutzt).
+- `invalid microham device path`: ungueltiger Device-String.
+- Audio startet nicht: `ffmpeg` fehlt oder ALSA-Device falsch.
+
+## 6) Sicherheitsregeln
+
+- Immer zuerst PTT-up/Fail-safe testen, dann PTT-down.
+- Keine Live-Credentials oder host-spezifische sensible Werte in dieses Repo schreiben.