aether-robotics 4.5.3

Autonomous multi-agent robotics system with DRL-First Hybrid FDIR

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

AETHER v4.5.3 — 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

---

What's New

v4.5.3 — Hotfix: retrieval no longer breaks planning, and AETHER won't fake a motion command

• Retrieved memory can't hijack the output format. v4.3.0 appended the RAG context after the planner's "reply with valid JSON only" rule, so the last thing the model read was arrow-formatted prose. Once memory was migrated, every plan failed to parse. Context now goes before a restated JSON contract, and the block itself uses plain prose — no arrows, no bracketed lists.
• Parse failures show the response. A bare "Could not parse JSON" made this class of bug undiagnosable. The raw reply (first 600 chars) is now printed on any parse failure, in both the planner and the decomposer.
• A movement command is never answered by a web search. web_search was the universal last-resort fallback in three separate places, so "drive forward until you get close to the wall" became a web search about driving — reported as SUCCESS with 0 faults, then replayed forever from memory. Now: research fallbacks are vetoed for motion intent, cached chains whose category contradicts the objective are discarded, and an intent/execution mismatch reports MISMATCH instead of SUCCESS. If no motion tool can be selected, AETHER says so and names the motion tools that do exist.
• Quieter diagnostics. huggingface_hub's unauthenticated-request warnings no longer print mid-planner-call.

v4.5.2 — Hotfix: reactive tools reachable in autonomous mode

• Autonomous mode registers parallel skills. Agent mode merged registered skill names into the tool manifest; the autonomous bootstrap discarded them. drive_until_obstacle was in the registry but absent from the manifest, so the planner's pick was rejected as "unavailable" and the goal died with "try rephrasing". Both modes now share the same merge.
• The planner only advertises tools that exist. v4.5.1's routing guidance names drive_until_obstacle and watch_distance explicitly, so it is now withheld on robots where they aren't registered — advertising an unresolvable tool is a manifest bug, not an LLM mistake.
• Registry gaps are reported honestly. A dropped tool triggers one re-plan with that tool barred; if the goal still can't be met, AETHER names the missing tool and the capability it needs instead of blaming your wording.
• OLED detection verifies instead of guessing. Discovery used to report an OLED as [OK] whenever the SPI node existed and luma.oled imported — even with no panel wired. Every write then failed on GPIO pin-numbering mode, the planner kept adding display steps because the tool looked available, and objectives whose real work had succeeded were reported DEGRADED. Detection now performs a real write and reports the reason when it fails; writes restore BCM mode and retry once (a later GPIO.cleanup() clears it); the planner no longer adds display steps unless you ask for one; correction aborts immediately on errors no retry can fix; and an unusable output sink no longer counts as a task fault.
• No command exits 0 in silence. The TUI restores the terminal on exit, which made a quick open/close look identical to a command that did nothing; it now prints a closing line, falls back to the classic CLI on any startup error, and main() returns an explicit exit code. New subprocess smoke tests invoke the real entry point and assert non-empty output for every documented invocation — the class of check that in-process tests cannot make.

v4.5.1 — Reactive and observational sensing (safety fix)

v4.5.0 could run a motion and a sensor read concurrently, but get_distance is single-shot: paired with a 3-second drive it returned one reading at the start and the robot then travelled blind. Sensing during motion needs primitives that keep sensing.

• drive_until_obstacle — reactive. Drives forward and stops itself when the ultrasonic sees an obstacle, easing off speed on approach. Use it whenever a goal says "watch for obstacles", "don't crash", or "stop when". Forward only: the sensor faces forward, so reversing "until obstacle" is refused rather than run blind.
• watch_distance — observational. Samples the sensor repeatedly for a whole window and returns every reading plus min/max/avg, without touching the motors — so it is safe in a parallel group with one motion tool. Optional stop_on_threshold_cm acts as a tripwire.
• Intent routing — the planner now distinguishes three intents that look alike in English: reactive ("watching for obstacles" → drive_until_obstacle), observational ("log the distances" → motion + watch_distance), and independent ("at the same time" → a normal parallel group). When a goal is ambiguous and motion is involved, it prefers reactive — an unnecessary stop is cheap, a collision is not.
• Device contention — the safety validator now rejects two tools claiming the same physical device even when their names differ (watch_distance + get_distance, or either alongside drive_until_obstacle, which polls that sensor internally).

