# Troubleshooting

> Known symptoms on UPAN Core with their likely cause and what to do, including the error codes the device returns.

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](/docs/api). 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](/docs/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](/docs/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](/docs/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](/docs/wiring#fast-inputs-and-sensor-supply) |
| 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 |