An open-source firmware and setup guide for running an EggBot-style drawing robot using an Arduino Uno (or clone) with a CNC Shield V3 and A4988 stepper drivers.

This project is specifically aimed at owners of the inexpensive Chinese "LY EggDraw" kits sold on AliExpress/eBay that ship with minimal or Chinese-only documentation. The firmware emulates the EBB (EiBotBoard) protocol, so it works with the standard Inkscape EggBot extensions.

Hardware Requirements

CNC Shield Pin Mapping

CNC Shield V3 Header → Arduino Pin → Function
─────────────────────────────────────────────────
X_STEP                  D2            Egg rotation motor — step
X_DIR                   D5            Egg rotation motor — direction
Y_STEP                  D3            Pen arm motor — step
Y_DIR                   D6            Pen arm motor — direction
EN                      D8            Motor enable (shared, active LOW)
SpnEn                   D12           Pen lift servo signal
SpnDir                  D13           Engraver output (optional)
Abort                   A0            PRG button (optional)
Hold                    A1            Pen toggle button (optional)
Resume                  A2            Motor enable button (optional)

Important: The servo MUST connect to the SpnEn header (pin 12). Do NOT use pin 4 — that's Z_STEP on the CNC Shield and will not work. Many EggDuino firmware versions online default to pin 4, which is the #1 reason these kits don't work with a CNC Shield.

Microstepping Jumpers

Install all three jumper caps under each A4988 module on the CNC Shield to enable 1/16 microstepping (3200 steps per revolution). This is required — the EBB protocol and Inkscape plugin assume 16× microstepping.

MS1  MS2  MS3    Mode
─────────────────────
 ■    ■    ■     1/16 step  ← install all three

Features

• EBB Protocol Emulation — compatible with standard EggBot Inkscape extensions
• CNC Shield V3 pin mapping — servo on SpnEn (D12), motors on X/Y slots
• Motor auto-timeout — stepper motors automatically disable after 60 seconds of inactivity to prevent overheating (configurable in config.h)
• CH340 support — patched Inkscape extensions detect CH340 USB-serial adapters
• 156 example SVGs — holidays, geometric patterns, TSP art, and more
• Diagnostic tool — Python script to verify hardware before using Inkscape

Quick Start

0. Assemble Hardware

See docs/hardware-assembly.md for complete assembly instructions including A4988 orientation, microstepping jumpers, servo wiring, and current limit tuning.

1. Upload Firmware

Arduino IDE:

1. Open firmware/EggDuino/EggDuino.ino
2. Select Tools → Board → Arduino Uno
3. Select the correct COM port
4. Click Upload

PlatformIO:

cd firmware/EggDuino
pio run --target upload

2. Run Diagnostics

Before touching Inkscape, verify everything works at the hardware level:

pip install pyserial
python diagnostics/diagnostics.py

This tests firmware communication, servo movement, and both stepper motors one at a time. You can also use interactive mode to send individual EBB commands:

python diagnostics/diagnostics.py --shell

3. Install Inkscape Extensions

See docs/inkscape-setup.md for detailed instructions.

Troubleshooting

See docs/troubleshooting.md for common issues and solutions.

Firmware Configuration

Key settings in firmware/EggDuino/config.h:

Project Structure

eggduino-cnc-shield/
├── firmware/EggDuino/    Arduino firmware (EBB protocol emulation)
├── diagnostics/          Serial diagnostic and testing tools
├── inkscape-extensions/  Patched Inkscape extension files
├── templates/            SVG templates for test plots
└── docs/                 Setup guides and troubleshooting

Credits & Acknowledgments

This project stands on the shoulders of several open-source projects and their authors. Thank you to everyone who shared their work:

• Evil Mad Scientist Laboratories — creators of the original EggBot and the EBB protocol. The Inkscape EggBot extensions and plotink libraries (ebb_serial.py, ebb_motion.py, plot_utils.py) are their work, adapted here for CH340 USB-serial boards.

• cocktailyogi — the original EggDuino firmware that proved an Arduino could emulate the EBB protocol and work with the standard Inkscape extensions.

• papabricole — refactored the EggDuino firmware into the clean modular architecture (EBBParser / EBBHardware) that this project's firmware is based on.

• Michael Margolis, Korman, and Philip van Allen — the VarSpeedServo library (LGPL 2.1+) bundled in the firmware for variable-speed pen lift control.

• drzejkopf — Thingiverse build guide documenting CNC Shield V3 servo wiring (SpnEn header + separate 5V tap) that helped us get the hardware working.

• LangdalP/plotcontrol — Python-based AxiDraw/EggBot controller, useful reference for alternative host software.

License

This project is licensed under the GNU General Public License v2 or later (GPL-2.0-or-later). See LICENSE for full details and per-component attribution.

The GPL was chosen to match the upstream Inkscape EggBot extensions. In short: you are free to use, modify, and share this project, as long as you share your changes under the same license.