Stabiler Zwischenstand vor Release 1.0

2026-07-23 23:15:56 +02:00
parent a5caf47b49
commit 5d3dfa6f52
4 changed files with 588 additions and 283 deletions
@@ -1,233 +1,184 @@
 # Funksender Tor

-Automatische Toröffnung per 433 MHz. Jedes Fahrzeug bekommt einen kleinen Sender
-am Zündungsplus, der Empfänger am Tor öffnet, sobald ein bekanntes Fahrzeug nah
-genug ist. Kein Knopfdruck, keine App, kein Account.
+ESPHome-Projekt fuer eine autonome Torsteuerung mit 433 MHz CC1101 Funk.

-**Hardware:** ESP32-C3 Super Mini + CC1101 (433 MHz) je Sender,
-ein bestehender ESP32 DevKit (`tor-steuerung`) + CC1101 als Empfänger am Tor —
-derselbe ESP, der schon Relais und Türsensoren steuert.
+Das System besteht aus zwei Teilen:

---
+- `auto_sender_01.yaml`: ESP32-C3 Sender im Fahrzeug
+- `tor_steuerung.yaml`: ESP32 Empfaenger an der Torsteuerung

-## Inhalt
+Home Assistant ist nur fuer OTA, Diagnose und Einstellungen vorgesehen. Die eigentliche Entscheidung und das Schalten des Relais laufen lokal auf der Torsteuerung. Das Tor kann also auch dann oeffnen, wenn Home Assistant, WLAN oder Internet ausfallen.

