Adding a Device

Adding an e‑ink device

Supported displays

Device	Panel	Notes
Waveshare ESP32‑S3 PhotoPainter	7.3" E6 (6‑colour)	AXP2101 power, battery, sleep schedule
Seeed reTerminal E1001	7.5" UC8179 (monochrome)	ADC battery, 3 buttons
Custom devices	—	Admins can register a GitHub firmware repo; the server clones & builds it into a flashable/OTA‑able device type.

Pairing flow (overview)

1. Flash the firmware to the device (see below), then power it on.
2. On first boot with no settings, the device creates its own WiFi hotspot PhotoDock-XXXX and shows a setup screen.
3. Connect your phone/laptop to that hotspot and open the captive page. Enter:
   • your home WiFi name + password, and
   • the Server URL — copy it from Settings → Device Setup (it's your Public dashboard URL).
4. Save. The device reboots, joins your WiFi, reaches the server, and shows a QR code / pairing code.
5. In the dashboard, go to Pair device (/pair) → scan the QR or type the code → choose which screen it belongs to. The device is now linked and receives an API key automatically.

The device then wakes on its interval, fetches the next photo for its screen, displays it, and deep‑sleeps to save battery.

Build / flash the firmware

The firmware is PlatformIO‑based (esp32/). Two ways to get a binary:

• Server build (recommended): from the dashboard, build firmware for your model. The server bakes your WiFi + server URL into the build, produces a flashable binary, then wipes the baked secrets. Flash it with the web flasher or esptool.
• From source:

  cd esp32
  pio run -e esp32s3-photopainter      # Waveshare PhotoPainter E6
  pio run -e reterminal-e1001          # Seeed reTerminal E1001
  pio run -e <env> -t upload           # flash over USB

⚠️ Never commit real WiFi credentials. esp32/src/config.h is meant to stay empty in git; the server bakes creds at build time and wipes them afterwards.

Updating firmware (OTA)

• The server serves the current firmware per model; each board only ever pulls its own build.
• Per‑screen Auto‑update (in the screen's edit dialog) pulls new firmware automatically; otherwise use Update now.
• The firmware changelog is recorded automatically on each build and shown read‑only in the dashboard.

Sleep schedule

Each screen can sleep on a schedule (e.g. 23:00 → 07:00). During the window the device shows a "Sleeping" page and stops refreshing to save battery. Times use the server timezone.