Troubleshooting — UPAN docs

This page collects the problems we already know about, with their cause and the fix. When the device refuses a command, it returns an error code such as ERROR_NOT_HOMED together with details: which limit, the requested and the allowed value, and for programs the index of the instruction. upan-cli prints these in plain words, for example device refused: LIMIT_EXCEEDED: TRAVEL_MAX — requested 120.000 mm, allowed 100.000 mm. The full list of codes is in the API reference. The board is v2 and the firmware is in development, so this list will grow.

The axis does not move

Symptom	Likely cause	What to do
Every move is refused with `ERROR_NO_MOTOR_POWER`	The device is powered from USB only, or the supply is too low	Connect and switch on the 12–24 V supply. USB alone is for setup only. See Power
Device is in stop right after power-on; moves fail with `ERROR_ESTOP_ACTIVE`; the light flashes red	Nothing is connected to the `ESTOP` input, or the NC contact is open or a wire is broken	Wire an NC stop button between pins 7 `+5V` and 6 `ESTOP` of the `OUT / E-STOP` terminal, or fit a jumper there. Then send `fault-clear`
Moves fail with `ERROR_FAULT_ACTIVE`	A fault happened earlier (limit switch, driver error, supply lost during a move). The device never resumes by itself	Find the cause in the fault event, fix it, then send `fault-clear`
`ERROR_NOT_HOMED` on an absolute move or a program	The position is unknown until the axis is homed. Homing is also lost after any stop or fault	Run `home`, or declare the position with `set-position`. A program may start with a `home` step. Relative moves and jog work without homing
`ERROR_LIMIT_SWITCH`	A limit switch is triggered in the direction of motion	Move away from the switch (that direction is allowed), then home again
Limit inputs read "triggered", although no switches are fitted	Limit inputs expect NC contacts. An open input means "pressed or broken wire"	Mark missing switches as absent: `config set --hard limit_min_absent=yes limit_max_absent=yes` (USB, after a short press of the button)
Move or program refused with `ERROR_LIMIT_EXCEEDED`	The request is outside the working or machine limits	Read the details: limit kind (`TRAVEL_MIN`, `TRAVEL_MAX`, `VELOCITY`, `ACCELERATION`), requested and allowed value. For a program, the response also gives the instruction index. Change that step, or the limits
Program refused with `ERROR_PROGRAM_INVALID`	A step in the program is not valid (structure, loop depth, input or output number)	The response gives the instruction index. Fix that step. `upan-cli program check` checks the form without a device
`ERROR_HOMING_FAILED`	Homing did not find the switch or the end stop within the travel	Check the limit switch wiring and the homing method in the machine settings
`ERROR_BUSY`	A move is already running	Wait for it to finish or send `stop`
Motor turns the wrong way	Coil order or mechanics	Set `invert_direction=yes` in the machine settings instead of rewiring

Settings are refused

Symptom	Likely cause	What to do
`ERROR_PRESENCE_REQUIRED` when changing machine limits	Machine limits need physical presence at the device	Press the button briefly (under 2 s), then send the command within 30 s
`ERROR_TRANSPORT_NOT_ALLOWED`	Machine limits were sent over a channel other than the USB-C setup port	Connect over the USB-C setup port. The network API does not offer this command at all; it can change working limits only
`ERROR_STORAGE`	Saving the settings to flash failed	The old settings are still in place. Try again with the axis at rest

Faults during motion

Symptom	Likely cause	What to do
`ERROR_DRIVER` fault	Driver error: overheating or a short circuit	Check motor wiring for shorts. Check that the driver has its heatsink and the vents are free. Reduce motor current if it is above the motor rating; above about 2 A use an external driver
Drivers in the sockets do not move, external drivers do	The supply is above about 28 V, so the sockets are switched off	Use a 12–24 V supply for the drivers in the sockets. See Power
`ERROR_TIMEOUT` in a program	A `wait_input` step did not see the input within its timeout	Check the input wiring and the timeout in the program. The event gives the instruction index
Jog stops on its own	The jog needs a steady stream of commands. The connection dropped or was too slow	Check Wi-Fi or USB. This is intended: a jog never runs away when the connection is lost
Lost steps on hard acceleration; the supply briefly switches off	LRS supplies go into "hiccup" on short overload	Use an HDR, NDR or SDR supply, a bigger supply, or lower the acceleration. See Power
The drivers in the sockets switch off after a hard stop	The decelerating motor pushed the supply voltage above about 28 V, and the over-voltage cut-off took the sockets off	Lower the deceleration, or use a lower supply voltage for heavy loads
The device restarted by itself	Unknown; may be a watchdog reset	`upan-cli info` shows the last reset cause and warns about watchdog resets. Report it with that output

UPAN Axis module

Symptom	Likely cause	What to do
Axes 3 and 4 do not move	The ribbon cable is not seated, or the module has no motor power	Switch off, reseat the ribbon cable on both ends, check the motor power wires to the module
Axes 3 and 4 stay disabled while the e-stop is released	The module shares the disable line with the Core	Check the e-stop wiring on the Core, then send `fault-clear`

Inputs, outputs and external drivers

Symptom	Likely cause	What to do
A 2-wire sensor reads ON all the time	Its leakage current is enough to switch the input	Use a 3-wire sensor or a dry contact
An NPN sensor does not switch the input	The common of the inputs is joined to `GND` from the factory, which suits PNP sensors and dry contacts	Cut the `COM1-GND` (or `COM2-GND`) jumper and connect the common to `+V`. See Wiring
A sensor on `+V` failed	`+V` is the supply voltage, up to 36 V	Use sensors rated for your supply voltage
An output switches off by itself	The load draws more than 0.5 A or is shorted; the output protects itself	Check the load. Switch a bigger load through a relay
External DM542-type driver holds the motor while UPAN Core is off	`EN` is low when UPAN Core is unpowered, and such drivers are then enabled	Expected behaviour of the driver
A sensor or an external driver does not work when powered from USB only	USB cannot supply enough current for the `+5V` pins	Connect the power supply
No Wi-Fi in a metal cabinet	The cabinet blocks the signal	Mount the antenna outside the cabinet with an SMA extension cable