urml-ardupilot-runtime 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- urml_ardupilot_runtime-0.5.0/.gitignore +114 -0
- urml_ardupilot_runtime-0.5.0/PKG-INFO +167 -0
- urml_ardupilot_runtime-0.5.0/README.md +133 -0
- urml_ardupilot_runtime-0.5.0/pyproject.toml +78 -0
- urml_ardupilot_runtime-0.5.0/src/urml_ardupilot_runtime/__init__.py +43 -0
- urml_ardupilot_runtime-0.5.0/src/urml_ardupilot_runtime/_version.py +3 -0
- urml_ardupilot_runtime-0.5.0/src/urml_ardupilot_runtime/adapter.py +881 -0
- urml_ardupilot_runtime-0.5.0/src/urml_ardupilot_runtime/config.py +168 -0
- urml_ardupilot_runtime-0.5.0/src/urml_ardupilot_runtime/probe.py +45 -0
- urml_ardupilot_runtime-0.5.0/tests/__init__.py +0 -0
- urml_ardupilot_runtime-0.5.0/tests/integration/__init__.py +0 -0
- urml_ardupilot_runtime-0.5.0/tests/integration/test_arducopter_bench.py +96 -0
- urml_ardupilot_runtime-0.5.0/tests/integration/test_arducopter_live.py +43 -0
- urml_ardupilot_runtime-0.5.0/tests/integration/test_arducopter_sitl_e2e.py +140 -0
- urml_ardupilot_runtime-0.5.0/tests/test_arducopter_adapter.py +655 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# --- Python ---
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
develop-eggs/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
MANIFEST
|
|
23
|
+
|
|
24
|
+
# Virtual envs
|
|
25
|
+
.venv/
|
|
26
|
+
venv/
|
|
27
|
+
env/
|
|
28
|
+
ENV/
|
|
29
|
+
.python-version
|
|
30
|
+
|
|
31
|
+
# Test / coverage / mypy / pyright
|
|
32
|
+
.coverage
|
|
33
|
+
.coverage.*
|
|
34
|
+
.cache
|
|
35
|
+
.pytest_cache/
|
|
36
|
+
.mypy_cache/
|
|
37
|
+
.dmypy.json
|
|
38
|
+
.pyre/
|
|
39
|
+
.pyright/
|
|
40
|
+
htmlcov/
|
|
41
|
+
nosetests.xml
|
|
42
|
+
coverage.xml
|
|
43
|
+
*.cover
|
|
44
|
+
.hypothesis/
|
|
45
|
+
.tox/
|
|
46
|
+
|
|
47
|
+
# --- Node / web tooling (kept out of core repo; here for safety) ---
|
|
48
|
+
node_modules/
|
|
49
|
+
.pnp.*
|
|
50
|
+
.yarn/cache/
|
|
51
|
+
.yarn/unplugged/
|
|
52
|
+
.yarn/build-state.yml
|
|
53
|
+
.yarn/install-state.gz
|
|
54
|
+
npm-debug.log*
|
|
55
|
+
yarn-debug.log*
|
|
56
|
+
yarn-error.log*
|
|
57
|
+
|
|
58
|
+
# --- C++ / Rust build artifacts (in case reference runtimes land here in early Phase 1) ---
|
|
59
|
+
target/
|
|
60
|
+
*.o
|
|
61
|
+
*.obj
|
|
62
|
+
*.a
|
|
63
|
+
*.lib
|
|
64
|
+
*.dll
|
|
65
|
+
*.dylib
|
|
66
|
+
*.exe
|
|
67
|
+
*.pdb
|
|
68
|
+
cmake-build-*/
|
|
69
|
+
CMakeCache.txt
|
|
70
|
+
CMakeFiles/
|
|
71
|
+
CMakeScripts/
|
|
72
|
+
Testing/
|
|
73
|
+
cmake_install.cmake
|
|
74
|
+
install_manifest.txt
|
|
75
|
+
compile_commands.json
|
|
76
|
+
|
|
77
|
+
# --- ROS 2 build dirs ---
|
|
78
|
+
build/
|
|
79
|
+
install/
|
|
80
|
+
log/
|
|
81
|
+
|
|
82
|
+
# --- Editor and OS junk ---
|
|
83
|
+
.vscode/
|
|
84
|
+
.idea/
|
|
85
|
+
*.swp
|
|
86
|
+
*.swo
|
|
87
|
+
*~
|
|
88
|
+
.DS_Store
|
|
89
|
+
Thumbs.db
|
|
90
|
+
desktop.ini
|
|
91
|
+
|
|
92
|
+
# --- Local-only artifacts ---
|
|
93
|
+
.env
|
|
94
|
+
.env.*
|
|
95
|
+
*.log
|
|
96
|
+
*.tmp
|
|
97
|
+
.local/
|
|
98
|
+
.scratch/
|
|
99
|
+
|
|
100
|
+
# --- Outreach campaign artifacts (operational, not part of the open standard) ---
|
|
101
|
+
# Target lists, message drafts, tracking data, and the launch-approval record
|
|
102
|
+
# stay local. They are private to the maintainer; committing them would
|
|
103
|
+
# telegraph the campaign before launch and could embarrass listed projects.
|
|
104
|
+
outreach/
|
|
105
|
+
|
|
106
|
+
# Outreach dashboard SQLite mirror (RFC-0275). Derived from
|
|
107
|
+
# examples/lighthouses/outreach*.yaml via tools/scripts/refresh_outreach_db.py.
|
|
108
|
+
# Regenerated on demand by `make outreach-refresh`.
|
|
109
|
+
tools/outreach.db
|
|
110
|
+
tools/.outreach.db
|
|
111
|
+
|
|
112
|
+
# Local Claude Code settings (per-machine; permission rules, etc.). Not committed.
|
|
113
|
+
.claude/settings.json
|
|
114
|
+
.claude/settings.local.json
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: urml-ardupilot-runtime
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: ArduPilot / MAVLink reference runtime for URML — Universal Robot Language.
|
|
5
|
+
Project-URL: Homepage, https://github.com/urml-dev/URML
|
|
6
|
+
Project-URL: Repository, https://github.com/urml-dev/URML
|
|
7
|
+
Project-URL: Issues, https://github.com/urml-dev/URML/issues
|
|
8
|
+
Author: URML Maintainers
|
|
9
|
+
License: BUSL-1.1
|
|
10
|
+
Keywords: arducopter,ardupilot,drone,mavlink,pixhawk,robotics,runtime,urml
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: Other/Proprietary License
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Requires-Dist: pydantic<3,>=2.6
|
|
21
|
+
Requires-Dist: pyyaml<7,>=6.0
|
|
22
|
+
Requires-Dist: urml-px4-runtime>=0.5.0
|
|
23
|
+
Requires-Dist: urml-ros2-runtime>=0.5.0
|
|
24
|
+
Requires-Dist: urml-validator>=0.5.0
|
|
25
|
+
Provides-Extra: ardupilot
|
|
26
|
+
Requires-Dist: pymavlink<3,>=2.4; extra == 'ardupilot'
|
|
27
|
+
Requires-Dist: pyserial<4,>=3.5; extra == 'ardupilot'
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
32
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
<p align="center">
|
|
36
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
37
|
+
</p>
|
|
38
|
+
|
|
39
|
+
<p align="center">
|
|
40
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
41
|
+
</p>
|
|
42
|
+
|
|
43
|
+
<p align="center">
|
|
44
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
45
|
+
</p>
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
# urml-ardupilot-runtime
|
|
50
|
+
|
|
51
|
+
**ArduPilot / MAVLink reference runtime for URML.** Flies ArduCopter (a Pixhawk-class board running ArduPilot, or ArduCopter SITL) from a validated URML program over [pymavlink](https://github.com/ArduPilot/pymavlink). No ROS 2 dependency. This is the package [RFC-0041](../../docs/rfcs/0041-ardupilot-integration.md) proposed; Copter ships first, Plane and Rover are follow-ups.
|
|
52
|
+
|
|
53
|
+
`ArduCopterAdapter` subclasses the PX4 reference adapter ([urml-px4-runtime](../px4-runtime/)). The MAVLink command set is shared; what this package adds is the firmware behaviour ArduPilot needs around those commands and PX4 does not.
|
|
54
|
+
|
|
55
|
+
## What ArduPilot needs that PX4 does not
|
|
56
|
+
|
|
57
|
+
| Concern | PX4Adapter | ArduCopterAdapter |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| Flight mode | implicit | enters `GUIDED` before take-off and setpoints, confirms on heartbeat |
|
|
60
|
+
| Arming | implicit | `MAV_CMD_COMPONENT_ARM_DISARM`, waits for the armed flag; a refusal carries the autopilot's `PreArm:` text |
|
|
61
|
+
| `COMMAND_ACK` | first ack wins | matched on `ack.command` |
|
|
62
|
+
| `move_to` | send setpoint, return | send setpoint, wait for arrival within `arrival_radius_m` |
|
|
63
|
+
| `land` / `return_to_home` | `NAV_LAND` / `NAV_RTL` commands | `LAND` / `RTL` mode entry |
|
|
64
|
+
| Global positions | none | `SET_POSITION_TARGET_GLOBAL_INT` for locations bound to WGS84 in the config |
|
|
65
|
+
| `capture` | not supported | `DO_DIGICAM_CONTROL` or a servo pulse; result carries the autopilot position at trigger time |
|
|
66
|
+
| `set_output` | not supported | ArduPilot gripper (`DO_GRIPPER`), winch (`DO_WINCH`), or servo (`DO_SET_SERVO`) |
|
|
67
|
+
| Serial | URL only | `baud` appended to `COMn` / `/dev/tty*` URLs; `pyserial` in the extra |
|
|
68
|
+
|
|
69
|
+
Nothing in this package disables `ARMING_CHECK` or any pre-arm gate. On a bench with no GPS fix the autopilot refuses GUIDED or arming, and the adapter reports that refusal as the step's `reason` and stops. That refusal is the intended bench proof.
|
|
70
|
+
|
|
71
|
+
## Method coverage
|
|
72
|
+
|
|
73
|
+
| URML primitive | MAVLink | ArduCopter behaviour |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `take_off` | `DO_SET_MODE(GUIDED)`, `COMPONENT_ARM_DISARM`, `NAV_TAKEOFF` | climbs; success when `GLOBAL_POSITION_INT.relative_alt` reaches 95 % of target |
|
|
76
|
+
| `move_to` (named, WGS84-bound) | `SET_POSITION_TARGET_GLOBAL_INT` | flies to lat/lon at relative altitude; optional `DO_SET_ROI_LOCATION` after arrival |
|
|
77
|
+
| `move_to` (named, NED-bound, or `pose`) | `SET_POSITION_TARGET_LOCAL_NED` | flies to local-NED offset from home |
|
|
78
|
+
| `hover` | mode confirm only | GUIDED holds position; a `hover` without `over` is a confirmed no-op |
|
|
79
|
+
| `land` | `DO_SET_MODE(LAND)` | waits for auto-disarm (bounded) |
|
|
80
|
+
| `return_to_home` | `DO_SET_MODE(RTL)` | clears any ROI first |
|
|
81
|
+
| `capture` (photo) | `DO_DIGICAM_CONTROL` or `DO_SET_SERVO` pulse | image stays on the camera; payload has `camera://shot/N` and the trigger-time position |
|
|
82
|
+
| `set_output` | `DO_GRIPPER` / `DO_WINCH` / `DO_SET_SERVO` | per `output_lines` binding in the config; winch uses relative-length control (+length deliver, -length retract) because ArduCopter 4.6 rejects the `WINCH_DELIVER` / `WINCH_RETRACT` actions |
|
|
83
|
+
| `release` (`mode: winch` / `latch`, RFC-0684) | `DO_WINCH` / `DO_GRIPPER` / `DO_SET_SERVO` | per `payload_mechanisms` binding; a winch lowers the payload (`height` metres, capped at `deliver_length_m`), opens a named `latch` at the bottom, then retracts the empty hook; a latch just opens |
|
|
84
|
+
| `measure` (distance, voltage), `wait_for`, `report`, `wait` | inherited from PX4Adapter | `wait_for(event: emergency_stop)` fires on the autopilot's `HEARTBEAT.system_status` `MAV_STATE_FLIGHT_TERMINATION` or `MAV_STATE_EMERGENCY`; not yet checked against ArduCopter |
|
|
85
|
+
| `release` (`mode: drop` / `place` / `hand_to_user`), `dock`, `grasp`, `detect`, `scan`, `speak`, `listen`, video capture | not supported | documented `not_supported` result, never raised |
|
|
86
|
+
|
|
87
|
+
## Install
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
pip install -e reference/ardupilot-runtime[ardupilot]
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The extra installs `pymavlink` and `pyserial`. Without it the module imports but constructing the adapter raises a clear install hint.
|
|
94
|
+
|
|
95
|
+
## Bring-up
|
|
96
|
+
|
|
97
|
+
Read-only probe. Sends no mode, arm, or motion command.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
python -m urml_ardupilot_runtime.probe COM5
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Prints the autopilot type, vehicle type, MAVLink system id, armed state, mode, firmware version, battery voltage, GPS fix, and any recent STATUSTEXT. A Pixhawk on USB is usually `COM<n>` on Windows and `/dev/ttyACM0` on Linux; ArduCopter SITL is `udp:127.0.0.1:14550`.
|
|
104
|
+
|
|
105
|
+
## Use
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
urml execute program.urml.yaml -m manifest.yaml --profile drone --no-policy \
|
|
109
|
+
--adapter ardupilot --adapter-config ardupilot_adapter.yaml
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
A minimal `ardupilot_adapter.yaml`:
|
|
113
|
+
|
|
114
|
+
```yaml
|
|
115
|
+
connection_url: "COM5"
|
|
116
|
+
baud: 115200
|
|
117
|
+
|
|
118
|
+
location_to_pose: # local metres from the launch point
|
|
119
|
+
bench_north: { north: 5.0, east: 0.0, alt: 3.0 }
|
|
120
|
+
home: { north: 0.0, east: 0.0, alt: 0.0 }
|
|
121
|
+
|
|
122
|
+
location_to_global: # WGS84, wins over location_to_pose for the same name
|
|
123
|
+
site_p1: { lat: 32.0853, lon: 34.7818, alt_agl: 100.0, look_at: { lat: 32.0850, lon: 34.7815 } }
|
|
124
|
+
|
|
125
|
+
camera:
|
|
126
|
+
kind: digicam # or `servo` with `channel`
|
|
127
|
+
|
|
128
|
+
output_lines:
|
|
129
|
+
payload_latch: { kind: gripper, instance: 1 }
|
|
130
|
+
winch: { kind: winch, instance: 1, deliver_length_m: 15.0, rate_m_s: 0.5 }
|
|
131
|
+
|
|
132
|
+
payload_mechanisms: # RFC-0684 `release(mode: winch | latch)`
|
|
133
|
+
delivery_winch: { kind: winch, instance: 1, deliver_length_m: 15.0, rate_m_s: 0.5 }
|
|
134
|
+
drop_hook: { kind: gripper, instance: 2 }
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`location_to_global` is written by [`tools/scripts/geocode_locations.py`](../../tools/scripts/geocode_locations.py) at configuration time. The runtime never geocodes and never touches the network.
|
|
138
|
+
|
|
139
|
+
From Python:
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
from urml_ardupilot_runtime import ArduCopterAdapter, load_ardupilot_config
|
|
143
|
+
from urml_ros2_runtime import URMLRuntime
|
|
144
|
+
|
|
145
|
+
with ArduCopterAdapter(load_ardupilot_config("ardupilot_adapter.yaml")) as adapter:
|
|
146
|
+
runtime = URMLRuntime(adapter)
|
|
147
|
+
result = runtime.execute(program, manifest, envelope, profiles=("drone",))
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`CompositeAdapter` from the PX4 runtime accepts an `ArduCopterAdapter` as its `flight` backend unchanged.
|
|
151
|
+
|
|
152
|
+
## Tests
|
|
153
|
+
|
|
154
|
+
Three tiers, mirroring the PX4 runtime:
|
|
155
|
+
|
|
156
|
+
- `tests/test_arducopter_adapter.py`: hermetic, a fake `pymavlink` is injected; runs everywhere.
|
|
157
|
+
- `tests/integration/test_arducopter_live.py`: gated on `URML_ARDUPILOT_INTEGRATION=1`; real pymavlink, no autopilot contacted.
|
|
158
|
+
- `tests/integration/test_arducopter_bench.py`: gated on `URML_ARDUPILOT_BENCH=<port>`; a real board, props off. Asserts the identity probe, a successful battery read through the runtime, and that a take-off is refused cleanly by the autopilot's own pre-arm checks.
|
|
159
|
+
- `tests/integration/test_arducopter_sitl_e2e.py`: gated on `URML_ARDUPILOT_SITL=1`; flies the `drone/flight_only_positive` conformance fixture against ArduCopter SITL.
|
|
160
|
+
|
|
161
|
+
## Status
|
|
162
|
+
|
|
163
|
+
Bench link verified on hardware (Pixhawk, ArduCopter 4.6.3, USB). The SITL e2e (flight-only fixture plus both flight-test examples) is green against ArduCopter SITL built from `Copter-4.6.3`, run locally on 2026-08-29. No physical flight is claimed anywhere in this repository; see [`docs/demos/sentence-to-pixhawk.md`](../../docs/demos/sentence-to-pixhawk.md) for the bench runbook and the two flight-test runbooks that gate a field run on a green SITL pass.
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
Business Source License 1.1: free for non-production use, commercial license for production (see [`LICENSING.md`](../../LICENSING.md)). The adapter talks to ArduPilot firmware (GPLv3) over MAVLink; it links `pymavlink` (LGPLv3) as a normal Python import and never links the firmware.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
A small, opinionated, human-readable language for describing robot intent.
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://urml.dev"><b>urml.dev</b></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# urml-ardupilot-runtime
|
|
16
|
+
|
|
17
|
+
**ArduPilot / MAVLink reference runtime for URML.** Flies ArduCopter (a Pixhawk-class board running ArduPilot, or ArduCopter SITL) from a validated URML program over [pymavlink](https://github.com/ArduPilot/pymavlink). No ROS 2 dependency. This is the package [RFC-0041](../../docs/rfcs/0041-ardupilot-integration.md) proposed; Copter ships first, Plane and Rover are follow-ups.
|
|
18
|
+
|
|
19
|
+
`ArduCopterAdapter` subclasses the PX4 reference adapter ([urml-px4-runtime](../px4-runtime/)). The MAVLink command set is shared; what this package adds is the firmware behaviour ArduPilot needs around those commands and PX4 does not.
|
|
20
|
+
|
|
21
|
+
## What ArduPilot needs that PX4 does not
|
|
22
|
+
|
|
23
|
+
| Concern | PX4Adapter | ArduCopterAdapter |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| Flight mode | implicit | enters `GUIDED` before take-off and setpoints, confirms on heartbeat |
|
|
26
|
+
| Arming | implicit | `MAV_CMD_COMPONENT_ARM_DISARM`, waits for the armed flag; a refusal carries the autopilot's `PreArm:` text |
|
|
27
|
+
| `COMMAND_ACK` | first ack wins | matched on `ack.command` |
|
|
28
|
+
| `move_to` | send setpoint, return | send setpoint, wait for arrival within `arrival_radius_m` |
|
|
29
|
+
| `land` / `return_to_home` | `NAV_LAND` / `NAV_RTL` commands | `LAND` / `RTL` mode entry |
|
|
30
|
+
| Global positions | none | `SET_POSITION_TARGET_GLOBAL_INT` for locations bound to WGS84 in the config |
|
|
31
|
+
| `capture` | not supported | `DO_DIGICAM_CONTROL` or a servo pulse; result carries the autopilot position at trigger time |
|
|
32
|
+
| `set_output` | not supported | ArduPilot gripper (`DO_GRIPPER`), winch (`DO_WINCH`), or servo (`DO_SET_SERVO`) |
|
|
33
|
+
| Serial | URL only | `baud` appended to `COMn` / `/dev/tty*` URLs; `pyserial` in the extra |
|
|
34
|
+
|
|
35
|
+
Nothing in this package disables `ARMING_CHECK` or any pre-arm gate. On a bench with no GPS fix the autopilot refuses GUIDED or arming, and the adapter reports that refusal as the step's `reason` and stops. That refusal is the intended bench proof.
|
|
36
|
+
|
|
37
|
+
## Method coverage
|
|
38
|
+
|
|
39
|
+
| URML primitive | MAVLink | ArduCopter behaviour |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `take_off` | `DO_SET_MODE(GUIDED)`, `COMPONENT_ARM_DISARM`, `NAV_TAKEOFF` | climbs; success when `GLOBAL_POSITION_INT.relative_alt` reaches 95 % of target |
|
|
42
|
+
| `move_to` (named, WGS84-bound) | `SET_POSITION_TARGET_GLOBAL_INT` | flies to lat/lon at relative altitude; optional `DO_SET_ROI_LOCATION` after arrival |
|
|
43
|
+
| `move_to` (named, NED-bound, or `pose`) | `SET_POSITION_TARGET_LOCAL_NED` | flies to local-NED offset from home |
|
|
44
|
+
| `hover` | mode confirm only | GUIDED holds position; a `hover` without `over` is a confirmed no-op |
|
|
45
|
+
| `land` | `DO_SET_MODE(LAND)` | waits for auto-disarm (bounded) |
|
|
46
|
+
| `return_to_home` | `DO_SET_MODE(RTL)` | clears any ROI first |
|
|
47
|
+
| `capture` (photo) | `DO_DIGICAM_CONTROL` or `DO_SET_SERVO` pulse | image stays on the camera; payload has `camera://shot/N` and the trigger-time position |
|
|
48
|
+
| `set_output` | `DO_GRIPPER` / `DO_WINCH` / `DO_SET_SERVO` | per `output_lines` binding in the config; winch uses relative-length control (+length deliver, -length retract) because ArduCopter 4.6 rejects the `WINCH_DELIVER` / `WINCH_RETRACT` actions |
|
|
49
|
+
| `release` (`mode: winch` / `latch`, RFC-0684) | `DO_WINCH` / `DO_GRIPPER` / `DO_SET_SERVO` | per `payload_mechanisms` binding; a winch lowers the payload (`height` metres, capped at `deliver_length_m`), opens a named `latch` at the bottom, then retracts the empty hook; a latch just opens |
|
|
50
|
+
| `measure` (distance, voltage), `wait_for`, `report`, `wait` | inherited from PX4Adapter | `wait_for(event: emergency_stop)` fires on the autopilot's `HEARTBEAT.system_status` `MAV_STATE_FLIGHT_TERMINATION` or `MAV_STATE_EMERGENCY`; not yet checked against ArduCopter |
|
|
51
|
+
| `release` (`mode: drop` / `place` / `hand_to_user`), `dock`, `grasp`, `detect`, `scan`, `speak`, `listen`, video capture | not supported | documented `not_supported` result, never raised |
|
|
52
|
+
|
|
53
|
+
## Install
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install -e reference/ardupilot-runtime[ardupilot]
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The extra installs `pymavlink` and `pyserial`. Without it the module imports but constructing the adapter raises a clear install hint.
|
|
60
|
+
|
|
61
|
+
## Bring-up
|
|
62
|
+
|
|
63
|
+
Read-only probe. Sends no mode, arm, or motion command.
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
python -m urml_ardupilot_runtime.probe COM5
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Prints the autopilot type, vehicle type, MAVLink system id, armed state, mode, firmware version, battery voltage, GPS fix, and any recent STATUSTEXT. A Pixhawk on USB is usually `COM<n>` on Windows and `/dev/ttyACM0` on Linux; ArduCopter SITL is `udp:127.0.0.1:14550`.
|
|
70
|
+
|
|
71
|
+
## Use
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
urml execute program.urml.yaml -m manifest.yaml --profile drone --no-policy \
|
|
75
|
+
--adapter ardupilot --adapter-config ardupilot_adapter.yaml
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
A minimal `ardupilot_adapter.yaml`:
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
connection_url: "COM5"
|
|
82
|
+
baud: 115200
|
|
83
|
+
|
|
84
|
+
location_to_pose: # local metres from the launch point
|
|
85
|
+
bench_north: { north: 5.0, east: 0.0, alt: 3.0 }
|
|
86
|
+
home: { north: 0.0, east: 0.0, alt: 0.0 }
|
|
87
|
+
|
|
88
|
+
location_to_global: # WGS84, wins over location_to_pose for the same name
|
|
89
|
+
site_p1: { lat: 32.0853, lon: 34.7818, alt_agl: 100.0, look_at: { lat: 32.0850, lon: 34.7815 } }
|
|
90
|
+
|
|
91
|
+
camera:
|
|
92
|
+
kind: digicam # or `servo` with `channel`
|
|
93
|
+
|
|
94
|
+
output_lines:
|
|
95
|
+
payload_latch: { kind: gripper, instance: 1 }
|
|
96
|
+
winch: { kind: winch, instance: 1, deliver_length_m: 15.0, rate_m_s: 0.5 }
|
|
97
|
+
|
|
98
|
+
payload_mechanisms: # RFC-0684 `release(mode: winch | latch)`
|
|
99
|
+
delivery_winch: { kind: winch, instance: 1, deliver_length_m: 15.0, rate_m_s: 0.5 }
|
|
100
|
+
drop_hook: { kind: gripper, instance: 2 }
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`location_to_global` is written by [`tools/scripts/geocode_locations.py`](../../tools/scripts/geocode_locations.py) at configuration time. The runtime never geocodes and never touches the network.
|
|
104
|
+
|
|
105
|
+
From Python:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from urml_ardupilot_runtime import ArduCopterAdapter, load_ardupilot_config
|
|
109
|
+
from urml_ros2_runtime import URMLRuntime
|
|
110
|
+
|
|
111
|
+
with ArduCopterAdapter(load_ardupilot_config("ardupilot_adapter.yaml")) as adapter:
|
|
112
|
+
runtime = URMLRuntime(adapter)
|
|
113
|
+
result = runtime.execute(program, manifest, envelope, profiles=("drone",))
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`CompositeAdapter` from the PX4 runtime accepts an `ArduCopterAdapter` as its `flight` backend unchanged.
|
|
117
|
+
|
|
118
|
+
## Tests
|
|
119
|
+
|
|
120
|
+
Three tiers, mirroring the PX4 runtime:
|
|
121
|
+
|
|
122
|
+
- `tests/test_arducopter_adapter.py`: hermetic, a fake `pymavlink` is injected; runs everywhere.
|
|
123
|
+
- `tests/integration/test_arducopter_live.py`: gated on `URML_ARDUPILOT_INTEGRATION=1`; real pymavlink, no autopilot contacted.
|
|
124
|
+
- `tests/integration/test_arducopter_bench.py`: gated on `URML_ARDUPILOT_BENCH=<port>`; a real board, props off. Asserts the identity probe, a successful battery read through the runtime, and that a take-off is refused cleanly by the autopilot's own pre-arm checks.
|
|
125
|
+
- `tests/integration/test_arducopter_sitl_e2e.py`: gated on `URML_ARDUPILOT_SITL=1`; flies the `drone/flight_only_positive` conformance fixture against ArduCopter SITL.
|
|
126
|
+
|
|
127
|
+
## Status
|
|
128
|
+
|
|
129
|
+
Bench link verified on hardware (Pixhawk, ArduCopter 4.6.3, USB). The SITL e2e (flight-only fixture plus both flight-test examples) is green against ArduCopter SITL built from `Copter-4.6.3`, run locally on 2026-08-29. No physical flight is claimed anywhere in this repository; see [`docs/demos/sentence-to-pixhawk.md`](../../docs/demos/sentence-to-pixhawk.md) for the bench runbook and the two flight-test runbooks that gate a field run on a green SITL pass.
|
|
130
|
+
|
|
131
|
+
## License
|
|
132
|
+
|
|
133
|
+
Business Source License 1.1: free for non-production use, commercial license for production (see [`LICENSING.md`](../../LICENSING.md)). The adapter talks to ArduPilot firmware (GPLv3) over MAVLink; it links `pymavlink` (LGPLv3) as a normal Python import and never links the firmware.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "urml-ardupilot-runtime"
|
|
7
|
+
version = "0.5.0"
|
|
8
|
+
description = "ArduPilot / MAVLink reference runtime for URML — Universal Robot Language."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "BUSL-1.1" }
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
authors = [{ name = "URML Maintainers" }]
|
|
13
|
+
keywords = ["robotics", "drone", "ardupilot", "arducopter", "pixhawk", "mavlink", "urml", "runtime"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 3 - Alpha",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: Other/Proprietary License",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Topic :: Scientific/Engineering",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"pydantic>=2.6,<3",
|
|
26
|
+
"PyYAML>=6.0,<7",
|
|
27
|
+
"urml-validator>=0.5.0",
|
|
28
|
+
"urml-ros2-runtime>=0.5.0",
|
|
29
|
+
"urml-px4-runtime>=0.5.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
# pymavlink is the MAVLink transport; pyserial is what pymavlink needs to
|
|
34
|
+
# open a USB or telemetry-radio serial port (a Pixhawk on COM5 or
|
|
35
|
+
# /dev/ttyACM0). The px4 extra omits pyserial because PX4 SITL is UDP;
|
|
36
|
+
# a physical ArduPilot board is almost always serial first.
|
|
37
|
+
ardupilot = [
|
|
38
|
+
"pymavlink>=2.4,<3",
|
|
39
|
+
"pyserial>=3.5,<4",
|
|
40
|
+
]
|
|
41
|
+
dev = [
|
|
42
|
+
"pytest>=8",
|
|
43
|
+
"pytest-cov>=5",
|
|
44
|
+
"ruff>=0.5",
|
|
45
|
+
"mypy>=1.10",
|
|
46
|
+
]
|
|
47
|
+
|
|
48
|
+
[project.urls]
|
|
49
|
+
Homepage = "https://github.com/urml-dev/URML"
|
|
50
|
+
Repository = "https://github.com/urml-dev/URML"
|
|
51
|
+
Issues = "https://github.com/urml-dev/URML/issues"
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.targets.wheel]
|
|
54
|
+
packages = ["src/urml_ardupilot_runtime"]
|
|
55
|
+
|
|
56
|
+
[tool.ruff]
|
|
57
|
+
line-length = 120
|
|
58
|
+
target-version = "py311"
|
|
59
|
+
src = ["src", "tests"]
|
|
60
|
+
|
|
61
|
+
[tool.ruff.lint]
|
|
62
|
+
select = ["E", "F", "W", "I", "B", "UP", "N", "ANN", "RUF"]
|
|
63
|
+
ignore = ["ANN401"]
|
|
64
|
+
|
|
65
|
+
[tool.ruff.lint.per-file-ignores]
|
|
66
|
+
"tests/*" = ["ANN"]
|
|
67
|
+
|
|
68
|
+
[tool.mypy]
|
|
69
|
+
strict = true
|
|
70
|
+
python_version = "3.11"
|
|
71
|
+
plugins = ["pydantic.mypy"]
|
|
72
|
+
mypy_path = "src"
|
|
73
|
+
packages = ["urml_ardupilot_runtime"]
|
|
74
|
+
|
|
75
|
+
[tool.pytest.ini_options]
|
|
76
|
+
minversion = "8.0"
|
|
77
|
+
testpaths = ["tests"]
|
|
78
|
+
addopts = ["-q", "--strict-markers"]
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""urml_ardupilot_runtime — ArduPilot / MAVLink reference runtime for URML.
|
|
2
|
+
|
|
3
|
+
Public API:
|
|
4
|
+
|
|
5
|
+
ArduCopterAdapter(config)
|
|
6
|
+
MAVLink adapter for ArduCopter (Pixhawk-class boards running ArduPilot,
|
|
7
|
+
or ArduCopter SITL). Subclasses the PX4 reference adapter and adds the
|
|
8
|
+
ArduPilot-specific preamble that PX4 does not need: GUIDED mode entry,
|
|
9
|
+
explicit arming, ack filtering by command id, arrival waits, global
|
|
10
|
+
(WGS84) setpoints, camera trigger, and output lines (gripper, winch,
|
|
11
|
+
servo). pymavlink is imported lazily so this module loads everywhere.
|
|
12
|
+
|
|
13
|
+
ArduPilotAdapterConfig
|
|
14
|
+
Connection + identity + location bindings. Loaded from YAML via
|
|
15
|
+
load_ardupilot_config(path).
|
|
16
|
+
|
|
17
|
+
probe(config)
|
|
18
|
+
Read-only identity snapshot of the connected autopilot. Also exposed as
|
|
19
|
+
``python -m urml_ardupilot_runtime.probe COM5``.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
from urml_ardupilot_runtime._version import __version__
|
|
25
|
+
from urml_ardupilot_runtime.adapter import ArduCopterAdapter, probe
|
|
26
|
+
from urml_ardupilot_runtime.config import (
|
|
27
|
+
ArduPilotAdapterConfig,
|
|
28
|
+
CameraTrigger,
|
|
29
|
+
GlobalPosition,
|
|
30
|
+
OutputLineBinding,
|
|
31
|
+
load_ardupilot_config,
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
__all__ = [
|
|
35
|
+
"ArduCopterAdapter",
|
|
36
|
+
"ArduPilotAdapterConfig",
|
|
37
|
+
"CameraTrigger",
|
|
38
|
+
"GlobalPosition",
|
|
39
|
+
"OutputLineBinding",
|
|
40
|
+
"__version__",
|
|
41
|
+
"load_ardupilot_config",
|
|
42
|
+
"probe",
|
|
43
|
+
]
|