aether-robotics 3.9.2__tar.gz → 3.9.4__tar.gz

{aether_robotics-3.9.2/aether_robotics.egg-info → aether_robotics-3.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-robotics
-Version: 3.9.2
+Version: 3.9.4
 Summary: Autonomous multi-agent robotics system with DRL-First Hybrid FDIR
 Author: Chahel Paatur
 License: MIT

{aether_robotics-3.9.2 → aether_robotics-3.9.4}/aether/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "3.9.2"
+__version__ = "3.9.4"
 __author__ = "Chahel Paatur"

{aether_robotics-3.9.2 → aether_robotics-3.9.4}/aether/adapters/sunfounder_picarx.py

@@ -13,6 +13,38 @@ from typing import Dict
 
 _ADAPTER_ID = "sunfounder_picarx"
 
+# Module-level reference to the live Picarx instance, set during register().
+# Used ONLY by the skill-internal continuous-motion primitives below — never
+# exposed as an LLM-callable tool.
+_picarx_instance = None
+
+
+def _continuous_forward(speed: float) -> None:
+    """Start the motor running forward at `speed`. Does NOT auto-stop.
+
+    INTERNAL: only callable by parallel skills that wrap the call in their
+    own try/finally with _continuous_stop() in the finally block. NOT
+    registered as an LLM-callable tool because it breaks the motion-cleanup
+    invariant. The adapter's atexit emergency_stop (v3.7.5) still neutralizes
+    the motor on AETHER exit.
+    """
+    global _picarx_instance
+    if _picarx_instance is None:
+        raise RuntimeError("sunfounder_picarx not initialized")
+    _picarx_instance.forward(float(speed))
+
+
+def _continuous_stop() -> None:
+    """Stop the motor immediately. Safe to call multiple times (idempotent
+    at the Robot HAT level). Called by parallel skills in their try/finally."""
+    global _picarx_instance
+    if _picarx_instance is None:
+        return  # nothing to stop, no init
+    try:
+        _picarx_instance.stop()
+    except Exception:
+        pass  # never raise in cleanup paths
+
 # Config files robot_hat tries to write at runtime. When these are not
 # writable by the current user, robot_hat's filedb.py / config.py invoke
 # os.popen('sudo chmod ...') / os.popen('sudo chown ...'), which pops a
@@ -367,6 +399,39 @@ def register(registry, manifest: dict) -> None:
             print(f"  [ADAPTER] sunfounder_picarx: cali_dir_value inversion "
                   f"failed: {e}")
 
+    # Expose the live instance to the skill-internal continuous-motion
+    # primitives (_continuous_forward / _continuous_stop). These are NOT
+    # registered as tools — only parallel skills with their own try/finally
+    # cleanup may call them. See the module-level helpers above.
+    global _picarx_instance
+    _picarx_instance = car
+
+    # v3.9.4: surface ultrasonic faults early so the user knows before running
+    # skills. This is detection only — it does NOT attempt to fix the sensor.
+    try:
+        # Take 3 quick reads; if all are -1, warn loudly
+        bad = 0
+        for _ in range(3):
+            d = car.ultrasonic.read()
+            if d is None or d < 0 or d > 400:
+                bad += 1
+            time.sleep(0.05)
+        if bad == 3:
+            print("  [ADAPTER] WARNING: ultrasonic sensor returned bad reads "
+                  "on 3/3 probes — drive_until_obstacle may fail.")
+            print("  [ADAPTER] Check sensor wiring (TRIG=D2, ECHO=D3, "
+                  "GND/3V3 power) or run:")
+            print("  [ADAPTER]   python3 -c 'from picarx import Picarx; "
+                  "print(Picarx().ultrasonic.read())'")
+        elif bad > 0:
+            print(f"  [ADAPTER] NOTE: ultrasonic returned {bad}/3 bad reads "
+                  f"— sensor may be intermittent.")
+        else:
+            print("  [ADAPTER] sunfounder_picarx: ultrasonic sensor OK")
+    except Exception:
+        # Never fail boot on a sensor probe — just skip
+        pass
+
     _meta = {"adapter_source": "tier1", "adapter_id": _ADAPTER_ID}
 
     def emergency_stop(**kwargs):
@@ -411,7 +476,9 @@ def register(registry, manifest: dict) -> None:
         speed = float(kwargs.get("speed", 40))
         duration = kwargs.get("duration")
         if duration is None:
-            duration = 1.0
+            # v3.9.4: 1.0s produced too little heading change on the bench;
+            # turn longer before recentering. LLM can still override.
+            duration = 2.0
         try:
             car.set_dir_servo_angle(-30)
             car.forward(speed)
@@ -425,7 +492,9 @@ def register(registry, manifest: dict) -> None:
         speed = float(kwargs.get("speed", 40))
         duration = kwargs.get("duration")
         if duration is None:
-            duration = 1.0
+            # v3.9.4: 1.0s produced too little heading change on the bench;
+            # turn longer before recentering. LLM can still override.
+            duration = 2.0
         try:
             car.set_dir_servo_angle(30)
             car.forward(speed)

{aether_robotics-3.9.2 → aether_robotics-3.9.4}/aether/skills/drive_until_obstacle.py

@@ -1,10 +1,17 @@
-"""AETHER v3.9.0 — drive_until_obstacle parallel skill.
+"""AETHER v3.9.3 — drive_until_obstacle parallel skill.
 
 Drives the robot forward while a second thread polls the ultrasonic sensor,
 stopping automatically when an obstacle is within target_cm. True threaded
-concurrency: motor pulses and sensor reads run on separate threads that share
+concurrency: motor drive and sensor reads run on separate threads that share
 a stop event.
 
+v3.9.3: the motor thread now drives CONTINUOUSLY (via the adapter's
+skill-internal _continuous_forward / _continuous_stop primitives) and only
+re-issues a command when the approach-speed band changes — eliminating the
+start-stop jitter and inconsistent stopping distance of the pulsed path. The
+pulsed path is retained as a fallback for adapters that don't expose the
+continuous primitives.
+
 Demo objective this satisfies (verbatim): "Go forward and stop ~5 cm in front
 of the wall — keep going forward and use the ultrasonic sensor in parallel to
 detect the wall, and stop when it's within 5 cm."
@@ -85,11 +92,66 @@ def drive_until_obstacle(target_cm: float = 5.0, max_speed: float = 25.0,
                 "final_distance_cm": None}
 
     def motor_task(should_stop):
-        """Pulse the motor forward until told to stop; always stop on exit.
+        """Drive the motor until told to stop; always stop on exit.
+
+        Prefers CONTINUOUS motion (v3.9.3): the motor runs without pause and
+        we only re-issue a forward command when the approach-speed band
+        changes. This eliminates the start-stop-start jitter the pulsed path
+        produced (10 accel/decel cycles per second) and makes the stopping
+        distance consistent. Falls back to the pulsed v3.9.1 behavior when the
+        adapter doesn't expose continuous primitives (e.g. a Tier 2 generated
+        adapter), preserving backward compatibility.
 
         Speed follows an approach curve based on the most recent sensor
         reading — full speed when far, easing to ~35% near the target — so