- [Verdrahtung CC1101](#verdrahtung-cc1101)
- [Flashen](#flashen) — **hier steht der USB-TTL-Kram**
- [ESPHome einrichten](#esphome-einrichten)
- [Reichweite einstellen](#reichweite-einstellen)
- [Weiteres Fahrzeug hinzufügen](#weiteres-fahrzeug-hinzufügen)
- [Paketformat](#paketformat)
+## Status

---
+Release-Kandidat: `1.0.0-rc1`

-## Verdrahtung CC1101
+Getestetes Funkpaket:

-Die Pins des CC1101 sitzen als **4 Zeilen à 2 Pins**, Antenne rechts:
-
-```
-① GND  │ VDD  ②
-③ GDO0 │ CSN  ④
-⑤ SCK  │ MOSI ⑥
-⑦ MISO │ GDO2 ⑧
+```text
+0xA7 0x3C 0x01 0x00
 ```

-> **Achtung:** Pin 1 ist **GND**, Pin 2 ist **VDD**. Nicht die verbreitete
-> Belegung mancher anderer CC1101-Boards annehmen, wo es umgekehrt ist —
-> Vertauschen macht das Modul und ggf. den ESP heiß.
+## Dateien

-| CC1101 | Signal | ESP32-C3 Super Mini |
-|--------|--------|---------------------|
-| 1 | GND | `G` (links) |
-| 2 | VDD | `3.3` (links) — **niemals 5V** |
-| 3 | GDO0 | `GPIO3` (links) |
-| 4 | CSN | `GPIO4` (links) |
-| 5 | SCK | `GPIO6` (rechts) |
-| 6 | MOSI | `GPIO7` (rechts) |
-| 7 | MISO | `GPIO5` (rechts) |
-| 8 | GDO2 | *frei lassen* |
-
-Schema: [`doku/verdrahtung-cc1101.svg`](doku/verdrahtung-cc1101.svg)
-(zeigt die Pin-Reihenfolge am CC1101 selbst — die Zuordnung zu GPIOs
-unterscheidet sich je nach ESP-Board, siehe Tabellen oben/unten.)
-
-### Empfänger (`tor-steuerung`, ESP32 DevKit)
-
-GPIO16 (Relais) und GPIO34/35 (Türsensoren) sind schon belegt. Der CC1101
-hängt deshalb an den freien VSPI-Standardpins:
-
-| CC1101 | Signal | ESP32 DevKit |
-|--------|--------|--------------|
-| 1 | GND | GND |
-| 2 | VDD | 3V3 |
-| 3 | GDO0 | `GPIO4` |
-| 4 | CSN | `GPIO5` |
-| 5 | SCK | `GPIO18` |
-| 6 | MOSI | `GPIO23` |
-| 7 | MISO | `GPIO19` |
-| 8 | GDO2 | *frei lassen* |
-
---
-
-## Flashen
-
-### Warum nicht über den USB-C-Anschluss?
-
-Der ESP32-C3 hat einen eingebauten USB-Serial/JTAG-Controller. Unter Windows 11
-sollte er automatisch als COM-Port erscheinen — **tut er aber nicht mehr, sobald
-Zadig einmal auf ihm gelaufen ist.**
-
-Was passiert war: Zadig ersetzt den nativen `usbser.sys` durch WinUSB bzw.
-selbstgenerierte libwdi/libusbK-Treiber. Danach zeigt der Geräte-Manager zwar
-einen COM-Port, aber esptool bekommt nur
-
-```
-A fatal error occurred: Failed to connect to ESP32-C3: No serial data received.
+```text
+esphome/
+  auto_sender_01.yaml
+  tor_steuerung.yaml
+README.md
+CHANGELOG.md
 ```

-Das lässt sich reparieren (siehe unten), ist aber fummelig. **Der USB-TTL-Adapter
-umgeht das Thema komplett.**
+## Hardware

-### USB-TTL-Adapter anschließen ← *das ist der Weg, der funktioniert hat*
+### Sender

-> **Adapter zwingend auf 3.3 V jumpern.** Der ESP32-C3 ist nicht 5V-tolerant.
+- ESP32-C3 DevKit / ESP32-C3 Super Mini
+- CC1101 433 MHz Modul
+- Versorgung passend zur Einbausituation

-| USB-TTL-Adapter | ESP32-C3 Super Mini |
-|-----------------|---------------------|
-| TX | `GPIO20` (rechts, vorletzter Pin) |
-| RX | `GPIO21` (rechts, letzter Pin) |
-| GND | `G` (links, 2. Pin) |
-| 3.3V | `3.3` (links, 3. Pin) |
+### Empfaenger

-TX und RX sind **gekreuzt** — das ist so richtig.
-Das CC1101 kann angeschlossen bleiben, GPIO20/21 kollidieren mit nichts.
+- ESP32 DevKit / ESP32 Relaisboard
+- CC1101 433 MHz Modul
+- Relaiskontakt fuer Torimpuls
+- Endschalter oder Rueckmeldekontakte fuer Tor AUF und Tor ZU

-Liefert der Adapter auf 3.3 V zu wenig Strom, den ESP stattdessen über ein
-USB-Netzteil an der USB-C-Buchse versorgen und vom Adapter nur TX, RX und GND
-anschließen. **Nicht beide Quellen gleichzeitig.**
+## Funkprotokoll

-### Boot-Modus
+Der Sender uebertraegt alle 2 Sekunden ein festes 4-Byte-Paket:

-**`GPIO9` ↔ `G` brücken, danach erst Strom drauf.** Reihenfolge ist wichtig.
-Nach dem Flashen die Brücke wieder entfernen.
-
-### Ablauf
-
-```bash
-# 1. Verbindung prüfen — COM-Port des TTL-Adapters aus dem Geräte-Manager
-python -m esptool --chip esp32c3 --port COM16 chip-id
+```text
+Byte 1: 0xA7  Magic
+Byte 2: 0x3C  Magic
+Byte 3: 0x01  Fahrzeug-ID
+Byte 4: 0x00  Reserve
 ```

-Erwartete Ausgabe:
+CC1101 Einstellungen:

-```
-Chip type:  ESP32-C3 AZ (QFN32) (revision v1.1)
-Features:   Wi-Fi, BT 5 (LE), Single Core, 160MHz, Embedded Flash 4MB (XMC)
-MAC:        44:b1:76:18:cb:ec
+- Frequenz: `433.92 MHz`
+- Modulation: `GFSK`
+- Symbolrate: `4800`
+- Paketlaenge: `4`
+- CRC: aktiv
+- Sync: `0x91 0xD3`
+
+## Sender flashen
+
+Datei:
+
+```text
+esphome/auto_sender_01.yaml
 ```

-```bash
-# 2. Factory-Image flashen (nicht die normale .bin!)
-python -m esptool --chip esp32c3 --port COM16 --baud 460800 \
-    write-flash 0x0 auto-sender-01.factory.bin
-```
+Das erste Flashen erfolgt bei deiner Hardware per TTL/USB-Adapter. Danach kann OTA verwendet werden, sobald der Sender im WLAN erreichbar ist.

-Bricht es bei 460800 ab, mit `--baud 115200` wiederholen.
-
-Danach GPIO9-Brücke raus, Strom aus/an. Ab hier läuft alles über OTA —
-der Adapter wird nicht mehr gebraucht.
-
-`esptool` installieren falls nötig: `pip install esptool`
-
-### Falls der interne USB doch mal repariert werden soll
-
-Als Administrator:
-
-```cmd
-pnputil /enum-drivers | findstr /i "libwdi libusb"
-pnputil /delete-driver oemXX.inf /uninstall /force
-```
-
-Alle gefundenen libwdi/libusbK-Pakete löschen, besonders das mit
-`MS_COMP_USBSER` — das kapert systemweit jedes CDC-Gerät. Danach neu starten.
-Windows zieht dann wieder `usbser.sys`.
-
-**Zadig nicht mehr auf den ESP32-C3 loslassen.** Für den eingebauten
-USB-Serial/JTAG ist es das falsche Werkzeug (außer man will JTAG-Debugging
-über OpenOCD).
-
---
-
-## ESPHome einrichten
-
-Beide Geräte tragen WLAN-Zugangsdaten, `api`-Verschlüsselungskey und
-OTA-Passwort **direkt in der YAML** statt über `secrets.yaml` — so war
-`tor_steuerung.yaml` schon angelegt, und `auto_sender_01.yaml` verwendet
-bewusst dieselben Werte, damit beide Geräte zusammenpassen.
-
-> **Achtung:** Damit stehen WLAN-Passwort und Schlüssel im Klartext in diesem
-> Repo. Nur vertretbar, wenn `git.dominicspringer.de` privat/intern bleibt.
-> Soll das Repo öffentlich werden, vorher alles auf `!secret`-Verweise
-> umstellen und eine lokale `secrets.yaml` (nicht committen) anlegen.
-
-1. In ESPHome (HA-Add-on) das jeweilige Gerät anlegen bzw. die bestehende
-   `tor-steuerung` mit dem neuen Inhalt überschreiben
-2. Inhalt der passenden Datei aus `esphome/` einfügen
-3. Drei Punkte → **Install** → **Manual download** → **Factory format**
-4. Mit esptool flashen (siehe oben)
-
-`reboot_timeout: 0s` beim Sender ist kein Versehen: im Auto ist kein WLAN in
-Reichweite, ohne diese Zeile startet der ESP alle 15 Minuten neu.
-
---
-
-## Reichweite einstellen
-
-Die Reichweite wird **nicht** am Sender begrenzt — alle Sender laufen mit voller
-Leistung. Der Empfänger entscheidet anhand der Signalstärke (RSSI), ob das
-Fahrzeug nah genug ist.
-
-Der Schwellwert liegt als Schieberegler **„RSSI Schwelle"** in Home Assistant,
-Änderungen brauchen kein Neuflashen.
-
-Einmessen:
-
-1. Empfänger-Log in ESPHome öffnen
-2. Mit dem Fahrzeug in verschiedenen Abständen anhalten
-3. RSSI-Werte notieren — z. B. `Fahrzeug 1, RSSI -73.5 dBm, LQI 12`
-4. Den Wert bei der gewünschten Distanz (~5 m) als Schwelle setzen
-
-Je näher der Wert an 0, desto kürzer die Reichweite. Startwert ist `-60`.
-
-Nach jeder Öffnung greift eine **Sperrzeit von 60 Sekunden**.
-
---
-
-## Weiteres Fahrzeug hinzufügen
-
-In `auto_sender_01.yaml` nur die beiden Substitutions oben ändern:
+Wichtige Anpassung fuer weitere Fahrzeuge:

 ```yaml
 substitutions:
-  geraet: auto-sender-02
-  fahrzeug_id: "0x02"
+  device_name: auto-sender-02
+  friendly_name: Auto Sender 02
 ```

-Der Empfänger akzeptiert IDs `0x01` bis `0x0A` (1–10) und muss dafür **nicht**
-angefasst werden. Sollen weniger Fahrzeuge erlaubt sein, im `on_packet`-Lambda
-die Zeile `if (fz < 1 || fz > 10)` anpassen.
+Und im Paket:

---
+```yaml
+- 0x02
+```

-## Paketformat
+Die LED blinkt nur einmal pro Minute kurz auf. Das reduziert unnoetige LED-Laufzeit, ist aber noch kein echter Akkubetrieb. Fuer Akkubetrieb sollte spaeter Deep Sleep oder ein Wakeup-Konzept ergaenzt werden.

-4 Bytes, GFSK, 4800 Baud, CRC-16 aktiv, Sync `0xD391`:
+## Empfaenger flashen

-| Byte | Inhalt |
-|------|--------|
-| 0 | `0xA7` Magic |
-| 1 | `0x3C` Magic |
-| 2 | Fahrzeug-ID (`0x01`–`0x0A`) |
-| 3 | reserviert (`0x00`) |
+Datei:

-Der Sender schickt das Paket alle 2 Sekunden, solange die Zündung an ist.
+```text
+esphome/tor_steuerung.yaml
+```
+
+Die Torsteuerung arbeitet autonom:
+
+1. CC1101 Paket empfangen
+2. Magic Bytes pruefen
+3. Fahrzeug-ID pruefen
+4. RSSI-Grenze pruefen
+5. Sperrzeit pruefen
+6. Relais lokal fuer 500 ms schalten
+
+Home Assistant wird nicht zum Oeffnen benoetigt.
+
+## Home Assistant Diagnose
+
+Die Torsteuerung stellt unter anderem bereit:
+
+- Letzte Fahrzeug-ID
+- Letzter RSSI
+- Letzter LQI
+- Pakete gesamt
+- Gueltige Pakete
+- Verworfene Pakete
+- Toroeffnungen
+- Sekunden seit letztem Paket
+- Sekunden seit letzter Toroeffnung
+- WLAN Signal
+- Freier Heap
+- Neustartgrund
+- Firmware-Version
+
+Einstellbar:
+
+- `RSSI Grenze`
+- `Sperrzeit`
+- `Testmodus`
+
+Der Testmodus prueft die komplette Logik, schaltet aber das Relais nicht.
+
+## WLAN
+
+Beide YAML-Dateien enthalten einen aktiven WLAN-Eintrag und vorbereitete weitere Eintraege:
+
+```yaml
+wifi:
+  networks:
+    - ssid: ${wifi_1_ssid}
+      password: ${wifi_1_password}
+```
+
+Weitere WLANs koennen in den `substitutions` und im `wifi.networks` Block aktiviert werden.
+
+## Testablauf vor Einbau
+
+1. Sender flashen.
+2. Empfaenger flashen.
+3. Pruefen, ob beide in Home Assistant online sind.
+4. Empfaenger auf `Testmodus` stellen.
+5. Sender in Reichweite bringen.
+6. RSSI, LQI und Paketzaehler pruefen.
+7. Testmodus deaktivieren.
+8. Torimpuls pruefen.
+9. Home Assistant oder WLAN testweise deaktivieren.
+10. Pruefen, dass der Empfaenger weiterhin lokal schaltet.
+
+## Git
+
+Zwischenstand speichern:
+
+```bash
+git add .
+git commit -m "Stabiler Zwischenstand vor Release 1.0"
+git push origin main
+```
+
+Nach erfolgreichem Test als Release markieren:
+
+```bash
+git add .
+git commit -m "Release 1.0.0 - autonome CC1101 Torsteuerung"
+git tag -a v1.0.0 -m "Erste stabile Version"
+git push origin main
+git push origin v1.0.0
+```
+
+Falls dein Standard-Branch `master` heisst, ersetze `main` durch `master`.