skruecken/powerpods
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add feature development guide and fix ESP-NOW proto generation.

Browse Source 
Document UART-to-ESP-NOW flow using Find me; align proto_generate_espnow with uart (python3, -I .).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
simon 2026-05-19 22:09:24 +02:00
parent efd6260201
commit 2e88358c53
4 changed files with 367 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Makefile
View File

@ -19,8 +19,8 @@ default:
@echo "Set PORT=$(PORT) (current) for goTool targets." @echo "Set PORT=$(PORT) (current) for goTool targets."
proto_generate_espnow: proto_generate_espnow:
cd main/proto && python ../../libs/nanopb/generator/nanopb_generator.py \ cd main/proto && python3 ../../libs/nanopb/generator/nanopb_generator.py \
-I ../../libs/nanopb/generator/proto esp_now_messages.proto -I . -I ../../libs/nanopb/generator/proto esp_now_messages.proto
proto_generate: proto_generate_uart proto_generate_espnow proto_generate: proto_generate_uart proto_generate_espnow

351
docs/adding-a-feature.md Normal file
View File

@ -0,0 +1,351 @@
# Feature hinzufügen — von UART bis ESP-NOW
Dieser Guide beschreibt die **komplette Kette** am Beispiel **Find me** (Commit `efd6260`): Host sendet ein UART-Kommando an den Master, der die Aktion lokal ausführt oder per ESP-NOW an einen Slave weiterleitet.
## Architektur (Überblick)
```mermaid
sequenceDiagram
participant Host as Host (goTool / Dashboard)
participant Master as Master (UART + ESP-NOW)
participant Slave as Slave (ESP-NOW)
Host->>Master: UART-Frame [cmd_id + UartMessage protobuf]
Master->>Master: cmd_* Handler (Queue)
alt client_id == 0
Master->>Master: z.B. led_ring_find_me()
else client_id > 0
Master->>Slave: ESP-NOW EspNowMessage (unicast)
Slave->>Slave: esp_now_recv_cb → Handler
end
Master->>Host: UART-Response (UartMessage)
```
| Schicht | Dateien | Rolle |
|---------|---------|--------|
| Schema UART | `main/proto/uart_messages.proto` | `MessageType`, Request/Response für Host ↔ Master |
| Schema ESP-NOW | `main/proto/esp_now_messages.proto` | Master ↔ Slave (ohne UART) |
| Transport UART | `main/uart.c`, `goTool/uart/` | Rahmen `0xAA … 0xCC`, Byte 0 = Command-ID |
| Dispatch | `main/cmd_handler.c`, `main/uart_cmd.c` | Queue + `uart_cmd_register()` |
| Master-Logik | `main/cmd_*.c` | Decode, Registry, ESP-NOW senden |
| ESP-NOW | `main/esp_now_comm.c` | Encode/Decode, Send, Slave-`recv_cb` |
| Geräte-Funktion | z.B. `main/led_ring.c` | Wiederverwendbare Aktion (Master + Slave) |
| Host | `goTool/cmd_*.go`, `api_serve.go`, `webui/` | CLI, HTTP, UI |
**Wichtig:** UART-Befehle laufen auf dem **Master** (nur wenn `app_config.master`). Slaves haben keinen UART-Command-Handler; sie reagieren auf **ESP-NOW**. Die eigentliche Wirkung (LED, Sensor, …) liegt in gemeinsamen Modulen (`led_ring`, `bosch456`, …).
---
## Wann braucht man was?
| Ziel | UART (`uart_messages.proto`) | ESP-NOW (`esp_now_messages.proto`) |
|------|------------------------------|-------------------------------------|
| Nur Master (angeschlossener Pod) | Ja | Nein |
| Einen registrierten Slave ansteuern | Ja (Master leitet weiter) | Ja |
| Slave → Master Rückmeldung | Optional (UART-Status) | Ja, wenn Slave antworten soll |
**Find me:** UART `FIND_ME` mit `client_id`; `0` = Master-Ring, `>0` = Unicast `ESPNOW_FIND_ME` an die Slave-MAC aus der Registry.
Referenz für **nur ESP-NOW-Weiterleitung ohne lokale Wirkung:** `cmd_espnow_unicast_test.c`
Referenz für **Master lokal + Slave + `client_id`:** `cmd_espnow_find_me.c`, `cmd_accel_deadzone.c`
---
## Schritt 1 — Protobuf (UART)
Datei: `main/proto/uart_messages.proto`
1. **Neue ID** in `enum MessageType` (freie Nummer wählen, z.B. `22`):
```protobuf
FIND_ME = 22;
```
2. **Request/Response** definieren und im `UartMessage`-`oneof` eintragen (neue Feldnummern, nicht wiederverwenden):
```protobuf
message EspNowFindMeRequest {
uint32 client_id = 1;
}
message EspNowFindMeResponse {
bool success = 1;
uint32 client_id = 2;
}
// in message UartMessage { oneof payload { …
EspNowFindMeRequest espnow_find_me_request = 19;
EspNowFindMeResponse espnow_find_me_response = 20;
}
```
3. **Generieren:**
```bash
make proto_generate_uart
make gotool-proto
```
Erzeugt u.a. `main/proto/uart_messages.pb.h`, `.pb.c` und `goTool/pb/uart_messages.pb.go`.
---
## Schritt 2 — Protobuf (ESP-NOW), falls Slaves betroffen
Datei: `main/proto/esp_now_messages.proto`
1. Neuer Wert in `enum EspNowMessageType`:
```protobuf
ESPNOW_FIND_ME = 10;
```
2. Payload-Nachricht + Eintrag im `EspNowMessage`-`oneof`:
```protobuf
message EspNowFindMe {
uint32 client_id = 1; // 0 = alle; sonst nur passende slave_id
}
// EspNowMessage.oneof:
EspNowFindMe find_me = 11;
```
3. **Generieren:**
```bash
make proto_generate_espnow
# oder: make proto_generate
```
**Hinweis:** Master und alle Slaves müssen dieselbe ESP-NOW-Proto-Version flashen, sobald sich `esp_now_messages.proto` ändert.
---
## Schritt 3 — Geräte-Logik (gemeinsam)
Funktion, die auf **Master und Slave** gleich wirken soll, gehört **nicht** in den UART-Handler, sondern in ein Modul (z.B. `led_ring`).
Find me:
- `led_ring_find_me()` in `led_ring.c` — sequenz `LED_CMD_FIND_ME` (3× rot/grün/blau, volle Helligkeit)
- Optional separater UART-Pfad nur für Ring-Steuerung: `LED_RING` mode `4` in `cmd_led_ring.c` (ohne ESP-NOW)
---
## Schritt 4 — UART-Command-Handler (nur Master)
Neue Dateien: `main/cmd_espnow_find_me.c`, `main/cmd_espnow_find_me.h`
Muster (gekürzt):
```c
static void reply(bool success, uint32_t client_id) {
alox_UartMessage response;
uart_cmd_init_response(&response, alox_MessageType_FIND_ME,
alox_UartMessage_espnow_find_me_response_tag);
response.payload.espnow_find_me_response.success = success;
response.payload.espnow_find_me_response.client_id = client_id;
uart_cmd_send(&response, TAG);
}
static void handle_find_me(const uint8_t *data, size_t len) {
alox_UartMessage uart_msg;
if (uart_cmd_decode(data, len, &uart_msg) != ESP_OK) { … }
const alox_EspNowFindMeRequest *req = UART_CMD_REQ(
&uart_msg, alox_UartMessage_espnow_find_me_request_tag,
espnow_find_me_request);
if (req == NULL) { … }
if (req->client_id == 0) {
led_ring_find_me(); // lokal
reply(true, 0);
return;
}
const client_info_t *client = client_registry_find_by_id(req->client_id);
if (client == NULL) { reply(false, req->client_id); return; }
esp_err_t err = esp_now_comm_send_find_me(client->mac, req->client_id);
reply(err == ESP_OK, req->client_id);
}
void cmd_espnow_find_me_register(void) {
uart_cmd_register(alox_MessageType_FIND_ME, handle_find_me);
}
```
Hilfs-APIs (`uart_cmd.h`):
| API | Zweck |
|-----|--------|
| `uart_cmd_decode()` | Protobuf-Body (ohne führendes Command-Byte) dekodieren |
| `UART_CMD_REQ()` | Sicheres Lesen des `oneof`-Zweigs |
| `uart_cmd_init_response()` | Response-Typ + `which_payload` setzen |
| `uart_cmd_send()` | Antwort UART raus |
**Registrierung** in `main/powerpod.c` (nur im `if (app_config.master)`-Block):
```c
cmd_espnow_find_me_register();
```
**Build:** `main/CMakeLists.txt` → `"cmd_espnow_find_me.c"`
**Logging-Namen:** `main/cmd_handler.c` → `case alox_MessageType_FIND_ME: return "FIND_ME";`
### Ablauf UART intern
1. `uart_read_task` liest Frame, legt `msg_id = payload[0]` und Rest in Queue.
2. `vCmdDispatcherTask` ruft den registrierten Handler mit `data` = Bytes **nach** der ID auf.
3. Handler antwortet synchron über `uart_cmd_send` (die LED-Animation läuft danach im `led_task` weiter).
---
## Schritt 5 — ESP-NOW senden (Master)
In `main/esp_now_comm.c`:
1. **Statische Sendefunktion** (wie `send_unicast_test`):
```c
static esp_err_t send_find_me(const uint8_t *dest_mac, uint32_t client_id) {
alox_EspNowMessage msg = alox_EspNowMessage_init_zero;
msg.type = alox_EspNowMessageType_ESPNOW_FIND_ME;
msg.which_payload = alox_EspNowMessage_find_me_tag;
msg.payload.find_me.client_id = client_id;
return send_message(dest_mac, &msg);
}
```
2. **Öffentliche API** in `esp_now_comm.h` / `.c`:
```c
esp_err_t esp_now_comm_send_find_me(const uint8_t mac[CLIENT_MAC_LEN],
uint32_t client_id);
```
Prüfungen: `mac != NULL`, `s_config.master`, Peer per `ensure_peer()` (passiert in `send_message`).
---
## Schritt 6 — ESP-NOW empfangen (Slave)
Im Slave-Zweig von `espnow_recv_cb` (`!s_config.master`):
1. Handler-Funktion, typisch mit **Master-MAC-Check** und **`client_id`-Filter** (wie Deadzone):
```c
static void handle_slave_find_me(const uint8_t *master_mac,
const alox_EspNowFindMe *req) {
uint32_t my_id = s_own_mac[5];
if (req->client_id != 0 && req->client_id != my_id) return;
if (s_slave_joined && !mac_equal(master_mac, s_master_mac)) return;
led_ring_find_me();
}
```
2. Im `switch (msg.which_payload)`:
```c
case alox_EspNowMessage_find_me_tag:
if (!s_slave_joined || !mac_equal(info->src_addr, s_master_mac)) break;
handle_slave_find_me(info->src_addr, &msg.payload.find_me);
break;
```
Slaves führen `led_ring_init()` in `powerpod.c` ebenfalls aus — Ring-Hardware ist auf beiden Rollen vorhanden.
---
## Schritt 7 — Host (goTool)
### CLI
`goTool/cmd_find_me.go`:
- `UartMessage` mit `Type: MessageType_FIND_ME` und `EspnowFindMeRequest`
- Payload = `[byte(MessageType_FIND_ME)] + proto.Marshal(msg)`
- `exchangePayload` → Response dekodieren
`main.go`: Command `find-me` registrieren, `-port` Pflicht.
```bash
go run . -port /dev/ttyUSB0 find-me
go run . -port /dev/ttyUSB0 find-me -client 16
```
### Dashboard / HTTP
1. `managedSerial.FindMe(clientID)` in `client_api.go` (UART-Serial mutex wie andere Befehle).
2. `POST /api/find-me` mit `{"client_id": 0}` in `api_serve.go`.
3. Button in `goTool/webui/index.html` (Master + pro Slave-Zeile).
### Serial-Format (Host)
Entspricht `main/README.md`:
| Byte | Inhalt |
|------|--------|
| Frame | `0xAA`, Länge, Payload, XOR-Checksum, `0xCC` |
| Payload[0] | `MessageType` (z.B. `22` = FIND_ME) |
| Payload[1…] | Nanopb-`UartMessage` |
---
## Schritt 8 — Dokumentation & Test
1. **`main/README.md`:** Zeile in UART-Tabelle, ggf. ESP-NOW-Tabelle, eigener Abschnitt mit Beispiel-`go run`.
2. **`goTool/README.md`:** Command-Tabelle + HTTP-API.
3. **Build:**
```bash
make proto_generate
cd goTool && go build .
idf.py build
```
4. **Manuell testen:**
| Test | Erwartung |
|------|-----------|
| `find-me` (client 0) | Master-Ring blinkt RGB |
| `find-me -client <id>` | Nur dieser Slave blinkt; Log Master: `unicast FIND_ME` |
| Slave offline / unbekannte ID | `success=false` in UART-Response |
| Dashboard-Buttons | Gleiches Verhalten wie CLI |
---
## Checkliste (Kurz)
- [ ] `uart_messages.proto`: `MessageType`, Request, Response, `oneof`
- [ ] `esp_now_messages.proto` (falls Slave): `EspNowMessageType`, Message, `oneof`
- [ ] `make proto_generate` + `make gotool-proto`
- [ ] Geräte-Modul (z.B. `led_ring_*`)
- [ ] `cmd_*.c` + `uart_cmd_register`
- [ ] `esp_now_comm`: `send_*` + Slave-`recv` case
- [ ] `CMakeLists.txt`, `powerpod.c`, `cmd_handler.c` Name
- [ ] goTool: CLI, `client_api`, optional `api_serve` + WebUI
- [ ] README aktualisieren
- [ ] Master + Slave flashen bei ESP-NOW-Proto-Änderung
---
## Referenz-Dateien (Find me)
| Bereich | Datei |
|---------|--------|
| UART Proto | `main/proto/uart_messages.proto` |
| ESP-NOW Proto | `main/proto/esp_now_messages.proto` |
| UART Handler | `main/cmd_espnow_find_me.c` |
| ESP-NOW | `main/esp_now_comm.c`, `main/esp_now_comm.h` |
| LED | `main/led_ring.c`, `main/led_ring.h` |
| Host CLI | `goTool/cmd_find_me.go` |
| HTTP/UI | `goTool/api_serve.go`, `goTool/webui/index.html` |
Ähnliche Features zum Abgucken:
- **Nur Master, kein ESP-NOW:** `cmd_version.c`, `cmd_led_ring.c`
- **Nur Slave per ESP-NOW (Master leitet nur durch):** `cmd_espnow_unicast_test.c`
- **Master + alle Slaves / Filter:** `cmd_accel_deadzone.c`
- **Großer ESP-NOW-Fluss mit Status:** `ota_espnow.c`, `cmd_ota.c`

2
goTool/README.md
View File

@ -34,6 +34,8 @@ go run . -port /dev/ttyUSB0 clients
`clients` requires slaves to have responded to master discover broadcasts first. `clients` requires slaves to have responded to master discover broadcasts first.
For adding commands end-to-end (UART, ESP-NOW, CLI, dashboard), see **[docs/adding-a-feature.md](../docs/adding-a-feature.md)** (Find me example).
### Automated tests ### Automated tests
Bench **configs** (`testdata/configs/`) list network, MACs, and serial ports (`uart.master` for commands, `*_console` for esptool reset). **Scenarios** run UART commands plus optional `reset` steps. Bench **configs** (`testdata/configs/`) list network, MACs, and serial ports (`uart.master` for commands, `*_console` for esptool reset). **Scenarios** run UART commands plus optional `reset` steps.

17
main/README.md
View File

@ -448,11 +448,18 @@ Target: ESP32-S3. Close serial monitor on the UART adapter port before running `
| `proto/*.pb.c/h` | Generated nanopb | | `proto/*.pb.c/h` | Generated nanopb |
| `CMakeLists.txt` | Sources, `esp_wifi`, drivers, git hash | | `CMakeLists.txt` | Sources, `esp_wifi`, drivers, git hash |
## Adding a new UART command ## Adding a new feature (UART → ESP-NOW)
1. Add or extend messages in `uart_messages.proto` and regenerate nanopb. End-to-end walkthrough (protobuf, master handler, ESP-NOW unicast to slaves, goTool, dashboard) with **Find me** as the worked example:
2. Create `cmd_*.c` with a handler; register with `uart_cmd_register(MessageType_…, handler)`.
3. Decode with `uart_cmd_decode()` / `UART_CMD_REQ()`; reply with `uart_cmd_init_response()` + `uart_cmd_send()`. **[docs/adding-a-feature.md](../docs/adding-a-feature.md)**
4. Extend `goTool` or another host client to send the matching frame.
Short checklist:
1. Add or extend messages in `uart_messages.proto` (and `esp_now_messages.proto` if slaves are involved); run `make proto_generate` and `make gotool-proto`.
2. Implement device logic in a shared module (e.g. `led_ring.c`), not only in the UART handler.
3. Create `cmd_*.c`, register with `uart_cmd_register()`; decode with `uart_cmd_decode()` / `UART_CMD_REQ()`; reply with `uart_cmd_init_response()` + `uart_cmd_send()`.
4. Master → slave: `esp_now_comm_send_*()` + slave branch in `espnow_recv_cb`.
5. Extend `goTool` (CLI, optional `/api/…` and web UI).
For ESP-NOW-driven PC updates later: map slave state to `ClientInfo` and send `CLIENT_INFO` over UART from the master. For ESP-NOW-driven PC updates later: map slave state to `ClientInfo` and send `CLIENT_INFO` over UART from the master.