# LLUAV SDK Troubleshooting Guide

## Connection Issues

### "Failed to connect to ws://<host>:53001"

**Symptoms**: `LLUAVConnectionError` immediately on `connect()`.

**Causes & Fixes**:
1. **Drone not reachable** — Verify network connectivity:
   ```bash
   ping <host>
   telnet <host> 53001
   ```
2. **Firewall blocking port 53001** — Ensure the drone's firewall allows inbound WebSocket connections.
3. **Wrong host/port** — Double-check the IP and port. Some firmware builds use a non-default port.
4. **Password mismatch** — If password protection is enabled but no password is provided, the server may immediately close the connection after the login failure.

### "Connection timeout"

**Symptoms**: `connect()` hangs and then raises timeout.

**Causes & Fixes**:
1. **High latency link** (e.g., 4G/5G telemetry) — Increase `timeout`:
   ```python
   client = LLUAVClient("192.168.1.100", timeout=30.0)
   ```
2. **Drone CPU overloaded** — The WebSocket server may be slow to respond if the flight controller is under heavy load. Check `sysinfo` after connecting.

### Continuous reconnection loop

**Symptoms**: Log shows "Reconnecting..." repeatedly every few seconds.

**Causes & Fixes**:
1. **Unstable network** — Check wireless signal strength. Consider using a dedicated ground-station radio instead of WiFi.
2. **Heartbeat too aggressive** — If the heartbeat command itself causes timeouts, increase `heartbeat_interval`:
   ```python
   client = LLUAVClient(..., heartbeat_interval=15.0)
   ```
3. **Server crashed** — The drone firmware may have restarted. Verify via ping.

### "Login first!"

**Symptoms**: Every command returns `ret=-1, msg="Login first!"`.

**Fix**: Provide the password in the constructor or call `login()` explicitly after connecting:
```python
client = LLUAVClient("192.168.1.100", password="your_password")
client.connect()  # auto-login happens here
```

---

## Command Queue & Timeout

### "Command timeout"

**Symptoms**: `LLUAVCommandError: Command timeout`.

**Causes & Fixes**:
1. **Command blocked by server** — Some commands (e.g., `savemap`, `preflight_check`) can take several seconds. Increase the per-command timeout:
   ```python
   client.save_map("/big_map", timeout=60.0)
   ```
2. **Queue congestion** — If many periodic tasks are registered with short intervals, the queue may grow faster than the drone can process. Reduce task frequency or remove unnecessary tasks.
3. **Server busy** — Check `get_statics()` for high CPU load or communication latency.

### "Max retries exceeded"

**Symptoms**: Command fails after 3 retries.

**Causes & Fixes**:
1. **Connection drops mid-flight** — The command was sent but the response was lost. The SDK retries automatically. If this happens frequently, check network stability.
2. **Command rejected by server** — If the server consistently returns `ret != 0`, the SDK does not retry (only network failures trigger retry). Check the error message.
3. **Too few retries** — Increase `max_retries`:
   ```python
   client = LLUAVClient(..., max_retries=5)
   ```

### Queue growing indefinitely

**Symptoms**: Memory usage increases over time; commands take longer and longer to complete.

**Causes & Fixes**:
1. **Periodic tasks too frequent** — Tasks are enqueued faster than the drone can respond. Increase interval or remove tasks.
2. **Blocking the caller** — In the sync Python client, calling `send_cmd(block=True)` from a tight loop without consuming the response can back up if the caller thread is slower than the queue drain. Use `block=False` and check the Future status.

---

## Flight Control Issues

### "Not allow when vehicle is ARMED!"

**Symptoms**: Command returns `ret=-1` with this message.

**Explanation**: The drone firmware blocks certain commands while the motors are armed. This is a safety feature.

**Affected commands**: `reboot_node`, `set_maplocate`, `set_mappath`, `disarm` (actually allowed), `savemap`, etc. See the `runOnArm` column in the firmware command table.

**Fix**: Only send these commands when disarmed, or use `land()` / `rtl()` first, then wait for disarm.

### "CMD not permitted to run in LOCK mode!"

**Symptoms**: Command rejected with this message.

**Explanation**: The server is in admin lock mode. Only commands marked `runInLock=true` are allowed for non-admin users.

**Fix**: Log in with admin password (`"1025"`) and call `admin_unlock()`.

---

## Language-Specific Issues

### Python: `ImportError: websocket-client is required`

**Fix**:
```bash
pip install websocket-client
# For async support:
pip install websockets
```

### Python Async: `RuntimeError: Event loop is closed`

**Cause**: Creating an `LLUAVAsyncClient` after the event loop has already been closed.

**Fix**: Ensure `asyncio.run()` or equivalent is active before calling `connect()`.

### C++: `websocketpp not found`

**Fix** (Ubuntu/Debian):
```bash
sudo apt install libwebsocketpp-dev nlohmann-json3-dev
```

### C++: Link errors mentioning `pthread`

**Fix**: Ensure CMake links Threads::Threads (already included in provided CMakeLists.txt).

### JavaScript: `WebSocket implementation not found`

**Fix**:
```bash
npm install ws
```

### Browser: `WebSocket connection failed`

**Cause**: Browsers enforce same-origin and mixed-content policies. Connecting to `ws://` from an `https://` page may be blocked.

**Fix**: Serve the page over `http://` or configure the drone with a TLS terminator for `wss://`.

---

## Performance Tuning

### Reducing command latency

1. **Disable heartbeat** if not needed behind a stable LAN:
   ```python
   client = LLUAVClient(..., heartbeat_interval=0)
   ```
2. **Shorten timeout** for fast commands on a reliable link:
   ```python
   client = LLUAVClient(..., timeout=3.0)
   ```

### Handling high-latency links (satellite / 4G)

1. **Increase timeout** to 30–60 seconds.
2. **Increase reconnect interval** to avoid flooding the network:
   ```python
   client = LLUAVClient(
       ...,
       timeout=30.0,
       reconnect_interval=5.0,
       max_reconnect_interval=120.0,
   )
   ```
3. **Reduce periodic task frequency** to avoid queue backlog.

---

## Logging & Debugging

### Enable SDK debug output

**Python**:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

**C++**: Rebuild with `DCMAKE_BUILD_TYPE=Debug` and add print statements in the callback handlers.

**JavaScript**:
```javascript
// Patch _processQueue to log
const orig = client._processQueue.bind(client);
client._processQueue = function() {
    console.log("Queue length:", client._queue.length);
    return orig();
};
```

### Capture raw protocol traffic

Use a WebSocket proxy or packet capture:
```bash
# Using wscat for manual inspection
npm install -g wscat
wscat -c ws://192.168.1.100:53001
> login your_password
> state
```
