This project turns an ESP32 into a standalone Wi-Fi Host for a Mini-Plotter/CNC machine. It serves a full-featured web-based control interface directly from its flash memory (LittleFS) and acts as a bridge, relaying G-code commands from the browser to the machine via Serial (UART).
The project is divided into two main parts: the Firmware (C++ code running on the ESP32) and the Web Interface (HTML/JS/CSS stored in the data/ folder).
| File | Description |
|---|---|
esp32_host_firmware.ino |
The main Arduino sketch. It handles: • Wi-Fi AP: Creates the "Cutter-Link" hotspot. • Web Server: Serves the files from LittleFS (Port 80). • WebSockets: Manages real-time bi-directional communication (Port 81). • Serial Bridge: Forwards G-code to the plotter and sends replies back to the client. |
README.md |
This documentation file. |
This folder contains the Single Page Application (SPA) that runs in the browser.
| File | Role | Description |
|---|---|---|
index.html |
Structure | The main entry point. Defines the layout: Console panel (left) and Workspace/Preview panel (right). |
script.js |
Controller | The "Brain" of the app. It initializes the application, manages the global state (job queue, sending status), and orchestrates interactions between the UI, Connection, and File handlers. |
styles.css |
Styling | Defines the dark/light theme, layout (Flexbox), and responsive design for mobile and desktop. |
Connection.js |
Network | Manages the WebSocket connection. It handles auto-reconnection, parsing incoming JSON messages (ack, serial, error), and sending G-code commands. |
Console.js |
Logging | Controls the on-screen log output (the black scrolling box), displaying system status, errors, and sent commands with color-coding. |
FileHandler.js |
Input | Handles file drag-and-drop and selection. It automatically detects file types: • .gcode: Loaded directly. • .svg: Parsed, scaled to fit the bed (230x310mm), and converted to G-code. |
SvgConverter.js |
Logic | A powerful vector engine that converts SVG shapes (Rects, Circles, Paths, Bezier Curves) into G-code. It performs unit conversion, coordinate mapping, and curve flattening using Look-Up Tables (LUT). |
Tabs.js |
Navigation | Manages switching between the three main views: G-Code Preview, SVG Preview, and Editor, using CSS visibility toggles. |
UI.js |
Feedback | Updates visual elements like the Status Badge (Connected/Disconnected), "Start/Stop" button states, and the active user count. |
Viewer.js |
Graphics | Renders the G-code path onto an HTML5 Canvas. It visualizes: • Blue Lines: Cutting moves (G1). • Grey Dashed: Rapid moves (G0). • Orange Dots: Segment points. |
- Wi-Fi Access Point: Generates a standalone network ("Cutter-Link").
- No Internet Required: The entire app runs locally from the ESP32.
- Smart SVG Import: Automatically centers and scales SVG drawings to fit the machine bed.
- Real-time Visualization: See the G-code path rendered instantly on a canvas.
- Live Control: Manual command console and real-time job progress tracking.
- WebSocket Protocol: Low-latency communication for immediate machine response.
-
Hardware:
- ESP32 Development Board (e.g., ESP32 DevKit V1).
- USB Cable.
- CNC/Plotter connected to ESP32 Serial pins (TX/RX).
-
Software:
- VS Code with PlatformIO IDE Extension.
-
Open the Project:
- Open VS Code.
File>Open Folder> Selectesp32_host_firmware.
-
Upload Firmware (C++):
- Click the PlatformIO Alien Icon (sidebar).
Project Tasks>esp32dev>General> Upload.- (Hold BOOT button on ESP32 if "Connecting..." fails).
-
Upload Filesystem (Web App):
- This copies the
data/folder to the chip. Project Tasks>esp32dev>Platform> Upload Filesystem Image.
- This copies the
- Connect: Join the Wi-Fi network "Cutter-Link" (Password:
Qatar2026). - Launch: Open
http://192.168.4.1in your browser (or follow the Captive Portal). - Run:
- Drag & drop a
.gcodeor.svgfile. - Check the preview.
- Click Start Cutting.
- Drag & drop a
- "LittleFS Mount Failed": Run Upload Filesystem Image again.
- "Wrong boot mode": Hold the BOOT button while uploading.
- SVG looks wrong: Ensure your SVG uses standard shapes/paths and units. The converter approximates curves; extremely complex paths might need simplification in Inkscape first.
