Pilot CNC-shield rig

Build the canonical Arduino + V3 CNC shield + 2× NEMA-17 differential-drive rig

The cheapest stepper-driven mobile rig that completes the end-to-end OctoMY™ firmware flow. Arduino Uno, V3 CNC shield, two A4988 stepper drivers, two NEMA-17 motors. The personality file ships in tree at content/personalities/pilot-cnc-shield/; this howto walks through assembly, wiring, and the first drive.

Pro Tip

The rig is a desk-scale toy — full throttle gets you a few hundred mm/s on stiction-free surfaces. The goal isn't to drive a long way; it's to verify that intent-based control all the way from the Remote joystick down to the stepper-pulse output works on real hardware.

Before you start

An Arduino Uno.
A V3 CNC shield (the cheap blue PCB; any clone works).
Two A4988 stepper driver modules.
Two NEMA-17 bipolar stepper motors.
A 12 V power supply for the steppers (a 2 A bench supply is fine).
Optional: a small chassis with two wheels driven by the steppers. You can also bench-test without wheels — just watch the shafts spin.

Wiring

The V3 CNC shield's pin map maps onto the Uno like this:

Pin	Function	Wiring note
D2	X-step (left-drive)	Step pulse — one rising edge per step
D5	X-dir (left-drive)	LOW = forward, HIGH = reverse
D3	Y-step (right-drive)	Step pulse
D6	Y-dir (right-drive)	Direction line
D8	EN (steppers enable, active-low)	Tie to GND for unconditional enable
A0–A2	Limit switches	Optional — leave unconnected for this rig

Plug the two A4988 modules into the X and Y slots of the shield. Adjust the current trimmer on each driver until the motor body is warm but not hot at full step. (Stepper sizing is hand-set; rule of thumb: trimmer voltage ≈ rated current × 0.7 Ω.)

Connect the 12 V supply to the shield's +12V / GND screw terminals. Do not power the Uno from the 12 V supply — keep the Uno on USB or a separate 5 V supply; the shield's onboard regulator is unreliable above 1 A.

Tie the shield's EN pin to GND using the dedicated jumper. The differential-drive lobe doesn't currently drive EN; without this jumper the drivers stay disabled and the motors won't move.

Deploy the personality

Open the Hub.
Navigate to Deploy.
Pick the pilot-cnc-shield personality from the in-tree list.
The Hub builds the firmware for the uno board target — the CNC shield is a passive accessory, so no separate board entry is needed.
The flash step writes the AVR ELF to the Uno over USB via stk500v2 (or AVR109 on newer bootloaders).
After flash, the Agent's runtime advances to Running and opens the numex serial link.

Drive it from Remote

Open the Remote app.
Controller menu → Ground Drive.
The joystick maps:
- Vertical axis → intent:ground-drive-2d.forward ∈ [-1, +1].
- Horizontal axis → intent:ground-drive-2d.yaw ∈ [-1, +1].
The auto-mounted port bank below the joystick exposes the optional inputs:
- switch:parking_brake — toggle to hold position.
- axis:max_step_rate — slide to cap the per-side step rate (default 1500 steps/s).

Push the joystick forward — both motors should advance equally. Twist sideways — one motor goes forward, the other goes backward; the rig pivots.

Pro Tip — sign convention

yaw = +1 is a left turn (CCW from above). If your rig turns the wrong way when you push left on the joystick, swap the cable polarity on one motor or flip its direction in the Studio actuator config (reverse flag). The lobe always emits left-turn-for-positive-yaw; the actuator wiring decides what "left" means.

Hazards

A4988 EN jumper omitted — the drivers stay disabled. Symptom: motors silent, no holding torque. Fix: install the EN-to-GND jumper.
Step rate too high — stepper torque drops with rate; at 8000 steps/s on a NEMA-17 at 12 V you'll get stalls. Default max_step_rate = 1500 leaves margin. Lower if you stall; never blame the lobe.
No homing — the differential-drive lobe is open-loop. Position drifts session to session. For a repeatable position rig, add encoders and a different lobe (future work).
Shared ground reference — make sure the Uno's GND and the 12 V supply's GND are tied together. Floating grounds cause erratic step pulses.

What's next

Add a second channel and author scenes between them — see the Author scenes howto.
Swap NEMA-17 for NEMA-23 if you outgrow desk-scale and want more torque.
Plumb encoders for closed-loop control — separate spec, future work.

Configure Fixo Controller — the general flow this personality is a worked example of.
Channels reference — the channel model the differential-drive lobe rides on.
The in-tree personality file is at content/personalities/pilot-cnc-shield/ with a developer-facing README. The same content is here in user-facing form.