Sensing Server APIs & WebSockets
Relevant source files
The following files were used as context for generating this wiki page:
The Sensing Server provides the programmatic interfaces for the RuView (WiFi-DensePose) platform. It exposes RESTful endpoints for system management and historical data retrieval, alongside high-frequency WebSocket streams for real-time human pose and vital sign data. These interfaces bridge the gap between low-level WiFi Channel State Information (CSI) processing and frontend visualizations or third-party integrations.
The system utilizes a hybrid architecture: a Rust-based wifi-densepose-api crate using the Axum framework handles core sensing logic, while a FastAPI-based layer manages extended middleware and authentication. This enables sub-100ms latency for real-time streaming to mobile, web, and desktop clients.
Sources: plans/overview.md:5-45, plugins/ruview/skills/ruview-cli-api/SKILL.md:46-54, references/README.md:27-31
REST API Architecture
The REST API manages the sensing lifecycle, environmental configuration, and historical data access. The Axum router serves requests on port 3000 by default when running via Docker or the sensing server binary.
Core Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/pose/status | Returns server health, uptime, and component capabilities. |
GET | /api/pose/zones | Retrieves configured sensing zones and occupancy grids. |
GET | /api/pose/frames | Returns a list of historical sensing frames (supports limit param). |
POST | /system/start | Initializes the CSI receiver and neural network pipeline. |
POST | /system/stop | Gracefully shuts down the data pipeline and saves state. |
PUT | /config | Updates detection thresholds, max persons, and tracking settings. |
Sources: ui/mobile/README.md:162-167, plans/phase1-specification/api-spec.md:126-175, v2/crates/wifi-densepose-desktop/README.md:45-55
Data Flow Overview
The diagram shows the transition from raw WiFi signal ingestion to multi-protocol data distribution.
Sources: plans/overview.md:5-30, plans/phase1-specification/functional-spec.md:55-65
WebSocket Protocol
The WebSocket interface provides high-frequency updates (10-30 FPS) for live sensing. The mobile and web applications connect to ws://<host>:3001/ws/sensing. The server supports automatic protocol upgrades from HTTP/HTTPS to WS/WSS.
Sensing Frame Structure
Real-time data is encapsulated in a SensingFrame object, which includes:
- Nodes: Array of individual sensing node metrics (RSSI, position).
- Features: Statistical features like mean RSSI, variance, and motion band power.
- Classification: Motion levels, presence detection, and confidence scores.
- Signal Field: A 3D voxel grid representing the environment.
- Vital Signs: Breathing rate (6-30 BPM) and heart rate proxy (40-120 BPM).
Sources: ui/mobile/README.md:144-160, plans/phase1-specification/api-spec.md:315-330
Connection Lifecycle
The sequence illustrates the low-latency streaming loop maintained between the client and server.
Sources: ui/mobile/README.md:139-160, plans/phase1-specification/api-spec.md:300-313, ui/TEST_REPORT.md:46-53
External Integrations
The Sensing Server extends its reach through standard IoT and broadcast protocols to support disaster response (MAT) and remote monitoring.
MQTT and Webhooks
The server publishes pose updates and alerts to a hierarchical MQTT topic structure:
wifi-densepose/pose/person/{id}: Individual person coordinates and activity.wifi-densepose/alerts/fall_detection: High-priority safety events.wifi-densepose/status/system: Hardware health and network connectivity.
Webhooks provide a push mechanism for event-driven notifications, supporting configurable retry policies and Bearer token authentication.
Sources: plans/phase1-specification/api-spec.md:486-535
Restream Integration
For live broadcasting, the system integrates with the Restream API. It generates a real-time pose visualization overlay (skeleton or dense pose) and streams it via RTMP to platforms such as YouTube and Twitch.
Sources: plans/phase1-specification/api-spec.md:546-575, plans/phase1-specification/functional-spec.md:197-210
Performance and Security
The API layer is designed to meet strict performance targets to ensure usability in safety-critical applications like fall detection.
| Metric | Target |
|---|---|
| End-to-End Latency | <100ms (95th percentile) |
| WebSocket Delivery | <50ms |
| Throughput | 10,000 REST requests/sec |
| Max Concurrent WS | 1,000 connections |
| Processing Rate | 10-30 FPS |
Sources: plans/phase1-specification/api-spec.md:658-675, plans/phase1-specification/functional-spec.md:162-175
Authentication and Authorization
Access to sensitive sensing data is protected via JSON Web Tokens (JWT). The system implements Domain-Based Access Control (DBAC):
- Healthcare Domain: Restricts data access according to privacy requirements.
- Security Domain: Enables enhanced audit logging and intrusion alerts.
- API Keys: Used for service-to-service communication between the server and external tools like
wifi-densepose-cli.
Sources: plans/phase1-specification/api-spec.md:440-475
Conclusion
The Sensing Server APIs and WebSockets form a robust communication backbone for RuView. By combining REST for configuration and WebSockets for real-time telemetry, the system enables complex human sensing tasks—such as through-wall pose estimation and vital sign monitoring—with high reliability and low latency. The inclusion of MQTT and Restream support ensures the platform is ready for both professional healthcare environments and mass-scale disaster response scenarios.