This project is published for educational and demonstration purposes only. It is not a production CNC pendant. It has not been validated for safety, reliability, or fitness for any purpose. DO NOT use it to control a real CNC machine — milling, lathe, laser, plasma, router, or otherwise.
CNC machines are dangerous. They can injure you, others, or damage equipment and material if commands are sent incorrectly, are ignored, or arrive out of order. This pendant offers no safety guarantees: commands can be dropped, rejected, delayed, or executed in unexpected sequences. The on-screen "E-STOP" button is not a substitute for a hardware emergency stop.
If you build, flash, or modify this code, you do so entirely at your own risk. The authors and contributors accept no liability for any damage, injury, loss, or other consequences arising from its use or misuse.
For real CNC control, use FluidNC's official tools and a properly engineered physical e-stop circuit wired directly to your controller.
A touch-screen control panel for FluidNC CNC controllers. Mount it on the side of your CNC machine and use it to home the spindle, jog the axes, start a job, set work coordinates, run macros, and watch what the machine is doing — all without reaching for a laptop.
Hardware: Waveshare ESP32-P4 WiFi6 Touch LCD 7B — 7-inch 1024×600 capacitive touch panel with an ESP32-P4 main chip and an ESP32-C6 WiFi co-processor. Firmware: ESP-IDF 5.5.x · LVGL 8.4 · UI authored in EEZ Studio.
- Flash the firmware — see docs/06-building-and-flashing.md.
- On first boot the pendant scans for WiFi networks — pick yours, enter the password.
- Open Settings → Machine → "Configure FluidNC Connection" — type your controller's hostname or IP, pick WebSocket for wireless or UART for wired.
- Tap Connect and the pendant lands on the Dashboard with live machine readouts.
Full documentation lives in docs/. Start with docs/README.md for a guided tour.
| If you want to… | Read |
|---|---|
| Understand what the pendant does and who it's for | 01-overview.md |
| Get the pendant onto WiFi and talking to your CNC | 02-getting-started.md |
| Know what every screen does | 03-screen-tour.md |
| Understand how it talks to FluidNC under the hood | 04-how-it-talks-to-fluidnc.md |
| Read the code — what lives where | 05-architecture.md |
| Build and flash the firmware | 06-building-and-flashing.md |
| Change colors, add screens, or modify behavior | 07-customizing.md |
| Fix something that's not working | 08-troubleshooting.md |
| Path | Purpose |
|---|---|
| main/ | Application code — state machine, action handlers, variable bridge |
| main/ui/ | UI generated by EEZ Studio — never edit by hand |
| GUI/ | EEZ Studio project file (.eez-project) — source of truth for the UI |
| components/fluidnc/ | FluidNC protocol — WebSocket / UART transports, grbl parser, dispatcher |
| components/wifi_setup/ | WiFi scan + connect via the ESP32-C6 co-processor |
| components/pendant_config/ | Persistent settings stored in NVS (flash) |
| assets/ | Source images, fonts, icons referenced by the EEZ Studio project |
sdkconfig.defaults |
Pinned project config — edit here, never sdkconfig |
- ✅ All UI screens render and respond to touch
- ✅ Real FluidNC protocol backend (WebSocket + UART), grbl status parser
- ✅ WiFi setup and auto-reconnect via ESP-Hosted to the ESP32-C6
- ✅ Persistent settings (WiFi creds, host, port, units, brightness, theme)
- ✅ Mock backend selectable via
idf.py menuconfigfor bench testing - 🟡 Probe cycles 1–3 (corner / center / tool length) — only Z touch-off implemented
- 🟡 Pagination for SD listings > 6 files