Installation Guide

Prerequisites

1. GNU ARM Embedded Toolchain

sudo apt update
sudo apt install cmake gcc-arm-none-eabi binutils-arm-none-eabi unzip build-essential

2. Pico SDK (2.1.1)

git clone https://github.com/raspberrypi/pico-sdk
cd pico-sdk
git submodule update --init
export PICO_SDK_PATH=/path/to/pico-sdk

Add PICO_SDK_PATH to your shell profile (e.g. ~/.bashrc).

3. Picotool (optional)

cd ~
git clone https://github.com/raspberrypi/picotool
cd picotool
mkdir build && cd build
cmake ..
make
sudo make install

Clone the Repository

git clone https://github.com/atrex66/stepper-ninja
cd stepper-ninja

Building with CMake

Step 1 — Create a build directory

cd firmware/
mkdir build && cd build

Step 2 — Configure CMake

Choose the command for your hardware combination:

Optional flags:

• Run from RAM after boot: add -DSTEPPER_NINJA_RUN_FROM_RAM=ON
• Legacy encoder PIO: prefix with CFLAGS='-Dencoder_pio_version=ENCODER_PIO_LEGACY'

Step 3 — Build

make

This generates stepper-ninja-picoX-W5XXX.uf2 (filename depends on CMake defines).

Flash the Pico

1. Hold BOOTSEL while plugging in USB to enter bootloader mode.
2. If reusing a pico with other firmware, first flash flash_nuke.uf2 to erase flash.
3. Copy stepper-ninja-picoX-W5XXX.uf2 to the mounted RPI-RP2 drive.
4. The Pico reboots and the firmware starts automatically.

W5500 Support

For a standard Pico with a W5500 module:

• Ensure the W5500 is properly wired (SPI pins, 3.3 V power).
• Use -DWIZCHIP_TYPE=W5500 in the CMake step.
• Optionally add -DSTEPPER_NINJA_RUN_FROM_RAM=ON for a RAM-executing build.

Pico2 Support

For a Pico2 with a W5500 module:

• Use -DBOARD=pico2 -DWIZCHIP_TYPE=W5500.
• Optionally add -DSTEPPER_NINJA_RUN_FROM_RAM=ON.

Installing the LinuxCNC HAL Driver

1. Install the driver

cd hal-driver
./install.sh

2. Create a HAL file (e.g. stepper-ninja.hal)

loadrt stepgen-ninja ip_address="192.168.0.177:8888"

addf stepgen-ninja.0.watchdog-process servo-thread
addf stepgen-ninja.0.process-send servo-thread
addf stepgen-ninja.0.process-recv servo-thread

net x-pos-cmd joint.0.motor-pos-cmd => stepgen-ninja.0.stepgen.0.command
net x-pos-fb stepgen-ninja.0.stepgen.0.feedback => joint.0.motor-pos-fb
net x-enable axis.0.amp-enable-out => stepgen-ninja.0.stepgen.0.enable

3. Update your INI file

[HAL]
HALFILE = stepper-ninja.hal

[EMC]
SERVO_PERIOD = 1000000

4. Run LinuxCNC

linuxcnc your_config.ini

Troubleshooting

CMake Error: PICO_SDK_PATH not found

export PICO_SDK_PATH=/path/to/pico-sdk

Missing pioasm / elf2uf2

cd pico-sdk/tools/pioasm
mkdir build && cd build
cmake .. && make

UTF-8 BOM Errors (e.g.  in linker output)

Use CMake ≥ 3.20.6 or add:

cmake -DCMAKE_UTF8_BOM=OFF ..

HAL Driver Errors

dmesg | grep stepgen-ninja

Community Notes

Thanks to the r/hobbycnc community (4.7k+ views!) for testing. Stepper-Ninja v1.0 is tagged as a stable release: v1.0 on GitHub.