Repository-README

Installation und die kürzesten Wege zu einem laufenden Setup.

Originaltitel im Repository: AI Drone

Software and guarded tools for a Raspberry Pi Zero 2 W companion, a FlywooF745 ArduPilot controller, downward MTF-01P range/optical flow, a forward MT-15 lidar, an IMX500 camera, and a payload servo.

The implemented flight path is a bounded GPS-free takeoff, optical-flow Loiter hold, and landing. Room navigation and calibrated tag approach remain planned work. Keep live inspection disarmed; actuator and flight commands require explicit authorization and their physical prerequisites.

The 9 September firmware and power update records the installed custom ArduCopter 4.7.1 build, connection/shutdown helpers and live checks. All four ESCs have the acoustically refined WAV 34 startup melody. The MT-15 integration report records forward lidar reaching the FC and Pi alongside downward range/flow. The earlier repair report records relative EKF aiding and the unresolved compass pre-arm issue. Recheck hardware before use; sensing and simulation results do not establish flight readiness.

The consolidation report records the shared main branch, Pi deployment and restored connectivity. The team-access follow-up verifies shared SSH permissions and eduroam preference; use the SSH alias setup for ssh seb@seb-is-pm. See CONTRIBUTING.md before starting new development work.

#Start here

Install uv and create the locked environment:

uv sync --frozen
uv run --locked drone-connect --help
uv run --locked drone-inspect --help

Python 3.11–3.13 is supported. The Pi uses Debian Python 3.13 with apt-installed Picamera2/libcamera bindings; the laptop environment does not need Pi hardware packages.

Use uv run --locked <command> for project commands; uv manages .venv without requiring activation. On the deployed Pi, include --group raspi to retain its vision dependencies, for example uv run --locked --group raspi drone-walk --duration 30. The detached worker keeps the selected interpreter for the whole recording; finish the job before syncing or updating its environment.

The helpers try Tailscale, hotspot, then Pi USB Ethernet:

uv run --locked drone-connect
uv run --locked drone-connect --transport hotspot

For deployment, select the reachable Pi address. This example uses Tailscale; when joined to AI-Drone-Zero, use PI_HOST=seb@192.168.4.1:

PI_HOST=seb@seb-is-pm.tail59e6a4.ts.net uv run --locked drone-deploy
PI_HOST=seb@seb-is-pm.tail59e6a4.ts.net uv run --locked drone-deploy --run inspect -- --duration 30

Deployment alone starts no task. The inspection requests telemetry and records available camera/sensor data without arming or moving anything. A battery may be needed to power sensors. See networking and the separate procedures for Pi USB Ethernet and direct FC USB.

For a timed, hand-carried recording with detached capture, CSV exports and an offline browser report, follow the room walkthrough procedure.

For full sensor capture that opens the mount once on AprilTag 3, disarmed or during manual flight, use scripts/tag_mount_capture.py.

#Commands

Use uv run --locked <command> --help for authoritative options. Before any actuation, follow the relevant operating procedure. In particular, normal arming checks must pass; simulation does not establish live flight readiness, mechanical servo travel, or an emergency-control arrangement.

#Documentation and evidence

The documentation map separates maintained procedures from dated observations:

• Hardware and configuration: inventory, FC wiring and parameters, firmware.
• Operation: sensor recording, connection and shutdown status, FC checks, GPS-free hover, planned AprilTag mission.
• History: dated captures in state/ and params/, historical notes, and retired code.

Raw recordings and local research/build artifacts remain under ignored artifacts/; they are not automatically included in a Git checkout. Project drone captures must never be replaced with another aircraft's configuration.

#Development checks

uv sync --frozen --group dev
uv run --frozen --group dev ruff format --check .
uv run --frozen --group dev ruff check .
uv run --frozen --group dev ty check .
uv run --frozen --group dev pytest -q
uv run --frozen --group dev lint-imports
uv run --frozen --group dev deptry .
git diff --check

The three opt-in simulator cases need the exact external ArduPilot checkout and SITL binary; see the pinned simulator acceptance gate. Contributor architecture and hardware boundaries are documented in CLAUDE.md and AGENTS.md.

The project site presents the same maintained guides alongside the historical project poster. Preview it with uv run --group docs python site/build.py --serve.