LLUAV WebSocket Protocol Specification

This document describes the wire protocol used by the LLUAV drone firmware's built-in WebSocket server and consumed by the SDK clients.

Transport

Protocol: WebSocket (RFC 6455)
Default Port: 53001
Text Frames Only: All commands and responses are exchanged as UTF-8 text frames.

Client opens a WebSocket connection to ws://<host>:53001.
If password protection is enabled, the client must send login <password> before any other command.
The server processes commands in the order received and replies with one JSON response per command.
The server does not push unsolicited messages; every response is triggered by a client command.

A request is a single text frame containing a command name optionally followed by arguments:

cmd [args]

cmd: The command string (e.g., takeoff, state, set_param).
args: Command-specific arguments separated from cmd by a single space.
Scalar values are passed as-is: ledon, takeoff.
Compound arguments use colons (:) for ordered fields:
- set_sp_ned 1.0:2.0:-3.0:0.5
- test_wp 10.0:5.0:-2.0
Waypoint IDs or height lists use commas (,):
- zyhk 1.5,2.0,2.5
- mw_exec 1001:1,2,3,5
JSON payloads are sent as raw strings when the command detects leading {/[:
- mission 1001:{"waypoints":[...]}

login <password>

Special passwords: - "1025" → grants admin privileges. - Any other matching password → standard user. - "0315" → explicitly logs the session out.

Every command produces exactly one JSON response:

{
  "ret": 0,
  "cmd": 52,
  "ts": 1714233600000,
  ...
}

Field	Type	Description
`ret`	`int`	Return code. `0` = success. Negative values indicate errors.
`cmd`	`int`	Internal command enum ID (useful for correlation).
`ts`	`int64`	Response timestamp in milliseconds (Unix epoch).

On success, additional command-specific fields are included (see Command Reference below).

On failure:

{
  "ret": -1,
  "cmd": 52,
  "ts": 1714233600000,
  "msg": "Not allow when vehicle is ARMED!"
}

Code	Meaning
`0`	Success
`-1`	General failure (see `msg` for details)
`-2`	Invalid arguments / unsupported command
`-3`	External system call failed (e.g., `sysinfo()`, disk I/O)
`-100`	Unhandled exception during command processing

The server enforces two gate checks before executing a command:

Login Gate: If a password is configured and the session is not logged in, all commands except login return {"ret":-1,"msg":"Login first!"}.
Armed Gate: If the vehicle is armed, commands marked runOnArm=false return {"ret":-1,"msg":"Not allow when vehicle is ARMED!"}.
Lock Gate: If lockMode=true and the user is not admin, commands marked runInLock=false return {"ret":-1,"msg":"CMD not permitted to run in LOCK mode!"}.

Command	Args	Response Fields
`state`	—	`state`: full FSM state JSON
`param`	—	`param`: all parameters JSON
`get_param`	`name`	`param`: single parameter JSON
`ver`	—	`version`: version info JSON
`sysinfo`	—	`sysinfo`: uptime, RAM, loads
`diskusage`	—	`available_MB`: free space
`statics`	—	`comm`, `rosrecord`, `stat`, `node_boot_sec`
`machineid`	—	`did`: unique hardware ID
`hud1`	—	`kfs`, `uav_pos_enu`, `extra`
`lidarpose`	—	`lidar_pose`: `{x,y,z,yaw,roll,pitch,frame,usec}`
`apron_state`	—	`apron_status`, `apron_comm`
`mavlink_msgs`	—	`mav_msgs`: message name → count map
`get_submap_info`	—	`kfs`: map ID and keyframe count
`show_sp`	—	Current setpoint data
`show_apguid2`	—	`guid2`
`showmsg`	`[count]`	`msgs`: recent log messages

Command	Args	Description
`takeoff`	—	Initiate takeoff
`land`	—	Emergency land
`rtl`	—	Return to launch
`mrtl`	—	Mission RTL
`tether_land`	—	Tethered landing
`set_sp_ned`	`x:y:z:yaw`	Set NED setpoint (meters, radians)
`tunnelfly`	`0` or `1`	Enable/disable tunnel fly mode
`disarm`	—	Force disarm
`sleep`	—	Enter sleep mode
`wakeup`	—	Wake from sleep
`autosleep_enable`	`0` or `1`	Enable auto-sleep
`zyhk`	`h1,h2,... [lx,ly,lyaw]`	Multi-height hover then land
`relocate_pos`	`x,y,z,yaw`	Relocate position (requires map_locate enabled)

Command	Args	Description
`mission`	`ext_id:path_or_json`	Submit a mission
`plan`	`plan_string`	Start a flight plan
`unlock_plan`	—	Clear plan execution lock
`mw_list`	—	List mission waypoints
`mw_exec`	`ext_id:wp_ids`	Execute waypoint IDs (comma-separated)
`ai1_mission`	`task_id:mission_file`	Submit AI1 mission
`obs_mission`	`0` or `1`	Toggle obstacle mission live mode
`dump_missionresult`	`[ext_id]`	Dump mission result
`dump_missionlist`	—	Dump short mission request list
`abort_report`	`[abort_id]`	Abort/finish mission report
`set_taskname`	`name`	Set current task name

Command	Args	Description
`savemap`	`path`	Save current map
`set_maplocate`	`0` or `1`	Enable/disable map localization
`set_mappath`	`path`	Set localization map path
`list_maps`	—	List saved maps
`rm_map`	`name`	Remove a saved map

Command	Args	Description
`set_param`	`name:value`	Set parameter
`get_param`	`name`	Get single parameter
`reset_param`	—	Reset all to defaults
`save_param`	`0` or `1`	Save parameters persistently
`passwd`	`new_password`	Change WS login password

Command	Args	Description
`apron_vol`	`voltage`	Set charging voltage
`apron_amp`	`amperage`	Set charging amperage

Command	Args	Description
`grabber_ctrl`	`pwm`	Control grabber PWM
`ara8_center`	—	Set ARA8 to center mode
`ara8_pitch`	`angle`	Set ARA8 pitch (-90..90)
`cv_test`	—	Trigger CV server test
`preflight_check`	—	Run preflight checks
`preflight_enable`	`0` or `1`	Enable preflight before takeoff
`clear_bags`	`[min_gb]`	Clear old bag files
`clear_images`	`[min_gb]`	Clear old images
`list_imagedir`	`[size]`	List image directories
`rm_imagedir`	`name`	Remove image directory
`test_wp`	`x:y:z`	Test waypoint reachability
`test_listwp`	`file_path`	Test waypoint list from file
`test_notif`	—	Test notification server
`savemsg`	—	Save messages to log
`bms_setpower`	`0` or `1`	Set BMS power output
`bms_setcharge`	`0` or `1`	Set BMS charge state
`help`	—	List available commands
`admin_lock`	—	Enable admin lock (admin only)
`admin_unlock`	—	Disable admin lock (admin only)