-        the final pulse is short and overshoot stays small."""
+        deceleration begins early and overshoot stays small."""
+        # Try to import the continuous primitives from the adapter. If the
+        # adapter doesn't expose them, fall back to the pulsed approach.
+        #
+        # Gate on _picarx_instance too: the sunfounder module is ALWAYS
+        # importable in-process, so import success alone does not mean the
+        # sunfounder adapter is the live one. A Tier 2 generated adapter
+        # leaves _picarx_instance None — in that case the primitives would
+        # raise RuntimeError, so we must fall back to the pulsed path. Only
+        # use continuous motion when the adapter is actually initialized.
+        try:
+            from aether.adapters.sunfounder_picarx import (
+                _continuous_forward, _continuous_stop, _picarx_instance
+            )
+            use_continuous = _picarx_instance is not None
+        except (ImportError, AttributeError):
+            use_continuous = False
+
+        if use_continuous:
+            try:
+                current_speed = None
+                while not should_halt(should_stop):
+                    with state_lock:
+                        current_dist = state.get("last_distance_cm")
+                    target_speed = _approach_speed(
+                        current_dist if current_dist is not None else 1000.0,
+                        target_cm, max_speed)
+                    # Only re-issue the forward command when speed actually
+                    # changes. Motion stays continuous; we just adjust the
+                    # speed setpoint — no stop between bands, no jitter.
+                    if target_speed != current_speed:
+                        with _MOTOR_LOCK:
+                            if should_halt(should_stop):
+                                break
+                            _continuous_forward(target_speed)
+                            current_speed = target_speed
+                    time.sleep(_POLL_S)  # poll cadence; motor keeps running
+            finally:
+                # Skill-owned cleanup: any exception (including a stop signal)
+                # halts the motor here. A daemon kill at interpreter exit skips
+                # this — the adapter emergency_stop from app's exit handler is
+                # the authoritative kill in that case.
+                with _MOTOR_LOCK:
+                    _continuous_stop()
+            return
+
+        # Pulsed fallback (v3.9.1 behavior) for adapters without
+        # continuous-motion support.
         try:
             while not should_halt(should_stop):
                 with state_lock:
