UAV API

HTTP REST API for controlling ArduPilot-compatible UAVs. Supports real drones via MAVLink and simulated drones via ArduPilot SITL. Plane support is in beta — see Vehicle Types below.

Features:

Multi-vehicle: ArduCopter (stable) and ArduPlane (beta), selected at startup via --vehicle
Full flight control: arm, takeoff, land, RTL, speed configuration
GPS and NED movement commands (fire-and-forget and blocking variants), heading control
Rich telemetry: GPS, NED position, compass, battery, sensor health
Mission scripting: upload, list, and execute .py/.sh scripts remotely (copter mode)
Gradys Ground Station integration: periodic GPS location push
Visual feedback via Mission Planner or any MAVLink GCS
Hardware peripherals: camera capture, servo PWM output (copter mode)
Configurable logging per component

Documentation
Installation
Getting Started
CLI Arguments Reference
Extra Features
Project Architecture
Flying through scripts

Documentation

This README covers installation, running the API, the CLI reference and the example clients. Reference material lives under docs/:

Document	Contents
`docs/api-specification.md`	The HTTP contract. Every endpoint's path, query/body schema and response shape. This is what the GrADyS ecosystem codes against — update it before changing an endpoint.
`docs/coordinate-frames.md`	GPS vs NED vs NED-velocity, why `z` is negative for altitude, and common MAVLink pitfalls. Read before writing movement logic.
`docs/plane-support.md`	Plane (beta) endpoint reference and how its behaviour differs from copter.
`docs/deployment.md`	Running the API as a systemd service on a companion computer, and fleet provisioning.

Installation

Prerequisites

Python 3.10+
For simulated flights: ArduPilot repository built locally, and xterm installed — unless you pass --headless, which needs no X server at all.
- Clone and build ArduPilot: https://ardupilot.org/dev/docs/where-to-get-the-code.html
- SITL setup guide: https://ardupilot.org/dev/docs/SITL-setup-landingpage.html
- ArduPilot's Tools/autotest directory should be on your PATH so sim_vehicle.py can be found — see Registering ArduPilot in PATH. Otherwise, point the API at the repository with --ardupilot_path.
For mission scripts: tmux installed. This applies on real drones too — each script runs in its own tmux session, in simulation and on hardware alike.

Installing from PyPI (recommended)

pip install uav-api

Restart your terminal after installation.

Installing from source (development)

git clone https://github.com/Project-GrADyS/uav_api
cd uav_api
pip install -e .

Restart your terminal after installation.

Getting Started

Running with a real drone

Connect your drone via UDP or USB, then start the API:

uav-api --port 8000 --uav_connection 127.0.0.1:17171 --connection_type udpin --sysid 1

The --connection_type controls the UDP direction:

udpin — API listens, drone connects to it (most common)
udpout — API connects out to the drone
usb — serial connection (set --uav_connection to the serial device path, e.g. /dev/ttyUSB0)

Deploying on hardware

The command above is for bringing a vehicle up by hand. For a companion computer that should start the API automatically on boot, install it as a systemd service — reference unit and config are in packaging/:

Substitute the __USER__ / __VENV__ / __CONFIG__ / __HOME__ placeholders in the unit, then:

sudo install -m 0644 packaging/systemd/uav-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now uav-api
journalctl -u uav-api -f

The API creates its own working directories on startup — scripts_path, script_logs, and the parent of log_path — so the deployment only has to make sure the service user can write to them.

For a fleet of drones, use gradys-fleet, which provisions companion computers from a blank image and manages every vehicle's identity, configuration and services from a single inventory. It also handles gradys-embedded, pre-flight verification and post-flight data collection. It renders the two files above per drone, so keep the copies in packaging/ in step with the templates there.

scripts/install_service.sh is deprecated. It assumes a machine that was already prepared by hand and is single-drone by construction.

See docs/deployment.md for the full guide — configuration notes, why the unit is written the way it is, and troubleshooting.

Running in simulation (SITL)

This starts both ArduCopter SITL (in a new xterm window) and the API — see Running headless for the no-window variant:

uav-api --simulated true --speedup 1 --port 8000 --sysid 1

SITL will bind to the address in --uav_connection (default 127.0.0.1:17171). The --speedup factor controls simulation speed (e.g. 5 = 5× real time). The --location argument sets the SITL home position (default AbraDF).

Running headless

--headless runs the same simulation without opening any window, so it works on a machine with no X server — CI, a remote box, or over SSH:

uav-api --simulated true --headless --speedup 1 --port 8000 --sysid 1

This does three things, and all three are required:

uav_api stops wrapping sim_vehicle.py in xterm.
It removes DISPLAY (along with SITL_RITW_TERMINAL, TMUX, STY and ZELLIJ) from the environment it hands to SITL. ArduPilot's run_in_terminal_window.sh launches the vehicle binary in whatever terminal those variables point at, and only runs it in the background when none are set — without the scrub you would still get a window on a desktop.
It passes --mavproxy-args=--daemon, so MAVProxy starts without an interactive shell. This one is not cosmetic: MAVProxy treats EOF on stdin as a request to quit, and sim_vehicle.py exits when MAVProxy does, so a headless SITL without it dies within milliseconds of starting.

A consequence of (3): there is no MAV> prompt to type commands into. In headless mode the log file below is your only view into SITL.

Since there is no terminal to read, output is written to files instead:

Output	Location
`sim_vehicle.py` and MAVProxy	`~/uav_api_logs/ardupilot_logs/sitl_<sysid>.log`
The vehicle binary (`ArduCopter`/`ArduPlane`)	`/tmp/<vehicle>.log`, chosen by ArduPilot

The vehicle binary's path is ArduPilot's choice, not uav_api's, and it does not include the sysid — several headless instances on one host will write over each other there. The per-sysid sitl_<sysid>.log is unaffected.

Locating ArduPilot (`--ardupilot_path`)

Simulated mode launches SITL through ArduPilot's sim_vehicle.py script. How that script is located depends on whether --ardupilot_path is provided:

`--ardupilot_path`	How `sim_vehicle.py` is resolved
omitted (default)	The bare command `sim_vehicle.py` is executed, so it is resolved through the `PATH` environment variable. This requires ArduPilot's `Tools/autotest` directory to be registered in `PATH`.
provided	The script is resolved explicitly as `<ardupilot_path>/Tools/autotest/sim_vehicle.py`. `~` is expanded, and `PATH` is ignored.

# Default — sim_vehicle.py comes from PATH
uav-api --simulated true --port 8000 --sysid 1

# Explicit — use this ArduPilot repository, regardless of PATH
uav-api --simulated true --ardupilot_path ~/ardupilot --port 8000 --sysid 1

Use --ardupilot_path when ArduPilot is not on your PATH, or when you keep several ArduPilot checkouts and want to select one per API instance.

