Home-Assistant/esphome/bambu-display/README.md

# Bambu and Elegoo 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 and Elegoo Printer 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 printer integrations must have current printer data.

## Pages and navigation

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

The configured swipe order is:

1. Print Status Overview — one steam gauge per printer. The filled part of
   each ring is that printer's print progress, drawn in the active filament
   color. Black filament keeps a grey ring behind the gauge so it stays visible
   on the black page. The center shows the percent complete in white, with the
   printer name and estimated finish time underneath.
   The local time is in the top-right corner. Tap a gauge to open that printer.
2. PrintsCharming — P1S, Office, both four-slot AMS units.
3. Polly-Pocket — A1 mini, Office, external spool.
4. Ds-Turd-Flinger — A1, Upstairs, four-slot AMS.
5. Jordyns-Layer-Slayer — A1, Upstairs, four-slot AMS.
6. Constipation-Orion — Office, left/right nozzles and both four-slot AMS units.
   AMS A uses `constipation_orion_ams_1`; AMS B retains its original
   `h2c_31b8ap5a2200288_ams_2` entity prefix.
7. Centauri Carbon — Elegoo FDM, Office, nozzle/bed current and target temperatures
   and model/auxiliary/enclosure fan speeds.
8. Saturn — Elegoo resin, Garage, progress, UV LED temperature, current/total layers,
   elapsed time, remaining time and estimated finish.

![Saturn resin page with synthetic telemetry](previews/saturn.png)

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

FDM pages show print status, job name, progress, nozzle and bed current/target
temperatures, remaining time, estimated finish time, current/total layers, print
stage, fan speeds and filament colors/types. The layout follows BambuHelper's
classic gauges: black background, bright green accents, six arc gauges and a
vertical AMS column. Nozzle arcs are orange and the bed arc is cyan. For dual-nozzle
printers the auxiliary-fan position becomes the right-nozzle gauge. The active
filament slot has a green outline. Print errors use red; paused prints use amber.

**HMS means Health Management System.** Its binary sensor means the Bambu integration
has one or more printer health notifications, which can include information or
maintenance messages as well as faults. Tap the status in the upper-right corner
or the scrolling message above the footer to open the health-details panel. It
shows the codes, severities and descriptions reported by Home Assistant, for up to
three current HMS notices, plus print-error details. Scroll vertically for long
messages and tap Close to return. If more than three notices exist, the panel says
how many additional notices are available in Home Assistant.

Elegoo pages use the same status-tap details panel for `print_error` and
`error_status_reason` enum values. `none` and `ok` are normal states; unknown or
unavailable errors do not imply a fault. Elegoo pages use `sdcp_status` for printer
connectivity and do not subscribe to Bambu HMS or AMS entities. The Saturn page
omits nozzle, bed, fan and filament widgets.

The status uses **HEALTH INFO** (cyan) for information-only notifications,
**HEALTH NOTICE** (amber) for common/unknown severities or incomplete details, and
**HEALTH ERROR** (red) for fatal/serious severities. Severity comes from the Bambu
integration's `N-Severity` attributes. Missing or unloaded messages never establish
an information-only status. The display does not dismiss or clear printer alerts.
The [`hms_errors` sensor attributes](https://github.com/greghesp/ha-bambulab/blob/main/custom_components/bambu_lab/pybambu/models.py)
provide `Count`, `1-Code`, `1-Error`, `1-Severity`, and the corresponding numbered
fields for subsequent notices. Stale attributes are ignored when the sensor is off.

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`, `s` or `ms`
unit, and temperature labels use the imported HA temperature unit. Only the visible
page is refreshed each second; every printer's subscriptions remain connected.
Auxiliary and exhaust fans are imported only for printers with those sensors;
unsupported fan readings show `--`. Finish time is estimated from HA's remaining
time and the HA-synchronized clock. Set `time.timezone` in the main YAML if your
timezone differs from `America/New_York`.

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 both device files and the entire `bambu-display/` folder together in the
   ESPHome configuration directory. `bambu-printer-display.yaml` is the first board
   and `bambu-printer-display-2.yaml` is the second. They share `board.yaml` and the
   generated fleet package, which is checked in, so the ESPHome dashboard can compile
   either file 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 the matching device file
   over that board's USB-to-UART bridge for the first flash; subsequent installs can
   use encrypted OTA. Flash `bambu-printer-display.yaml` to the first panel and
   `bambu-printer-display-2.yaml` to the second. Each file has its own ESPHome name,
   so both panels can be online together.
4. Add **Bambu Printer Display** or **Bambu Printer Display 2** through Home
   Assistant's ESPHome integration using the same API encryption key. Each 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 `board.yaml` rather than borrowed from a 5″ board.

The display and LVGL both use **big-endian RGB565**. With `mipi_rgb`'s named
`red`/`green`/`blue` pin groups, its generated bus pin map already exchanges the
two bytes. Selecting little-endian pixels corrupts colors on the physical panel
even though a host preview can look correct. Keep both byte-order settings aligned
with the bus mapping; changing the RGB/BGR label alone is insufficient for this
RPI panel's direct framebuffer path.

To check the physical colors, open the device's **Display Color Test** diagnostic
button in Home Assistant. It shows labeled red, green, blue, white, cyan and magenta
blocks. Swipe to return to the printers. This test page is skipped during normal
printer navigation. Its expected image is [previews/color_test.png](previews/color_test.png).

CLI checks from the repository root:

```sh
esphome config esphome/bambu-printer-display.yaml
esphome config esphome/bambu-printer-display-2.yaml
esphome compile esphome/bambu-printer-display.yaml
esphome compile esphome/bambu-printer-display-2.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, swipe page and fleet gauge. The practical
limit depends on the board's available RAM and flash, and adding printers requires
regenerating and installing the firmware. Seven printers are configured; generation
is also tested with nine. Each Bambu 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`. Use `extra_fans: [aux_fan, exhaust_fan]` only where those HA entities
exist; their mappings are in `EXTRA_FANS`. A remaining-time override also updates its unit subscription.
Filament entries use the Bambu integration's `type`, `color` and `active` attributes.

For Elegoo printers, set `profile: elegoo_fdm` or `profile: elegoo_resin` (the default
profile is `bambu`). These profiles map progress to `percent_complete`, job name to
`file_name`, remaining time to `remaining_print_time`, and total layers to
`total_layers`. The FDM profile reads targets from the HA `number` entities
`target_nozzle_temp` and `target_bed_temp`; it only monitors their state. Per-metric
`entities` overrides support `sensor`, `binary_sensor` and `number` domains.
Sensor types, duration units and enum states follow the
[Elegoo integration definitions](https://github.com/danielcherubini/elegoo-homeassistant/blob/main/custom_components/elegoo_printer/definitions.py).

The configured Elegoo prefixes are `centauri_carbon` and `saturn`, matching the
repository entity snapshot. Some older automations refer to `saturn_iv`; if your
live integration still uses that prefix, change the Saturn `entity_prefix` before
regenerating. If individual entities have different names in your integration
version, use `entities` overrides, for example:

```yaml
  entities:
    print_error_reason: sensor.saturn_current_print_error_status_reason
```

No new HA helpers are required. `dual_nozzle`, filament slots and `extra_fans` are
Bambu options; the Elegoo FDM profile includes its three fan subscriptions.

## 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 seven pages and a synthetic health
notice into `previews/`. The demo notice is not a diagnosis of any real printer. 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.
The preview also checks Elegoo telemetry, error text and clearing of offline data.