PrintSphere

Round ESP32-S3 printer companion for Bambu Lab with a circular display, touch setup, hybrid cloud/local routing, and the current code paths for cover preview, camera snapshots, and battery-aware operation.

MakerWorld

• MakerWorld model: https://makerworld.com/de/models/2517189-printsphere-bambu-status-display-standalone-1-75
• End-user setup guide: MAKERWORLD.md

Hardware And Stack

• ESP-IDF v5.5.x
• LVGL v9.4.0
• Waveshare ESP32-S3 AMOLED 1.75
• AXP2101 PMU integration via XPowersLib
• no Home Assistant required

Current Codebase Features

• official Waveshare BSP for display, touch, and LVGL
• NVS-based configuration storage
• AP+STA Wi-Fi manager
• local setup portal on esp_http_server
• Web Config PIN unlock flow from the display
• Bambu Cloud login flow with email/password plus email-code or 2FA handling
• hybrid routing logic between Bambu Cloud and the local printer path
• cloud MQTT status plus metadata / cover preview handling
• local MQTT status path with live reconnect logic from the web portal
• embedded Bambu CA bundle for local MQTT TLS verification
• merged status, metrics, temperatures, errors, and HMS data depending on model and source availability
• cloud cover image/title page in the UI where available
• local camera snapshot page with tap refresh and periodic refresh while open
• arc color tuning from Web Config with live preview behavior
• chamber light toggle path on supported models
• battery and USB status with power-aware behavior
• on-device error text lookup when storage-backed lookup is available

Setup Flow

1. Flash release/firmware.bin.
2. On first boot, the device starts a setup AP:
   • SSID: PrintSphere-Setup
   • password: printsphere
3. Open http://192.168.4.1 and save your home Wi-Fi.
4. After the reboot, reopen Web Config on the device IP in your home network.
5. Hold anywhere on the display for about one second to request a Web Config PIN.
6. Enter the six-digit PIN in the browser.
   • PIN lifetime: about 2 minutes
   • unlocked browser session: about 10 minutes
7. Connect Bambu Cloud.
   • This is currently the expected real-world setup path.
   • Bambu email/password plus optional email code or 2FA code are supported.
8. Optionally connect the local printer path:
   • printer IP or hostname
   • printer serial number
   • access code

Cloud and local credentials can usually be applied live from Web Config without another reboot. Changing the connection mode itself still restarts the device.

Connection Modes

• Hybrid: Current default recommendation. PrintSphere tries to combine cloud and local data, picks the better active path at runtime, and still uses the local camera when available.
• Cloud only: Cloud monitoring and cover preview only. Local MQTT and the local camera page are disabled.
• Local only: Mainly a technical or experimental mode at the moment. The current end-user setup still assumes a working Bambu Cloud login, and the cloud cover page is not used in this mode.

Model Notes

• Cloud can now also carry progress, remaining time, layers, and temperatures on many models.
• In Hybrid, the current code prefers cloud status for P2S and the H2 family.
• The current code has local status paths for: A1, A1 Mini, P1P, P1S, X1, X1C, X1E
• P2S local status is not supported.
• The H2 family requires Developer Mode for local status.
• The local JPEG camera path is currently written for: A1, A1 Mini, P1P, P1S
• RTSP-style camera handling is recognized for: P2S, H2C, H2D, H2D Pro, H2S, X1, X1C, X1E but that path will not be implemented as the hardware is not capable of displaying video live feeds with more that 0.5fps.
• The code currently exposes chamber light control on supported P1S, P2, H2, and X1 models.

UI Overview

• Page 1: can show progress ring, lifecycle state, job name, temperatures, layers, remaining time, Wi-Fi, battery, and USB state
• Page 2: can show cloud cover preview and title
• Page 3: can show local camera snapshots when that path is working
• Long-press on the display: requests a Web Config PIN
• Tap on the camera page: requests a refresh of the current image
• Tap the center logo on page 1 on supported printers: requests a chamber light toggle

Web Config

Web Config currently exposes sections for:

• Step 1 - Wi-Fi
• Connection Mode
• Step 2 - Bambu Cloud
• Step 3 - Local Printer Path
• Arc Colors

Arc colors are intended to preview live immediately and can be saved without restarting the device.

Current Limitations

• current end-user setup still assumes a working Bambu Cloud login
• local camera and MJPEG/RTSP work are not fully finished yet
• cloud/local behavior on newer families still needs broader real-world validation
• P2S local status is not supported in the current code
• H2 local status requires Developer Mode
• local MQTT TLS now uses an embedded Bambu CA bundle
• most hands-on testing so far has been on P1S and P1P

Flashing

release/firmware.bin is the merged initial-flash image for empty devices.

The newest merged image stays in /release/; older versioned builds can be moved to /release/archive/.

Web Flashers

web.esphome.io https://web.esphome.io/

• connect USB
• choose the COM port
• do not use "Prepare for first use"
• install firmware.bin directly

espboards.dev https://www.espboards.dev/tools/program/

• write firmware.bin to address 0x0

esptool-js https://espressif.github.io/esptool-js/

• write firmware.bin to address 0x0

The bootloader is already included in the merged image.

Local Build / Flash

If you clone the repo and build it yourself:

idf.py -p PORT flash

Alternatively, write the merged image directly with esptool:

esptool.exe --chip esp32s3 --port PORT write_flash 0x0 release/firmware.bin