Flipdot-display/src/esp32/README.md

# ESP32: controller

PlatformIO environments: `esp32` (OTA) and `esp32_usb` (USB)

The ESP32 decides what is shown on the display. It never touches the panel itself. The
BROSE9323 driver is built with `-D ESPSERIAL`, so every GFX call is sent to the Nano over
`Serial2` (UART2, GPIO 17 TX / GPIO 16 RX, 115200 baud). `Serial` (USB) is only used for
debug output. Wiring is described in the [main README](../../README.md#wiring-between-esp32-and-nano).

## Files

| File | Contents |
|------|----------|
| `main.cpp` | setup, OTA, clock / power logic, Home Assistant callbacks |
| `libs.h` | includes and global objects (display, MQTT, WiFi, pins, timezone) |
| `bitmaps.h` | 1-bit bitmaps (Pikachu, thought bubble, Nintendo logo, ...) |
| `nano_flash_bridge.h/.cpp` | WiFi to serial bridge for flashing the Nano over WiFi (TCP port 2323) |
| `secrets.example.h` | template for `secrets.h` (WiFi and MQTT credentials, **gitignored**) |

## Features

- **OTA updates** through ArduinoOTA. Hostname: `FlipDotDisplay`.
- **OTA panic window:** after a crash or watchdog reset, the ESP32 runs only the OTA
  handler for 15 seconds before it starts the main code. A firmware that crashes on boot
  can still be replaced over the air.
- **NTP time** with timezone `CET-1CEST,M3.5.0,M10.5.0/3` (Europe/Amsterdam).
- **Home Assistant** through MQTT (`home-assistant-integration` library) with two switches:
  - `FlipDotDisplayClock`: clock on, or the Nintendo logo when off
  - `FlipDotDisplayPower`: turns the display off through the relay
- **Relay on GPIO 13** switches the power for both the panels and the Nano. `LOW` turns it
  on.
  - **On:** the ESP waits for the Nano's `READY` message, at most 3 s
    (`NANO_BOOT_TIMEOUT`), before it sends frames. The relay stays on while it is needed;
    the ESP only waits when it actually switches the relay on.
  - **Off:** the ESP stops sending and releases its TX pin (`Serial.end()` and the pin set
    to input). An idle UART line is high and would otherwise power the Nano through its RX
    pin.
- **Nano flash bridge:** `pio run -e nano_ota -t upload` flashes the Nano through the ESP32.
  While a flash session runs, the clock is paused. See the
  [main README](../../README.md#flashing-the-nano-over-wifi).
- **Status LED** (built-in) blinks fast when WiFi is down and slowly when connected. It is
  off at night or when the display is powered off.

## Schedule

| Time | Display |
|------|---------|
| 08:00 – 17:00 | Pikachu and the clock, updated every minute |
| 17:00 – 22:00 | Yawning Pikachu and the clock |
| 22:00 – 23:30 | Clock shown only during the minutes :00, :15, :30 and :45; power is off in between |
| 23:31 – 08:00 | Screen cleared, power off |

## Adding bitmaps

Convert an image with [image2cpp](https://javl.github.io/image2cpp/) to "Arduino code",
horizontal, 1 bit per pixel. Paste the array into `bitmaps.h` and draw it with
`display.drawBitmap(x, y, bitmap, w, h, 1)`. The display is 84 × 19 pixels.