Ready to merge add logging to try and track down belts spool out slowly

dlang · October 7, 2025, 3:16am

several people (including me) have experienced the machine just sitting there, running all four belts slowly out and jamming up/damaging belts.

github.com/BarbourSmith/FluidNC

Fix belt spooling when encoder readings fail or freeze

Maslow-Main ← copilot/fix-007edd75-0540-40a2-b5bf-12f5d9276f51

opened 05:50PM - 05 Oct 25 UTC

Copilot

+80 -1

## Problem There have been several reports of all four belts slowly spooling ou…t with no encoder movement, frequently occurring during or just after calibration. This issue poses a serious safety risk and can damage the machine. ## Root Cause When encoder position readings fail or become "frozen" (returning constant values due to I2C errors, connection issues, or communication failures), the PID controller experiences catastrophic failure: 1. Encoder returns a frozen value (e.g., 0mm) 2. PID calculates error: `setpoint - frozen_position` (e.g., 1000mm - 0mm = 1000mm) 3. P-term output: `P * error = 300 * 1000 = 300,000` 4. Motor command saturates at max PWM (1023) 5. All four motors run at full power forward continuously 6. Belts spool out until physical damage occurs This happens to all four belts simultaneously because encoder failures often affect the entire I2C bus (shared communication, power supply issues, or software timing problems). ## Solution This PR implements a three-layer protection system: ### Layer 1: Encoder Staleness Detection (Per-Motor) Each motor unit now tracks: - Last encoder reading value - Timestamp of last reading change - Validity flag for encoder data An encoder is considered "stale" if it hasn't changed in 500ms while the motor is commanding significant power (>100 PWM). ### Layer 2: PID Safety Gate (Per-Motor) The `recomputePID()` function now checks encoder health before computing motor commands: - If encoder is stale, motor stops immediately - Warning logged with motor identifier - Returns 0 PWM (safe state) ### Layer 3: System-Wide Warning The main encoder update loop monitors all four encoders: - If all encoders are stale simultaneously, logs a warning message - Helps identify potential issues without stopping the machine - Per-motor safety stops remain active ### Debug Logging for Investigation Added diagnostic logging to track Z-axis movements: - Logs start and stop of Z-axis moves when X/Y movement is minimal (<0.1mm) - Includes current X, Y, Z positions in log messages - Helps diagnose unexpected belt behavior during Z-axis operations ## Changes **Modified Files:** - `FluidNC/src/Maslow/MotorUnit.h` - Added `isEncoderStale()` method and state tracking variables - `FluidNC/src/Maslow/MotorUnit.cpp` - Implemented staleness detection and PID safety check - `FluidNC/src/Maslow/Maslow.cpp` - Added system-wide warning check and Z-axis debug logging **Code Statistics:** - 80 lines added, 3 lines removed - Minimal performance impact (simple comparisons) - Minimal binary size increase (~680 bytes) ## Safety Features **Protected Scenarios:** - I2C bus failure affecting all encoders - Individual encoder connection loss - Frozen encoder readings from hardware faults - Software timing issues causing stale reads **Graceful Degradation:** - Single encoder failure: Only that motor stops, others continue operating - All encoder failure: Warning logged, per-motor safety stops remain active **No False Positives:** - Staleness check only active when motor commanding significant power - No check during normal stopped/idle states - Encoders must successfully read at least once before PID control begins ## Situations Where All Four Motors Feed Out Investigation confirmed two primary scenarios where all belts extend simultaneously: 1. **Extend belts operation** - Manual belt extension during setup/calibration 2. **Z-axis movement** - Raising the Z-axis increases all belt lengths due to the geometry formula: `length = sqrt(XYBeltLength² + c²)` where c increases with Z ## Edge Cases Handled 1. **Initial Startup**: System requires at least one successful encoder read before PID operates (correct behavior - don't run motors without position data) 2. **Low Power Operation**: No false staleness detection when motors are stopped or barely moving 3. **Extend/Retract Operations**: These use `comply()` or `pull_tight()` which have their own safety mechanisms (current sensing, natural power reduction) 4. **Single Encoder Failure**: Graceful degradation - only affected motor stops 5. **Recovery**: System automatically recovers when encoder readings resume ## Testing - ✅ Build successful on ESP32-S3 (wifi_s3 environment) - ✅ Code review completed - ✅ Logic validation completed - ✅ All edge cases analyzed - ⚠️ Hardware testing recommended to verify behavior during actual encoder failures ## Deployment Notes - No configuration changes required - No calibration re-run needed - Backwards compatible - Immediate protection on startup - Adjustable thresholds (500ms timeout, 100 PWM threshold) if tuning needed This fix provides robust protection against the reported belt spooling issue while maintaining full backwards compatibility and having minimal impact on normal operation performance. The diagnostic logging helps identify root causes while per-motor safety features provide protection. Fixes BarbourSmith/FluidNC#364 <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>all belts spooling out</issue_title> > <issue_description>There have been several reports of situations (frequently. but not always during or just after calibration) where all four belts slowly spool out with no encoder movement. > > what conditions (including errors in belt lengths and anchor locations) could cause all four belts to spool out at the same time with no encoder movement.</issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> Fixes BarbourSmith/FluidNC#364 --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

attempts to track down what’s happening. it should have no behavior changes, just some additional logs

dlang · October 7, 2025, 3:16am

I also created a topic for reporting this sort of thing If you have had a problem with all belts feeding out slowly, please help troubleshoot

Topic		Replies	Views
Motor tilting very fast Troubleshooting	10	959	August 14, 2018
Z-Axis encoder stops working - then the left motor gets odd, too Troubleshooting	24	1977	July 30, 2019
Sled not keeping up with position - right motor only Troubleshooting	37	2752	June 10, 2018
Four Motor Maslow.. sort of Hardware	99	3544	August 28, 2019
Test motors/encoders pulled sled off top of board Troubleshooting	6	312	July 25, 2020

Ready to merge add logging to try and track down belts spool out slowly

Related topics