# robot-hardware

Firmware ESP32 de Ti-Pote. Gère l'OLED (yeux animatroniques), et
à terme l'audio I2S, les servos et les LEDs. Communique avec le
`robot-client` (Pi Zero / laptop en dev) via un protocole binaire
sur UART.

## Stack

- **Framework** : Arduino via [PlatformIO](https://platformio.org/)
- **Cibles** : `esp32dev` (prototype actuel) et `esp32-s3` (cible finale, cf. `docs/hardware.md`)
- **Libs** : `U8g2` pour l'OLED SSD1309

## Layout

```
apps/robot-hardware/
├── platformio.ini          # envs esp32dev + esp32-s3
├── include/
│   └── protocol_types.h    # Référence du protocole (C++) — mirroir TS côté robot-client
├── src/
│   └── main.cpp            # setup/loop : RX frames → dispatch → Eyes
├── lib/
│   ├── Protocol/           # Encoder/decoder binaire + CRC8
│   └── Eyes/               # Rendu des 10 émotions sur SSD1309
└── legacy/                 # Prototypes .ino originaux (référence)
```

## Protocole UART (v0)

```
┌────────┬──────┬──────────┬──────────┬─────────────┬──────┐
│ START  │ TYPE │ LENGTH_H │ LENGTH_L │  PAYLOAD    │ CRC8 │
│ 0xAA   │ 1B   │ 1B       │ 1B       │ 0..65535 B  │ 1B   │
└────────┴──────┴──────────┴──────────┴─────────────┴──────┘
```

CRC8 : polynôme `0x07`, init `0x00`, calculé sur
`TYPE + LENGTH + PAYLOAD`.

Types de messages implémentés dans cette itération :

| Code    | Nom                | Direction   | Payload                    |
|---------|--------------------|-------------|----------------------------|
| `0x05`  | `STATUS`           | host → fw   | vide (heartbeat)           |
| `0x08`  | `ACK`              | fw → host   | opaque (contexte)          |
| `0x20`  | `DISPLAY_EMOTION`  | host → fw   | 1 byte (code émotion 0..9) |
| `0x21`  | `DISPLAY_CLEAR`    | host → fw   | vide                       |
| `0xF0`  | `PING`             | host → fw   | opaque                     |
| `0xF1`  | `PONG`             | fw → host   | echo du PING               |
| `0xFD`  | `LOG`              | fw → host   | texte UTF-8                |
| `0xFE`  | `ERROR`            | fw → host   | texte UTF-8                |

Les codes `0x01..0x09` sont réservés pour la Phase 2 (audio, servos,
LEDs) — voir `docs/hardware.md`.

## Build & flash

Installe [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation/index.html)
(extension VSCode ou `pipx install platformio`), puis :

```bash
cd apps/robot-hardware

# Compile
pio run

# Flash (auto-détection du port)
pio run -t upload

# Terminal série — tu verras les LOG frames en binaire + les
# bytes bruts. Pour un monitor plus lisible pendant le bring-up,
# préfère la demo TypeScript (voir ci-dessous).
pio device monitor
```

Pour cibler l'ESP32-S3 :

```bash
pio run -e esp32-s3 -t upload
```

## Câblage OLED (SSD1309, 4-wire HW SPI)

| OLED | ESP32 (VSPI) |
|------|--------------|
| VCC  | 3.3V         |
| GND  | GND          |
| SCK  | GPIO18       |
| SDA  | GPIO23       |
| CS   | GPIO5        |
| DC   | GPIO16       |
| RES  | GPIO17       |

Si tu changes ces pins, modifie `EyesPins` dans `src/main.cpp` (ou
passe des pins custom à `Eyes{EyesPins{...}}`).

## Tester depuis le robot-client

Avec l'ESP32 branché en USB sur ton laptop :

```bash
export HARDWARE_SERIAL_PORT=/dev/ttyUSB0     # ou /dev/ttyACM0, /dev/tty.usbserial-XXXX…
pnpm --filter @ti-pote/robot-client hw:demo
```

La demo fait un `ping` puis cycle sur les 10 émotions. Tu dois
voir les yeux changer toutes les 1.2 s sur l'OLED.

## Phase 2 (à venir)

- `AUDIO_UP` / `AUDIO_DOWN` : streaming I2S 16 kHz via buffer DMA
- `SERVO_CMD` : contrôle PWM des servos de tête
- `LED_CMD` : animations NeoPixel
- Bascule de `Serial` vers `Serial2` pour la liaison Pi ↔ ESP32