Defaults and Profile Configuration

grblHAL uses a layered default system. This document covers:

• DEFAULT_ symbols — compile-time defaults in config.h that set initial values for every $ setting
• Profile configuration symbols — compile-time defines in my_machine.h that select hardware features, spindle types, motor count, ganging, and more
• Machine profiles — pre-baked $ setting overrides used by the web builder and gsender

1. The Defaults Precedence Chain

Values are resolved in this order (last wins):

The DEFAULT_ symbols are baked into the firmware binary. After flashing, the runtime values are written to EEPROM (emulated in flash or FRAM). A $RST=* command restores a group of settings to their DEFAULT_ values.

2. Profile Configuration Symbols

These are #define statements placed in my_machine.h (or platformio.ini as -D flags) that select the machine's hardware capabilities at compile time. They are not $ settings — they control which code paths are compiled and which driver modules are linked.

Motor / Axis

Spindle Selection

Spindle type is selected by SPINDLE0_ENABLE through SPINDLE3_ENABLE. Each takes an integer constant from the spindle_control.h enum:

Convenience bitmasks:

#define SPINDLE_ALL_VFD ((1<<SPINDLE_HUANYANG1)|(1<<SPINDLE_HUANYANG2)|(1<<SPINDLE_GS20)|(1<<SPINDLE_YL620A)|(1<<SPINDLE_MODVFD)|(1<<SPINDLE_H100)|(1<<SPINDLE_NOWFOREVER))
#define SPINDLE_ALL      (SPINDLE_ALL_VFD|(1<<SPINDLE_PWM0))

These bitmasks serve two purposes:

1. In raw C code (driver_opts.h): gates compilation of VFD plugin code:

#if SPINDLE_ENABLE & SPINDLE_ALL_VFD
#define VFD_ENABLE 1
#endif

2. As SPINDLE0_ENABLE value: SPINDLE_ALL_VFD or SPINDLE_ALL can be used in any context — #define in my_machine.h, -D in platformio.ini, or the web builder profile. The firmware registers all VFD types (or all VFDs + PWM0) at runtime, with the first available spindle as the default.

All valid SPINDLE0_ENABLE values:

How SPINDLE0_ENABLE is set in each context:

Symbol reference:

Trinamic Stepper Drivers

Network

Features (Enable Flags)

CoreXY / Kinematics

Rotary Axis

3. Complete DEFAULT_ Reference by $ Setting

Each entry shows the DEFAULT_ symbol, its $ setting number, the type/range, factory default, and a brief description.

Stepper Output ($0–$4, $8, $29, $37, $680)

Limits ($5, $18, $20–$21)

$21 bit flags:

• Bit 0: Enable hard limits
• Bit 1: Check limits at initialization
• Bit 2: Disable hard limits for rotary axes

Homing ($22–$27, $43–$49, $671, $347–$349)

$22 bit flags:

• Bit 0: Enable homing
• Bit 1: Enable single-axis homing commands ($HX, $HY, etc.)
• Bit 2: Force alarm state on startup (require homing)
• Bit 3: Set machine origin at homed location
• Bit 5: Allow setting home position with $-commands
• Bit 6: Allow soft reset to override init lock
• Bit 8: Force using limit switches for homing
• Bit 10: Run startup scripts only when homed

Spindle – Primary ($9, $16, $30–$36, $38, $80–$85, $340, $394, $395, $539)

$9 bit flags:

• Bit 1: Disable spindle enable at zero speed
• Bit 2: Disable laser mode on PWM spindle
• Bit 3: Enable PWM ramping
• Bit 4: Ignore spindle on/off delays

$16 bit flags:

• Bit 0: Invert spindle enable pin
• Bit 1: Invert spindle direction (CCW) pin
• Bit 2: Invert spindle PWM pin

Spindle – Second ($709, $716, $730–$736)

$709 and $716 use the same bit assignments as $9 and $16 respectively.

Coolant ($15, $673)

$15 bits: bit 0 = coolant flood, bit 1 = coolant mist.

Tool Change ($341–$346, $485)

$346 bits: bit 0 = don't restore position, bit 1 = tool change at G30, bit 2 = fast probe pull-off.

Probing ($6, $19, $65)

$6 bits: bit 0 = probe, bit 1 = toolsetter. $19 bits: bit 0 = probe, bit 1 = toolsetter. $65 bits: bit 0 = allow feed override during probe, bit 1 = soft limits during probe.

Status Report ($10)

$10 bits:

• Bit 0: Report machine position (MPos)
• Bit 1: Report buffer state (Bf)
• Bit 2: Report line numbers (Ln)
• Bit 3: Report feed and speed (FS)
• Bit 4: Report pin state (Pn)
• Bit 5: Report work coordinate offset (WCO)
• Bit 6: Report overrides
• Bit 7: Report probe coordinates
• Bit 8: Sync planner on WCO change
• Bit 9: Auto-report parser state (default: off)
• Bit 10: Report alarm substate (default: off)
• Bit 11: Report run substate (default: off)
• Bit 12: Report while homing (default: off)
• Bit 13: Report distance to go (default: off)

