Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,6 @@ vosk-model*/

# Scratch output created by the dataset downloader
mute_mode/tmp_videos/

# Mute Mode v2: downloaded WLASL videos (re-fetch with mute_mode/wlasl_fetch.py)
mute_mode/raw_videos/
118 changes: 73 additions & 45 deletions README.md

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions assets/architecture.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 6 additions & 6 deletions assets/mode_matrix.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions blind_mode/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,15 @@
# 0.03 s gives a small margin; anything beyond that is a bad reading or a
# disconnected sensor — return None instead of hanging forever.
ECHO_TIMEOUT_S = 0.03

# ── Decision engine tuning (used by engine.py) ───────────────────────────────
POLL_INTERVAL_S = 0.1 # target loop period; the engine uses measured time
MIN_VALID_CM = 2.0 # HC-SR04 blind zone
MAX_VALID_CM = 400.0 # HC-SR04 rated range; longer echoes are noise
SPEED_DEADBAND_CM_S = 15.0 # ignore closing speeds below this (sensor jitter)
SPEED_EMA_ALPHA = 0.5 # smoothing for the closing speed
TTC_ALERT_S = 1.5 # haptic alert when time to collision is below this
TTC_SPEAK_S = 1.0 # spoken alert (center sensor) below this
PROXIMITY_WARN_CM = 60.0 # short pulse for a close but static obstacle
PROXIMITY_DANGER_CM = 30.0 # longer pulse + speech for a very close obstacle
STALE_AFTER_S = 0.6 # forget a sensor's history after this long without a valid echo
8 changes: 4 additions & 4 deletions blind_mode/distance.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,16 @@ def get_distance(trig, echo, timeout=ECHO_TIMEOUT_S):
GPIO.output(trig, GPIO.LOW)

# Wait for ECHO to go HIGH — bail out if it takes too long
deadline = time.time() + timeout
deadline = time.perf_counter() + timeout
while GPIO.input(echo) == 0:
if time.time() > deadline:
if time.perf_counter() > deadline:
return None # echo never rose — sensor disconnected or faulty

# Capture the moment ECHO went HIGH, then wait for it to go LOW
pulse_start = time.time()
pulse_start = time.perf_counter()
pulse_end = pulse_start
while GPIO.input(echo) == 1:
pulse_end = time.time()
pulse_end = time.perf_counter()
if (pulse_end - pulse_start) > timeout:
return None # echo stuck HIGH — sensor fault or no return

Expand Down
136 changes: 136 additions & 0 deletions blind_mode/engine.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# blind_mode/engine.py
# -----------------------------------------------------------------------------
# Blind Mode decision engine (hardware free, fully unit testable).
#
# Fixes over the original loop:
# * closing speed uses the REAL time between readings. The old loops divided
# by a hard coded 0.1 s even though reading three sensors (plus, in the
# ModeManager adapter, blocking motor pulses) made the true interval much
# longer, which inflated speeds and produced false "imminent" alerts.
# * readings are median filtered and out of range echoes are rejected, so a
# single bad echo no longer looks like an object teleporting toward you.
# * speed is smoothed and a small dead band ignores sensor jitter.
# * a PROXIMITY alert fires for close obstacles even when nothing is moving.
# The old logic only used time to collision, so a user standing still with
# a wall 20 cm in front of them got no warning at all.
# -----------------------------------------------------------------------------

from collections import deque
from dataclasses import dataclass
from typing import Dict, List, Optional

try:
from blind_mode import config as _cfg
except ImportError: # scripts run from inside blind_mode/
import config as _cfg

MIN_VALID_CM = getattr(_cfg, "MIN_VALID_CM", 2.0)
MAX_VALID_CM = getattr(_cfg, "MAX_VALID_CM", 400.0)
SPEED_DEADBAND_CM_S = getattr(_cfg, "SPEED_DEADBAND_CM_S", 15.0)
SPEED_EMA_ALPHA = getattr(_cfg, "SPEED_EMA_ALPHA", 0.5)
TTC_ALERT_S = getattr(_cfg, "TTC_ALERT_S", 1.5)
TTC_SPEAK_S = getattr(_cfg, "TTC_SPEAK_S", 1.0)
PROXIMITY_WARN_CM = getattr(_cfg, "PROXIMITY_WARN_CM", 60.0)
PROXIMITY_DANGER_CM = getattr(_cfg, "PROXIMITY_DANGER_CM", 30.0)
STALE_AFTER_S = getattr(_cfg, "STALE_AFTER_S", 0.6)


def ttc_to_pulse_ms(ttc: Optional[float], threshold: float = TTC_ALERT_S) -> Optional[int]:
"""Same tiers as haptic.get_alert_intensity: <0.5 s 500 ms, <1.0 s 300 ms, <1.5 s 150 ms."""
if ttc is None:
return None
if ttc < 0.5:
return 500
if ttc < 1.0:
return 300
if ttc < threshold:
return 150
return None


def proximity_to_pulse_ms(distance: Optional[float]) -> Optional[int]:
if distance is None:
return None
if distance < PROXIMITY_DANGER_CM:
return 300
if distance < PROXIMITY_WARN_CM:
return 150
return None


