# Troubleshooting Guide

## 1. Connection & Detection Issues

**Problem:** SMD Red is not recognized over USB\
**Possible Causes:**

* Faulty USB cable or port
* Missing or incompatible USB driver
* Incorrect serial port used in the code

**Solutions:**

* Use the `USB_Port()` function from the SDK to auto-detect the correct port.
* Try with another cable and USB port.
* Ensure drivers like FTDI or CH340 are properly installed (especially on Windows).
* Restart the computer and try reconnecting the device.
* Confirm the LED indicator is active.

<table><thead><tr><th width="131.39996337890625">LED Color</th><th width="230.4000244140625">Meaning</th><th width="385.4000244140625">Details</th><th data-hidden></th></tr></thead><tbody><tr><td>🟡 <strong>Yellow</strong></td><td>No EEPROM Save Detected</td><td>Stays on until user performs EEPROM save. Also appears after Factory Reset. If still lit after saving, EEPROM may have issues. Not considered an error by itself.</td><td></td></tr><tr><td>⚪ <strong>White</strong></td><td>IDLE / Firmware Status</td><td>Solid: IDLE mode. Blinking fast (every 50ms): No valid firmware or hardware mismatch. Blinking slow (every 150ms): Scanning modules.</td><td></td></tr><tr><td>🟢 <strong>Green</strong></td><td>Ready / Motor Active</td><td>Indicates the motor driver is active and ready to drive. Should be on when the motor is running.</td><td></td></tr><tr><td>🔵 <strong>Blue</strong></td><td>Autotuning Active</td><td>Blinks during PID tuning. Torque must be enabled. It is normal to see blue and green together during this state.</td><td></td></tr><tr><td>🔴 <strong>Red</strong></td><td>Overcurrent / Current Limit</td><td>Turns on when the motor draws excessive current or exceeds the defined current limit. Can resume by toggling torque off and on.</td><td></td></tr><tr><td>🟣 <strong>Purple</strong></td><td>Communication Issue</td><td>Appears when communication fails between modules or host device.</td><td></td></tr><tr><td>🟦 <strong>Cyan</strong></td><td>User Indicator</td><td>Blinks when <code>userIndicator</code> is triggered by user code. Not shown unless explicitly activated.</td><td></td></tr></tbody></table>

**Problem:** `attach(Red(ID))` fails or gives timeout

* Make sure the correct `ID` is used for the SMD Red connected.
* Use `scan_modules()` to detect all available modules.

## 2. Motor Not Moving or Moving Incorrectly

**Problem:** Motor doesn’t respond to control commands\
**Check:**

* Torque is enabled
* Operation mode is set
* CPR is configured
* Firmware and API version compatibility:\
  Make sure the firmware and API are on the same major version (e.g., `2.*.*`).\
  You can verify this using the command:

```
get_firmware_version()
```

**Problem:** Motor rotates in the opposite direction

* Invert the duty cycle (e.g., use `-value`)
* Physically switch motor wires if possible
* Adjust inversion settings in software logic

**Problem:** Motor vibrates or moves erratically

* Double-check the power supply
* Lower the control frequency or PID gains
* Reduce mechanical load temporarily to test

## 3. Torque Enable and Operation Mode Setup

**Always ensure this sequence:**

1. `attach(Red(smd_id))`
2. `set_operation_mode()`
3. `set_shaft_cpr()`
4. `enable_torque()`

**Common Mistakes:**

* Enabling torque before setting mode/CPR
* Setting wrong operation mode (e.g., using `POSITION` for a brushed DC motor)
* Forgetting to re-enable torque after changing settings

## 4. Position, Velocity, and Torque Control Issues

**Problem:** No movement in position control

* Make sure target setpoint differs from current position
* Use correct unit: ticks, not degrees
* CPR must match the encoder used

**Problem:** Velocity setpoint has no effect

* Confirm that the velocity mode is selected
* Check if PID tuning is appropriate for your load

**Problem:** In torque control, motor draws too much current

* Set a proper `current_limit`
* Check for mechanical resistance or misalignment

## 5. Encoder and Feedback Problems

**Problem:** `get_position()` returns 0 or constant values

* Encoder might not be connected
* CPR not configured correctly
* Shaft may not be moving

**Problem:** Sudden jumps or noisy feedback

* Use shielded cables
* Avoid running encoder wires near power lines
* Add averaging/filtering logic in your application

## 6. Servo Control Issues

**Problem:** Servo doesn't move or jitters

* Make sure it's in `POSITION` mode
* Torque must be enabled
* CPR value should be appropriate (e.g., 4096 for 0–180° servos)

**Problem:** Set position command is ignored

* Use `set_position(module_id, angle, smd_id)`
* Ensure the angle is within valid range (0–180 degrees, mapped to ticks)

## 7. Watchdog and Safety Triggers

**Problem:** Motor stops after a few seconds

* Watchdog might be enabled and not refreshed
* Disable it during development using:

```python
master.set_watchdog(module_id, 0, smd_id)
```

**Problem:** Motor disabled after overload

* Check `get_error_flags()` for overcurrent or overtemperature
* Use `clear_errors()` if needed

## 8. Python SDK Usage Mistakes

**Common Errors:**

* Passing wrong `module_id` or `smd_id`
* Forgetting to attach the device
* Mixing up control modes (e.g., calling `set_duty_cycle` in `POSITION` mode)
* Not handling exceptions (wrap critical code in `try/except`)

## 9. Communication and Timing Issues

**Problem:** Communication timeout

* Try reducing loop frequency
* Add delays between high-frequency read/write operations
* Use `get_driver_info()` and `scan_modules()` to debug

**Problem:** Conflict with another serial device

* Ensure the port is not in use by other software (e.g., Arduino IDE)

## 10. Diagnostic and Debugging Tools

Use the following SDK functions to debug:

* `get_driver_info(smd_id)`
* `scan_modules(smd_id)`
* `get_position(module_id, smd_id)`
* `get_velocity(module_id, smd_id)`
* `get_current(module_id, smd_id)`
* `get_error_flags(module_id, smd_id)`

## 11. Environmental and Hardware Considerations

* Keep motor away from heat sources or enclosed areas
* Avoid long unshielded cables for encoders
* Check power supply stability under load
* Ensure RJ-11 connectors are fully seated

## 12. Best Practices and Preventive Tips

* Always initialize devices in proper order: attach → configure → enable
* Use retry logic when reading feedback
* Log sensor and motor states for debugging
* Perform PID tuning under real load conditions
* Keep firmware and SDK up-to-date
* Avoid forcing motors when torque is disabled

## Feedback

Found this page helpful? [Let us know](https://docs.acrome.net/help/reach-us) what you think.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.acrome.net/electronics/smd-red/troubleshooting-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.