goal> drive forward for 3 seconds while watching for obstacles
  [EXEC] drive_until_obstacle(max_duration_s=3.0, stop_distance_cm=20)
  [OK] obstacle at 21.2 cm — stopped

v4.5.0 — Parallel autonomous execution (with hard safety guards)

Autonomous mode now runs physically-independent sub-objectives concurrently instead of one at a time — so the robot can observe while it moves, not only after it stops.

• Parallel groups — sub-objectives may declare "parallel_group": "name" to run together and "depends_on": ["group"] to wait. Omit both and they run sequentially, exactly as in v4.0.0.2. Existing goal files keep working untouched.

• Motion + sensing — running a motion and an observation together. ⚠️ Pair the motion with watch_distance (v4.5.1), not a bare get_distance: get_distance is single-shot and returns one reading at the start of the group, so the robot travels blind for the rest of the motion.

• Hard safety validator — grouping is enforced, not trusted. Five rules reject unsafe concurrency and auto-serialize it:

  Rejected	Why
  Two locomotion tools	they fight over the same motors
  emergency_stop + anything	an emergency stop must run alone
  Two writes to one servo channel	final position undefined
  Two actuator writes on one adapter	the adapter can't service both
  The same sensor twice	one device, and both reads sample the same pose

  A rejected group still executes — one task at a time — and the reason is fed back to the planner so it stops proposing that shape.

• Safety chain unchanged — the v3.9.0 executor still owns daemon workers, the process-wide stop, and the atexit halt. Ctrl-C mid-group pauses the goal (resumable), fires emergency stop, and leaves nothing latched. emergency_stop is always forced to run alone.

• Analytics — parallel_group_executed, parallel_group_rejected, and parallelism_speedup (sequential estimate vs actual wall time) show where concurrency is paying off.

[AUTONOMOUS Group 1/3] Running 2 tasks in parallel
  ● get_distance()
  ● capture_image()
  [OK] 2/2 completed in 411ms

v4.3.0 — Memory retrieval (RAG over your own history)

AETHER now learns from what you have already asked it to do. Every recorded objective is embedded locally, and each new plan is grounded in the most similar successful runs from your history.

Retrieval is opt-in (v4.3.0.1): pip install 'aether-robotics[rag]'. The extra pulls PyTorch, which is a large download and has no wheels on 32-bit Raspberry Pi OS — so the core install stays small and AETHER runs identically without it, just with retrieval switched off.

• Local embeddings — all-MiniLM-L6-v2 (22 MB, 384-dim, ~50 ms on a Pi 4). Downloads once, then runs entirely offline; no objective text ever leaves the machine.
• Semantic retrieval — retrieve_similar(query, k, min_similarity, filter_success) finds past objectives by meaning, not keywords: "go forward for three seconds" matches a stored "drive forward for 2 seconds" at 0.71 similarity.
• Grounded planning — the agent planner, the autonomous decomposer, and aether --fix each get a RELEVANT PAST OBJECTIVES block of successful precedents (~70 tokens). With no relevant history the block is omitted entirely, so prompts are byte-identical to v4.2.0.
• aether memory — inspect and search what AETHER remembers:

aether memory                       # counts, embedding state, disk usage
aether memory list -n 10            # recent objectives and their tool chains
aether memory search "turn around"  # semantic search with similarity scores
aether memory migrate               # (re-)embed entries
aether memory export dump.json      # dump to a file

• Automatic migration — entries recorded before v4.3.0 are embedded on first boot with progress output, written atomically; an interrupted migration simply resumes next run.
• Privacy — objectives are scrubbed by the v3.9.6 redactor before embedding, so no vector is ever derived from a secret. The memory_retrieval telemetry event carries only a query hash, result count, top similarity, memory size, and latency — never the query text and never a vector.

