Overview
Stepper-Ninja keeps matching configuration headers in two places:
firmware/inc/config.hhal-driver/config.h
In normal use, hal-driver/config.h should be a symlink to firmware/inc/config.h, not a separately maintained copy. If symlinks are missing, recreate them:
cd hal-driver
./make_symlinks.shWhich File Should You Edit?
Edit firmware/inc/config.h for Pico firmware behaviour. hal-driver/config.h should point to it as a symlink. Some values in footer.h are overridden automatically when breakout_board is not 0.
Network Defaults
These define the startup network configuration stored in flash until changed via the serial terminal.
| Define | Meaning |
|---|---|
DEFAULT_MAC | Default Ethernet MAC address |
DEFAULT_IP | Default static IP address |
DEFAULT_PORT | UDP port used by the HAL driver |
DEFAULT_GATEWAY | Default gateway |
DEFAULT_SUBNET | Default subnet mask |
DEFAULT_TIMEOUT | Communication timeout in microseconds |
Board Selection
breakout_board selects the hardware layout.
| Value | Meaning |
|---|---|
0 | Custom pin mapping from config.h |
1 | Stepper-Ninja breakout board |
2 | IO-Ninja breakout board |
3 | Analog-Ninja breakout board |
100 | BreakoutBoard100 |
When breakout_board > 0, footer.h replaces custom pin definitions with board-specific values.
Motion Channels
| Define | Meaning |
|---|---|
stepgens | Number of step-generator channels |
stepgen_steps | Step output pins |
stepgen_dirs | Direction output pins |
step_invert | Invert step outputs per channel |
encoders | Number of encoder channels |
enc_pins | First pin of each quadrature encoder pair (B is next GPIO) |
enc_index_pins | Index pins for encoders |
enc_index_active_level | Active level of each index input |
Pins defined as gpio if only using numbers eg:22, or use real pico pcb pin numbers by "pin_12"
Encoder Mode
| Define | Meaning |
|---|---|
ENCODER_PIO_LEGACY | Original quadrature counter PIO |
ENCODER_PIO_SUBSTEP | Newer substep-aware PIO (default) |
encoder_pio_version | Selects which PIO is compiled |
// Default — recommended
#define encoder_pio_version ENCODER_PIO_SUBSTEP
// Switch back to legacy
#define encoder_pio_version ENCODER_PIO_LEGACYOverride from the build command line:
CFLAGS='-Dencoder_pio_version=ENCODER_PIO_LEGACY' cmake -S firmware -B build -DWIZCHIP_TYPE=W5500Encoder velocity estimation is done in the HAL driver for legacy mode. In legacy mode, firmware sends per-cycle encoder count deltas; in substep mode, velocity calculated in pico and sent to HAL side.
Digital Inputs and Outputs
| Define | Meaning |
|---|---|
in_pins | Input GPIO list |
in_pullup | Enable pull-up per input |
out_pins | Output GPIO list |
These are used only in custom mode or where the selected breakout board does not override them.
PWM Options
| Define | Meaning |
|---|---|
use_pwm | Enables PWM support |
pwm_count | Number of PWM outputs |
pwm_pin | PWM output pins |
pwm_invert | Invert PWM per channel |
default_pwm_frequency | Default PWM frequency |
default_pwm_maxscale | HAL scaling limit |
default_pwm_min_limit | Minimum PWM output limit |
Set use_pwm to 1 only when channel count and pins are valid for your board.
Raspberry Pi SPI Mode
| Define | Meaning |
|---|---|
raspberry_pi_spi | Use SPI link to Raspberry Pi instead of Wiznet Ethernet |
raspi_int_out | Interrupt/status pin toward Raspberry Pi |
raspi_inputs | Raspberry Pi visible inputs |
raspi_input_pullups | Pull-up setting for those inputs |
raspi_outputs | Raspberry Pi controlled outputs |
When raspberry_pi_spi is 0, the firmware uses the Wiznet Ethernet path.
Timing Defaults
| Define | Meaning |
|---|---|
default_pulse_width | Default step pulse width in nanoseconds |
default_step_scale | Default steps per unit |
use_timer_interrupt | Enables step command ring buffer and timer-driven step output |
use_timer_interrupt buffers step commands and can reduce visible PC-to-Pico jitter.
Footer-Controlled Defines
These live in footer.h and depend on the selected board or platform. Do not change casually.
| Define | Meaning |
|---|---|
use_stepcounter | Uses step counter instead of the quadrature encoder path |
debug_mode | Extra debug behaviour for Raspberry Pi communication |
max_statemachines | Derived total PIO state machine count |
pico_clock | Pico system clock used by the firmware |
Build-Time Options (CMake)
| Option | Meaning |
|---|---|
-DWIZCHIP_TYPE=W5100S | Build for W5100S |
-DWIZCHIP_TYPE=W5500 | Build for W5500 |
-DBOARD=pico | Build for Pico |
-DBOARD=pico2 | Build for Pico2 |
-DSTEPPER_NINJA_RUN_FROM_RAM=ON | Copy firmware to SRAM before execution |
Full example:
cmake -S firmware -B build -DBOARD=pico2 -DWIZCHIP_TYPE=W5500 -DSTEPPER_NINJA_RUN_FROM_RAM=ONRecommended Workflow
- Select the board with
breakout_board. - Set
stepgens,encoders, and pin lists if using custom mode. - Choose
encoder_pio_version. - Enable PWM only if your hardware uses it.
- Keep firmware and HAL driver config files aligned via the symlink.
- Build firmware and HAL driver after every meaningful config change.
For network settings changed at runtime, see the IP Configuration Guide.