# LLUAV SDK API Reference

## Common Constructor Options

All three language implementations accept the following configuration parameters:

| Option | Python | C++ | JS | Default |
|--------|--------|-----|-----|---------|
| `host` | `str` | `std::string` | `string` | `"localhost"` |
| `port` | `int` | `int` | `number` | `53001` |
| `password` | `str\|None` | `std::string` | `string\|null` | `None/""` |
| `timeout` | `float` (seconds) | `std::chrono::milliseconds` | `number` (ms) | `10s` |
| `auto_reconnect` | `bool` | `bool` | `boolean` | `True` |
| `reconnect_interval` | `float` (seconds) | `std::chrono::milliseconds` | `number` (ms) | `1s` |
| `max_reconnect_interval` | `float` (seconds) | `std::chrono::milliseconds` | `number` (ms) | `30s` |
| `max_retries` | `int` | `int` | `number` | `3` |
| `heartbeat_interval` | `float` (seconds) | `std::chrono::milliseconds` | `number` (ms) | `5s` |
| `heartbeat_cmd` | `str` | `std::string` | `string` | `"state"` |

---

## Connection Management

### `connect()` / `connect()` / `connect()`

Establish the WebSocket connection, start background worker threads/tasks, and automatically log in if a password is configured.

**Returns**: `None` (Py sync), `awaitable None` (Py async / C++ void / JS Promise<void>)

**Raises**:
- `LLUAVConnectionError` — if the initial connection or login fails.

### `disconnect()` / `disconnect()` / `disconnect()`

Gracefully close the connection, stop all background threads/tasks, and cancel/reject any pending commands in the queue.

**Returns**: `None` / `void` / `Promise<void>`

### `is_connected()` / `is_connected()` / `isConnected()`

Check whether the WebSocket is currently open and ready.

**Returns**: `bool`

---

## Core Send API

### `send_cmd(cmd, args, timeout, block)` / `send_cmd(cmd, args, timeout)` / `sendCmd(cmd, args, options)`

The fundamental API used by all high-level methods. Enqueues a command and waits for the JSON response.

**Parameters**:
- `cmd` (`str`) — Command name, e.g. `"takeoff"`.
- `args` (`str`, optional) — Command arguments string. Default `""`.
- `timeout` — Override the default timeout for this specific command.
- `block` (Python sync only) — If `True`, blocks until response. If `False`, returns a `concurrent.futures.Future`.

**Returns**:
- Python sync: `dict` if `block=True`, else `Future[dict]`.
- Python async: `dict`.
- C++: `nlohmann::json`.
- JS: `Promise<object>`.

**Raises**:
- `LLUAVConnectionError` — not connected and reconnect failed or disabled.
- `LLUAVCommandError` — server returned `ret != 0`, or command timed out / exceeded max retries.

---

## Periodic Task API

### `add_periodic_task(name, interval, cmd, args)` / `add_periodic_task(name, interval, cmd, args)` / `addPeriodicTask(name, intervalSec, cmd, args)`

Register a named periodic task. The SDK will automatically enqueue this command at the specified interval.

**Parameters**:
- `name` — Unique task identifier.
- `interval` — Interval in seconds.
- `cmd` — Command name.
- `args` — Command arguments (optional).

**Behavior**:
- Tasks are enqueued into the same FIFO queue as user commands, so they never interrupt an in-flight command on the wire.
- If the queue is backed up, the task may be delayed but will never be dropped.

### `remove_periodic_task(name)` / `remove_periodic_task(name)` / `removePeriodicTask(name)`

Unregister a previously added periodic task.

---

## Authentication

### `login(password)`

Explicitly authenticate with the given password. Usually not needed if `password` was provided to the constructor (auto-login handles it).

**Parameters**:
- `password` — The login password string.

### `admin_lock()` / `admin_unlock()`

Enable or disable admin lock mode. Requires admin privileges (password `"1025"`).

---

## State & Telemetry

| Method | Args | Description |
|--------|------|-------------|
| `get_state()` | — | Full FSM state JSON |
| `get_param(name)` | `name` (optional) | All params, or specific param by name |
| `get_version()` | — | Firmware version info |
| `get_sysinfo()` | — | Uptime, RAM, CPU load |
| `get_disk_usage()` | — | Available disk space (MB) |
| `get_statics()` | — | Comm stats, ROS record stats, node uptime |
| `get_machine_id()` | — | Unique hardware ID |
| `get_hud1()` | — | Submap info + UAV ENU pose + volume estimate |
| `get_lidar_pose()` | — | Lidar pose in ENU degrees |
| `get_apron_state()` | — | Charging pad status and comm stats |
| `get_mavlink_msgs()` | — | MAVLink message reception counts |
| `get_submap_info()` | — | Submap keyframe info |
| `show_setpoint()` | — | Current setpoint |
| `show_ap_guid2()` | — | AP GUID2 |
| `show_msg(count)` | `count` (default -1) | Recent log messages |

---

## Flight Control

| Method | Args | Description |
|--------|------|-------------|
| `takeoff()` | — | Command takeoff |
| `land()` | — | Emergency land |
| `rtl()` | — | Return to launch |
| `mission_rtl()` | — | Mission RTL |
| `tether_land()` | — | Tethered landing |
| `set_sp_ned(x, y, z, yaw)` | 4 floats | Set NED setpoint (meters, radians) |
| `relocate_pos(x, y, z, yaw)` | 4 floats | Relocate position (requires map_locate) |
| `tunnel_fly(enable)` | `bool` | Enable/disable tunnel fly |
| `disarm()` | — | Force disarm |
| `sleep()` | — | Enter sleep mode |
| `wakeup()` | — | Wake from sleep |
| `auto_sleep_enable(enable)` | `bool` | Enable auto-sleep |
| `zyhk(heights, land_x, land_y, land_yaw)` | `list<float>`, floats | Multi-height hover mission |