If neither applies — no --ardupilot_path and no sim_vehicle.py on PATH — SITL exits immediately and the API aborts startup with SITL failed to initialize.

Registering ArduPilot in PATH

Append ArduPilot's Tools/autotest directory to PATH in your shell profile (~/.bashrc, or ~/.zshrc for zsh), replacing ~/ardupilot with your clone location:

echo 'export PATH=$PATH:$HOME/ardupilot/Tools/autotest' >> ~/.bashrc
source ~/.bashrc

ArduPilot's own environment installer (Tools/environment_install/install-prereqs-ubuntu.sh) adds this line for you, so if you followed the official SITL setup guide it is likely already done.

Verify it worked:

which sim_vehicle.py
# /home/<user>/ardupilot/Tools/autotest/sim_vehicle.py

If the command prints nothing, the directory is not on PATH — fix the export or pass --ardupilot_path instead.

Vehicle Types

The API supports two ArduPilot vehicles, selected at startup with --vehicle:

Vehicle	Flag	Status
ArduCopter (QuadCopter)	`--vehicle copter` (default)	Stable — full router surface, integration tests pass.
ArduPlane / QuadPlane	`--vehicle plane`	Beta

⚠️ Beta: Plane support is in beta — some functionalities may not work as intended. The plane endpoint surface is intentionally smaller than copter (no /mission/*, no /peripherical/*, fewer movement endpoints) and there are no integration tests yet. Treat as preview. Full details in docs/plane-support.md.

Run as plane in simulation:

uav-api --vehicle plane --simulated true --speedup 1 --port 8000 --sysid 1

This spawns ArduPlane SITL (instead of ArduCopter) and registers only the plane routers. Consumer URLs are unchanged — /command/arm, /movement/go_to_gps, /telemetry/gps work the same way; the endpoint set is smaller. Plane mode exposes:

/command/arm, /command/disarm, /command/takeoff?alt&pitch_deg&vtol, /command/land, /command/rtl, /command/set_home
POST /movement/go_to_gps, POST /movement/go_to_gps_wait, POST /movement/land_at, GET /movement/stop
/telemetry/general, /telemetry/gps, /telemetry/battery_info, /telemetry/sensor_status, /telemetry/error_info, /telemetry/home_info

Calls to copter-only routes (/mission/*, /peripherical/*, /movement/go_to_ned, etc.) return HTTP 404 in plane mode.

Logging in different vehicles

The CLI token used in --log_console and --debug is the vehicle-agnostic VEHICLE — the same flag value regardless of --vehicle. The internal logger that emits the records, however, is named after the vehicle: COPTER or PLANE. The console formatter prints [<logger>-<sysid>] as the prefix, so what you actually see depends on --vehicle:

# Copter (default)
uav-api --simulated true --log_console VEHICLE ...
# console: [COPTER-1] INFO - Sending COMMAND_LONG ...

# Plane (beta)
uav-api --vehicle plane --simulated true --log_console VEHICLE ...
# console: [PLANE-1] INFO - Sending COMMAND_LONG ...

In short: pass VEHICLE, expect to see COPTER or PLANE in the printed lines.

Using a configuration file

All arguments can be provided via an INI file:

[api]
port=8000
uav_connection=127.0.0.1:17171
connection_type=udpin
sysid=1

[simulated]
ardupilot_path=~/ardupilot
location=AbraDF
speedup=1

[logs]
log_console=[VEHICLE, UVICORN]

Run with:

uav-api --config /path/to/config.ini

Values in the config file override CLI arguments. The file is read after the command line is parsed, and every key it contains is written over the parsed value — so uav-api --config drone.ini --port 9000 still listens on the port set in the file.

Only write the keys you actually want to change; omitting a key gives you its default. In particular, do not write None as a value: INI values are read as strings, so log_path = None produces a log file literally named None rather than the default path.

Boolean keys (simulated, udp, headless) accept true/false, yes/no, on/off or 1/0, in any case. Anything else is rejected at startup rather than guessed at.

Example config files for single and multi-UAV simulated setups are available at flight_examples/uavs/uav_1.ini and uav_2.ini. For a real drone, start from packaging/uav-api.ini.example.

ardupilot_path is optional here too — drop the key to resolve sim_vehicle.py from PATH.

The mere presence of a [simulated] section turns simulated mode on, whatever the section contains. An explicit simulated = false key overrides that, since keys are applied after the section is detected — but a real-drone config is clearest with no [simulated] section at all.

Spawning programmatically

You can start the API from Python code using spawn_with_args, which runs the server in a background process:

from uav_api.run_api import spawn_with_args

# Start a simulated UAV API on port 8001
process = spawn_with_args([
    "--simulated", "true",
    "--speedup", "5",
    "--port", "8001",
    "--sysid", "1",
])

# ... interact with the API at http://localhost:8001 ...

# Shut down
process.terminate()
process.join(timeout=15)

spawn_with_args accepts the same arguments as the uav-api CLI and returns a multiprocessing.Process. For a blocking call (e.g. when building your own entry point), use run_with_args instead:

from uav_api.run_api import run_with_args

# Blocks until the server is stopped (Ctrl+C)
run_with_args(["--port", "8000", "--sysid", "1"])

Verifying the API

Open the interactive Swagger UI in your browser:

http://localhost:<port>/docs

Scroll to the telemetry router and call GET /telemetry/general:

A successful response confirms the API is connected to the vehicle:

CLI Arguments Reference

All arguments can be passed on the command line or set in an INI config file. Run uav-api --help for a quick reference. Note that when both are used, values in the config file win.

General (all modes)

Argument	Default	Description
`--config`	None	Path to INI config file (`[api]`, `[simulated]`, `[logs]` sections)
`--vehicle`	`copter`	`copter` (default) or `plane` (beta). Selects which routers register and which ArduPilot SITL spawns. See Vehicle Types.
`--port`	8000	HTTP port the API listens on
`--sysid`	10	MAVLink system ID; must match the drone's `SYSID_THISMAV` parameter
`--uav_connection`	`127.0.0.1:17171`	MAVLink address — `host:port` for UDP, or serial device path for USB
`--gradys_gs`	None	`host:port` of Gradys Ground Station — enables periodic GPS location push
`--scripts_path`	`~/uav_scripts`	Directory where uploaded scripts are saved and executed from (copter mode). Created at startup if missing.
`--python_path`	`python3`	Python binary used to run uploaded `.py` scripts

Connection (real drone)

Argument	Default	Description
`--connection_type`	`udpin`	`udpin` — API listens; `udpout` — API connects out; `usb` — serial

Simulation only

Argument	Default	Description
`--simulated`	`false`	Set to `true` to spawn ArduPilot SITL alongside the API (binary is `ArduCopter` or `ArduPlane` depending on `--vehicle`)
`--ardupilot_path`	`None`	Path to local ArduPilot repository. When omitted, `sim_vehicle.py` is resolved from the `PATH` environment variable; when set, SITL is launched from `<ardupilot_path>/Tools/autotest/sim_vehicle.py`. See Locating ArduPilot.
`--location`	`AbraDF`	Named home position for SITL (defined in `~/.config/ardupilot/locations.txt`)
`--speedup`	1	SITL simulation time multiplier
`--gs_connection`	`[]`	Extra `host:port` addresses SITL streams telemetry to (e.g. Mission Planner)
`--headless`	`false`	Run SITL without opening any terminal window; requires no X server. Output goes to `~/uav_api_logs/ardupilot_logs/sitl_<sysid>.log`. See Running headless.

Logging

Argument	Default	Description
`--log_console`	`[]`	Components to print logs to console: `VEHICLE` `UVICORN` `GRADYS_GS` `SCRIPT`. `VEHICLE` is vehicle-agnostic — see Logging in different vehicles for the prefix actually printed.
`--log_path`	`~/uav_api_logs/uav_logs/uav_<sysid>.log`	File path to write all component logs combined. Its parent directory is created at startup.
`--debug`	`[]`	Same component names as `--log_console` but at DEBUG verbosity
`--script_logs`	`~/uav_api_logs/script_logs`	Directory where script stdout/stderr are saved as timestamped `.log` files. Created at startup if missing.

The API creates the directories it needs at startup — scripts_path, script_logs, and the parent of log_path — whether the path came from the default or from a config file, expanding ~ along the way. Nothing has to pre-create them for it.

UDP/QUIC mode

Argument	Default	Description
`--udp`	`false`	Use Hypercorn with QUIC/HTTP3 (UDP) instead of Uvicorn (TCP)
`--certfile`	None	Path to TLS certificate PEM file. Auto-generated self-signed cert if omitted.
`--keyfile`	None	Path to TLS private key PEM file. Auto-generated if omitted.

QUIC requires TLS. When --udp is set without --certfile/--keyfile, self-signed certs are auto-generated in ~/uav_api_certs/.

Starting the API in UDP/QUIC mode:

uav-api --udp --simulated true --port 8000 --sysid 1

Consuming the API over HTTP/3 (QUIC):

Since QUIC uses UDP and TLS, clients must support HTTP/3. Install niquests:

pip install niquests

import niquests

base_url = "https://localhost:8000"

session = niquests.Session(verify=False)
response = session.get(f"{base_url}/telemetry/general")
print(response.json())
session.close()

See the flight examples section below — all examples support HTTP/3 via the --h3 flag.

Note: The API uses HTTPS (not HTTP) in UDP mode because QUIC requires TLS. The Swagger UI at https://localhost:<port>/docs also works — your browser may warn about the self-signed certificate.

Extra Features

Gradys Ground Station Integration

When --gradys_gs <host:port> is set, the API starts a background coroutine that POSTs the vehicle's GPS position to the Gradys GS every second:

uav-api --port 8000 --sysid 1 --gradys_gs 192.168.1.10:5000

Each POST to http://<gradys_gs>/update-info/ includes: latitude, longitude, altitude, device type, a sequence number, and the API's own IP and port. This allows the Gradys ecosystem to track the UAV in real time.

Visual Feedback with Mission Planner

When running in simulated mode, use --gs_connection to stream MAVLink telemetry to Mission Planner (or any GCS software):

uav-api --simulated true --sysid 1 --gs_connection [192.168.1.5:14550]

Connect Mission Planner to the specified UDP address to see live position, attitude, and flight data.

Logging System

Control what gets logged and where with the logging arguments:

# Print VEHICLE and UVICORN logs to console
uav-api --log_console VEHICLE UVICORN ...

# Write all logs to a file
uav-api --log_path ~/uav_api.log ...

# Enable DEBUG verbosity for the VEHICLE component
uav-api --debug VEHICLE ...

# Save script stdout/stderr to a directory
uav-api --script_logs ~/uav_api_logs/script_logs ...

Available log components: VEHICLE, UVICORN, GRADYS_GS, SCRIPT. The VEHICLE token routes to the active vehicle's logger; the actual line prefix you see is [COPTER-<sysid>] or [PLANE-<sysid>] depending on --vehicle — see Logging in different vehicles.

Mission Script Management

The API can host and execute Python or shell scripts on the UAV's companion computer. This is useful for deploying autonomous mission logic remotely.

Upload a script:

POST /mission/upload-script   (multipart form, field: file)

Accepts .py and .sh files. Saved to --scripts_path (default ~/uav_scripts).

List uploaded scripts:

GET /mission/list-scripts

Execute a script:

POST /mission/execute-script/
Body: {"script_name": "my_script"}

Each execution gets its own tmux session named UAV_API_<sysid>-<script>-<timestamp> (the script's . is replaced with _). The session is owned by the script process — when the script exits, the session closes automatically. Re-running the same script while it is already running returns HTTP 400. Attach to a session for live output:

tmux attach -t UAV_API_1-my_script_py-20260528_143012

If --script_logs is set, stdout and stderr are saved as:

<script_logs>/<name>_<timestamp>_out.log
<script_logs>/<name>_<timestamp>_err.log

List currently running scripts:

GET /mission/running-scripts

Returns each running script along with its tmux session name, start timestamp, and log paths. Stopped entries are retained internally but not shown here.

Stop a running script:

POST /mission/stop-script/
Body: {"script_name": "my_script"}

Sends Ctrl+C to the tmux session (so the script can run any finally / atexit cleanup — e.g. land the drone), waits briefly, then kills the session. Returns HTTP 404 if the script is unknown to the API, or 400 if it is no longer running.

Clear uploaded scripts:

DELETE /mission/clear-scripts

Deletes all .py and .sh files from --scripts_path. Does not affect running scripts.

A background task in the API lifespan polls tmux every ~2s and marks scripts as stopped in an in-memory table as soon as their session ends, so running-scripts always reflects live state.

Camera Peripheral

Take a photo using a whitelisted camera CLI tool. The chosen tool must be installed on the system:

Tool	Install	Notes
`fswebcam`	`sudo apt install fswebcam`	USB webcams on Linux
`rpicam-still`	Pre-installed on Raspberry Pi OS Bookworm+	Modern Raspberry Pi camera
`libcamera-still`	`sudo apt install libcamera-apps`	Generic libcamera (Pi and other boards)

Endpoint: GET /peripherical/take_photo

Parameter	Default	Description
`command`	(required)	One of: `fswebcam`, `rpicam-still`, `libcamera-still`
`resolution`	`1280x720`	Capture resolution (`WIDTHxHEIGHT`)
`capture_time`	`150`	Warm-up / exposure delay in milliseconds

Examples:

# USB webcam with fswebcam
curl "http://localhost:8000/peripherical/take_photo?command=fswebcam" --output photo.jpg

# Raspberry Pi camera at 1920x1080
curl "http://localhost:8000/peripherical/take_photo?command=rpicam-still&resolution=1920x1080" --output photo.jpg

# libcamera with 500ms warm-up
curl "http://localhost:8000/peripherical/take_photo?command=libcamera-still&capture_time=500" --output photo.jpg

Returns the image as image/jpeg (Content-Disposition: attachment; filename="photo.jpg").

Servo Output

Send a PWM signal to a servo motor connected to one of the flight controller's actuator ports. Uses the MAVLink DO_SET_SERVO command.

Endpoint: POST /peripherical/servo_output

Request body:

Field	Type	Description
`channel`	int	Servo channel (1-based, matches the flight controller actuator port)
`pwm`	int	PWM value in microseconds (typically 1000–2000)

Example:

curl -X POST "http://localhost:8000/peripherical/servo_output" \
  -H "Content-Type: application/json" \
  -d '{"channel": 9, "pwm": 1500}'

Response:

{"device": "uav", "id": "1", "result": "Servo 9 set to 1500 PWM"}

Project Architecture

Module Map

Path	Purpose
`uav_api/run_api.py`	CLI entry point — parses args, runs setup, launches uvicorn
`uav_api/api_app.py`	FastAPI app definition; conditional router registration by `--vehicle`; imports lifespan from `lifespan.py`
`uav_api/lifespan.py`	Async lifespan context manager — startup/shutdown of SITL, drain loop, scripts watcher, and GS task, with partial-startup cleanup
`uav_api/vehicles/copter.py`	Copter MAVLink wrapper — full GUIDED surface (~1850 lines)
`uav_api/vehicles/plane.py`	Plane MAVLink wrapper (beta) — GUIDED + TAKEOFF-mode takeoff, QuadPlane helpers
`uav_api/args.py`	CLI argument parsing; config serialized to `UAV_ARGS` env var
`uav_api/routers/router_dependencies.py`	Lazy singletons `get_copter_instance` / `get_plane_instance` + `args` via `Depends()`
`uav_api/gradys_gs.py`	Async coroutine that POSTs GPS location to Gradys GS every second
`uav_api/log.py`	Logger configuration; routes `VEHICLE` token to `COPTER`/`PLANE` logger based on `--vehicle`
`uav_api/setup.py`	Idempotent startup setup — creates the scripts, script-log and log directories (defaulted or configured) plus the ArduPilot locations file
`uav_api/routers/copter_command.py`	Copter endpoints: arm, takeoff, land, RTL, speed, home
`uav_api/routers/copter_movement.py`	Copter endpoints: go_to_gps, go_to_ned, drive (fire-and-forget + blocking pairs), set_heading
`uav_api/routers/copter_telemetry.py`	Copter endpoints: GPS, NED, compass, battery, sensor status, home info
`uav_api/routers/copter_mission.py`	Copter endpoints: upload-script, list-scripts, execute-script, running-scripts, stop-script, clear-scripts
`uav_api/routers/copter_peripherical.py`	Copter endpoints: take_photo, servo_output
`uav_api/routers/plane_command.py`	Plane endpoints (beta): arm, disarm, takeoff, land, RTL, set_home
`uav_api/routers/plane_movement.py`	Plane endpoints (beta): go_to_gps, go_to_gps_wait, land_at, stop
`uav_api/routers/plane_telemetry.py`	Plane endpoints (beta): general, GPS, battery, sensor status, error, home info
`uav_api/classes/movement.py`	Pydantic models: `Gps_pos`, `Local_pos`, `Local_velocity`
`uav_api/classes/peripherical.py`	Pydantic model: `Servo_output`
`uav_api/classes/attitude.py`	Pydantic model: `Attitude_target` (used internally by `Plane.set_attitude()`)
`uav_api/classes/script.py`	Pydantic model: `Script`
`flight_examples/`	Example client scripts and INI config files (Copter)
`packaging/systemd/uav-api.service`	Canonical systemd unit for running the API on a companion computer
`packaging/uav-api.ini.example`	Canonical real-drone INI config example
`scripts/install_service.sh`	Deprecated single-drone installer — see Deploying on hardware

Processes and Coroutines

The application lifecycle is managed by a FastAPI @asynccontextmanager lifespan. The following are started on API startup and stopped on shutdown:

Always started

uvicorn HTTP server Launched by uav_api/run_api.py. All processes below run within its lifetime.

MAVLink drain loop An asyncio task running copter.run_drain_mav_loop(). Continuously drains buffered MAVLink messages to prevent connection stalls. Cancelled on shutdown.

Conditional: simulated mode (`--simulated true`)

ArduPilot SITL process Spawned as xterm -e sim_vehicle.py -v {ArduCopter|ArduPlane} ... subprocess (the vehicle binary is chosen by --vehicle). Tagged with a unique environment variable (UAV_SITL_TAG=SITL_ID_<sysid>). On shutdown, all system processes carrying that tag are killed via psutil, ensuring clean teardown even if xterm spawned child processes.

Conditional: Gradys GS integration (`--gradys_gs` is set)

GS location push coroutine An asyncio task running send_location_to_gradys_gs() (defined in uav_api/gradys_gs.py). POSTs the vehicle's GPS position to http://<gradys_gs>/update-info/ every second using a shared aiohttp.ClientSession. Task is cancelled and the session is closed on shutdown.

Dependency Injection

Module-level singletons in uav_api/routers/router_dependencies.py hold one Copter, one Plane, and one parsed args namespace. Routers pick the right one via FastAPI's Depends():

Depends(get_copter_instance)  # shared Copter (copter routers; one MAVLink connection)
Depends(get_plane_instance)   # shared Plane  (plane routers; one MAVLink connection)
Depends(get_scripts_table)    # table with script execution information
Depends(get_args)             # parsed CLI/config arguments

Only one vehicle singleton is instantiated per process — the one matching --vehicle. CLI arguments are serialized to JSON in the UAV_ARGS environment variable before uvicorn forks, allowing all processes to access the same configuration without re-parsing.

API Response Format

All successful responses follow a uniform envelope:

{"device": "uav", "id": "<sysid>", "result": "..."}

Telemetry endpoints add an "info": {...} field with the sensor data. All errors raise HTTP 500 with a descriptive "detail" string.

Flying through scripts

One of the perks of using UAV API is being able to quickly write scripts that control drone movement. Here are some examples.

Running examples

To run the following examples, start the API inside the flight_examples directory:

uav-api --config ./uavs/uav_1.ini

Note that this configuration file contains default values for parameters, change the values such that it matches your environment. You can also use your own configuration file or start the API through arguments.

Once the API is up and running, run one of the examples below in a new terminal instance. All examples run with zero arguments using sensible defaults, but every parameter is configurable via command-line flags.

Common Pattern

All flight examples share a helper module (flight_examples/flight_helpers.py) that provides:

add_common_args(parser) — adds --url, --altitude, --h3, and --certfile to any argparse parser, all with defaults.
create_session(args) — returns a requests.Session (HTTP) or niquests.Session (HTTP/3 over QUIC when --h3 is set).
send_command(session, base_url, endpoint, ...) — sends GET/POST requests, checks status codes, and exits on failure.
get_home_ned(session, base_url) / get_home_gps(session, base_url) — captures the current position as a home reference (call after arming, before takeoff).
ned_relative_to_absolute(relative, home) — converts a home-relative NED point to absolute coordinates.
wait_for_arrival(session, base_url, target, ...) — polls /telemetry/ned until the drone is within tolerance of the target.
setup_graceful_shutdown(session, base_url) — registers a Ctrl+C handler that sends RTL before exiting.

Key conventions:

NED coordinates are specified relative to the home position (captured after arming, before takeoff). The script converts them to absolute coordinates when sending commands.
GPS altitude is relative to the home altitude captured at startup.
HTTP/3 is supported by all examples via the --h3 flag (requires niquests and TLS certs from the --udp mode).
Ctrl+C triggers RTL (Return to Launch) for safe shutdown.

Simple Takeoff and Landing

The simplest example — arm, take off, and land. This file is located at flight_examples/takeoff_land/takeoff_land.py.

"""Takeoff and land — the simplest flight example."""

import sys
import os
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from flight_helpers import add_common_args, get_base_url, create_session, send_command, setup_graceful_shutdown

parser = argparse.ArgumentParser(description="Arm, take off, and land.")
add_common_args(parser)
args = parser.parse_args()

base_url = get_base_url(args)
session = create_session(args)
setup_graceful_shutdown(session, base_url)

# Arm
send_command(session, base_url, "/command/arm")
print("Vehicle armed.")

# Take off
send_command(session, base_url, "/command/takeoff", params={"alt": args.altitude})
print(f"Vehicle took off to {args.altitude}m.")

# Land
send_command(session, base_url, "/command/land")
print("Vehicle landed.")

NED Square

In this example the UAV flies a square pattern using home-relative NED coordinates. The square side length defaults to 20m and is configurable via --side. This file is located at flight_examples/ned_square/ned_square.py.

import sys
import os
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from flight_helpers import (
    add_common_args, get_base_url, create_session, send_command,
    get_home_ned, ned_relative_to_absolute, setup_graceful_shutdown,
)

parser = argparse.ArgumentParser(description="Fly a square pattern using NED coordinates.")
add_common_args(parser)
parser.add_argument('--side', type=float, default=20,
                    help='Side length of the square in meters (default: 20)')
args = parser.parse_args()

base_url = get_base_url(args)
session = create_session(args)
setup_graceful_shutdown(session, base_url)

# Arm vehicle
send_command(session, base_url, "/command/arm")
print("Vehicle armed.")

# Capture home NED position after arming, before takeoff
home = get_home_ned(session, base_url)

# Take off
send_command(session, base_url, "/command/takeoff", params={"alt": args.altitude})
print(f"Vehicle took off to {args.altitude}m.")

# Define square waypoints as relative offsets from home
side = args.side
alt = -args.altitude
relative_points = [
    (side, side, alt),
    (side, -side, alt),
    (-side, -side, alt),
    (-side, side, alt),
]

# Fly the square
for rel in relative_points:
    absolute = ned_relative_to_absolute(rel, home)
    point_data = {"x": absolute[0], "y": absolute[1], "z": absolute[2]}
    send_command(session, base_url, "/movement/go_to_ned_wait", params=point_data, method="POST")
    print(f"Vehicle at absolute NED ({absolute[0]:.1f}, {absolute[1]:.1f}, {absolute[2]:.1f})")

# Return to launch
send_command(session, base_url, "/command/rtl")
print("Vehicle landed at launch.")

NED Square (Polling)

This example does the same thing as the last one but instead of using the blocking go_to_ned_wait endpoint, it uses the non-blocking go_to_ned and polls /telemetry/ned to check arrival. While more verbose, this approach allows your program to do other things while the UAV is in transit. This file is located at flight_examples/ned_square_polling/ned_square_polling.py.

import sys
import os
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from flight_helpers import (
    add_common_args, get_base_url, create_session, send_command,
    get_home_ned, ned_relative_to_absolute, wait_for_arrival, setup_graceful_shutdown,
)

parser = argparse.ArgumentParser(description="Fly a square pattern using NED coordinates (polling version).")
add_common_args(parser)
parser.add_argument('--side', type=float, default=20,
                    help='Side length of the square in meters (default: 20)')
args = parser.parse_args()

base_url = get_base_url(args)
session = create_session(args)
setup_graceful_shutdown(session, base_url)

# Arm vehicle
send_command(session, base_url, "/command/arm")
print("Vehicle armed.")

# Capture home NED position after arming, before takeoff
home = get_home_ned(session, base_url)

# Take off
send_command(session, base_url, "/command/takeoff", params={"alt": args.altitude})
print(f"Vehicle took off to {args.altitude}m.")

# Define square waypoints as relative offsets from home
side = args.side
alt = -args.altitude
relative_points = [
    (side, side, alt),
    (side, -side, alt),
    (-side, -side, alt),
    (-side, side, alt),
]

# Fly the square using non-blocking go_to_ned + polling
for i, rel in enumerate(relative_points, start=1):
    absolute = ned_relative_to_absolute(rel, home)
    point_data = {"x": absolute[0], "y": absolute[1], "z": absolute[2]}
    print(f"\nWaypoint {i}: sending go_to_ned -> ({absolute[0]:.1f}, {absolute[1]:.1f}, {absolute[2]:.1f})")
    send_command(session, base_url, "/movement/go_to_ned", params=point_data, method="POST")
    arrived = wait_for_arrival(session, base_url, absolute, tolerance=1.0, timeout=120)
    if arrived:
        print(f"Waypoint {i}: arrived.")
    else:
        print(f"Waypoint {i}: timed out — aborting, sending RTL.")
        send_command(session, base_url, "/command/rtl")
        exit(1)

# Return to launch
send_command(session, base_url, "/command/rtl")
print("\nSquare complete — vehicle returning to launch.")

Make polygon with Go To

This example raises the drone to a height defined by the user and then, using the endpoint go_to_ned_wait, takes the drone to the vertices of regular polygons also to be defined by the user. These polygons have their center located at the point where the drone was raised and are always made vertically. Whenever a polygon is finished, the drone returns to the center before starting the next one. The algorithm that maps the polygon points is found in the make_polygon_points function and works by inscribing a polygon with s vertices inside a circle of radius r and the NED coordinates of the center defined as offset. Since the polygon is inscribed, we know that its vertices are located on the perimeter of the circle, and since we also know that the polygon is regular, the vertices are equidistant, so we can find the angular distance of each vertex from $\frac{2\pi}{n}$. Now, numbering each vertex v from $v_{0}=0$ to $v_{n}=s-1$, we can find the angle of each one using the function:

$$\theta_{i}=v_{i}\frac{2\pi}{n}$$

Finally, knowing the angle of the vertices, the coordinates of the center, and knowing that the polygon must be drawn vertically, we can define the NED coordinates of the vertices as:

$$x_{i}=\sin(v_{i}\frac{2\pi}{n})+x_{offset}$$ $$y_{i}=y_{offset}$$ $$z_{i}=-\cos(v_{i}\frac{2\pi}{n})+z_{offset}$$

For example, to create a triangle, a square, and a pentagon inscribed in a circle with radius 3m at 4m height:

python go_to_polygon.py --sides 3 4 5 --radius 3 --height 4

All arguments have defaults (sides=4, radius=10, height=20), so running with no arguments creates a square.

This file is located at flight_examples/go_to_polygon/go_to_polygon.py.

import sys
import os
import math
from time import sleep
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from flight_helpers import (
    add_common_args, get_base_url, create_session,
    send_command, setup_graceful_shutdown
)

SLEEP_TIME = 5


def make_polygon_points(r, s, offset):
    points = []
    for v in range(s):
        point = {
            "x": r*math.sin(v*2*math.pi/s) + offset["x"],
            "y": offset["y"],
            "z": -(r*math.cos(v*2*math.pi/s)) + offset["z"]
        }
        print(f"polygon point {v}: {point}")
        points.append(point)
    return(points)


# Get the user's arguments
parser = argparse.ArgumentParser()
add_common_args(parser)
parser.add_argument('--sides', type=int, nargs='+', default=[4])
parser.add_argument('--radius', type=int, default=10)
parser.add_argument('--height', type=int, default=20)
args = parser.parse_args()

# Ensures that the user defines a valid regular polygon
if 1 in args.sides or 2 in args.sides:
    print(f"Error: Polygon must have more than two sides!")
    exit()

# Failsafe: Ensure that the radius is smaller than the height of the perimeter's center
if args.radius >= args.height:
    print(f"Error: height value must be higher than the radius value!")
    exit()

base_url = get_base_url(args)
session = create_session(args)
setup_graceful_shutdown(session, base_url)

# Arming vehicle
send_command(session, base_url, "/command/arm")
print("Vehicle armed.")

# Get the NED coordinates of the initial position with the vehicle still on the ground
initial_result = send_command(session, base_url, "/telemetry/ned")
initial_pos = initial_result["info"]["position"]
print(f"Initial point: {initial_pos}")

# Taking off
send_command(session, base_url, "/command/takeoff", params={"alt": args.height})
print("Vehicle took off")

sleep(SLEEP_TIME)

# Get the NED coordinates of the center of the polygons
center_result = send_command(session, base_url, "/telemetry/ned")
center_pos = center_result["info"]["position"]
print(f"center point: {center_pos}")

# Failsafe: Ensures the drone has reached the desired altitude
if abs(center_pos["z"]-initial_pos["z"]) >= args.height+2 or abs(center_pos["z"]-initial_pos["z"]) <= args.height-2:
        print(f"Error: Vehicle did not reach the desired height.")
        send_command(session, base_url, "/command/land")
        print("Vehicle landed.")
        exit()

polygon_list = args.sides
for s in polygon_list:
    print(f"\n ---polygon {s}---------------------------------- \n")

    polygon_points = make_polygon_points(args.radius, s, center_pos)

    for point in polygon_points:
        send_command(session, base_url, "/movement/go_to_ned_wait", params=point, method="POST")
        print(f"\nGo to point: {point})")

        sleep(SLEEP_TIME)

        tele_ned_result = send_command(session, base_url, "/telemetry/ned")
        tele_ned_pos = tele_ned_result["info"]["position"]
        print(f"Vehicle at {tele_ned_pos})")

    # Return to center
    send_command(session, base_url, "/movement/go_to_ned_wait", params=center_pos, method="POST")
    print(f"\nVehicle going back to the center")

    sleep(SLEEP_TIME)
    print(f"Vehicle at the center")

# Landing
send_command(session, base_url, "/command/land")
print("\nVehicle landed.")

Make polygon with Drive

This example works the same way as the last one with one change: it uses the drive_wait endpoint to move the drone via relative trajectory vectors instead of absolute coordinates. The make_polygon_trajectory function computes edge vectors as deltas between consecutive polygon vertices:

$$x_{i}=r \cdot \sin(v_{i+1}\frac{2\pi}{n}) - r \cdot \sin(v_{i}\frac{2\pi}{n})$$ $$y_{i}=0$$ $$z_{i}=-(r \cdot \cos(v_{i+1}\frac{2\pi}{n}) - r \cdot \cos(v_{i}\frac{2\pi}{n}))$$

This file is located at flight_examples/drive_polygon/drive_polygon.py.

import sys
import os
import math
from time import sleep
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from flight_helpers import (
    add_common_args, get_base_url, create_session,
    send_command, setup_graceful_shutdown
)

SLEEP_TIME = 5


def make_polygon_trajectory(r, l):
    vectors = []
    for n in range(l):
        vector = {
            "x": round(r * math.sin((n + 1) * 2 * math.pi / l) - r * math.sin(n * 2 * math.pi / l)),
            "y": 0,
            "z": -(round(r * math.cos((n + 1) * 2 * math.pi / l) - r * math.cos(n * 2 * math.pi / l)))
        }
        print(f"polygon vector {n}: {vector}")
        vectors.append(vector)

    return vectors


# Get the user's arguments
parser = argparse.ArgumentParser()
add_common_args(parser)
parser.add_argument('--sides', type=int, nargs='+', default=[4])
parser.add_argument('--radius', type=int, default=10)
parser.add_argument('--height', type=int, default=20)
args = parser.parse_args()

base_url = get_base_url(args)
session = create_session(args)
setup_graceful_shutdown(session, base_url)

# Validation
if 1 in args.sides or 2 in args.sides:
    print(f"Error: Polygon must have more than two sides!")
    exit()

if args.radius >= args.height:
    print(f"Error: height value must be higher than the radius value!")
    exit()

# Arming vehicle
send_command(session, base_url, "/command/arm")
print("Vehicle armed.")

initial_result = send_command(session, base_url, "/telemetry/ned")
initial_pos = initial_result["info"]["position"]
print(f"Initial point: {initial_pos}")

send_command(session, base_url, "/command/takeoff", params={"alt": args.height})
print("Vehicle took off")

sleep(SLEEP_TIME)

center_result = send_command(session, base_url, "/telemetry/ned")
center_pos = center_result["info"]["position"]
print(f"center point: {center_pos}")

# Altitude failsafe
if abs(center_pos["z"]-initial_pos["z"]) >= args.height+2 or abs(center_pos["z"]-initial_pos["z"]) <= args.height-2:
        print(f"Error: Vehicle did not reach the desired height.")
        send_command(session, base_url, "/command/land")
        print("Vehicle landed.")
        exit()

polygon_list = args.sides
for l in polygon_list:
    print(f"\n ---polygon {l}---------------------------------- \n")

    polygon_trajectory = make_polygon_trajectory(args.radius, l)

    for vector in polygon_trajectory:
        send_command(session, base_url, "/movement/drive_wait", params=vector, method="POST")
        print(f"\nTrajectory vector: {vector})")

        sleep(SLEEP_TIME)

        tele_ned_result = send_command(session, base_url, "/telemetry/ned")
        tele_ned_pos = tele_ned_result["info"]["position"]
        print(f"Vehicle at {tele_ned_pos})")

    # Return to center
    send_command(session, base_url, "/movement/go_to_ned_wait", params=center_pos, method="POST")
    print(f"\nVehicle going back to the center")

    sleep(SLEEP_TIME)
    print(f"Vehicle at the center")

# Landing
send_command(session, base_url, "/command/land")
print("\nVehicle landed.")

Delivery Mission Simulation

This example simulates a complete delivery cycle: home -> pickup -> delivery -> home. The drone uses the non-blocking go_to_ned endpoint with wait_for_arrival polling to check arrival via Euclidean distance:

$$d = \sqrt{(x_{target}-x_{current})^2 + (y_{target}-y_{current})^2 + (z_{target}-z_{current})^2}$$

Coordinates are home-relative NED. The script adds the home position to convert to absolute:

$$P_{target} = P_{home} + P_{input}$$

A SAFE_OFFSET (-2m) is added to the Down component during flight for safe cruise altitude. Pickup and delivery locations default to (10,0,-5) and (0,10,-5) but are configurable via --pickup and --delivery.

python delivery_simulation.py --pickup 1,3,-3 --delivery 0,2,-3

This file is located at flight_examples/delivery/delivery_simulation.py.

python delivery_simulation.py (runs with defaults: pickup=10,0,-5, delivery=0,10,-5)

"""Delivery simulation: pickup a package, fly to delivery point, return home."""

import sys
import os
import time
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))

from flight_helpers import (
    add_common_args, get_base_url, create_session, send_command,
    get_home_ned, ned_relative_to_absolute, wait_for_arrival,
    setup_graceful_shutdown, euclidean_distance,
)

SLEEP_DURATION = 4
TAKEOFF_ALTITUDE = 5
SAFE_OFFSET = -2


def parse_ned(s):
    """Parse a 'N,E,D' string into a tuple of three floats."""
    parts = tuple(map(float, s.split(",")))
    if len(parts) != 3:
        raise argparse.ArgumentTypeError(f"Expected N,E,D format, got: {s}")
    return parts


def ensure_negative_altitude(ned):
    """Ensure the Down component is negative (above ground in NED)."""
    if ned[2] >= 0:
        print("Altitude must be negative in NED coordinates. Adjusted to negative value.")
        return (ned[0], ned[1], -abs(ned[2]))
    return ned


def go_to_relative(session, base_url, relative, home):
    """Navigate to a home-relative NED point with SAFE_OFFSET applied to Down."""
    target_abs = (
        relative[0] + home[0],
        relative[1] + home[1],
        relative[2] + home[2] + SAFE_OFFSET,
    )
    send_command(session, base_url, "/movement/go_to_ned",
                 params={"x": target_abs[0], "y": target_abs[1], "z": target_abs[2]},
                 method="POST")
    return target_abs


# --- Argument parsing ---
parser = argparse.ArgumentParser(
    description="Simulate a drone delivery: home -> pickup -> delivery -> home."
)
add_common_args(parser)
parser.add_argument("--pickup", type=str, default="10,0,-5",
                    help="Pickup location as N,E,D (default: 10,0,-5)")
parser.add_argument("--delivery", type=str, default="0,10,-5",
                    help="Delivery location as N,E,D (default: 0,10,-5)")
args = parser.parse_args()

pickup_location = ensure_negative_altitude(parse_ned(args.pickup))
delivery_location = ensure_negative_altitude(parse_ned(args.delivery))

base_url = get_base_url(args)
session = create_session(args)
setup_graceful_shutdown(session, base_url)

# --- Mission start ---
print(f"\nPickup:   {pickup_location}")
print(f"Delivery: {delivery_location}")

# Arm
print("Arming...")
send_command(session, base_url, "/command/arm")
time.sleep(SLEEP_DURATION)

# Get home location after arming, before takeoff
home = get_home_ned(session, base_url)
time.sleep(SLEEP_DURATION)

print(f"Takeoff to {TAKEOFF_ALTITUDE}m...")
send_command(session, base_url, "/command/takeoff", params={"alt": TAKEOFF_ALTITUDE})
time.sleep(SLEEP_DURATION)

# --- Leg 1: Home -> Pickup ---
print(f"Going to pickup location: {pickup_location}")
target_abs = go_to_relative(session, base_url, pickup_location, home)
time.sleep(SLEEP_DURATION)

if wait_for_arrival(session, base_url, target_abs):
    print("Drone arrived at pickup location.")
time.sleep(SLEEP_DURATION)

print("Landing to pick up package...")
send_command(session, base_url, "/command/land")
time.sleep(SLEEP_DURATION)

time.sleep(SLEEP_DURATION)

# Arm and take off again
print("Arming...")
send_command(session, base_url, "/command/arm")
time.sleep(SLEEP_DURATION)

print(f"Takeoff to {TAKEOFF_ALTITUDE}m...")
send_command(session, base_url, "/command/takeoff", params={"alt": TAKEOFF_ALTITUDE})
time.sleep(SLEEP_DURATION)

# --- Leg 2: Pickup -> Delivery ---
print(f"Going to delivery location: {delivery_location}")
target_abs = go_to_relative(session, base_url, delivery_location, home)
time.sleep(SLEEP_DURATION)

if wait_for_arrival(session, base_url, target_abs):
    print("Drone arrived at delivery location.")
time.sleep(SLEEP_DURATION)

print("Landing to deliver package...")
send_command(session, base_url, "/command/land")
time.sleep(SLEEP_DURATION)

time.sleep(SLEEP_DURATION)

# Arm and take off again
print("Arming...")
send_command(session, base_url, "/command/arm")
time.sleep(SLEEP_DURATION)

print(f"Takeoff to {TAKEOFF_ALTITUDE}m...")
send_command(session, base_url, "/command/takeoff", params={"alt": TAKEOFF_ALTITUDE})
time.sleep(SLEEP_DURATION)

# --- Leg 3: Delivery -> Home ---
home_relative = (0, 0, 0)
print(f"Returning to home...")
target_abs = go_to_relative(session, base_url, home_relative, home)
time.sleep(SLEEP_DURATION)

if wait_for_arrival(session, base_url, target_abs):
    print("Drone arrived near home location.")
time.sleep(SLEEP_DURATION)

print("Landing at home location...")
send_command(session, base_url, "/command/land")
time.sleep(SLEEP_DURATION)

print("Mission accomplished.")

GPS-Based Follower

This example tracks a leader drone using GPS coordinates instead of NED. It uses a setup/loop architecture: the setup phase captures home altitude, arms, and takes off; the loop phase continuously reads the leader's GPS and moves the follower with a configurable offset.

The core algorithm converts meter-based offsets into GPS coordinate deltas using Haversine approximation:

$$\Delta_{lat} = \frac{offset_{north}}{111111}$$

$$\Delta_{lon} = \frac{offset_{east}}{111111 \cdot \cos(lat_{leader})}$$

For altitude, relative altitude is calculated by subtracting the home altitude captured at setup:

$$alt_{target} = \max(2.0, (alt_{leader} - alt_{ground}) + offset_{alt})$$

All parameters are configurable via argparse: --leader-url, --offset-north, --offset-east, --offset-alt. Ctrl+C triggers RTL. The loop runs at 2Hz.

This file is located at flight_examples/gps_follower/gps_follower.py.

import math
import time
import sys
import os
import argparse

sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from flight_helpers import (
    add_common_args, get_base_url, create_session,
    send_command, get_home_gps, setup_graceful_shutdown,
)


def parse_args():
    parser = argparse.ArgumentParser(description="GPS follower — tracks a leader drone with a configurable offset.")
    add_common_args(parser)
    parser.add_argument('--leader-url', type=str, default='localhost:8001',
                        help='Leader API host:port (default: localhost:8001)')
    parser.add_argument('--offset-north', type=float, default=-3,
                        help='North offset in meters; negative = behind (default: -3)')
    parser.add_argument('--offset-east', type=float, default=0,
                        help='East offset in meters (default: 0)')
    parser.add_argument('--offset-alt', type=float, default=2.0,
                        help='Altitude offset above leader in meters (default: 2.0)')
    return parser.parse_args()


def setup(session, base_url, leader_session, leader_base_url, altitude):
    """One-time setup: arm, capture home altitude, capture leader home altitude, and take off."""
    print("--- STARTING SETUP ---")

    # Arm the vehicle
    print("Arming the vehicle...")
    send_command(session, base_url, "/command/arm")

    # Capture home GPS after arming, before takeoff
    home = get_home_gps(session, base_url)
    home_alt = home[2]
    print(f"Follower home altitude captured: {home_alt:.1f}m")

    # Capture leader home GPS altitude (different barometer calibration)
    leader_home = get_home_gps(leader_session, leader_base_url)
    leader_home_alt = leader_home[2]
    print(f"Leader home altitude captured: {leader_home_alt:.1f}m")

    # Take off
    print(f"Taking off to {altitude}m...")
    send_command(session, base_url, "/command/takeoff", params={"alt": altitude})

    print("--- SETUP COMPLETE ---")
    return home_alt, leader_home_alt


def loop(session, base_url, leader_session, leader_base_url, home_alt, leader_home_alt, args):
    """Repeated loop: read leader position, compute offset, move follower."""
    try:
        data = send_command(leader_session, leader_base_url, "/telemetry/gps")
        l_pos = data["info"]["position"]

        leader_lat = float(l_pos["lat"])
        leader_lon = float(l_pos["lon"])
        leader_alt = float(l_pos["alt"])

        print(f"[Leader] Lat: {leader_lat:.6f}, Lon: {leader_lon:.6f}")

        # Compute target position with offset (Haversine approximation)
        delta_lat = args.offset_north / 111111.0
        delta_lon = args.offset_east / (111111.0 * math.cos(math.radians(leader_lat)))

        target_lat = leader_lat + delta_lat
        target_lon = leader_lon + delta_lon

        leader_relative_alt = leader_alt - leader_home_alt
        raw_target_alt = leader_relative_alt + args.offset_alt
        target_alt = max(2.0, raw_target_alt)

        fly_data = {"lat": target_lat, "long": target_lon, "alt": target_alt}
        send_command(session, base_url, "/movement/go_to_gps", params=fly_data, method="POST")

        print(f">> Moving follower to: {target_lat:.6f}, {target_lon:.6f}, alt={target_alt:.1f}m")

    except Exception as e:
        print(f"Loop error: {e}")

    time.sleep(0.5)


if __name__ == "__main__":
    args = parse_args()

    follower_base_url = get_base_url(args)
    scheme = "https" if args.h3 else "http"
    leader_base_url = f"{scheme}://{args.leader_url}"

    follower_session = create_session(args)
    leader_session = create_session(args)

    setup_graceful_shutdown(follower_session, follower_base_url)

    home_alt, leader_home_alt = setup(follower_session, follower_base_url,
                                      leader_session, leader_base_url, args.altitude)

    print("\n--- FOLLOWING LEADER (Ctrl+C to RTL and exit) ---\n")
    while True:
        loop(follower_session, follower_base_url,
             leader_session, leader_base_url, home_alt, leader_home_alt, args)

Release files for uav-api 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uav-api 0.2.2
File	Size	Uploaded
uav_api-0.2.2.tar.gz	147.9 kB	Aug 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for uav-api 0.2.2
File	Interpreter	ABI	Platform	Reset
uav_api-0.2.2-py3-none-any.whl 78.8 kB Aug 13, 2026	Python 3	none	any	Details

Total release size: 226.8 kB

Release files / uav_api-0.2.2.tar.gz

Download URL	uav_api-0.2.2.tar.gz
Size	147.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`2a0205aa708927f628dc1340bdb5bd29b0a4e71e020ff0f2acb823c3630cc4e7`
BLAKE2b-256 checksum How to use checksums	`11a7734fee862443b436cce789c96305a10d3cb55d20abba83da99a09d20d8b3`
Upload date	Aug 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.4`

Release files / uav_api-0.2.2-py3-none-any.whl

Download URL	uav_api-0.2.2-py3-none-any.whl
Size	78.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`57fc1433c3914c018f14d7b47f5f311e0ce2fa471c138f39196aa745b381c440`
BLAKE2b-256 checksum How to use checksums	`c1bd3257246afe30fad0e2b4c4f6fcd6d108081f7c359893a1e3482d2aad24e0`
Upload date	Aug 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.4`