@@ -137,6 +199,19 @@ def drive_until_obstacle(target_cm: float = 5.0, max_speed: float = 25.0,
                 if failures > _MAX_SENSOR_FAILURES:
                     with state_lock:
                         state["stop_reason"] = "sensor failing"
+                    # v3.9.4: surface the fault with actionable wiring guidance
+                    # (detection only — no software fix for the sensor).
+                    print(
+                        f"\n  [SENSOR FAULT] Ultrasonic sensor returned -1 or "
+                        f"out-of-range {state['sensor_failures']} times during "
+                        f"drive_until_obstacle.\n"
+                        f"  This usually means a wiring or hardware issue:\n"
+                        f"    • Check the ultrasonic sensor's 4-pin cable is firmly seated\n"
+                        f"    • TRIG should be on D2, ECHO on D3 (Robot HAT)\n"
+                        f"    • Verify power: red=3V3/5V, black=GND\n"
+                        f"    • Try: python3 -c 'from picarx import Picarx; print(Picarx().ultrasonic.read())'\n"
+                        f"  Skill halted safely for safety.\n"
+                    )
                     should_stop.set()
                     return
                 time.sleep(_POLL_S)

{aether_robotics-3.9.2 → aether_robotics-3.9.4/aether_robotics.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aether-robotics
-Version: 3.9.2
+Version: 3.9.4
 Summary: Autonomous multi-agent robotics system with DRL-First Hybrid FDIR
 Author: Chahel Paatur
 License: MIT

{aether_robotics-3.9.2 → aether_robotics-3.9.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aether-robotics"
-version = "3.9.2"
+version = "3.9.4"
 description = "Autonomous multi-agent robotics system with DRL-First Hybrid FDIR"
 readme = "README.md"
 license = {text = "MIT"}

{aether_robotics-3.9.2 → aether_robotics-3.9.4}/tests/test_drive_until_obstacle.py

@@ -205,3 +205,103 @@ def test_demo_drive_until_obstacle_at_5cm_motor_ceases_after_stop():
     time.sleep(0.4)
     assert reg.move_calls == calls_at_return, "motor kept pulsing after stop"
     assert reg.stop_calls >= 1
+
+
+# ── v3.9.3: continuous-motion motor_task ───────────────────────────────
+#
+# These exercise the path where the sunfounder adapter is LIVE (its
+# _picarx_instance is wired) so the skill drives continuously instead of
+# pulsing. The existing FakeRegistry tests above run with _picarx_instance
+# None (autouse fixture below), so they keep exercising the pulsed path —
+# this is the exact Tier 2 / generic-adapter backward-compat fallback.
+import aether.adapters.sunfounder_picarx as sp  # noqa: E402
+from unittest.mock import MagicMock  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def _picarx_instance_none(monkeypatch):
+    """Default every test to 'sunfounder adapter not live' → pulsed path.
+    Continuous tests opt in by setting _picarx_instance themselves."""
+    monkeypatch.setattr(sp, "_picarx_instance", None, raising=False)
+
+
+def test_motor_task_uses_continuous_when_available(monkeypatch):
+    """With the adapter live, the motor issues only a FEW forward commands
+    (one per approach-speed band change), NOT a pulse 10x/second."""
+    fwd, stop = MagicMock(), MagicMock()
+    monkeypatch.setattr(sp, "_continuous_forward", fwd)
+    monkeypatch.setattr(sp, "_continuous_stop", stop)
+    monkeypatch.setattr(sp, "_picarx_instance", object())   # adapter is live
+
+    reg = FakeRegistry([60, 50, 40, 30, 20, 12, 8, 5, 5, 5])
+    result = drive_until_obstacle(target_cm=5, max_speed=30, timeout_s=8, registry=reg)
+
+    assert "obstacle at" in result["stop_reason"]
+    # Continuous: forward issued once per band (max → 60% → 35%), never spammed.
+    assert 1 <= fwd.call_count <= 3, f"expected ≤3 forward calls, got {fwd.call_count}"
+    # The pulsed registry path must NOT have been used at all.
+    assert reg.move_calls == 0
+    # Speeds applied via the approach curve, monotonically non-increasing.
+    speeds = [c.args[0] for c in fwd.call_args_list]
+    assert speeds == sorted(speeds, reverse=True), speeds
+    stop.assert_called()   # skill-owned cleanup fired
+
+
+def test_motor_task_falls_back_to_pulsed_when_no_continuous(monkeypatch):
+    """Adapter without continuous primitives (e.g. Tier 2) → pulsed
+    move_forward, repeatedly (backward compatibility)."""
+    monkeypatch.delattr(sp, "_continuous_forward", raising=False)
+    monkeypatch.delattr(sp, "_continuous_stop", raising=False)
+
+    reg = FakeRegistry([100])     # wall never appears → keeps pulsing
+    result = drive_until_obstacle(target_cm=5, max_speed=30, timeout_s=1.0, registry=reg)
+
+    assert result["timed_out"] is True
+    assert reg.move_calls >= 2, f"pulsed path should re-issue; got {reg.move_calls}"
+    assert reg.stop_calls >= 1    # pulsed path's finally stop
+
+
+def test_continuous_motor_task_always_stops_on_exception(monkeypatch):
+    """An exception mid-loop (e.g. HAT fault during a forward) must still stop
+    the motor via the skill's finally → _continuous_stop."""
+    boom = MagicMock(side_effect=RuntimeError("HAT fault mid-drive"))
+    stop = MagicMock()
+    monkeypatch.setattr(sp, "_continuous_forward", boom)
+    monkeypatch.setattr(sp, "_continuous_stop", stop)
+    monkeypatch.setattr(sp, "_picarx_instance", object())
+
+    reg = FakeRegistry([100])
+    drive_until_obstacle(target_cm=5, max_speed=30, timeout_s=1.0, registry=reg)
+
+    boom.assert_called()    # the failing forward ran
+    stop.assert_called()    # finally still stopped the motor
+
+
+def test_continuous_motor_task_stops_on_should_stop(monkeypatch):
+    """When the sensor confirms an obstacle and sets should_stop, the motor's
+    finally fires _continuous_stop."""
+    fwd, stop = MagicMock(), MagicMock()
+    monkeypatch.setattr(sp, "_continuous_forward", fwd)
+    monkeypatch.setattr(sp, "_continuous_stop", stop)
+    monkeypatch.setattr(sp, "_picarx_instance", object())
+
+    reg = FakeRegistry([6, 4, 4, 4])   # obstacle confirmed quickly
+    result = drive_until_obstacle(target_cm=5, max_speed=30, timeout_s=5, registry=reg)
+
+    assert "obstacle at" in result["stop_reason"]
+    stop.assert_called()
+
+
+# ── v3.9.4: clearer sensor-fault surfacing ─────────────────────────────
+
+def test_sensor_fault_log_includes_wiring_guidance(capsys):
+    """When the sensor fails (>20 bad reads), the skill halts safely AND prints
+    actionable wiring guidance. Behavior is unchanged — only the log is richer."""
+    reg = FakeRegistry([-1])   # no echo, ever → sensor failing
+    result = drive_until_obstacle(target_cm=5, max_speed=30, timeout_s=5, registry=reg)
+
+    assert result["stop_reason"] == "sensor failing"   # unchanged behavior
+    out = capsys.readouterr().out
+    assert "SENSOR FAULT" in out
+    assert "TRIG" in out and "ECHO" in out
+    assert "wiring" in out

{aether_robotics-3.9.2 → aether_robotics-3.9.4}/tests/test_sunfounder_picarx_adapter.py

@@ -125,7 +125,7 @@ def test_turn_left_recenters_servo_on_exception():
 def test_turn_left_default_duration_when_none_provided():
     reg, car = _register()
     _, sleep_mock = _call(reg, "turn_left")   # no kwargs
-    sleep_mock.assert_called_once_with(1.0)
+    sleep_mock.assert_called_once_with(2.0)   # v3.9.4: 1.0 → 2.0
     # and it still recenters
     assert ("set_dir_servo_angle", 0) in car.calls
 
@@ -476,3 +476,143 @@ def test_is_gpio_busy_error_matches_varied_types():
     assert _is_gpio_busy_error(Exception("gpio line is busy"))
     assert not _is_gpio_busy_error(ValueError("bad pin number"))
     assert not _is_gpio_busy_error(ImportError("no module named picarx"))
+
+
+# ── v3.9.3: skill-internal continuous-motion primitives ────────────────
+
+@pytest.fixture(autouse=True)
+def _reset_picarx_instance():
+    """register() sets the module-global _picarx_instance; isolate tests."""
+    saved = sp._picarx_instance
+    sp._picarx_instance = None
+    yield
+    sp._picarx_instance = saved
+
+
+def test_continuous_primitives_not_in_registry():
+    """The continuous primitives must NEVER be LLM-callable — they break the
+    motion-cleanup invariant by design and are only safe inside a skill's own
+    try/finally. register() must not expose them as tools."""
+    reg, car = _register()
+    assert "_continuous_forward" not in reg.tools
+    assert "_continuous_stop" not in reg.tools
+    # And no alias under a non-underscore name either.
+    assert "continuous_forward" not in reg.tools
+    assert "continuous_stop" not in reg.tools
+    # The standard 12-tool vocabulary is still present.
+    assert "move_forward" in reg.tools
+    assert "emergency_stop" in reg.tools
+
+
+def test_continuous_forward_requires_init():
+    """_continuous_forward before register() (no instance) must raise rather
+    than silently no-op — a skill calling it pre-init is a bug."""
+    sp._picarx_instance = None
+    with pytest.raises(RuntimeError):
+        sp._continuous_forward(20.0)
+
+
+def test_continuous_stop_idempotent():
+    """_continuous_stop must be safe to call repeatedly and never raise —
+    it lives in cleanup paths."""
+    fake = FakePicarx()
+    sp._picarx_instance = fake
+    sp._continuous_stop()
+    sp._continuous_stop()   # second call must not raise
+    assert fake.calls.count(("stop",)) == 2
+
+    # Also safe with no instance (returns early, no raise).
+    sp._picarx_instance = None
+    sp._continuous_stop()
+
+
+def test_continuous_stop_never_raises_when_hat_errors():
+    """If the underlying car.stop() throws, _continuous_stop swallows it."""
+    class BoomStop(FakePicarx):
+        def stop(self):
+            raise RuntimeError("HAT I2C error")
+    sp._picarx_instance = BoomStop()
+    sp._continuous_stop()   # must not propagate
+
+
+def test_register_sets_picarx_instance():
+    """After register(), the module-global instance is wired so the skill's
+    continuous primitives can drive it."""
+    assert sp._picarx_instance is None        # reset by fixture
+    reg, car = _register()
+    assert sp._picarx_instance is not None
+    assert sp._picarx_instance is car
+
+
+def test_continuous_forward_drives_instance():
+    """_continuous_forward issues a forward() WITHOUT a following stop()."""
+    fake = FakePicarx()
+    sp._picarx_instance = fake
+    sp._continuous_forward(33.0)
+    assert ("forward", 33.0) in fake.calls
+    assert ("stop",) not in fake.calls        # continuous: no auto-stop
+
+
+# ── v3.9.4: turn default duration 1.0 → 2.0 ────────────────────────────
+
+def test_turn_left_default_duration_is_2s():
+    reg, car = _register()
+    _, sleep_mock = _call(reg, "turn_left")   # no duration → default
+    sleep_mock.assert_called_once_with(2.0)
+    assert ("set_dir_servo_angle", 0) in car.calls   # still recenters
+
+
+def test_turn_right_default_duration_is_2s():
+    reg, car = _register()
+    _, sleep_mock = _call(reg, "turn_right")
+    sleep_mock.assert_called_once_with(2.0)
+    assert ("set_dir_servo_angle", 0) in car.calls
+
+
+def test_turn_left_explicit_duration_still_works():
+    reg, car = _register()
+    _, sleep_mock = _call(reg, "turn_left", duration=0.5)
+    sleep_mock.assert_called_once_with(0.5)   # LLM override unaffected
+
+
+# ── v3.9.4: boot-time ultrasonic health probe (detection only) ─────────
+
+def _picarx_cls_with_reads(reads):
+    """A FakePicarx subclass whose ultrasonic.read() yields `reads`, then -1.
+    The boot probe reads exactly 3 times."""
+    class _USPicarx(FakePicarx):
+        def __init__(self):
+            super().__init__()
+            seq = list(reads)
+            us = MagicMock()
+            us.read.side_effect = lambda: seq.pop(0) if seq else -1
+            self.ultrasonic = us
+    return _USPicarx
+
+
+def test_register_warns_on_all_bad_sensor_reads(capsys):
+    _register(picarx_cls=_picarx_cls_with_reads([-1, -1, -1]))
+    out = capsys.readouterr().out
+    assert "WARNING: ultrasonic sensor returned bad reads" in out
+    assert "TRIG=D2" in out and "ECHO=D3" in out
+
+
+def test_register_quiet_on_all_good_sensor_reads(capsys):
+    _register(picarx_cls=_picarx_cls_with_reads([50, 50, 50]))
+    out = capsys.readouterr().out
+    assert "ultrasonic sensor OK" in out
+    assert "WARNING" not in out
+
+
+def test_register_notes_intermittent_sensor(capsys):
+    _register(picarx_cls=_picarx_cls_with_reads([50, -1, 50]))
+    out = capsys.readouterr().out
+    assert "NOTE: ultrasonic returned 1/3 bad reads" in out
+
+
+def test_register_never_fails_boot_when_ultrasonic_attr_missing():
+    """Base FakePicarx has no `ultrasonic` attr — the probe must swallow the
+    AttributeError and register the full tool vocabulary anyway."""
+    reg, car = _register()   # default FakePicarx, no ultrasonic
+    assert "move_forward" in reg.tools
+    assert "get_distance" in reg.tools