{"id":50745128,"url":"https://github.com/justinh-rahb/klipper-micro","last_synced_at":"2026-06-10T20:02:15.044Z","repository":{"id":361104513,"uuid":"1249458207","full_name":"justinh-rahb/klipper-micro","owner":"justinh-rahb","description":"A stripped-down Klipper host that runs on an ESP32 CYD (Cheap Yellow Display), driving a standard Klipper MCU.","archived":false,"fork":false,"pushed_at":"2026-05-29T06:54:45.000Z","size":67,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T08:30:55.126Z","etag":null,"topics":["cyd","esp32","klipper","micropython"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justinh-rahb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":"docs/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"buy_me_a_coffee":"wildtang3nt"}},"created_at":"2026-05-25T18:11:51.000Z","updated_at":"2026-05-29T06:54:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/justinh-rahb/klipper-micro","commit_stats":null,"previous_names":["justinh-rahb/klipper-micro"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/justinh-rahb/klipper-micro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinh-rahb%2Fklipper-micro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinh-rahb%2Fklipper-micro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinh-rahb%2Fklipper-micro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinh-rahb%2Fklipper-micro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justinh-rahb","download_url":"https://codeload.github.com/justinh-rahb/klipper-micro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinh-rahb%2Fklipper-micro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34168086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cyd","esp32","klipper","micropython"],"created_at":"2026-06-10T20:02:14.230Z","updated_at":"2026-06-10T20:02:15.033Z","avatar_url":"https://github.com/justinh-rahb.png","language":"Python","funding_links":["https://buymeacoffee.com/wildtang3nt","https://www.buymeacoffee.com/wildtang3nt"],"categories":[],"sub_categories":[],"readme":"# klipper-micro\n\nA stripped-down Klipper *host* that runs on an ESP32 CYD (Cheap Yellow\nDisplay), driving a standard Klipper MCU over UART. Built for appliance-style\nuse cases — filament dryers, chamber heaters, supplemental fan controllers —\nwhere running a full Raspberry Pi + Klippy + Moonraker stack is overkill.\n\nThe CYD provides a 2.8\" touchscreen UI; WiFi exposes a small HTTP API for\nremote control. The Klipper MCU on the other end of the UART line runs\nunmodified stock firmware.\n\n\u003e **Status: protocol layer and CYD UI firmware validated on real hardware.**\n\u003e Phase 1 (CPython tests, 18/18 passing against a mock MCU) and Phase 2\n\u003e (CYD bring-up with the pinned LVGL-enabled MicroPython image) are complete.\n\u003e USB serial transport added — connect to a real Klipper MCU from a laptop\n\u003e with `scripts/connect.py` before wiring to the CYD.\n\n## What it talks to\n\n| Layer | Software |\n|---|---|\n| Touch + web UI | klipper-micro (this repo), running on ESP32 CYD |\n| Klipper host protocol over UART | klipper-micro (this repo) |\n| Klipper MCU firmware | Stock `Klipper3d/klipper` build, target initially STM32 |\n\nThe protocol layer borrows directly from upstream Klipper via a git submodule\nat [`vendor/klipper`](vendor/klipper). `msgproto.py` and the clock-sync\nregression math are used as-is; the only piece we reimplement is the C\n`serialqueue` (which can't run on MicroPython) — see\n[`src/proto/queue.py`](src/proto/queue.py).\n\n## Repo layout\n\n```\nsrc/                MicroPython app — uploaded to the ESP32\n  proto/            Klipper host protocol (msgproto, transport, queue, handshake, clocksync)\n  devices/          Heater, fan, thermistor, safety  (Phase 3)\n  ui/               LVGL screens                      (Phase 4)\n  web/              HTTP API + dashboard              (Phase 5)\ntests/              CPython pytest suite + mock MCU\nvendor/klipper/     Pinned submodule of Klipper3d/klipper\nscripts/            sync_vendor.sh, flash.sh, upload.sh\ndocs/               Architecture, protocol, hardware, config\nexamples/           Reference JSON configs (filament dryer, chamber heater)\n```\n\n## Development\n\n```bash\ngit clone --recursive https://github.com/justinh-rahb/klipper-micro.git\ncd klipper-micro\n./scripts/sync_vendor.sh                            # copies msgproto.py + clocksync.py from vendor/klipper\npython3 -m venv .venv\n.venv/bin/pip install pytest pytest-asyncio mpremote pyserial\n.venv/bin/python -m pytest tests/ -v                # 18 tests against the mock MCU\n```\n\n### Bring up a real CYD\n\n```bash\n./scripts/flash.sh   /dev/tty.usbserial-3110         # erases + flashes the pinned LVGL CYD image + installs zlib/logging\n./scripts/upload.sh  /dev/tty.usbserial-3110         # pushes full app (boot.py, main.py, proto/, ui/) and resets board\n./scripts/selftest.sh /dev/tty.usbserial-3110        # runs device_selftest.py — 19 checks\n```\n\nAfter `upload.sh` completes the board soft-resets and the GUI starts automatically.\nOn every subsequent power-on MicroPython runs `boot.py` then `main.py` without\nany host involvement.\n\nThe default firmware comes from de-dh's CYD LVGL project and is downloaded on\ndemand into `firmware/cache/`. Use `MP_FIRMWARE_FLAVOR=stock` if you want the\nplain upstream ESP32 MicroPython image instead.\n\nRun the mock MCU and an interactive REPL against it:\n\n```bash\n.venv/bin/python tests/mock_mcu.py --port 5555 \u0026\n# then in Python:\n#   import asyncio\n#   from proto.handshake import connect\n#   from proto.transport import StreamTransport\n#   t = await StreamTransport.connect_tcp(\"127.0.0.1\", 5555)\n#   q, cs = await connect(t)\n```\n\n### Validate a real Klipper MCU over USB serial (no CYD needed)\n\nIf your Klipper MCU is connected over USB (CDC ACM), you can run the full\nhandshake from your laptop without touching the CYD:\n\n```bash\n# Linux\npython scripts/connect.py /dev/ttyACM0\n\n# macOS (USB-serial adapter or native USB MCU)\npython scripts/connect.py /dev/tty.usbmodem001\n\n# Windows\npython scripts/connect.py COM3\n\n# Print the MCU's get_config response too\npython scripts/connect.py /dev/ttyACM0 --query\n```\n\n`scripts/connect.py` uses `SerialTransport` (backed by pyserial) and runs the\nsame `connect()` handshake path as the on-device code.  If it succeeds the MCU\nis ready to be wired to the CYD's UART.\n\n**Transport classes at a glance:**\n\n| Class | When to use |\n|---|---|\n| `StreamTransport` | CPython tests, TCP connection to mock MCU |\n| `SerialTransport` | CPython + real MCU over USB serial (pyserial) |\n| `UartTransport` | MicroPython / ESP32 hardware UART (standard CYD) |\n| `UsbCdcTransport` | MicroPython on ESP32-S2/S3 or RP2040 native USB |\n\n[![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/wildtang3nt)\n\n## License\n\nSource files under `src/` are MIT-licensed (this project). `vendor/klipper/` is\nGPLv3, used in source form per its license; any redistribution of derived\nbinaries needs to respect that.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinh-rahb%2Fklipper-micro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinh-rahb%2Fklipper-micro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinh-rahb%2Fklipper-micro/lists"}