# Troubleshooting

By symptom. The error flags and what clears them are in [Errors and recovery](https://docs.source-robotics.com/STEPFOC-docs/108/06-operation/errors/); the
faults of the firmware that are known and not yet fixed, with what to do until they are, in
[Known issues](https://docs.source-robotics.com/STEPFOC-docs/108/08-troubleshooting/known-issues/).

## The motor does not move

```mermaid
flowchart TD
    A([The motor does not move]) --> B{Does the driver answer?}
    B -- no --> C[The supply and its polarity, the LED;<br>UART: the baud rate, TX and RX;<br>CAN: the node ID, 1 Mbit/s, the termination]
    B -- yes --> D{Calibrated?}
    D -- no --> E[Enter the motor parameters, then #Cal and #Save]
    D -- yes --> F{An error active? The LED on steadily}
    F -- yes --> G[#Error names it: fix the cause, then #Clear]
    F -- no --> H{A current limit above 0?}
    H -- no --> I[#Ilim to the stepper's rated current, #Save]
    H -- yes --> J[Command a setpoint in a closed-loop mode;<br>#Mode and #Info show the state]
```

## The driver does not answer

| Symptom | Check |
|---|---|
| No LED | the supply, DC+ and DC−, the power cable's orientation. If the cable was the wrong way round the driver is destroyed |
| LED on, nothing on the terminal | 256000 baud; TX to RX and RX to TX; the adapter's port; 3.3 V adapter; the line ending CR+LF |
| LED on, nothing on CAN | the node ID; 1 Mbit/s on the adapter; termination (about 60 Ω across CAN H and CAN L with everything unpowered); the CAN cable's orientation |
| `Unknown command` | the name's spelling and case: `#Kpiq`, not `#kpiq` |
| the LED keeps blinking and nothing answers after a firmware update | the bootloader has no valid firmware, or its CRC does not match after an upload with the programming adapter: flash again through the bootloader, see [Updating through the bootloader](https://docs.source-robotics.com/STEPFOC-docs/108/07-firmware/update/) |

## Motor GUI

| Symptom | Check |
|---|---|
| the browser offers no port | a Chromium-based browser (Chrome, Edge, Brave, Opera); Firefox and Safari have no Web Serial |
| the port is listed but will not open | another program holds it: a terminal, PlatformIO's monitor, the Arduino serial monitor |
| the port opens, nothing appears | the driver's power; TX and RX crossed on a non-Source adapter; the baud rate on a non-Source adapter (256000) |
| *No connection* on CAN | the CANvas adapter's port; the bus termination; the node ID of the driver; 1 Mbit/s |
| the calibration does not start | calibration runs over the serial connection only, not over CAN |
| *Unsaved changes* after a power cycle | the settings were not saved to the driver; Save writes them |
| the firmware update finds no bootloader | power-cycle the driver while the GUI scans, to catch the bootloader's 2 s window. A driver with firmware 103 or older from the `main` branch has no bootloader: [Installing the bootloader on an older board](https://docs.source-robotics.com/STEPFOC-docs/108/07-firmware/bootloader/) |

## Calibration

The messages and their causes are in [Motor parameters and calibration](https://docs.source-robotics.com/STEPFOC-docs/108/05-setup/calibration/). The ones that
come back most:

| Symptom | Cause |
|---|---|
| `Magnet test: Failed` | magnet too far, axially magnetised, or missing |
| the motor wobbles left and right during calibration | one coil is not connected |
| the motor does not move in the open-loop step | a coil open or not soldered; calibration then fails at the next step with `Phase order is wrong!` |
| `Phase order is wrong!` | the motor did not respond to the commutation check; wiring, current limit, magnet |
| calibration succeeds, the motor then runs badly or in the wrong direction | the magnet slipped on the shaft; glue it and calibrate again |
| calibration succeeds but the LED stays on and `#Error` shows nothing | should not happen with firmware 106 and newer, which replaces a damaged configuration block with the defaults at power-up; if `#Info` shows `-1`: `#Default`, parameters, calibrate again |

## The motor

| Symptom | Cause |
|---|---|
| crunching or whining at speed | the current limit or the current loop gains too high; lower `#Ilim`, lower `#Cbw` and calibrate again, or lower `#Kpiq` |
| humming, oscillating at rest | `#Kpv` or `#Kpp` too high; see [Current limit and loop tuning](https://docs.source-robotics.com/STEPFOC-docs/108/05-setup/tuning/) |
| weak torque | `#Ilim` low; the supply's current limit; the wrong `#R`/`#L` (the computed current gains are off) |
| the motor is hot | normal for a stepper at its rated current; lower `#Ilim`, enable the thermistor |
| it stops with a Vbus error when decelerating | the supply cannot absorb the returned energy; a different supply, or a brake resistor |
| it stops with a velocity error | the speed passed 30,000,000 ticks/s, a fixed threshold that `#Vlimit` does not change: a runaway, so check the magnet and the calibration |
| it loses position with a load | that is a torque limit: a stepper under FOC does not lose steps, it falls behind; raise `#Ilim` within the motor's rating, or more motor |
| it holds position with a sawtooth noise | the position loop gain; the magnet distance |

## Low-quality motors

Motors with visibly bad windings, an uneven back-EMF or a resistance that differs between the two coils calibrate
poorly and run rough. The [tested motors](https://docs.source-robotics.com/STEPFOC-docs/108/03-technical-data/tested-motors/) are known good.

## The magnet and the encoder

- The distance is 1 mm. "Magnet Good" from the magnet test does not mean the distance is right, only that the
  field is strong enough.
- A magnet touching the chip can destroy the microcontroller; a magnet too far gives a noisy, wrong position.
- The magnet must be diametrically magnetised and centred on the shaft.

## The driver gets hot or shuts down

The firmware does not monitor the driver stage: if the stage stops on its own, for heat or a short, the motor
loses torque and no error is reported. Lower the current limit, give the board airflow, check the motor leads for
a short. Near 2.8 A the driver needs cooling.

## After a firmware update

`#Info` shows the new release. If the values look wrong or the LED stays on: `#Default`, enter the motor
parameters, `#Cal`, `#Save`. A release note says when an update clears the calibration.

## Getting help

[Support](https://docs.source-robotics.com/STEPFOC-docs/108/support/) says where to ask and what to include; `#Info`'s output is the first thing.