6 grblHAL for PiBot V5.88 Ultra

Official ESP32 board map and Web Builder target · status checked 2026-08-04

✅

Official target available. PiBot V5.88 Ultra is now listed in the grblHAL Controllers repository, has an ESP32-S3 board map in the official ESP32 driver, and can be selected directly in the official Web Builder.

⚠

The current target is still marked Experimental!. Official inclusion means that the source and Web Builder target exist; it does not mean every V5.88 connector, plugin, spindle mode, or axis combination has been verified on real hardware. Build a minimal configuration first and validate it on the bench before connecting a machine.

Status at a Glance

Official Controllers listListed
PiBot V5.88 Ultra appears under the ESP32 driver with a direct Web Builder link.

Official board mapMerged
pibot_5_88_ultra_map.h was merged on 2026-07-07.

Web BuilderAvailable
Select ESP32 and PiBot V5.88 Ultra, 8MB+ flash.

Support levelExperimental
Compilation and selection are available; real-board validation is still requested by grblHAL.

The initial upstream pull request reported compilation validation with the ESP-IDF environment used by Web Builder. The grblHAL Controllers list and Web Builder both ask board owners to report real-hardware results. A later 2026-07-26 commit fixed direction output for the second PWM spindle, so use a newly generated build instead of an older cached firmware file.

Important Difference from FluidNC

Do not upload the FluidNC config.yaml to grblHAL.

FluidNC assigns pins and features through YAML.
grblHAL assigns the board pins at compile time through its board map and selected plugins.
Tool numbers, spindle selection, coolant outputs, control inputs, settings, and WebUI files are not interchangeable.
Flashing grblHAL replaces the existing FluidNC firmware. Back up the FluidNC firmware package, config.yaml, WebUI file, and machine settings first.

Current Web Builder Capabilities

The official ESP32 driver.json currently advertises the following capabilities for this target:

Item	Current official Web Builder declaration	Practical meaning
Processor / flash profile	ESP32-S3, `8MB+ flash`	Use the exact PiBot V5.88 Ultra board entry, not a generic ESP32 or older PiBot entry.
Axes	Maximum 4	The V5.88 hardware is 6+1 axis, but the current official Web Builder target is capped at four axes. Do not claim or assume a six-axis Web Builder build yet.
Connection	Native USB available	Native ESP32-S3 USB serial can be selected in the build.
Serial ports	2	The board map assigns UART1 to Modbus and UART2 to pendant/FNC-expander use.
Storage / network	SD card and Wi-Fi available	Enable only what the machine needs, then test each selected plugin.
Bluetooth	Not advertised	Do not enable or promise native Bluetooth support for this ESP32-S3 target.
I2C	Not advertised by Web Builder	The map contains OLED I2C pin definitions, but the current builder capability is `i2c: 0`; treat OLED/I2C as unverified in generated builds.
EEPROM / FRAM	Not advertised	Settings use the storage method supplied by the ESP32 build.

Official Board Map Summary

Motion outputs and limits

Motor	Step / Direction / Enable	Limit input	Notes
X	`I2SO.2 / I2SO.1 / I2SO.0`	GPIO.42 min, GPIO.41 max	Driver CS: `I2SO.3`
Y	`I2SO.5 / I2SO.4 / I2SO.7`	GPIO.40 min, GPIO.39 max	Driver CS: `I2SO.6`
Z	`I2SO.10 / I2SO.9 / I2SO.8`	GPIO.38	Driver CS: `I2SO.11`
4th motor (M3)	`I2SO.13 / I2SO.12 / I2SO.15`	GPIO.37 when enabled	Driver CS: `I2SO.14`

ℹ

The source map also contains M4 and M5 mappings for additional motors, but the official Web Builder target currently declares a four-axis limit. Those extra definitions are relevant to future or custom source builds, not evidence that the current public Web Builder supports all six axes.

I/O and peripherals