Motion Planning ($11, $12, $28, $32)

Jogging ($40)

Parking and Safety Door ($41, $42, $56–$61, $392, $393)

$41 bits: bit 0 = enable parking, bit 1 = deactivate upon init, bit 2 = enable parking override control. $61 bits: bit 0 = ignore door when idle, bit 1 = keep coolant on when door open.

Control Signals ($14, $17)

$14/17 bit assignments: bit 0 = Reset, bit 1 = Feed Hold, bit 2 = Cycle Start, bit 3 = Safety Door, bit 4 = Block Delete, bit 5 = Single Block, bit 6 = Motor Fault, bit 7 = Motor Warning, bit 8 = E-Stop, bit 9 = Probe, bit 10 = Probe 2, bit 11 = Tool Setter, bit 12 = Stop Disable, bit 13 = Limits Override, bit 14 = Macro 0, bit 15 = Macro 1.

Motor Fault/Warning ($742–$745)

Filesystem ($650)

$650 bits: bit 0 = auto-mount SD, bit 1 = hide LittleFS from listings, bit 2 = hierarchical listing.

Rotary Axes ($376, $538)

RGB / NeoPixel ($536, $537)

ModBus ($374, $681)

$374 baud rate mapping: 0=9600, 1=14400, 2=19200, 3=38400.

Reset Actions ($676)

$676 bits: bit 0 = keep homed status, bit 1 = keep offsets, bit 2 = keep rapids override, bit 3 = keep feed override.

Per-Axis Settings ($100–$199, $800+)

Each axis (X, Y, Z, A, B, C...) has a block of settings at a base offset:

For axis Y, add 1 to each offset; Z +2, A +3, B +4, C +5, U +6, V +7, W +8.

Spindle Linearization ($66–$69, plugin)

These are only available when ENABLE_SPINDLE_LINEARIZATION is defined:

Miscellaneous ($13, $39, $62, $63, $64, $384, $398, $481, $482, $484)

$63 bits: bit 0 = disable laser during hold, bit 1 = restore spindle/coolant after hold.

4. Network Defaults (driver_opts.h)

Network configuration defaults are defined in driver_opts.h, not as DEFAULT_ symbols. They are compile-time values used when the network stack initializes.

5. Machine Profiles

Machine profiles bundle a complete machine configuration (compile-time symbols + setting overrides) for a specific machine model. Two systems ship them:

• Web builder — JSON profiles with default_symbols (compiler defines) and setting_defaults (DEFAULT_ overrides)
• gsender client — JavaScript modules exporting { $key: value } EEPROM setting objects

Web Builder Profiles

Profiles live in the grblhal-profiles repository (e.g. profiles/altmill.json). Each profile has two sections:

• default_symbols — compile-time defines (N_AXIS, SPINDLE0_ENABLE, N_TOOLS, etc.)
• setting_defaults — DEFAULT_* symbol overrides baked into the firmware binary

Web builder profile values are stored as JSON strings or numbers and are translated to C defines by the builder's code generator. For example, "SPINDLE0_ENABLE": "SPINDLE_ALL_VFD" causes the generator to emit multiple C defines that register all VFD spindle types.

gsender Client Profiles

gsender ships per-machine $ setting presets as JavaScript modules. These are applied at the EEPROM layer after flashing. For example, the Altmill gsender profile exports an ALTMILL_DEFAULT object with overrides like:

Derived variants adjust travel and steps for larger machines:

• Altmill 2x4: $131=648
• Altmill 4x8: $8=2, $101=214.44, $111=25000, $131=2661, $132=220

6. Overriding DEFAULT_ at Compile Time

In my_machine.h

// Override the default step pulse
#undef DEFAULT_STEP_PULSE_MICROSECONDS
#define DEFAULT_STEP_PULSE_MICROSECONDS 4.0f

// Override default homing enable
#undef DEFAULT_HOMING_ENABLE
#define DEFAULT_HOMING_ENABLE 1

// Force soft limits on by default
#undef DEFAULT_SOFT_LIMIT_ENABLE
#define DEFAULT_SOFT_LIMIT_ENABLE 1

// Set per-axis defaults
#undef DEFAULT_X_MAX_TRAVEL
#define DEFAULT_X_MAX_TRAVEL 800.0f
#undef DEFAULT_Y_MAX_TRAVEL
#define DEFAULT_Y_MAX_TRAVEL 600.0f

Via build flags (platformio.ini)

build_flags =
    -D DEFAULT_STEP_PULSE_MICROSECONDS=3.0f
    -D DEFAULT_HOMING_ENABLE=1
    -D DEFAULT_X_MAX_TRAVEL=800.0f

Via ESP-IDF CMakeLists.txt

target_compile_definitions(grblHAL PRIVATE
    DEFAULT_STEP_PULSE_MICROSECONDS=4.0f
    DEFAULT_HOMING_ENABLE=1
)

7. Restoring Defaults at Runtime

Use $RST= to reset groups to their compiled-in DEFAULT_ values: