Metadata-Version: 2.4
Name: aether-robotics
Version: 3.7.4
Summary: Autonomous multi-agent robotics system with DRL-First Hybrid FDIR
Author: Chahel Paatur
License: MIT
Project-URL: Homepage, https://github.com/ChahelPaatur/AETHER
Project-URL: Repository, https://github.com/ChahelPaatur/AETHER
Project-URL: Issues, https://github.com/ChahelPaatur/AETHER/issues
Keywords: robotics,autonomous,FDIR,fault-detection,raspberry-pi,drone,AI
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Hardware
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: requests>=2.32.0
Provides-Extra: full
Requires-Dist: anthropic>=0.50.0; extra == "full"
Requires-Dist: flask>=3.0.0; extra == "full"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "full"
Requires-Dist: matplotlib>=3.7.0; extra == "full"
Provides-Extra: pi
Requires-Dist: picamera2; extra == "pi"
Requires-Dist: RPi.GPIO; extra == "pi"
Requires-Dist: gpiozero; extra == "pi"
Requires-Dist: smbus2; extra == "pi"
Provides-Extra: drone
Requires-Dist: pymavlink; extra == "drone"
Requires-Dist: pyserial; extra == "drone"
Provides-Extra: ml
Requires-Dist: ultralytics; extra == "ml"
Requires-Dist: scipy; extra == "ml"
Requires-Dist: scikit-learn; extra == "ml"
Dynamic: license-file

```
    ████████████████████████████████
   ████████████████████████████████
  █████╔═══════════════════╗█████
  █████║  ▄████▄   ▄████▄  ║█████
  █████║ ████████████████ ║█████
  █████║ ██████████████ ║█████
  █████║ █▀▀████████▀▀█ ║█████
  █████║  ▀████▀   ▀████▀  ║█████
  █████║▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄║█████
  █████║  ━━━━━━━━━━━━━━━  ║█████
  █████║  ▌ AETHER  v3 ▐  ║█████
  █████║  ━━━━━━━━━━━━━━━  ║█████
  █████╚═══════════════════╝█████
   ████████████████████████████████
    ████████████████████████████████
```

# AETHER v3.7.4 — Autonomous Robotics Operating System

> AETHER is the autonomous operating system for robots. Plug in and talk to your robot in plain English and ask it to do anything you want.

AETHER connects to whatever hardware is present at startup, discovers every actuator through an interactive GPIO calibration walk, and writes a `physical_map` of every servo and motor by BCM pin. That map feeds into an LLM planner that translates plain-English objectives into the correct hardware action — pin pre-filled, servo type resolved, direction inferred. Motion commands dispatch to GPIO, while a PPO fault-detection network runs concurrently on the 15-dimensional sensor observation vector, detecting and recovering from failures in real time. Every layer — discovery, pin mapping, natural-language planning, execution, fault recovery — runs on a Raspberry Pi with no cloud dependency except the Anthropic API for the planner.

[Demo and docs → aether-robotics.com](https://aether-robotics.com)

---

## What's New

### v3.7.0 — Auto-Adapter System

AETHER now detects unknown robot HATs and boards automatically during `--calibrate`. Seven pre-built Tier 1 adapters cover the most common kits (SunFounder PiCar-X, Freenove 4WD and Mecanum, Adeept HAT v3, PCA9685 generic, L298N direct GPIO, Waveshare motor driver). For anything else, Tier 2 reads the manufacturer's Python library, calls Claude to generate an adapter, runs it through 6 static-validation rules, and requires a live hardware behavioral test before accepting it. Tier 3 is a guided interactive wizard for when no library is available. All generated adapters are stored locally at `~/.aether/adapters/` and load automatically on future runs.

New flags: `--generate-adapter-from <path>`, `--save-to <path>`, `--no-auto-adapter`.

See [docs/auto-adapter-system.md](docs/auto-adapter-system.md).

### v3.6.0 — MAVLink Quadcopter Integration

AETHER now drives MAVLink flight controllers (INAV / ArduPilot / PX4) through the same natural-language interface as GPIO robots. The same Robot Genome that maps rover wheels maps quadcopter rotors. Five non-negotiable arming safety rules are enforced in every motor command: arm-permitted flag required, pre-arm check must pass, sensor availability verified, 30-second inactivity auto-disarm, emergency stop always registered. Bench-demo verified (props off). Flight commands (takeoff, hover, land) gated behind `--arm-permitted`.

See [docs/mavlink-integration.md](docs/mavlink-integration.md).

---

## Quick Start

```bash
pip install aether-robotics
aether --calibrate
aether --mode agent
```

Calibration walks every safe GPIO pin (BCM 4–27, excluding I2C/SPI/UART), pulses each with a positional servo sweep, and prompts you to label what moved. The result is a `physical_map` saved in your calibration profile and loaded automatically at next startup.

If AETHER detects a known HAT board during calibration, it loads the matching Tier 1 adapter and registers capabilities automatically. For unknown boards, it offers to generate one.

Once calibrated:

```
objective> move the wheel forward for 5 seconds
[PLAN]  [LLM]  servo_cont_wheel
[EXEC]  servo_cont_wheel(speed=50, duration=5)
[OK]    success=True  (5009ms)
```

---

## What AETHER Does That Others Don't

- **Discovers the robot.** Calibration walks every GPIO pin, you label what moved, AETHER builds a `physical_map` with BCM pin, device type, and action label for each actuator (unlike ROS/Viam where you configure drivers manually before the system knows what hardware exists).
- **Publishes the Robot Genome.** Every calibrated robot gets a versioned `robot.json` identity card — a stable, portable description of its locomotion class, actuators, and sensors. Capabilities are derived deterministically from the genome (same hardware = same capability set), so skills written for a `differential_drive` genome run on every matching robot without wiring changes. See [docs/robot-genome-v1.md](docs/robot-genome-v1.md) for the published schema.
- **Speaks natural language.** Type plain English; the LLM planner resolves intent against your robot's genome capabilities and dispatches the correct actuator — BCM pin pre-filled, servo type resolved, direction inferred (unlike ROS action servers that require typed message structs and correct namespace knowledge).
- **Detects faults in real time.** DRL-First Hybrid FDIR achieves SFRI 69.99, 100% detection rate, and 100% recovery rate over 6,023 real-hardware steps (unlike threshold-rule systems that require manual parameter tuning per platform and miss novel fault signatures).
- **Improves through use.** Correction traces are logged per step; operational memory and sim-to-real action transfer are on the roadmap (unlike static planners that repeat the same failure mode without feedback).
- **Drives drones via MAVLink.** The same genome that maps your rover's wheels maps your quadcopter's rotors. Plug in a MAVLink FC (INAV / ArduPilot / PX4), calibrate once, and type plain English — AETHER handles arm, motor test, and attitude commands via the same natural-language interface as every other robot it knows. See [docs/mavlink-integration.md](docs/mavlink-integration.md).
- **Adapts to unknown HATs automatically.** Plug in a SunFounder PiCar-X, Freenove 4WD, Adeept, Waveshare, or any custom driver board and AETHER figures it out during `--calibrate`. Seven pre-built Tier 1 adapters cover the most common HATs. For anything unknown, Tier 2 reads the manufacturer's Python library and generates a validated adapter using Claude — subject to static safety rules, a sandboxed dry-run, and a mandatory hardware behavioral test before it's accepted. Tier 3 collects control snippets interactively when no library is available. Generated adapters are stored locally at `~/.aether/adapters/` and load automatically on future runs. See [docs/auto-adapter-system.md](docs/auto-adapter-system.md).

### Robot Genome

```bash
aether --genome show
```

```
Robot Genome
  ID:         f47ac10b-...
  Locomotion: differential_drive
  Hash:       a3f1d92e...

Capabilities (6)
  drive_backward  drive_forward  emergency_stop  stop  turn_left  turn_right
```

The genome is stored at `configs/robot.json` and auto-migrates from `physical_map` on
first load of a v3.4.x profile. Skills declare `SKILL_REQUIRES = ["drive_forward", ...]`
and AETHER rejects skills the robot's genome cannot satisfy — before any hardware moves.
Full schema, derivation rules, and skill authoring guide: [docs/robot-genome-v1.md](docs/robot-genome-v1.md).

---

## Commands

### Modes

| Flag | Description |
|------|-------------|
| `--mode sim` | Simulation with fault injection against a virtual robot (default) |
| `--mode agent` | Interactive LLM-planned objectives on live hardware; prompts for input |
| `--mode realworld` | Continuous live-hardware FDIR loop — camera + system sensors, no planner |
| `--mode server` | HTTP API on `--port`; accepts `POST /objective` and `GET /health` |

### Useful Flags

| Flag | When to use |
|------|-------------|
| `--calibrate` | First-time setup — walks every GPIO pin, you label what moves; loads or generates HAT adapters |
| `--recalibrate` | Re-run the full pin walk (e.g. after wiring changes); skips known-empty pins; preserves `robot_id` |
| `--auto-calibrate` | Headless calibration with no interactive prompts |
| `--genome show` | Print the loaded robot genome (locomotion, actuators, capabilities) and exit |
| `--task "objective"` | Task description for `--mode sim` |
| `--schedule "..."` | Scheduled runs: `"every 30s: scan environment"`, `"for 5min: obj"`, `"until 22:00: obj"` |
| `--continuous` | Run `--mode realworld` indefinitely until Ctrl-C |
| `--robot {rover_v1,drone_v1}` | Robot config for `--mode sim` (default: `rover_v1`) |
| `--faults {disabled,enabled,heavy}` | Fault injection level for sim/realworld (default: `disabled`) |
| `--scenario TEXT` | Sim scenario: `simple`, `obstacles`, `imu_fault`, `battery`, `compound`, `fault_heavy` |
| `--max-steps N` | Max steps per episode (default: 300) |
| `--seed N` | Random seed for reproducible sim runs (default: 42) |
| `--render` | Print ASCII state render at each sim step |
| `--plots` | Generate matplotlib SFRI/metrics plots after a sim run |
| `--no-learning` | Freeze PPO weights — useful for controlled benchmarking |
| `--port N` | Port for `--mode server` (default: 8080) |
| `--auto-install` | Install missing Python packages without prompting |
| `--auto-update` | Pull the latest version without prompting |
| `--no-install` | Skip the package-install prompt entirely |
| `--no-update` | Skip the update check |
| `--verbose` | Enable debug logging |

### MAVLink Flags (v3.6.0+)

| Flag | When to use |
|------|-------------|
| `--arm-permitted` | Enable arming and flight commands for MAVLink robots; required before any motor spins |

### Auto-Adapter Flags (v3.7.0+)

| Flag | When to use |
|------|-------------|
| `--generate-adapter-from PATH` | Offline mode: read vendor library at PATH, call Claude, validate, print summary; does not require hardware |
| `--save-to PATH` | Save the output of `--generate-adapter-from` to PATH instead of `/tmp/` |
| `--no-auto-adapter` | Disable Tier 2/3 adapter generation; Tier 1 pre-built adapters still load normally |

---

## Supported Hardware

**Tested and working**

Raspberry Pi 4 Model B · USB camera or picamera2 · GPIO servos (positional or continuous-rotation) · SSD1306 OLED over SPI · Anthropic API (LLM planner and vision)

**HAT boards with Tier 1 adapters (v3.7.0)**

| Board | Detection | Capabilities |
|-------|-----------|--------------|
| SunFounder PiCar-X | `picarx` importable or I2C 0x14 | forward · backward · turn · camera pan/tilt · distance |
| Freenove 4WD | `Motor` importable | 6 motion tools |
| Freenove Mecanum | I2C 0x40 + `Motor` | 8 motion tools including strafe left/right |
| Adeept HAT v3 | `adeept` importable | 6 motion tools |
| PCA9685 generic | I2C 0x40 + `Adafruit_PCA9685` | 6 motion tools |
| L298N direct GPIO | GPIO available, no I2C, `RPi.GPIO` | 6 motion tools |
| Waveshare motor driver | `waveshare_motor` importable or I2C 0x47 | 6 motion tools |

**MAVLink flight controllers (bench-demo in v3.6.0)**

INAV · ArduPilot · PX4. Auto-detected during `--calibrate`; arm, motor test, and attitude commands verified at bench (props off). Flight commands gated behind `--arm-permitted`.

**Should work, unverified**

Pi Zero 2 W · Pi 5 (requires `rpi-lgpio` in place of `RPi.GPIO`)

**In development**

Arduino/ESP32 serial bridge · multi-robot coordination

---

## Architecture

```
  User input (plain English)
        │
        ▼
  ToolDiscovery ──────────────► physical_map + robot.json genome
        │                                  │
        │                    AdapterResolver (Tier 1 → 2 → 3)
        │                         └── ~/.aether/adapters/  (persisted)
        ▼                                  │
  LLMPlanner ◄──── genome capabilities injected into planner context
        │
        ▼
  NavigationEngine  (L1 camera / L2 GPIO / L3 MAVLink)
        │                         │
        ▼                         ▼
  Hardware (servo/motor/FC)  FaultAgent (PPO, 15-dim obs → fault class)
                                   │
                             detect · recover · log
```

---

## Benchmarks

Real-hardware deployment: Raspberry Pi 4, GPIO servos, live camera, Anthropic API planner.

| Metric | Value | Conditions |
|--------|------:|------------|
| SFRI | **69.99** | 6,023 steps, real hardware |
| MTTR | **1.35 steps** | Mean time to recover from injected fault |
| Detection rate | **100%** | 0 misses, 0 false positives |

> SFRI (Stability Fault Recovery Index) = 35×DR + 25×(1 − MTTR/max\_steps) + 10×RR − 30×FPR. Range 0–70; higher is better.

---

## Roadmap

- ✓ **Phase 1 — Reverse Engineering** — GPIO pin walk, physical_map, LLM-planned hardware control
- ✓ **Phase 2 — Robot Genome** — versioned `robot.json` schema, deterministic capability derivation, skill portability ([docs/robot-genome-v1.md](docs/robot-genome-v1.md))
- ✓ **Phase 3 — Auto-Adapter System** — Tier 1 pre-built adapters, Tier 2 LLM-generated + validated, Tier 3 guided wizard; `--generate-adapter-from` offline mode ([docs/auto-adapter-system.md](docs/auto-adapter-system.md))
- **Phase 4 — Vision-Language Grounding** — "follow the orange cone", scene-grounded navigation, in progress
- **Phase 5 — Operational Memory + Sim-to-Real Action Transfer**
- **Phase 6 — Multi-robot coordination**

---

## Early Access

AETHER is in early access. We're working with a small number of robotics teams and researchers to refine the platform. Email chahelpaatur@aether-robotics.com for access.

---

## Citation

```bibtex
@software{aether2026,
  title   = {AETHER: Autonomous Operating System for Robots},
  author  = {Paatur, Chahel},
  year    = {2026},
  version = {3.7.0},
  url     = {https://aether-robotics.com},
  note    = {DRL-First Hybrid FDIR with physical-map calibration, LLM planning, MAVLink integration, and Auto-Adapter System},
}
```

---

AETHER is proprietary software in early access. All rights reserved. © 2026 Chahel Paatur.