Retrieval degrades gracefully: without the [rag] extra (or if the model can't load) the retrieval block is omitted and planning behaves exactly as it did in v4.2.0 — no errors, no stack traces. aether memory tells you which state you're in.

v4.2.0 — Full-screen TUI

Run aether with no arguments and the terminal becomes a product-grade, Claude Code-style TUI built on textual — minimal, orange-on-your-terminal-background, no full-screen repaint:

• Layout — header (version · mode · adapters), a sidebar mode list with the AETHER mascot parked bottom-left, the active mode's pane, and a live status bar (adapters · telemetry · session clock · action count · animated busy spinner).
• Agent mode — type an objective; planning renders in-flow right below it as a live block: a thinking animation while Claude plans, then a concise "thought" chain (move_forward → get_distance → stop) and a step list whose dots animate ○ pending → spinner running → ● done, each with its wall-clock seconds.
• Doctor mode — the diagnostic report as live ✓/⚠/✗ sections with a rerun key.
• Slash commands + palette — /agent, /doctor, /clear, /help, /exit, … from the input, or Ctrl+P for a fuzzy command palette. Ctrl+D exits, Ctrl+C cancels the current operation (never exits), Ctrl+L clears.
• Classic CLI untouched — every --mode, doctor, analytics, --fix, --calibrate invocation runs the exact pre-4.2.0 CLI. The TUI opens only for bare aether (or aether --tui) on an interactive terminal; pipes/CI and AETHER_CLASSIC=1 always get the classic REPL.

aether                    # full-screen TUI
aether --tui              # explicit
AETHER_CLASSIC=1 aether   # force the classic REPL

Autonomous, Calibrate, Fix, and Analytics currently open in the TUI as panes pointing at their classic commands; native TUI widgets for them land in a follow-up.

v4.1.5 — Rich terminal UI

The whole CLI got a Claude Code-inspired visual overhaul — same flow, same commands, just rendered with rich:

• Boot log adapter panels — each loaded adapter shown with its role (● primary / ○ namespaced), tool count, I2C address, and claimed GPIO pins.
• Autonomous mode live status bar — a persistent panel showing the goal, a progress bar, the current sub-objective, and elapsed time vs. budget, updated between steps with ✓/▶ step markers.
• aether analytics dashboard — sessions overview, top-tools and adapters tables, --fix and autonomous panels, color-coded success rates.
• --calibrate wizard — numbered menu tables and validated rich prompts.
• LLM spinners — a live spinner whenever AETHER waits on Claude (planning, goal decomposition, --fix proposals).
• Colored status tags — [OK]/[FAIL]/[WARN] colorized in terminals.
• Strict plain-text fallback — in pipes, CI, or with --no-color / AETHER_NO_COLOR=1, every output path emits the exact pre-4.1.5 plain text, so log parsers and scripts are unaffected.

v4.1.0 — Local analytics + opt-in telemetry

• aether analytics — local usage dashboards: sessions, top tools by call count and success rate, adapters loaded, error patterns, --fix and autonomous-mode stats. Data lives in ~/.aether/analytics/; --export FILE dumps JSON, --clear wipes it.
• Telemetry is strictly opt-in (v4.1.0.2: one-time consent prompt on every mode entrypoint). When enabled, anonymized events go to PostHog — goal text and errors are hashed, never sent raw. Toggle with aether analytics --enable-telemetry / --disable-telemetry; inspect with --telemetry-status.

v4.0.0 — Autonomous mode

Give AETHER a high-level goal and it decomposes, executes, observes, and replans on its own:

aether --mode autonomous --goal "map out the room" --time-budget 300

• LLM goal decomposition — the goal becomes an ordered list of sub-objectives bound to your robot's actual registered tools (never legacy/unavailable ones, v4.0.0.2).
• Self-directed execution loop — each step executes against the live ToolRegistry, logs an observation, and persists the goal after every state change; Ctrl-C loses at most the in-flight step.
• Adaptive replanning — a failed step triggers an LLM replan of the remaining plan, or a clean abort with a reason.
• Resumable — --resume continues a paused/timed-out goal, --status inspects it, --history lists finished goals, --clear drops it.
• Safety — motors are stopped only at end-of-goal or interrupt (each tool already carries its own try/finally stop); a final report synthesizes what actually happened from real observations.

v3.11.5 → v3.11.10 — Namespacing, servo naming, GPIO-conflict detection

• Tool namespacing (v3.11.5) — every adapter's tools register as <adapter>.<tool>; bare names route to the primary adapter, secondaries stay reachable via their namespace. First-loaded-wins collisions are gone.
• --calibrate structured wizard + named servos (v3.11.6) — map channels, name servos (gripper → first-class move_gripper(angle) tool at next boot), set pulse-width limits, and test channels per adapter.
• GPIO conflict detection (v3.11.10) — adapters declare their BCM pins; conflicts are detected at load and shown in aether doctor's GPIO allocation map.
• PCA9685 safety hardening — guaranteed hard-off via MODE1 SLEEP with wake-on-write, FULL-OFF stop writes (no auto-spin on restart), neutral pulses for continuous servos, and exit hooks that fire the correct namespaced emergency_stop.

v3.11.0 — Multi-HAT discovery + multi-adapter loading

AETHER no longer assumes exactly one HAT. It now scans all hardware and loads every detected adapter.

• Multi-pass discovery — every I2C device (and USB-serial port, for MAVLink) is probed; discovery returns a confidence-ranked list instead of stopping at the first match:

  [DISCOVERY] Detected hardware:
    - I2C 0x14: sunfounder_picarx (confidence: 0.95)
    - I2C 0x16: yahboom_robot_hat (confidence: 0.90)
  

• Multi-adapter registration — all detected adapters register in confidence order. Tool-name collisions are first-loaded-wins; the ignored tool is preserved in a collision shadow registry (a _TOOL_ORIGIN map attributes every tool to its owning adapter) and a warning is printed.
• robot.json v1.1 — composite robots get an adapters[] array attributing tools + I2C address to each adapter. v1.0 (single-adapter) genomes keep loading unchanged.
• aether doctor shows each detected adapter, per-adapter tool counts, and a predicted collision count.
• PCA9685 all-call filter — the 0x70 broadcast address is dropped from discovery when 0x40 is also present (it's the same chip answering twice).

Tool collisions were first-loaded-wins in this release; namespacing (v3.11.5) and GPIO-conflict detection (v3.11.10) superseded that — see above.

v3.10 — Self-Healing (aether doctor, aether kits, aether --fix)

AETHER can now diagnose and repair itself.

• aether doctor (v3.10.0) — a read-only diagnostic: Python/OS, group membership, API key, I2C/serial/camera/SPI hardware, which adapter would load, file-system state, and recent boot errors. Exits non-zero if anything fails.
• aether kits (v3.10.0) — list / info <kit> / install <kit>. info is read-only (queried without touching hardware); install runs an auditable per-kit YAML recipe with explicit consent at each sudo step.
• aether --fix (v3.10.5 → v3.10.10) — describe a misbehavior in plain English and AETHER proposes a fix, then drives the robot to verify it before keeping it:
  • Value calibration via ~/.aether/overrides.json (adapter-qualified keys, full history, atomic writes) — e.g. "the car doesn't turn enough" → bumps sunfounder_picarx.turn_angle.
  • Code patches via ~/.aether/proposed_patches/ (v3.10.10) — a unified diff against an aether/ file, restricted by an allowlist (no vendor/test/version files), patch --dry-run-gated, backed up before apply, verified by a behavior test in a fresh subprocess, and auto-rolled-back on failure.
  • Patches never auto-apply; every behavior test is motor-safety gated; the boot path warns if a pip upgrade overwrote an active patch.

See docs/DOCUMENTATION.md (full reference).

v3.9.x — Motion quality, safety, and three more kits

• 10 Tier 1 adapters (v3.9.7): added SunFounder PiDog (quadruped walking gait), Yahboom robot HAT (YB_Pcb_Car, I2C 0x16), and GoPiGo3 (Dexter Industries) — bringing built-in kit support to ten.
• Smooth driving (v3.9.3): drive_until_obstacle drives continuously (re-issuing only on approach-speed band changes) to eliminate start-stop jitter; pulsed fallback for non-SunFounder adapters.
• Robust ultrasonic (v3.9.4–v3.9.5): boot-time sensor health probe + clearer wiring guidance, and a consecutive (not cumulative) bad-read counter so motor-EMI noise no longer trips false "sensor failing" halts.
• Security (v3.9.6): API keys and other secrets are redacted from experience memory (redact_secrets), with a one-time scrub of any previously-leaked secrets at startup. Also restored OLED GPIO mode after the motor probe.

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.

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.

---

Quick Start

pip install aether-robotics                         # core install (fast, ~80 MB)
pip install 'aether-robotics[rag]'                  # + vector memory retrieval

aether --calibrate                                  # first-time hardware setup
aether                                               # full-screen TUI (v4.2.0)
aether --mode agent                                 # classic REPL — talk to your robot
aether --mode autonomous --goal "map out the room"  # hand it a goal and step back
aether analytics                                    # local usage dashboard

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 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.
• Adapts to unknown HATs automatically. Plug in a SunFounder PiCar-X or PiDog, Freenove 4WD/Mecanum, Adeept, Waveshare, Yahboom, GoPiGo3, or any custom driver board and AETHER figures it out during --calibrate. Ten pre-built Tier 1 adapters cover the most common kits. 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.

Robot Genome

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.

---

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
--mode autonomous	High-level goal in, self-directed sub-task decomposition and execution out (v4.0.0)

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
--no-color	Disable colored/formatted output (also via AETHER_NO_COLOR=1) — for CI, scripts, log parsing
--verbose	Enable debug logging

Autonomous Mode Flags (v4.0.0+)

Flag	When to use
--goal "..."	The high-level goal (omit to be prompted, e.g. "map out the room")
--time-budget SECONDS	Max wall-clock time for the goal (default: 300)
--resume	Continue the saved goal (paused or timed-out)
--status	Print current goal state and exit
--history	Show completed goals
--clear	Drop the active goal (asks y/N)

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

Self-Healing Subcommands (v3.10+)

Command	What it does
aether doctor	Read-only diagnostic report (system, install, API key, hardware, adapter, file system, recent boot). Exit 1 on any failure.
aether kits list	List all 10 Tier 1 kits + Tier 2/3 notes
aether kits info <kit>	Detection logic, tools, locomotion class, vendor library, and install scope for one kit
aether kits install <kit>	Guided installer (per-sudo-step consent) from an auditable YAML recipe
aether --fix	Describe an issue in English → AETHER proposes a value override or code patch, drives the robot to verify, then keeps or rolls back
aether --fix --list / --history / --revert <key> / --revert-all	Inspect/revert value calibration overrides (~/.aether/overrides.json)
aether --fix --list-patches / --review <hash> / --apply <hash>	Inspect, review (diff), or apply a proposed code patch
aether --fix --revert-patch <hash> / --revert-all-patches / --reapply-all	Roll back code patches from backup, or re-apply after a pip upgrade

Analytics Subcommands (v4.1.0+)

Command	What it does
aether analytics	Summary dashboard: sessions, top tools, adapters, --fix + autonomous stats, recent errors
aether analytics --sessions / --tools / --errors / --autonomous / --fix	Drill into one slice (-n N to limit)
aether analytics --export FILE	Dump all local analytics as JSON for external tools
aether analytics --clear	Clear local analytics data (asks y/N)
aether analytics --enable-telemetry / --disable-telemetry / --telemetry-status	Manage strictly opt-in anonymized telemetry

---

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)

10 HAT boards / kits with Tier 1 adapters (v3.9.7)

Board	Detection	Capabilities
SunFounder PiCar-X	picarx importable or I2C 0x14	forward · backward · turn · camera pan/tilt · distance
SunFounder PiDog	pidog importable (Robot HAT 0x14)	quadruped walking gait · head 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
Yahboom robot HAT	YB_Pcb_Car importable or I2C 0x16	drive · turn · camera pan/tilt · distance
GoPiGo3	easygopigo3 / gopigo3 importable (SPI)	drive · turn · ToF distance

Install any of these with aether kits install <name> (recipes shipped for PiCar-X, PiDog, Freenove 4WD, Yahboom, GoPiGo3).

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)
• ✓ Phase 3 — Auto-Adapter System — Tier 1 pre-built adapters (now 10), Tier 2 LLM-generated + validated, Tier 3 guided wizard; --generate-adapter-from offline mode (docs/auto-adapter-system.md)
• ✓ Phase 3.5 — Self-Healing — aether doctor/kits diagnostics, and aether --fix value-calibration overrides + verified code patching (v3.10)
• ✓ Phase 3.6 — Multi-HAT — multi-pass discovery + multi-adapter loading with robot.json v1.1 (v3.11.0), tool namespacing + primary-adapter routing (v3.11.5), structured --calibrate wizard with named servos (v3.11.6), GPIO-conflict detection (v3.11.10)
• ✓ Phase 3.7 — Autonomous Mode — LLM goal decomposition, self-directed execution loop with adaptive replanning, resumable persisted goals (v4.0.0)
• ✓ Phase 3.8 — Analytics + UX — local usage analytics with strictly opt-in telemetry (v4.1.0), rich terminal UI with plain-text fallback (v4.1.5)
• 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 [e-mail] for access.

---

Citation

@software{aether2026,
  title   = {AETHER: Autonomous Operating System for Robots},
  author  = {Paatur, Chahel},
  year    = {2026},
  version = {4.5.3},
  url     = {https://aether-robotics.com},
  note    = {DRL-First Hybrid FDIR with physical-map calibration, LLM planning, MAVLink integration, multi-HAT Auto-Adapter System, self-healing calibration/code patching, autonomous goal decomposition, a full-screen TUI, memory retrieval, and safety-validated parallel execution},
}

---

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