265 lines
10 KiB
Markdown
265 lines
10 KiB
Markdown
# AGENTS.md — Klubhaus Doorbell
|
||
|
||
Multi-target Arduino/ESP32 doorbell alert system using ntfy.sh.
|
||
|
||
## Quick Reference
|
||
|
||
```bash
|
||
# Compile, upload, monitor
|
||
BOARD=esp32-32e-4 mise run compile # compile
|
||
BOARD=esp32-32e-4 mise run upload # upload (auto-kills monitor)
|
||
BOARD=esp32-32e-4 mise run monitor # start JSON monitor daemon
|
||
BOARD=esp32-32e-4 mise run log-tail # watch colored logs
|
||
BOARD=esp32-32e-4 mise run cmd COMMAND=dashboard # send command
|
||
BOARD=esp32-32e-4 mise run state # show device state
|
||
|
||
# Install libs (run after cloning)
|
||
mise run install-libs-shared # shared libs (ArduinoJson, NTPClient)
|
||
BOARD=esp32-32e-4 mise run install # shared + board-specific libs
|
||
```
|
||
|
||
**Default BOARD**: `esp32-32e-4` (set in mise.toml)
|
||
|
||
## Project Overview
|
||
|
||
Three board targets share business logic via a common library:
|
||
|
||
| Board | Display | Library | Build Command |
|
||
|-------|---------|---------|--------------|
|
||
| ESP32-32E | SPI TFT 320x240 (ILI9341) | TFT_eSPI | `BOARD=esp32-32e mise run compile` |
|
||
| ESP32-32E-4" | SPI TFT 320x480 (ST7796) | TFT_eSPI | `BOARD=esp32-32e-4 mise run compile` |
|
||
| ESP32-S3-Touch-LCD-4.3 | 800x480 RGB parallel | LovyanGFX | `BOARD=esp32-s3-lcd-43 mise run compile` |
|
||
|
||
## Essential Commands
|
||
|
||
All commands run via **mise**:
|
||
|
||
```bash
|
||
# Install all dependencies (shared libs + vendored display libs)
|
||
mise run install-libs-shared
|
||
mise run install # install shared + board-specific libs (requires BOARD env)
|
||
|
||
# Generic commands (set BOARD environment variable)
|
||
BOARD=esp32-32e mise run compile # compile for ESP32-32E
|
||
BOARD=esp32-32e mise run upload # upload to ESP32-32E
|
||
BOARD=esp32-32e mise run monitor # monitor ESP32-32E
|
||
|
||
BOARD=esp32-32e-4 mise run compile # compile for ESP32-32E-4"
|
||
BOARD=esp32-32e-4 mise run upload # upload to ESP32-32E-4"
|
||
BOARD=esp32-32e-4 mise run monitor # monitor ESP32-32E-4"
|
||
|
||
BOARD=esp32-s3-lcd-43 mise run compile # compile for ESP32-S3-LCD-4.3
|
||
BOARD=esp32-s3-lcd-43 mise run upload # upload to ESP32-S3-LCD-4.3
|
||
BOARD=esp32-s3-lcd-43 mise run monitor # monitor ESP32-S3-LCD-4.3
|
||
|
||
# Other useful tasks
|
||
mise run format # format code
|
||
mise run clean # clean build artifacts
|
||
mise run kill # kill running monitor/upload for BOARD
|
||
mise run log-tail # tail colored logs (requires BOARD)
|
||
mise run cmd COMMAND=dashboard # send command to device (requires BOARD)
|
||
mise run state # show device state (requires BOARD)
|
||
|
||
# LSP / IDE support
|
||
mise run gen-compile-commands # generate compile_commands.json for LSP
|
||
mise run gen-crush-config # generate .crush.json with BOARD-based FQBN
|
||
|
||
# Arduino maintenance
|
||
mise run arduino-clean # clear Arduino CLI cache (staging + packages)
|
||
|
||
# Raw serial access
|
||
mise run monitor-raw # raw serial monitor (arduino-cli)
|
||
mise run monitor-tio # show tio command for terminal UI
|
||
```
|
||
|
||
**Upload port override**: `PORT=/dev/ttyXXX BOARD=esp32-32e mise run upload`
|
||
|
||
**Prerequisites**: arduino-cli with `esp32:esp32` platform installed, mise.
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
libraries/KlubhausCore/src/ Shared Arduino library
|
||
├── KlubhausCore.h Umbrella include (board sketches use this)
|
||
├── Config.h Constants, timing, WiFiCred struct
|
||
├── ScreenState.h State enums/structs
|
||
├── IDisplayDriver.h Pure virtual display interface
|
||
├── DisplayManager.h Thin wrapper delegating to IDisplayDriver
|
||
├── NetManager.* WiFi, HTTP, NTP
|
||
└── DoorbellLogic.* State machine, ntfy polling
|
||
|
||
boards/
|
||
├── esp32-32e/
|
||
│ ├── esp32-32e.ino Main sketch
|
||
│ ├── board_config.h Board-specific config
|
||
│ ├── secrets.h WiFi creds (gitignored, copy from .example)
|
||
│ ├── tft_user_setup.h TFT_eSPI config
|
||
│ └── DisplayDriverTFT.* Concrete IDisplayDriver for TFT
|
||
├── esp32-32e-4/
|
||
│ ├── esp32-32e-4.ino Main sketch
|
||
│ ├── board_config.h Board-specific config
|
||
│ ├── secrets.h WiFi creds (gitignored, copy from .example)
|
||
│ ├── tft_user_setup.h TFT_eSPI config
|
||
│ └── DisplayDriverTFT.* Concrete IDisplayDriver for TFT
|
||
└── esp32-s3-lcd-43/
|
||
├── esp32-s3-lcd-43.ino Main sketch
|
||
├── board_config.h Board-specific config
|
||
├── secrets.h WiFi creds (gitignored, copy from .example)
|
||
├── LovyanPins.h Pin definitions
|
||
└── DisplayDriverGFX.* Concrete IDisplayDriver for LovyanGFX
|
||
|
||
vendor/ Vendored display libs (recreated by install-libs)
|
||
├── esp32-32e/TFT_eSPI/
|
||
├── esp32-32e-4/TFT_eSPI/
|
||
└── esp32-s3-lcd-43/LovyanGFX/
|
||
```
|
||
|
||
## Code Patterns
|
||
|
||
### Header Guards
|
||
Use `#pragma once` (not `#ifndef` guards).
|
||
|
||
### Formatting
|
||
- 4-space indentation, no tabs
|
||
- WebKit-based style (see `.clang-format`)
|
||
- Column limit: 100
|
||
- Opening brace stays on same line (`BreakBeforeBraces: Attach`)
|
||
|
||
### Class Design
|
||
- Pure virtual `IDisplayDriver` interface in shared library
|
||
- Each board implements a concrete driver (e.g., `DisplayDriverTFT`, `DisplayDriverGFX`)
|
||
- `DisplayManager` delegates to `IDisplayDriver` — no display-lib coupling in shared code
|
||
|
||
### Arduino Patterns
|
||
- `setup()` runs once at boot — call `begin()` on managers
|
||
- `loop()` runs continuously — call `update()` on managers
|
||
- Use `millis()` for timing (not `delay()`)
|
||
- Serial console at 115200 baud for debug commands
|
||
|
||
## Testing/Debugging
|
||
|
||
**Serial commands** (type into serial monitor at 115200 baud):
|
||
|
||
| Command | Action |
|
||
|---------|--------|
|
||
| `alert` | Trigger a test alert |
|
||
| `silence` | Silence current alert |
|
||
| `dashboard` | Show dashboard screen |
|
||
| `off` | Turn off display |
|
||
| `status` | Print state + memory info |
|
||
| `reboot` | Restart device |
|
||
|
||
## Monitor Daemon and Logging
|
||
|
||
The build system includes a Python-based monitor agent that provides JSON logging and command pipes.
|
||
|
||
- **JSON log**: `/tmp/doorbell-$BOARD.jsonl` – each line is `{"ts":123.456,"line":"..."}`
|
||
- **State file**: `/tmp/doorbell-$BOARD-state.json` – current device state (screen, alert status, etc.)
|
||
- **Command FIFO**: `/tmp/doorbell-$BOARD-cmd.fifo` – send commands via `echo 'dashboard' > /tmp/doorbell-$BOARD-cmd.fifo`
|
||
|
||
Commands to interact with the daemon:
|
||
|
||
```bash
|
||
BOARD=esp32-32e mise run monitor # Start monitor daemon (background)
|
||
BOARD=esp32-32e mise run log-tail # Tail colored logs
|
||
BOARD=esp32-32e mise run cmd COMMAND=dashboard # Send command
|
||
BOARD=esp32-32e mise run state # Show current device state
|
||
```
|
||
|
||
The monitor daemon automatically starts after upload and is killed before upload to avoid serial port conflicts.
|
||
|
||
## Gotchas
|
||
|
||
1. **secrets.h is gitignored**: Copy from `.example` before building:
|
||
```bash
|
||
cp boards/esp32-32e/secrets.h.example boards/esp32-32e/secrets.h
|
||
cp boards/esp32-32e-4/secrets.h.example boards/esp32-32e-4/secrets.h
|
||
cp boards/esp32-s3-lcd-43/secrets.h.example boards/esp32-s3-lcd-43/secrets.h
|
||
```
|
||
|
||
2. **Display libs are vendored**: Each board uses a different display library. The build system uses `--libraries` to link only the board's vendored lib — never link both TFT_eSPI and LovyanGFX in the same build.
|
||
|
||
3. **No unit tests**: This is an embedded Arduino sketch — no test suite exists. Verify changes by building and deploying to hardware.
|
||
|
||
4. **LSP errors are expected**: The LSP cannot find `Arduino.h` because it requires arduino-cli to resolve. Ignore clangd/IntelliSense errors about missing Arduino types; builds work correctly via arduino-cli.
|
||
|
||
5. **Build artifacts in board dirs**: Build output goes to `boards/[board]/build/` — cleaned by `mise run clean`.
|
||
|
||
6. **WiFi credentials are per-board**: Each board directory has its own `secrets.h` because boards may be on different networks.
|
||
|
||
7. **Use BOARD environment variable**: All build commands require the `BOARD` environment variable (e.g., `BOARD=esp32-32e mise run compile`). The default BOARD is `esp32-32e-4` (set in mise.toml).
|
||
|
||
8. **Lockfile system**: The build system uses lockfiles (`/tmp/doorbell-$BOARD.lock`) to prevent concurrent upload/monitor operations. Use `mise run kill` to clean up stuck processes.
|
||
|
||
## Known Fixes
|
||
|
||
- **dashboard/off admin commands reset inactivity timer** (DoorbellLogic.cpp:234,240) — Admin commands like `dashboard` and `off` now reset the inactivity timer so the display doesn't turn off immediately after switching screens.
|
||
|
||
## Documentation Lookup Rule
|
||
|
||
When uncertain about CLI tool flags or argument syntax:
|
||
1. Run the tool with `-h` or `--help` first
|
||
2. If unclear, search for official documentation matching the tool version
|
||
3. Prefer checking the tool's own help/docs over guessing
|
||
4. For Arduino CLI, check `arduino-cli <command> --help` or official Arduino CLI docs
|
||
|
||
## LSP / IDE Configuration
|
||
|
||
The project uses clangd for C++ and arduino-language-server for Arduino. The `.crush.json` contains dynamic FQBN resolution:
|
||
|
||
```json
|
||
{
|
||
"lsp": {
|
||
"arduino": {
|
||
"command": "arduino-language-server",
|
||
"args": ["-fqbn", "$(cat boards/${BOARD:-esp32-32e-4}/board-config.sh | grep '^FQBN=' | cut -d'\"' -f2)"]
|
||
},
|
||
"cpp": {
|
||
"command": "clangd"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Generate compile_commands.json** for accurate IDE diagnostics:
|
||
```bash
|
||
BOARD=esp32-32e-4 mise run gen-compile-commands
|
||
```
|
||
|
||
**Generate static .crush.json** for a specific board:
|
||
```bash
|
||
BOARD=esp32-32e-4 mise run gen-crush-config
|
||
```
|
||
|
||
## Hardware Research Log
|
||
|
||
### Hosyond ESP32-32E 4" (320x480) - Planned
|
||
|
||
**Source**: https://www.lcdwiki.com/4.0inch_ESP32-32E_Display
|
||
|
||
| Spec | Value |
|
||
|------|-------|
|
||
| Display Controller | ST7796S |
|
||
| Resolution | 320x480 |
|
||
| Touch | XPT2046 (resistive) |
|
||
| Library | TFT_eSPI V2.5.43 (same as 32E) |
|
||
|
||
**GPIO Pinout**:
|
||
|
||
| Function | GPIO |
|
||
|----------|------|
|
||
| LCD CS | 15 |
|
||
| LCD DC | 2 |
|
||
| LCD MOSI | 13 |
|
||
| LCD SCLK | 14 |
|
||
| LCD RST | EN |
|
||
| LCD BL | 27 |
|
||
| Touch CS | 33 |
|
||
| Touch IRQ | 36 |
|
||
|
||
**Quirks**:
|
||
- SPI pins shared between LCD and touch
|
||
- Touch IRQ on IO36 (input-only) triggers LOW on touch
|
||
- Backlight on IO27 (HIGH = on)
|
||
- Common anode RGB LEDs on IO16, IO17, IO22 (LOW = on)
|