Follow this process to setup and debug motion on a new FluidNC machine.
Before you start to test the motion be sure your startup messages are free of all errors and warnings. See the troubleshooting guide for help with that.
Click on a box for more information. You can also use the side navigation bar to go to the sections.
When a stepper motor is powered, it will be difficult or impossible to turn by hand. This is called “motor lock”. Conversely, if the motor is unpowered - either as a result of the driver not having power or the driver’s enable signal in inactive - it is usually fairly easy to manually rotate the motor shaft.
When a motor goes from the unlocked to locked state, you can often hear a “thunk” sound. A locked stepper motor will also usually be warm to the touch.
For an external stepper driver, the “enable” signal is usually actually a “disable”. If you do not connect anything to the ENA input of an external stepper driver, the motor will lock.
If a motor is not locked, there are several possibilities
Be sure to test the lock by trying to rotate the motors in the lock AND unlock states. Ignore the text responses from FluidNC. That is just showing you what FluidNC is trying to do. Also, some motors under load will "thunk" for both lock and unlock transitions, so do not use that to determine the lock state.
If you have external stepper drivers and their ENA input is not connected, the steppers should lock whenever power is applied to the drivers. Some external drivers have a “charge pump” safety feature that can be disabled with a switch. If so you should disable that feature.
Stepstick driver modules and onboard driver chips usually have an enable line that FluidNC can control. Some controllers have one such line that disables all of the drivers as a group - see shared_stepper_disable_pin. Other controllers have separate lines so each driver can be controlled individually - see disable_pin . In typical use, FluidNC will automatically enable the drivers before starting any motion, and then after motion has stopped for a configurable amount of time - see idle_ms - they will be disabled. If idle_ms is 255, FluidNC will leave them enabled all the time unless you use $MD to disable them manually.
You can manually disable the drivers by sending or manually enable with $ME. If $MD enables and $ME disables, the polarity of the corresponding enable line is wrong.
If a stepper motor makes clicking sounds instead of moving, the usual cause is that it is trying to go too fast. Possible causes include:
If a stepper motor locks but silently will not move, it is usually because the step signal (sometimes labeled PUL for pulse) is not getting to the driver
See Testing Step Pins for one way to test Step and Direction pins.
If, say, you asked to move X but Y moved instead, you must swap the X and Y axes
Option 1 - Swap the X and Y motor cables
Option 2 - In the yaml config file, replace the “x:” label with “y:”, and vice versa
Option 3 - In the yaml config file, swap the step_pin:, direction_pin:, and possibly the disable_pin: values between the x: and y: sections.
Option 1 - Swap a pair of wires in the stepper cable - like this
Option 2 - In the yaml config file, find the direction_pin: for the axis that is going backwards. Either add or remove :low from the value. For example, if it says direction_pin: gpio.12, change that to direction_pin: gpio.12:low. Conversely, it if already says gpio.12:low, change it to gpio.12.
Reference
If the axis will only move in one direction, the most common reason is a problem with the direction signal to the stepper driver. Possibilities include:
Another possibility is a bad connection between the stepper driver and the motor, so that only one of the two motor coils is getting power. The most common manifestation of this problem is that the direction is erratic, randomly switching directions, but that can sometimes be mistaken as one-direction-only.
The amount that the axis moves for each pulse that is sent to the stepper motor driver is controlled by steps_per_mm . It is affected by the mechanical system (screw pitch, pulley sizes, etc) and by the driver’s “microstepping” setting. If you understand how all this works, you can calculate the correct value for steps_per_mm . Otherwise, you can just change steps_per_mm until it works. If you asked to move 10 mm but it actually moved 5 mm, you would need to double the steps_per_mm value. In general, multiply steps_per_mm by the factor expected_distance / actual_distance .
Once an axis is moving reliably, going the specified distance and direction, you can adjust acceleration_mm_per_sec2 and max_rate_mm_per_min to make it go faster. One convenient test procedure is to set max_rate_mm_per_min to a very high value then use G1 Fnnn moves to test at specific rates, then when you have settled on a good top end rate, set max_rate_mm_per_min to that limiting value.
When acceleration is low, the machine might not reach the top speed before half of the distance, so it will then switch to deceleration without ever “cruising”. Use long distances and bump up the acceleration until the motors stall near the beginning of the acceleration phase. Then back off the acceleration so it doesn't stall and start increasing the rate.
When you have discovered how fast your machine can travel, test with loads, especially for machines with spindles that can experience side loads. You will want to decrease the max rate so that it will not stall under any reasonable situation. Keep in mind that, over time, things get worse due to lubrication conditions, wear, debris, temperature, etc. Give yourself some headroom by using conservative settings.