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. This configuration is for the C capacitive-touch version.

Inspired by 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

The configured swipe order is:

1. Fleet — one row per printer: status, job name, progress, finish time and time remaining. The header counts printers that need attention, are printing, paused, idle, offline or still syncing. Tap a row 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.

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 rows, arc gauges and filament slots. A swipe consumes the rest of that touch so dragging across a row 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 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.

CLI checks from the repository root:

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:

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 row. 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.

- 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.

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:

  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

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.