215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
# 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
|
||
|
||
|
||
|
||
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](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 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.
|
||
|
||
```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.
|