# Bambu fleet display

ESPHome/LVGL monitor for the **Sunton ESP32-8048S043C**, with an 800×480 landscape RGB
display, GT911 capacitive touch, 16 MB flash and 8 MB octal PSRAM. The hardware pins
and LCD timings follow the [ESPHome device reference](https://devices.esphome.io/devices/sunton-esp32-8048s043c/).
This configuration is for the **C** capacitive-touch version.

Inspired by [BambuHelper](https://github.com/Keralots/BambuHelper), this implementation
subscribes to the existing Home Assistant Bambu Lab entities over a single encrypted
ESPHome API connection. Home Assistant handles the printer connections. No Bambu
access codes, cloud credentials or additional Home Assistant automations are needed.
Home Assistant must be running and its Bambu integration must have current printer data.

## Pages and navigation

![LVGL preview with synthetic printer telemetry](previews/prints_charming.png)

The configured swipe order is:

1. PrintsCharming — P1S, Office, both four-slot AMS units.
2. Polly-Pocket — A1 mini, Office, external spool.
3. Ds-Turd-Flinger — A1, Upstairs, four-slot AMS.
4. Jordyns-Layer-Slayer — A1, Upstairs, four-slot AMS.
5. Constipation-Orion — Office, left/right nozzles and four-slot AMS.

Swipe left for the next printer or right for the previous printer. Navigation wraps
from the last page to the first. Previous/Next buttons provide the same navigation.
Swipes propagate through the metric cards and filament slots. A swipe consumes the
rest of that touch so dragging across a navigation button does not also click it.

Each page shows print status, job name, progress, nozzle and bed current/target
temperatures, remaining time, current/total layers, print stage, part fan speed and
filament colors/types. The active filament slot has a green outline. Print errors
and HMS alerts change the status badge to red; paused prints use amber. The display
shows an alert badge rather than the detailed HMS diagnostic text.

When Home Assistant disconnects or a printer is offline, its live metrics are cleared
to `--` rather than continuing to show cached values as live. Unknown individual
values also show `--`. Remaining time respects the HA sensor's `h`, `min` or `s`
unit, and temperature labels use the imported HA temperature unit. Only the visible
page is refreshed each second; every printer's subscriptions remain connected.

This version provides monitoring and local page navigation. Camera feeds, cover
images, printer pause/stop controls, power switching, cloud login and automatic
printer rotation are outside its current scope.

## Install

1. Keep `esphome/bambu-printer-display.yaml` and the entire `bambu-display/` folder
   together in the ESPHome configuration directory. The generated package is checked
   in, so the ESPHome dashboard can compile it without running the generator first.
2. Supply the existing `api_encryption_key`, `wifi_iot_ssid` and `wifi_password`
   entries in that directory's `secrets.yaml`.
3. Use ESPHome **2026.9.0 or newer**. Compile and install
   `bambu-printer-display.yaml` over the board's USB-to-UART bridge for the first
   flash; subsequent installs can use encrypted OTA.
4. Add **Bambu Printer Display** through Home Assistant's ESPHome integration using
   the same API encryption key. The display only subscribes to entities, so it does
   not require permission to perform Home Assistant actions.
5. Confirm all pages receive data and verify touch direction and color order on the
   physical panel. Entity IDs match the repository's `ha-entities.txt` snapshot;
   renamed or disabled entities in live HA must be corrected/enabled there.

The USB D+/D− GPIO19/20 pins are used by the board's touch bus. Logging therefore
uses UART0. ESPHome may still warn about these two pins; they are intentional for
this board. If GT911 is not found at `0x5D`, inspect the I²C scan and use its reported
address (some hardware revisions select `0x14`). Backlight is GPIO2; RGB data pins
and timings are explicit in the main YAML rather than borrowed from a 5″ board.

CLI checks from the repository root:

```sh
esphome config esphome/bambu-printer-display.yaml
esphome compile esphome/bambu-printer-display.yaml
```

## Change or expand the fleet

Edit **`printers.yaml`**, then regenerate and flash the display:

```sh
python esphome/bambu-display/generate.py
python esphome/bambu-display/generate.py --check
```

The generator requires PyYAML (already included in ESPHome's Python environment).
Do not hand-edit `generated.yaml`. There is no two-printer limit in the generator;
adding a printer creates its own subscriptions, widgets and swipe page. The practical
limit depends on the board's available RAM and flash, and adding printers requires
regenerating and installing the firmware. Five printers are configured; generation
is also tested with seven. Each printer's filament strip supports up to eight slots.

```yaml
- id: another_printer
  name: Another Printer
  subtitle: Workshop
  entity_prefix: my_bambu_printer
  entities:
    progress: sensor.renamed_progress
    time_left: sensor.renamed_remaining_time
  filament_banks:
    - label: A
      entity_prefix: my_bambu_printer_ams_1
```

For a dual-nozzle printer add `dual_nozzle: true`. For external filament add
`external_spools: [{label: EXT, entity: sensor.my_external_spool}]`. Per-metric
`entities` overrides use the keys in `NUMERIC`, `DUAL`, `TEXT` and `BINARY` inside
`generate.py`. A remaining-time override also updates its unit subscription.
Filament entries use the Bambu integration's `type`, `color` and `active` attributes.

## Development checks and screenshots

```sh
python -m unittest discover -s esphome/bambu-display -v
clang++ -std=c++17 -Wall -Wextra -Werror esphome/bambu-display/test_dashboard.cpp -o /tmp/bambu-dashboard-test
/tmp/bambu-dashboard-test
python esphome/bambu-display/preview.py
```

`preview.py` compiles the same generated LVGL widgets for ESPHome's SDL host with
clearly synthetic telemetry, then captures all five pages into `previews/`. It needs
ESPHome, Pillow, a C++ compiler and SDL2 (`sdl2-config` on PATH). It runs headlessly,
without connecting to Home Assistant or any printer. It also injects LVGL pointer
samples to check left/right swipes, page wraparound and consumption of a swipe that
starts on a navigation button. These are software layout
previews; physical panel timings, touch and Wi-Fi still need a hardware check.