-
Notifications
You must be signed in to change notification settings - Fork 46
Add BigTreeTech Knomi v2 board support #41
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
30 changes: 30 additions & 0 deletions
NOTICE.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| # Notice / Attribution | ||
|
|
||
| This repository is a **derivative** of [PrintSphere](https://github.com/cptkirki/PrintSphere) | ||
| by [cptkirki](https://github.com/cptkirki) (Cpt_Kirk). | ||
|
|
||
| Upstream project: | ||
| - Source: https://github.com/cptkirki/PrintSphere | ||
| - License: Federation Non-Commercial License (FNCL) v1.1 (see `LICENSE`) | ||
| - Copyright (c) 2026 Cpt_Kirk | ||
|
|
||
| ## Changes in this fork | ||
|
|
||
| Relative to upstream PrintSphere, this tree adds or extends: | ||
|
|
||
| - BigTreeTech **Knomi v2** hardware support (GC9A01 + CST816S BSP, board config, build variant) | ||
| - Knomi-oriented UI layout (compact AMS, preview, fonts, humidity pill) | ||
| - Display rotation via GC9A01 MADCTL (SPI / `OTHER` panel path) | ||
| - HMS / error-lookup fix for UTF-8 BOM in the embedded TSV | ||
| - Packaging and flash paths for the `knomi_v2` release variant | ||
|
|
||
| Unmodified upstream behavior for Waveshare AMOLED 1.75 and LCD 2.8C is intended to remain available via the existing `PRINTSPHERE_HW_VARIANT` builds. | ||
|
|
||
| ## License obligations | ||
|
|
||
| When you share this software (modified or not), the FNCL requires that you: | ||
|
|
||
| 1. Keep the `LICENSE` text and copyright notice. | ||
| 2. Clearly mark that the software was changed and briefly describe the changes (this file). | ||
|
|
||
| Commercial use requires a separate license from the copyright holder. |
154 changes: 63 additions & 91 deletions
README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,133 +1,105 @@ | ||
| # PrintSphere | ||
| # PrintSphere (Knomi & Waveshare) | ||
|
|
||
| PrintSphere is a round ESP32-S3 companion display for Bambu Lab printers. It shows print progress, temperatures, remaining time, AMS information, errors, cover previews and supported camera snapshots. | ||
| Round ESP32-S3 companion display for Bambu Lab printers — print progress, temperatures, remaining time, AMS, errors, cover previews, and supported camera snapshots. | ||
|
|
||
| It works directly with Bambu Cloud, the printer's local connection, or both. Home Assistant is not required. | ||
| Works with **Bambu Cloud**, the printer’s **local** connection, or both. Home Assistant is not required. | ||
|
|
||
| <img width="400" height="300" alt="PrintSphere AMOLED display" src="https://github.com/user-attachments/assets/820c2e9b-10a7-4430-949c-e8b0adc1357d" /> <img width="400" height="300" alt="PrintSphere interface" src="https://github.com/user-attachments/assets/5923dc59-0123-4df1-b54d-673c6dbad23b" /> | ||
| > **Based on [PrintSphere by cptkirki](https://github.com/cptkirki/PrintSphere).** | ||
| > This repository is a derivative under the [Federation Non-Commercial License (FNCL) v1.1](LICENSE). | ||
| > See [NOTICE.md](NOTICE.md) for attribution and a summary of changes (notably **BigTreeTech Knomi v2** support). | ||
|
|
||
| Latest stable version: **v1.6.2** | ||
| Latest packaged line: **v1.6.2** (+ Knomi v2 variant) | ||
|
|
||
| ## Supported hardware | ||
|
|
||
| Choose the correct hardware in the installer: | ||
|
|
||
| | Hardware | Installer name | Battery support | | ||
| | Hardware | Variant id | Battery | | ||
| | --- | --- | --- | | ||
| | Waveshare ESP32-S3 Touch AMOLED 1.75 | `1.75 AMOLED` | Yes, including charging and USB detection | | ||
| | Waveshare ESP32-S3 Touch LCD 2.8C | `2.8" LCD` | Yes, using the board's battery measurement | | ||
| | Waveshare ESP32-S3 Touch AMOLED 1.75 | `amoled_1_75` | Yes (charging / USB detection) | | ||
| | Waveshare ESP32-S3 Touch LCD 2.8C | `lcd_2_8c` | Yes (board measurement) | | ||
| | BigTreeTech Knomi v2 | `knomi_v2` | No (USB/DC); dim / screen-off still apply | | ||
|
|
||
| Firmware for one variant must not be installed on the other variant. | ||
| Flash **only** the firmware built for your board. Variants are not interchangeable. | ||
|
|
||
| ## Install PrintSphere | ||
| ## Install | ||
|
|
||
| You need a USB data cable and a desktop version of Chrome or Edge. | ||
| You need a USB data cable and desktop Chrome or Edge. | ||
|
|
||
| 1. Open the **[PrintSphere Web Installer](https://cptkirki.github.io/PrintSphere/flash/)**. | ||
| 1. Open the **Web Installer** for this fork (GitHub Pages / Releases — see below). | ||
| 2. Select your hardware variant. | ||
| 3. Connect the device by USB and choose **Install selected firmware**. | ||
| 4. Keep the USB cable connected after installation. | ||
| 5. The installer searches for nearby Wi-Fi networks and sends your Wi-Fi details directly to PrintSphere over USB. | ||
| 6. Open Web Config using the IP address shown by PrintSphere and connect your Bambu printer. | ||
| 3. Connect the device and install the matching full image. | ||
| 4. Keep USB connected so Wi‐Fi can be provisioned over serial. | ||
| 5. Open **Web Config** on the IP shown on the display and connect your printer. | ||
|
|
||
| ### Wi-Fi fallback | ||
| Upstream installer (original project): [cptkirki Web Installer](https://cptkirki.github.io/PrintSphere/flash/) | ||
|
|
||
| If USB Wi-Fi setup is unavailable, connect to the fallback access point: | ||
| ### Wi‐Fi fallback | ||
|
|
||
| - Wi-Fi name: `PrintSphere-Setup` | ||
| - SSID: `PrintSphere-Setup` | ||
| - Password: `printsphere` | ||
| - Setup page: [http://192.168.4.1](http://192.168.4.1) | ||
|
|
||
| Select your home Wi-Fi there. After PrintSphere connects, continue through Web Config on its home-network IP address. | ||
| - Setup: [http://192.168.4.1](http://192.168.4.1) | ||
|
|
||
| ## Connect your printer | ||
|
|
||
| Web Config offers three connection modes: | ||
|
|
||
| - **Hybrid (recommended):** combines cloud and local data and automatically uses the better status path. Local camera snapshots remain available on supported printers. | ||
| - **Cloud only:** uses Bambu Cloud for status and cover previews. Local MQTT and local camera snapshots are disabled. | ||
| - **Local only:** connects directly to the printer without requiring a Bambu Cloud account. Cloud cover previews are unavailable. | ||
|
|
||
| For Bambu Cloud, enter your account details and complete an email-code or 2FA step if requested. | ||
|
|
||
| For a local connection, enter: | ||
|
|
||
| - Printer IP address or hostname | ||
| - Printer serial number | ||
| - Printer access code | ||
|
|
||
| Cloud and local printer settings can normally be connected without restarting PrintSphere. | ||
|
|
||
| ## Update without losing your settings | ||
| Web Config modes: | ||
|
|
||
| Use an **OTA update** for an already configured PrintSphere. OTA keeps Wi-Fi, printer profiles and display settings. | ||
| - **Hybrid (recommended)** — cloud + local; picks the better status path; local JPEG camera when supported | ||
| - **Cloud only** — Bambu Cloud status & covers; no local MQTT / local camera | ||
| - **Local only** — direct printer MQTT; no cloud covers | ||
|
|
||
| 1. Open the [PrintSphere Web Installer](https://cptkirki.github.io/PrintSphere/flash/). | ||
| 2. Select the same hardware variant currently installed on your device. | ||
| 3. In **OTA Update**, enter the IP address shown by PrintSphere. | ||
| 4. Open the OTA updater and confirm **Flash from URL** in Web Config. | ||
| Local connection needs printer IP/hostname, serial, and access code. | ||
|
|
||
| You can also open Web Config directly and use its **Firmware Update** section. It accepts either a matching OTA `.bin` file or a GitHub firmware URL. | ||
| ## Updates (OTA) | ||
|
|
||
| The public installer performs the initial USB flash. OTA itself runs through Web Config so the firmware can safely update the inactive application slot and retain the configuration. | ||
| Use an **OTA** image so Wi‐Fi and printer settings stay in NVS. | ||
|
|
||
| > Devices running v1.5.x or older need one initial USB flash before using v1.6.x OTA images because v1.6 introduced a new partition layout. | ||
| 1. Install or download the matching `printsphere_ota-*.bin` from [Releases](../../releases). | ||
| 2. In Web Config → Firmware Update, flash from file or URL. | ||
|
|
||
| ## Main features | ||
| Full USB images (`printsphere_full-*.bin`) are for first install or recovery. | ||
|
|
||
| - Print progress, remaining time, layers and temperatures | ||
| - AMS and external-spool information | ||
| - Cloud cover preview and project title | ||
| - Local JPEG camera snapshots on supported printers | ||
| - Pause, resume and stop controls | ||
| - Chamber-light control on supported printers | ||
| - Multi-printer profiles and live printer switching | ||
| - Bambu HMS and error descriptions on the device | ||
| - Adjustable display rotation and status colors | ||
| - Battery-aware dimming and screen-off settings | ||
| - Configurable sound notifications and custom WAV files | ||
| - Secure Web Config access using a temporary PIN | ||
| - OTA firmware updates that retain the device configuration | ||
| ## What’s in the box (features) | ||
|
|
||
| ## Printer and camera support | ||
| - Progress, remaining time, layers, nozzle/bed temps | ||
| - AMS + external spool | ||
| - Cloud cover + job title | ||
| - Local JPEG camera on supported models (A1 / A1 Mini / A2L / P1P / P1S) | ||
| - Chamber light on supported models | ||
| - Multi-printer profiles | ||
| - HMS / print-error text from the embedded lookup table | ||
| - Display rotation, status colors, sounds, portal PIN | ||
| - Battery-aware power policy on Waveshare boards | ||
|
|
||
| PrintSphere contains status paths for: | ||
| ## Printer notes | ||
|
|
||
| Status paths exist for: | ||
| `A1`, `A1 Mini`, `A2L`, `P1P`, `P1S`, `P2S`, `H2C`, `H2D`, `H2D Pro`, `H2S`, `X1`, `X1C`, `X1E`, `X2D` | ||
|
|
||
| Local JPEG snapshots are available on `A1`, `A1 Mini`, `A2L`, `P1P` and `P1S`. | ||
| RTSP cameras (X1 / H2 / P2S / X2D families) are **not** shown as live video on ESP32-S3. Cloud covers can still appear. | ||
|
|
||
| `P2S`, the `H2` family, the `X1` family and `X2D` use RTSP video. The ESP32-S3 cannot decode these streams, so their live camera view is not available in PrintSphere. Cloud cover previews can still be shown. | ||
| ## Build from source | ||
|
|
||
| The `H2` family and `X2D` require Developer Mode for local printer status. Availability of individual values can differ between printer models and firmware versions. | ||
| ESP-IDF **v5.5.4**, Windows or Linux. See [docs/Build/README.md](docs/Build/README.md). | ||
|
|
||
| ## Web Config | ||
| ```bash | ||
| # Example: Knomi v2 | ||
| idf.py -B build-knomi_v2 -DPRINTSPHERE_HW_VARIANT=knomi_v2 -p COMx build flash | ||
| ``` | ||
|
|
||
| Web Config includes: | ||
| ## Releases | ||
|
|
||
| - Wi-Fi scanning and configuration | ||
| - Cloud and local printer connections | ||
| - Connection mode and printer selection | ||
| - Display rotation, colors and time zone | ||
| - Battery, USB and screen power-saving options | ||
| - AMS display behavior | ||
| - Sound notification settings | ||
| - Portal PIN protection | ||
| - Firmware updates by file upload or URL | ||
| GitHub Releases publish: | ||
|
|
||
| After initial setup, Web Config can be protected with a temporary six-digit PIN. Long-press the PrintSphere display for about one second to request a PIN. | ||
| | File | Use | | ||
| | --- | --- | | ||
| | `printsphere_full-*-knomi_v2.bin` | USB first flash / recovery (Knomi) | | ||
| | `printsphere_ota-*-knomi_v2.bin` | OTA (Knomi) | | ||
| | `printsphere_full-*-2.8c.bin` / `...-amoled...` | Waveshare variants when packaged | | ||
|
|
||
| ## Known limitations | ||
| ## Credits | ||
|
|
||
| - RTSP camera streams cannot be displayed on the ESP32-S3. | ||
| - Newer printer families have received less real-world testing than `P1S` and `P1P`. | ||
| - Some local V2 protocol values can differ from the older V1 printer fields. | ||
| - Cloud features require internet access and a working Bambu Cloud account. | ||
| - **Upstream:** [cptkirki/PrintSphere](https://github.com/cptkirki/PrintSphere) — core firmware, Web Config, cloud/local paths, Waveshare BSPs | ||
| - **This fork:** Knomi v2 port, layout fixes, rotation/HMS fixes — see [NOTICE.md](NOTICE.md) | ||
|
|
||
| ## Links | ||
| ## License | ||
|
|
||
| - [PrintSphere Web Installer](https://cptkirki.github.io/PrintSphere/flash/) | ||
| - [MakerWorld model](https://makerworld.com/de/models/2517189-printsphere-bambu-status-display-standalone-1-75) | ||
| - [v1.6.2 release notes](release/RELEASE_NOTES_v1.6.2.md) | ||
| - [Building, cloning and manual flashing](docs/Build/README.md) | ||
| - [License](LICENSE) | ||
| [Federation Non-Commercial License (FNCL) v1.1](LICENSE) — non-commercial use; keep license + mark modifications. Commercial use needs a separate license from the copyright holder. |
18 changes: 18 additions & 0 deletions
components/btt_knomi_v2/CMakeLists.txt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| idf_component_register( | ||
| SRCS | ||
| "btt_knomi_v2.c" | ||
| INCLUDE_DIRS | ||
| "include" | ||
| "include/bsp" | ||
| REQUIRES | ||
| driver | ||
| esp_driver_gpio | ||
| esp_driver_i2c | ||
| esp_driver_spi | ||
| esp_lcd | ||
| esp_lcd_gc9a01 | ||
| esp_lcd_touch | ||
| esp_lcd_touch_cst816s | ||
| esp_lvgl_adapter | ||
| esp_codec_dev | ||
| ) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.