BiOScan 1138 🛰️

Real-time WiFi RTI & through-wall human detection dashboard for SignalEyez.

Built on FastAPI + Strawberry GraphQL (backend) and React 19 + TypeScript + Tailwind (frontend). Wraps the existing SignalEyez Python engine — no hardware changes required.

What is BiOScan 1138?

BiOScan 1138 is a web-based real-time dashboard that visualizes through-wall human detection using WiFi signals. It leverages Radio Tomographic Imaging (RTI) techniques to detect human presence and movement by analyzing changes in WiFi signal strength (RSSI) from nearby access points.

The system works by:

• Continuously scanning WiFi signals from access points in the environment
• Analyzing RSSI variance patterns to detect movement and human presence
• Using FFT analysis to identify breathing patterns (0.15-0.50 Hz band)
• Generating RTI heatmaps using Tikhonov regularization to visualize person positions
• Providing real-time updates through GraphQL subscriptions over WebSockets

This dashboard wraps the SignalEyez engine, providing an intuitive UI for monitoring and controlling the detection system without requiring any modifications to existing WiFi infrastructure.

---

Architecture

CoreWLAN (macOS WiFi)
  └─→ ScannerService (daemon thread, ~1 Hz)
        └─→ EventBus [TOPIC_SCAN]
              ├─→ DetectorService  →  TOPIC_DETECTION  →  liveDetection  (GraphQL sub)
              └─→ SpatialService   →  TOPIC_SPATIAL    →  liveSpatial    (GraphQL sub)

bioscan_1138/
├── main.py                    ← FastAPI entry point
├── requirements.txt
├── core/
│   ├── config.py              ← Pydantic BaseSettings (env-driven)
│   └── events.py              ← Thread-safe asyncio pub/sub event bus
├── scanner/
│   ├── models.py              ← APReading, ScanCycle
│   ├── service.py             ← Wraps macos_scanner (CoreWLAN)
│   └── schema.py              ← GraphQL: scannerStatus query
├── detector/
│   ├── models.py              ← DetectionFrame, APState, BreathingInfo
│   ├── service.py             ← Wraps HumanDetector (baseline → monitoring)
│   └── schema.py              ← GraphQL: detectionStatus query + liveDetection subscription
├── spatial/
│   ├── models.py              ← SpatialFrame, PersonPosition, HeatmapGrid
│   ├── service.py             ← Wraps SpatialEstimator + RTI solver
│   └── schema.py              ← GraphQL: spatialStatus query + liveSpatial subscription
├── graphql/
│   └── schema.py              ← Merged schema: Query, Mutation, Subscription
└── frontend/                  ← React 19 dashboard (see frontend/README.md)

---

Prerequisites

Requirement	Version
macOS	12+ (for CoreWLAN)
Python	3.13 (not 3.14 — strawberry-graphql compatibility)
Node.js	18+

Python 3.13 via Homebrew: brew install python@3.13

---

Backend Setup & Run

1. Create Virtual Environment (Python 3.13)

cd /Users/ibrahim/projects/bioscan_1138

python3.13 -m venv .venv
source .venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

3. Environment Variables (optional)

Create a .env file in bioscan_1138/:

WIFI_INTERFACE=en5        # your WiFi interface (check: networksetup -listallhardwareports)
SENSITIVITY=medium        # low | medium | high
ROOM_WIDTH_M=12.0
ROOM_HEIGHT_M=10.0
CORS_ORIGINS=["http://localhost:5173"]

4. Start the Server

cd /Users/ibrahim/projects/bioscan_1138
source .venv/bin/activate

python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

• API: http://localhost:8000
• GraphiQL IDE: http://localhost:8000/graphql
• Health check: http://localhost:8000/

⚠️ The scanner needs Location Services enabled for your terminal in System Preferences → Privacy.

---

GraphQL API

Queries

query {
  engineStatus { isRunning phase sensitivity wifiInterface scanCount }
  scannerStatus { isRunning scanCount scannerClass }
  detectionStatus { humanDetected confidence breathingDetected phase }
  spatialStatus { flatWidthM flatHeightM persons { x y confidence } }
}

Mutations

mutation {
  startEngine(sensitivity: "medium", interface: "en5") { isRunning phase }
  stopEngine { isRunning }
}

Subscriptions (WebSocket)

subscription {
  liveDetection {
    humanDetected confidence breathingRateBpm
    numDynamicAps numBreathingAps numTotalAps
    phase baselineProgress timestamp
  }
}

subscription {
  liveSpatial {
    persons { x y sigma confidence breathingRateBpm }
    apPositions { groupId x y isSameRoom }
    heatmap { data rows cols }
  }
}

---

Frontend Dashboard

The frontend is a modern React 19 dashboard with real-time visualization capabilities. It provides an intuitive interface for monitoring WiFi-based human detection and spatial tracking.

Tech Stack

• React 19 with latest features (useOptimistic, useTransition, Suspense)
• TypeScript 5.9 for full type safety
• Vite 7 for fast development and optimized builds
• Tailwind CSS 3 with custom dark sci-fi theme
• Apollo Client 3 for GraphQL queries, mutations, and subscriptions
• graphql-ws for WebSocket-based real-time updates
• Recharts for animated signal variance charts
• Three.js + React Three Fiber for 3D spatial visualization
• GraphQL Codegen for auto-generated typed hooks

Dashboard Components

Component	Description
Toolbar	Engine controls (start/stop), sensitivity settings, WiFi interface selection, connection status
Live Signal Chart	Real-time rolling RSSI variance chart showing activity from detected access points over 60s window
3D Spatial Map	Interactive 3D RTI heatmap visualization with detected person positions and AP locations
Status Indicator	Live detection status with pulsing badges (CLEAR/MOVEMENT/HUMAN DETECTED), confidence percentage, breathing rate BPM, and AP statistics
System Info Panel	Technical details about the detection algorithms and framework

Detection Status Flow

1. Connecting → Loading spinner while establishing WebSocket connection
2. ENGINE IDLE → System ready, awaiting start command
3. CALIBRATING → Yellow progress bar during baseline collection (~30s, keep area clear)
4. CLEAR 🟢 → No human presence detected
5. MOVEMENT 🔵 → Motion detected but below human detection threshold
6. HUMAN DETECTED 🔴 → Confirmed human presence with pulsing indicator and breathing BPM

Real-time Features

• WebSocket subscriptions for live data streaming with automatic reconnection
• Optimistic updates for instant UI feedback on control actions
• Responsive grid layout that adapts from mobile (single column) to desktop (5-column grid)
• Smooth animations with Suspense-based loading states
• Auto-generated GraphQL hooks with full TypeScript inference

Setup & Run

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173 and connects to the backend at http://localhost:8000.

For detailed frontend documentation, see frontend/README.md.

---

Development Notes

• The backend imports modules from SignalEyez at runtime via relative path ../signaleyez/ (hardcoded in spatial/service.py). Both projects should live side-by-side under ~/projects/:

  ~/projects/
  ├── bioscan_1138/        ← This project
  └── signaleyez/          ← Clone from https://github.com/Yuribenjamin/signaleyez
  

• Baseline collection takes ~30 seconds with the area clear. Keep the scan zone empty during calibration.
• Sensitivity presets (low, medium, high) are defined in signaleyez/signal_processing/human_detector.py.
• WebSocket subscriptions use the graphql-ws sub-protocol (not the legacy subscriptions-transport-ws).
• The system requires macOS 12+ for CoreWLAN WiFi scanning capabilities.
• Location Services must be enabled for your terminal application in System Preferences → Privacy for WiFi scanning to work.