Troubleshooting

Find the symptom, work down the list. Most problems are a missing ground, a missing terminator, two drivers on the same ID, or a setting that was applied but never saved.

Tip

On a motor’s Diagnostics tab, Copy report collects the identity, settings, telemetry and faults in one paste. Include it when you ask for help.

No adapter foundTercio Control can’t see the Tercio FD.No motor appearsAdapter connected, Motors list empty.Two motors act as oneThey share a node ID.Calibration failsThe encoder did not follow the motor.The motor does not moveCommands are refused or blocked.Buzzes or oscillatesAt standstill or after moves.StallsThe shaft falls behind.Encoder faultReadings stopped or the magnet is gone.Driver faultNot responding, or bridge switched off.OverheatingWarnings and shutdown.Step/dir does nothingMode, EN, levels, scaling.Wrong position at power-upTurns made while off are not known.Settings lostApplied but never saved.Python timeoutsPort busy or wrong node.

Tercio Control finds no adapter

• Use Chrome or Edge on a desktop computer. Firefox and Safari have no Web Serial.
• Check the cable carries data: some USB-C cables only charge. The adapter’s green LED only proves power.
• Close other programs that use the port (a Python script, a serial monitor, another Tercio Control tab).
• Linux: add yourself to the dialout group and log in again. See Connecting.
• The browser list shows the adapter as tercioFD. If it is not there, check that the computer sees it at all: Device Manager (Windows), ls /dev/cu.usbmodem* (macOS), ls /dev/ttyACM* (Linux).

No motor appears

The adapter is connected, but the Motors list is empty.

1. Is the S1 powered? Its red LED is on.
2. Is the bus wired? CAN-H to CAN-H, CAN-L to CAN-L, GND to GND. Swapped H and L is the most common mistake.
3. Is the bus terminated? Fit the J9 jumper on the last S1. With power off, CAN-H to CAN-L should measure about 60 Ω.
4. What does the adapter say? On its page in Tercio Control: Last error: No acknowledge means no node answers at all (power, wiring); stuff, form or CRC errors mean a signal problem (termination, twisted pair, stubs). See Bus health.
5. Is the firmware v2? A driver still on the first firmware speaks another protocol. Update it.
6. Select Scan bus once the driver is powered.

Two motors act as one

They share a node ID; new drivers are all node 1. Connect them one at a time and give each its own ID, or use AssignNodeId with their serial numbers. See Node IDs.

Calibration fails

Calibration failed means the encoder did not follow the motor as expected.

Check
Magnet	Present, diametric, centred, 0.5–3 mm from the chip. The Diagnostics tab shows Magnet too weak/strong.
Full steps per revolution	200 for a 1.8° motor, 400 for a 0.9° motor.
Gear ratio	1 with the on-board encoder.
Run current	High enough for the shaft to follow. Try 800 mA or more.
Motor wiring	Each coil on its own pair of terminals (A1/A2, B1/B2).
Free shaft	Nothing may stop it turning a quarter turn each way.

The motor does not move

A command that is refused comes back with a status. Tercio Control shows it as a message; Python raises TercioError.

Status	Fix
Disabled	Enable the motor.
NotCalibrated	Run Calibrate.
Faulted	A hard fault is latched. See Faults.
Busy	A procedure is running, or step/dir mode is on (Settings → Inputs).

A move also stops short at a soft limit, and does not go toward an active switch while Stop at limit switches is on (check the limit min/max flags).

It buzzes, hunts or oscillates

• At standstill: raise the deadband a little, lower Kp, lower the hold current.
• After moves: lower Kp, lower or remove Ki.
• Check the magnet is centred: an off-centre magnet gives a reading that wobbles once per turn.

More in Tuning.

Stalls

Stall means the shaft fell behind the target by more than the Stall threshold.

• Lower the acceleration or speed, or run Find speed limits to measure what the axis can do.
• Raise the run current (up to 1770 mA) and the supply voltage (up to 28 V).
• Check Quiet mode up to: StealthChop loses torque at speed.
• Look for mechanical binding.

Encoder fault

Encoder means the encoder could not be read, or the magnet disappeared while the loop ran. The bridge is off.

• Check the magnet (it may have come loose).
• With an external encoder: check the wiring and that Encoder matches what is connected.
• Clear faults; if the encoder is readable again, enable the motor.

Driver not responding or driver fault

• Driver not responding: the S1 lost contact with the TMC2209. Check the supply voltage on the Diagnostics tab and power-cycle.
• Driver fault: the driver switched its bridge off, usually a short between motor wires or to ground. Power off and check the motor wiring and ferrules.

Overheating

The board warns at 10 °C below Shut down at and switches the motor off at it. Lower the run or hold current, add airflow, and check the motor is not stalling against a load. Clearing the fault needs the board to be 5 °C below the limit.

Step/dir does nothing

1. Is the motor calibrated? Step/dir mode only runs after calibration.
2. Is Follow step/dir input on (Settings → Inputs), and saved?
3. EN: with the default EN input active low, EN must be pulled low. Unconnected, it keeps the motor off. The ext enable flag in telemetry shows what the S1 sees.
4. Are the signals 3.3 V, and is the controller’s ground connected to J5 pin 5?
5. Wrong distance per step? Check full steps, microsteps and gear ratio against the controller’s steps per unit, with the calculator.

The position is wrong after power-up

The S1 knows the angle within one turn at power-up, not how many whole turns the shaft made while off. Home after power-up if the axis can move more than half a turn while unpowered.

Settings are lost after a power cycle

They were applied but not saved. Select Save to motor (Python: motor.save()). If saving fails, the Saving settings failed warning appears; try again.

Python: timeouts or “port busy”

• Only one program can open the port. Close Tercio Control.
• Bus() without a port name picks the first serial port; name it: Bus("COM5").
• A timeout error on every command: the node ID is wrong, or the driver is not on the bus. Try bus.discover().