# 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)