Function in current map	Pin(s)	Important note
Probe	GPIO.47	Enable the Probe input option only when it is wired and tested.
Tool setter	GPIO.3	Requires the V5.88 board jumper selection described in the Pinout Reference.
Safety door	GPIO.48	Available only when that pin is not used as the M5 limit input.
Coolant flood / mist	GPIO.10 / GPIO.15	These are compile-time assignments in the grblHAL map.
Aux outputs	GPIO.4 / GPIO.5	Mapped as auxiliary signals; verify the selected plugin and electrical terminal before use.
Primary PWM spindle	PWM GPIO.45	The current map uses a dummy enable and does not assign primary spindle direction.
Second PWM spindle / 0-10 V path	PWM GPIO.6, enable GPIO.7, direction GPIO.8	Direction handling was fixed upstream on 2026-07-26. Measure the outputs before connecting a VFD.
Laser header signal	GPIO.46	Declared as `AUXOUTPUT5`; the current map does not assign it as the primary or second spindle PWM output. Verify a laser-specific build before connecting a laser.
Modbus UART1	TX GPIO.12, RX GPIO.11	For the isolated RS485 circuit; enable Modbus RTU only when required.
Pendant / FNC expander UART2	TX GPIO.0, RX GPIO.35	Used by MPG or FNC Expander when the relevant plugin is enabled.
SD card	CS GPIO.9; shared SPI bus	SPI MISO GPIO.2, MOSI GPIO.1, clock GPIO.21.
OLED I2C definitions	SDA GPIO.14, SCL GPIO.13	Definitions exist in the map, but I2C is not currently advertised in this Web Builder target.

Build with the Official Web Builder

Back up the current FluidNC files and record the machine wiring and working settings.
Open the official grblHAL Web Builder with the V5.88 target selected.
Confirm Driver: ESP32 and Boards: PiBot V5.88 Ultra, 8MB+ flash. The Notes field should show Experimental!.
Select three or four axes to match the machine. The current public target does not offer more than four.
For the first build, use the minimum required features. Avoid optional and third-party plugins until the basic motion, limits, probe, and spindle signals have passed a bench test.
Select the connection and only the spindle/Modbus options actually used by the machine. Do not enable a function simply because it appears in the builder.
Click Generate and download firmware and keep a record of every selected option. A future rebuild with different plugins can change pin ownership and available settings.

Flash and First Start

⚠

Flashing replaces FluidNC. The V5.88 FluidNC Windows installer, YAML, and WebUI package are not a grblHAL installer. Use the firmware generated by grblHAL Web Builder and follow the official ESP32 flashing guidance.

Read the official Compiling grblHAL / flashing guide. For ESP32, grblHAL points to Espressif Flash Download Tool on Windows or the Espressif Python utility.
Do the first boot with motors, spindle/VFD, laser, and high-power loads disconnected.
Capture the $I report and confirm that the firmware identifies the expected ESP32 driver and PiBot V5.88 board.
Follow the official First Run Grbl Settings guide. grblHAL control inputs default toward normally-closed safety wiring; an unwired input may intentionally hold the controller in Alarm.
Configure steps per unit, travel, speed, acceleration, homing direction, limit polarity, and control-input polarity for the actual machine. Do not copy FluidNC YAML values blindly.

Required Bench Validation

Test	Pass condition
Boot identity	`$I` identifies the expected build; selected plugins are present and no unexpected reset loop occurs.
USB / sender	The chosen serial connection remains stable through reset, unlock, status polling, and a short dry-run.
Motion	One axis at a time: enable, step and direction LEDs/signals match commands before motors are connected.
Limits and probe	Each input changes only its intended state. Check idle and triggered states before enabling homing.
Coolant / auxiliary outputs	GPIO.10, GPIO.15, GPIO.4 and GPIO.5 assignments match the selected build and physical terminals.
Spindle / laser / 0-10 V	Measure voltage and direction contacts with a multimeter before connecting a VFD or laser. Pay special attention to the current map's GPIO.45, GPIO.46 and GPIO.6/7/8 roles.
RS485	Modbus is tested with the isolated VFD simulator or a safely disconnected VFD setup before spindle operation.
SD / Wi-Fi	Only if enabled: storage mounts, network starts, and the selected WebUI/streaming functions remain stable.

When reporting a result upstream, include the Web Builder build date, the saved option selection, the downloaded firmware date, $I output, exact board revision, and which physical tests passed or failed.

Official Resources

← V5.88 Introduction 5 Documentation →