@dataclass
class SensorState:
label: str
distance: Optional[float]
speed: Optional[float]
ttc: Optional[float]
pulse_ms: Optional[int]
reason: Optional[str] # "ttc", "proximity" or None


class SensorTrack:
"""Filtered distance, speed and time to collision for one ultrasonic sensor."""

def __init__(self, label: str, window: int = 3):
self.label = label
self._raw = deque(maxlen=window)
self._last_d: Optional[float] = None
self._last_t: Optional[float] = None
self._speed: Optional[float] = None

def update(self, distance: Optional[float], t: float) -> SensorState:
valid = distance is not None and MIN_VALID_CM <= distance <= MAX_VALID_CM
if valid:
self._raw.append(float(distance))
elif self._last_t is not None and t - self._last_t > STALE_AFTER_S:
# sensor has been silent for a while: forget the old state
self._raw.clear()
self._last_d = self._last_t = self._speed = None

if not self._raw:
return SensorState(self.label, None, None, None, None, None)

d = sorted(self._raw)[len(self._raw) // 2] # median filter
if valid and self._last_d is not None and self._last_t is not None and t > self._last_t:
inst = (self._last_d - d) / (t - self._last_t)
self._speed = inst if self._speed is None else SPEED_EMA_ALPHA * inst + (1 - SPEED_EMA_ALPHA) * self._speed
if valid:
self._last_d, self._last_t = d, t

speed = self._speed
ttc = d / speed if (speed is not None and speed > SPEED_DEADBAND_CM_S and d > 0) else None

p_ttc = ttc_to_pulse_ms(ttc)
p_prox = proximity_to_pulse_ms(d)
pulse, reason = None, None
if p_ttc is not None or p_prox is not None:
if (p_ttc or 0) >= (p_prox or 0):
pulse, reason = p_ttc, "ttc"
else:
pulse, reason = p_prox, "proximity"
return SensorState(self.label, d, speed, ttc, pulse, reason)


class BlindEngine:
"""Turns timestamped readings from all sensors into haptic and speech decisions."""

def __init__(self, labels=("left", "center", "right")):
self.tracks = {lb: SensorTrack(lb) for lb in labels}

def step(self, readings: Dict[str, Optional[float]], t: float) -> List[SensorState]:
return [self.tracks[lb].update(readings.get(lb), t) for lb in self.tracks]

@staticmethod
def speech_for(states: List[SensorState]) -> Optional[str]:
"""Short spoken warning, or None. Center has priority, then the closer side."""
by = {s.label: s for s in states}
c = by.get("center")
if c and ((c.ttc is not None and c.ttc < TTC_SPEAK_S) or
(c.distance is not None and c.distance < PROXIMITY_DANGER_CM)):
return "Obstacle ahead"
sides = [s for s in states if s.label in ("left", "right") and s.distance is not None
and (s.distance < PROXIMITY_DANGER_CM or (s.ttc is not None and s.ttc < 0.5))]
if sides:
closest = min(sides, key=lambda s: s.distance)
return f"Obstacle {closest.label}"
return None
57 changes: 57 additions & 0 deletions blind_mode/haptic.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,63 @@ def get_alert_intensity(ttc, threshold=1.5):
return None


class HapticDriver:
"""
Non blocking driver for all haptic motors.

The ModeManager adapter used to call pulse_motor() inline, which froze the
sensor loop for up to 500 ms per motor. Here a single background thread
switches motors off when their pulse expires, and a motor that is already
buzzing is not re-triggered until its pulse plus a short gap has passed,
so overlapping pulses cannot cut each other short and the wearer feels
distinct buzzes whose length encodes urgency.
"""

GAP_MS = 120

def __init__(self, motors=None, gpio=None):
import threading
self._gpio = gpio or GPIO
self._motors = dict(motors or MOTORS)
self._off_at = {lb: 0.0 for lb in self._motors}
self._next_ok = {lb: 0.0 for lb in self._motors}
self._lock = threading.Lock()
self._stop = threading.Event()
self._thread = threading.Thread(target=self._run, daemon=True, name="haptic-driver")
self._thread.start()

def pulse(self, label, duration_ms):
"""Request a pulse; returns True if it started, False if the motor is still busy."""
if not duration_ms or label not in self._motors:
return False
now = time.monotonic()
with self._lock:
if now < self._next_ok[label]:
return False
self._gpio.output(self._motors[label], self._gpio.HIGH)
self._off_at[label] = now + duration_ms / 1000.0
self._next_ok[label] = self._off_at[label] + self.GAP_MS / 1000.0
return True

def _run(self):
while not self._stop.is_set():
now = time.monotonic()
with self._lock:
for lb, t_off in self._off_at.items():
if t_off and now >= t_off:
self._gpio.output(self._motors[lb], self._gpio.LOW)
self._off_at[lb] = 0.0
self._stop.wait(0.01)

def stop(self):
self._stop.set()
self._thread.join(timeout=0.5)
with self._lock:
for lb, pin in self._motors.items():
self._gpio.output(pin, self._gpio.LOW)
self._off_at[lb] = 0.0


# ── Unit tests for get_alert_intensity ─────────────────────────────────────

def _test_get_alert_intensity():
Expand Down
Loading
Loading