Table of Contents
FAQ
TF Card Issue:
- Avoid using SD cards with excessively large capacity or high speed, as the ESP32 library may not support them. We conducted tests using a Class 4 TF card.
XYYZAB config yaml
Why do bidirectional raster engravings show an offset or double image?
This FAQ covers a direction-dependent raster engraving problem: alternate scan lines do not start at the same horizontal position, so text and image edges look doubled or ghosted.
The comparison that led to this guide was made on a PiBot V4.96 Pro running FluidNC 3.8.3. Changing only the stepping engine from I2S_STREAM to I2S_STATIC significantly reduced the offset on that machine.
This result is a useful troubleshooting case, not proof that every bidirectional offset is caused by FluidNC or that every machine must use I2S_STATIC. Loose mechanics, acceleration, laser response time and LightBurn's Scanning Offset Adjustment can produce a similar appearance.
1. Confirm that the problem is direction-dependent
- Save the current LightBurn file and record speed, acceleration, line interval/DPI and power.
- Engrave a small text or rectangle using bidirectional scanning.
- Repeat the same job with bidirectional scanning disabled.
- If the one-way result is clean but alternate lines shift in the two-way result, continue with the checks below.
2. Check the mechanics first
Before changing the controller configuration, check the X-axis belt tension, pulley/set-screw tightness, carriage play, backlash and cable drag. Repeat the test at a lower speed and acceleration. Mechanical looseness must be corrected before applying software compensation.
LightBurn also documents this symptom and recommends checking the mechanics before using Scanning Offset Adjustment:
3. Compare the FluidNC stepping engine
Back up the working YAML file first. In the stepping: section, change only the engine line:
stepping: engine: I2S_STATIC
Do not change steps/mm, speed, acceleration, pulse width or LightBurn settings during this comparison. Upload the YAML, restart FluidNC, and check the startup log for Stepping:I2S_static. Then run exactly the same engraving again.
On the reported V4.96 Pro case, this single change produced a much cleaner bidirectional result. FluidNC's official project discussions also show that changing between I2S_STREAM and I2S_STATIC is a valid diagnostic step on I2SO controller designs:
4. If the offset remains
- Restore the backed-up YAML if
I2S_STATICdoes not improve the result. - Reduce engraving speed and acceleration and repeat the same controlled test.
- Use LightBurn's Scanning Offset Adjustment to measure and compensate for a repeatable speed-dependent offset.
- When requesting help, provide the board version, FluidNC version, sanitized YAML, startup log, LightBurn speed/line interval, and clear before/after photos. Remove Wi-Fi passwords and private network details before sharing files.
Related boards: V5.77 Carrier and V5.88 Ultra FAQ pages link to this master troubleshooting guide. Always keep the pin assignments and other settings from the correct board-specific YAML.
24v Probe
- Of course, a 24V probe can be used. Please refer to the pin map. You can set the probe to a port that includes SWVCC (position 2 in the diagram as the input) and select SWVCC at 24V as your working voltage (position 7).
EXpander V4.1 OR V4.0
- the new version of the expander 4.1 . I added two voltage-dividing resistors. Please check if the silkscreen on the back is marked as 4.1 (the front silkscreen is incorrect).
If you want to use these ports as regular switches, please connect +5V and the signal. Due to the presence of a voltage divider, there will be a 3V voltage at the STM32 port. You can configure it for high-level triggering.
Customer Videos 1
closed-loop driver
- You can use a closed-loop driver, but it can only receive EN, DIR, CLK, and GND signals, with no feedback information sent back to the mainboard. The mainboard only has outputs and lacks input capabilities.
—
Shared FAQ: Pendant, Expander and RJ12 RX/TX
The RX/TX swap solutions are not specific to V4.96. Pendant V4.2, I/O Expander V5, RJ12 Adapter V4.2, the latest ESP3D firmware and older-pendant cable options are documented in the shared FAQ for all compatible PiBot controller boards:
For this V4.96 page only, the direct RJ12 UART2 starting point remains TX GPIO.27, RX GPIO.25, 1000000 8N1. Other boards must use their own pin assignments and test instructions.