---

## Mission Management

| Method | Args | Description |
|--------|------|-------------|
| `mission(ext_id, path_or_json)` | `int`, `str` | Submit mission with external ID |
| `start_plan(plan_str)` | `str` | Start a flight plan |
| `unlock_plan()` | — | Clear plan execution lock |
| `mission_wp_list()` | — | Get mission waypoint list |
| `mission_wp_exec(ext_id, wp_ids)` | `int`, `str` | Execute comma-separated waypoint IDs |
| `ai1_mission(task_id, mission_file)` | `str`, `str` | Submit AI1 mission |
| `obs_mission(enable)` | `bool` | Toggle obstacle mission live |
| `dump_mission_result(ext_id)` | `int` (optional) | Dump result by ext ID |
| `dump_mission_list()` | — | Dump short mission list |
| `abort_report(abort_id)` | `int` (default -1) | Finish/abort mission report |
| `set_taskname(name)` | `str` | Set task name |

---

## Map Management

| Method | Args | Description |
|--------|------|-------------|
| `save_map(path)` | `str` | Save current map |
| `set_map_locate(enable)` | `bool` | Enable/disable map localization |
| `set_map_path(path)` | `str` | Set localization map path |
| `list_maps()` | — | List saved maps |
| `rm_map(name)` | `str` | Remove a saved map |

---

## Camera & Recording

| Method | Args | Description |
|--------|------|-------------|
| `capture()` | — | Capture single photo (RGB + IR) |
| `snapshot()` | — | System snapshot |
| `record_toggle()` | — | Toggle video recording |
| `savebag(start)` | `bool` | Start/stop ROS bag recording |
| `siyi_reboot()` | — | Reboot SIYI camera/gimbal |
| `siyi_format()` | — | Format SIYI SD card |
| `siyi_center()` | — | Center SIYI gimbal |
| `siyi_init()` | — | Initialize SIYI (close HDMI) |
| `siyi_downvideo(vid)` | `int` (default -1) | Download latest video |
| `siyi_sync()` | — | Trigger SIYI sync |

---

## LED Control

| Method | Args | Description |
|--------|------|-------------|
| `led_on()` / `led_off()` | — | Turn LED on/off |
| `led_enable()` / `led_disable()` | — | Enable/disable LED control |
| `led_pwm(pwm)` | `int` | Set LED PWM |
| `led_blink()` | — | Start LED blinking |

---

## Parameter Management

| Method | Args | Description |
|--------|------|-------------|
| `set_param(name, value)` | `str`, value | Set parameter |
| `get_param_value(name)` | `str` | Get single parameter |
| `reset_params()` | — | Reset all to defaults |
| `save_params(force)` | `bool` | Save persistently |
| `change_password(new_password)` | `str` | Change WS password |

---

## Apron (Charging Pad)

| Method | Args | Description |
|--------|------|-------------|
| `set_apron_vol(voltage)` | `float` | Set charging voltage |
| `set_apron_amp(amperage)` | `float` | Set charging amperage |

---

## System Management

| Method | Args | Description |
|--------|------|-------------|
| `reboot_node()` | — | Reboot flight control node |
| `reboot_ap()` | — | Reboot autopilot |
| `reboot_system()` | — | Reboot onboard computer |
| `poweroff_system()` | — | Power off onboard computer |
| `prepare_poweroff()` | — | Flush logs before poweroff |
| `reboot_dlo()` | — | Reboot DLO |
| `restart_dlo()` | — | Restart DLO pipeline |
| `kill_livox(script)` | `str` (optional) | Kill Livox driver |

---

## Lidar & Perception

| Method | Args | Description |
|--------|------|-------------|
| `lidar_onoff(on)` | `bool` | Turn lidar on/off |
| `lidar_warn()` | — | Get lidar warning zones |
| `utg_get()` | — | Trigger UTG thickness read |
| `utg_set(speed)` | `int` | Set UTG sonic speed |

---

## Other

| Method | Args | Description |
|--------|------|-------------|
| `grabber_ctrl(pwm)` | `int` | Control grabber PWM |
| `ara8_center()` | — | Set ARA8 to center |
| `ara8_pitch(angle)` | `int` | Set ARA8 pitch angle |
| `cv_test()` | — | Trigger CV test |
| `preflight_check()` | — | Run preflight checks |
| `preflight_enable(enable)` | `bool` | Enable preflight before takeoff |
| `clear_bags(min_gb)` | `int` (default -1) | Clear old bag files |
| `clear_images(min_gb)` | `int` (default -1) | Clear old images |
| `list_imagedir(size)` | `int` (default -1) | List image directories |
| `rm_imagedir(name)` | `str` | Remove image directory |
| `test_wp(x, y, z)` | 3 floats | Test waypoint reachability |
| `test_wp_list(file_path)` | `str` | Test waypoint list from file |
| `save_msg()` | — | Save messages to log |
| `bms_setpower(on)` | `bool` | Set BMS power |
| `bms_setcharge(on)` | `bool` | Set BMS charge |
| `help()` | — | List available commands |
