The SmartSpectra OnPrem package includes four Python example clients that demonstrate different usage patterns, from basic gRPC communication to advanced alternative IPC backends. This guide covers the three advanced examples beyond the Hello World tutorial.

Note: For TypeScript/JavaScript web applications, see TypeScript SDK and Web Applications Guide - TypeScript SDK and Web Applications Guide.

Overview

Example	Purpose	IPC Backend	Key Features
hello_world_on_prem_client.py	Basic introduction	gRPC	Camera capture, metrics display
full_example_on_prem_client.py	Complete gRPC API	gRPC	All endpoints, frame upload, comprehensive control
alt_ipc_example_on_prem_client.py	Alternative IPC	File or Redis	Non-gRPC deployment, backend switching
redis_ipc_metrics_saving_client.py	Metrics collection	Redis	SmartSpectra-IPC package, data aggregation

Full Example Client

File: samples/full_example_on_prem_client.py

Purpose

Demonstrates comprehensive usage of the SmartSpectra OnPrem gRPC API, including:

Manual frame upload from camera or video file
Streaming metrics (core and edge)
Status monitoring
Recording control
Processing reset
Log streaming
All gRPC service endpoints

Server Configuration

Run physiology_server with standard gRPC backend:

physiology_server \
  --port 50051 \
  --venv_directory=".venv" \
  --buffer_duration 0.2 \
  --enable_phasic_bp \
  --also_log_to_stderr

Key Flags:

--port 50051: gRPC server port
--buffer_duration 0.2: Core metrics output frequency (200ms accumulation)
--enable_phasic_bp: Enable phasic blood pressure inference
--use_camera: Client uploads frames via gRPC

Running the Example

python samples/full_example_on_prem_client.py

Controls:

s / start: Start recording
t / stop: Stop recording
r / reset: Reset processing (clears Core buffer)
q / quit: Quit application
h / help: Show help

Use Cases

Learning the complete gRPC API surface
Building custom clients with full control
Integrating with systems that need frame-by-frame control
Testing all service endpoints programmatically

Alternative IPC Example Client

File: samples/alt_ipc_example_on_prem_client.py

Purpose

Demonstrates alternative IPC backends (File and Redis) for systems that cannot use gRPC for data streaming. This client:

Reads metrics from File IPC (JSONL) or Redis pub/sub
Displays frames from IPC backends
Provides simple control interface
Shows backend-agnostic client design

Note: This example does NOT use gRPC for metrics streaming. It uses gRPC only for control operations (StartCore, SetRecording, etc.).

Server Configuration - File IPC

physiology_server \
  --streaming_backend=file \
  --use_camera \
  --camera_device_index=0 \
  --filesystem_ipc_config_path=./file_ipc_config.json \
  --venv_directory=".venv" \
  --buffer_duration 0.2 \
  --also_log_to_stderr

Key Configuration:

--streaming_backend=file: Use File IPC backend
--use_camera: Required for alternative IPC backends
--filesystem_ipc_config_path: Path to File IPC configuration (optional)

Generate Default Config:

physiology_server --save_default_file_ipc_config

# Creates: default_file_ipc_config.json

Server Configuration - Redis IPC

physiology_server \
  --streaming_backend=redis \
  --use_camera \
  --camera_device_index=0 \
  --redis_host=localhost \
  --redis_port=6379 \
  --redis_key_prefix=physiology \
  --venv_directory=".venv" \
  --buffer_duration 0.2 \
  --also_log_to_stderr

Key Configuration:

--streaming_backend=redis: Use Redis IPC backend
--use_camera: Required for alternative IPC backends
--redis_host, --redis_port: Redis server connection
--redis_key_prefix: Prefix for pub/sub channels

Running the Example

File IPC Mode:

python samples/alt_ipc_example_on_prem_client.py --backend=file --base_dir=./file_ipc_output

Redis IPC Mode:

python samples/alt_ipc_example_on_prem_client.py --backend=redis --redis_host=localhost --redis_port=6379

Command Line Arguments:

--backend: Choose file or redis
--base_dir: File IPC output directory (file mode only)
--redis_host: Redis server host (redis mode only)
--redis_port: Redis server port (redis mode only)
--redis_key_prefix: Redis channel prefix (redis mode only)

Use Cases

Deployments where gRPC is blocked by firewalls
Integration with non-gRPC-capable systems
File-based data exchange workflows
Multiple concurrent consumers via Redis pub/sub
Separation of control (gRPC) and data (IPC) channels

Redis IPC Metrics Saving Client

File: samples/redis_ipc_metrics_saving_client.py

Purpose

Demonstrates production-grade metrics collection using the SmartSpectra-IPC package. This example:

Uses MetricsCollector for high-level Redis interaction
Aggregates metrics from core and edge channels
Writes continuous JSONL file + periodic & final JSON summaries
Provides session management
Shows proper async/await patterns for gRPC + Redis

This is the recommended approach for Redis-based metrics collection in production deployments.

Automatic Snapshot Behavior:

The collector automatically subscribes to the recording_state channel and writes snapshots:

Every 30 seconds during active recording (periodic snapshots)
When recording starts (initial snapshot)
When recording stops (final snapshot)
Snapshot files use session-specific naming: metrics_{session_id}_snapshot_temp.json

The final aggregated summary is written when recording stops and saved to metrics_{session_id}.json (or the base filename if no session ID is set).

Server Configuration - Standard

physiology_server \
  --venv_directory=".venv" \
  --port 50051 \
  --buffer_duration 0.2 \
  --enable_phasic_bp \
  --enable_eda \
  --also_log_to_stderr \
  --streaming_backend=redis \
  --use_camera \
  --camera_device_index=0

Server Configuration - Advanced (with Micromotion)

For micromotion tracking, the user must be fully visible in the frame (head to knees). This often requires camera rotation:

physiology_server \
  --venv_directory=".venv" \
  --port 50051 \
  --buffer_duration 0.2 \
  --enable_phasic_bp \
  --enable_eda \
  --also_log_to_stderr \
  --log_edge_core_transfer_times \
  --log_throughput_and_latency \
  --log_dropped_frames \
  --log_verbosity=1 \
  --streaming_backend=redis \
  --use_camera \
  --camera_device_index=2 \
  --input_transform_mode=ccw90

Advanced Configuration Explained:

Physiological Metrics:

--enable_phasic_bp: Enable phasic (beat-to-beat) blood pressure inference
--enable_eda: Enable electrodermal activity (EDA/GSR) measurement

Logging & Diagnostics:

--log_edge_core_transfer_times: Log communication latency between Edge and Core
--log_throughput_and_latency: Log effective FPS and system latency (3s window)
--log_dropped_frames: Log when frames are dropped due to processing delays
--log_verbosity=1: Increase log detail level

Camera & Orientation:

--camera_device_index=2: Select specific camera device (adjust to your system)
--input_transform_mode=ccw90: Rotate camera feed 90° counter-clockwise

Input Transform Modes:

Camera rotation is required when the physical camera orientation doesn't match the required pose:

Mode	Description	Use Case
None	No transformation	Camera is upright, user faces camera normally
ccw90	Rotate 90° counter-clockwise	Camera mounted on right side, rotated left
cw90	Rotate 90° clockwise	Camera mounted on left side, rotated right
rot180	Rotate 180°	Camera is upside down

Micromotion Tracking Requirements:

Micromotion detection measures subtle body movements for additional physiological signals. Requirements:

User must be fully visible from head to knees
Camera should capture the full body in frame
Stable seating position (chair, bench, etc.)
Good lighting conditions
Minimal background motion

When camera rotation is needed (e.g., --input_transform_mode=ccw90), the physical camera is typically mounted sideways to capture more vertical space, then the video is rotated in software to the correct orientation for processing.

Running the Example

Basic Usage:

python samples/redis_ipc_metrics_saving_client.py \
  --port 50051 \
  --combined_metrics_file ./metrics.jsonl \
  --summary_file ./metrics_summary.json

Note: Session IDs are now auto-generated (datetime-based) when recording starts. The client automatically creates session-specific files like metrics_{session_id}.jsonl when recording begins.

Command Line Arguments:

--port: Physiology Server gRPC port (default: 50051)
--redis_host: Redis server hostname (default: localhost)
--redis_port: Redis server port (default: 6379)
--redis_key_prefix: Redis channel prefix (default: physiology)
--combined_metrics_file: Base path for continuous JSONL output (session-specific files created automatically)
--summary_file: Base path for final aggregated JSON summary (session-specific files created automatically)
--append: Append to existing files instead of truncating
--whitespace: Include whitespace in JSON output for readability

Controls:

s / start: Start recording
t / stop: Stop recording
r / reset: Reset processing
q / quit: Quit and finalize

Output Files

Session-Specific File Naming:

When recording starts, the collector automatically creates session-specific files with the session ID appended to the base filename:

Base config: metrics.jsonl → Actual file: metrics_20251006_205619.jsonl
Base config: metrics_summary.json → Actual file: metrics_20251006_205619.json

Continuous JSONL (metrics_{session_id}.jsonl):

Each line contains one complete metrics envelope:

{"type":"core_metrics","timestamp":1234567890,"payload":{"pulse":{"strict":{"value":72.5,"confidence":0.95},...},...}}

{"type":"edge_metrics","timestamp":1234567891,"payload":{"eda":0.42,"breathing":{"upper_trace":[{"time":1.53333294,"value":0.0119628906,"stable":true,"timestamp":"1759779683578333"}]},...}}

Periodic Snapshots (metrics_{session_id}_snapshot_temp.json):

Written automatically every 30 seconds during recording and when recording starts/stops. Contains real-time aggregated data.

Final JSON Summary (metrics_{session_id}.json):

Written when recording stops. Aggregated struct-of-arrays format:

{
  "meta": {
    "session_id": "20251006_205619",
    "started_at_iso": "2025-01-03T14:30:22",
    "updated_at_iso": "2025-01-03T14:45:30",
    "stopped_at_iso": "2025-01-03T14:45:30",
    "duration_seconds": 908.5,
    "total_samples": 54510
  },
  "series": {
    "physiology:core_metrics": {
      "pulse.strict": {
        "timestamps": [1234567.0, 1234568.0, ...],
        "values": [72.5, 72.3, ...],
        "relative_us": [...]
      }
    }
  }
}

Visualizing Collected Metrics

After collecting metrics with redis_ipc_metrics_saving_client.py, you can visualize them using the provided plotting utility.

File: samples/plot_metrics.py

Purpose:

Loads the JSON summary file produced by redis_ipc_metrics_saving_client.py and creates publication-quality visualizations of physiological metrics.

Usage:

python samples/plot_metrics.py --summary_file ./metrics_summary.json

Plots Generated:

The script creates a single figure with 6 subplots:

Edge EDA - Electrodermal activity (galvanic skin response)
Edge Upper Breathing Trace - Respiratory waveform from edge processing
Core Phasic Blood Pressure - Beat-to-beat blood pressure variations
Core Upper Breathing Trace - Respiratory waveform from core processing
Combined Z-scores - Normalized overlay of all metrics for comparison
Timestamp Differences - Inter-sample timing analysis for quality assessment

Output:

Displays interactive plot window
Saves high-resolution PNG: metrics_plot.png (150 DPI)
Time axes formatted as HH:MM:SS for readability
Sample counts and statistics included in titles

Dependencies:

pip install matplotlib numpy scipy

Example Workflow:

# 1. Start Redis server (in separate terminal)
redis-server
 
# 2. Start physiology_server with Redis backend (in separate terminal)
physiology_server \
  --streaming_backend=redis \
  --use_camera \
  --camera_device_index=0 \
  --redis_host=localhost \
  --redis_port=6379 \
  --redis_key_prefix=physiology \
  --venv_directory=".venv" \
  --buffer_duration=0.2 \
  --enable_phasic_bp \
  --enable_eda \
  --also_log_to_stderr
 
# 3. Run metrics collector (connects to physiology_server, collects from Redis)
python samples/redis_ipc_metrics_saving_client.py \
  --port 50051 \
  --session_id session_001 \
  --redis_host=localhost \
  --redis_port=6379 \
  --redis_key_prefix=physiology \
  --combined_metrics_file ./metrics.jsonl \
  --summary_file ./metrics_summary.json
 
# 4. After collection is complete, visualize results
python samples/plot_metrics.py --summary_file ./metrics_summary.json
 
# Output: metrics_plot.png

Tips:

The z-score plot (subplot 5) is useful for comparing signals with different scales
Timestamp differences (subplot 6) help identify timing irregularities or frame drops
All plots share a common time axis for synchronized viewing

Use Cases

Production metrics collection and storage
Experimental data acquisition with session tracking
Integration with analysis pipelines (Pandas, NumPy, R)
Long-running monitoring deployments
Creating datasets for research
Post-session data visualization and quality assessment

Comparison Matrix

Feature	Full Example	Alt IPC Example	Redis Saving Client
gRPC Metrics	✅ Streaming	❌	❌
File IPC	❌	✅ Read-only	❌
Redis IPC	❌	✅ Read-only	✅ Full integration
Frame Upload	✅ From client	❌ Server-side	❌ Server-side
Data Aggregation	❌	❌	✅ Struct-of-arrays
Session Management	❌	❌	✅
Control Interface	✅ Full	✅ Limited	✅ Full
SmartSpectra-IPC	❌	❌	✅
Best For	Learning API	Non-gRPC systems	Production data collection

Common Server Flags Reference

Core Metrics Control

--buffer_duration: Accumulation time before Core processing (seconds)
- Lower values (0.1-0.2): Higher update frequency, more processing load
- Higher values (0.2-0.5): Lower update frequency, less processing load

Recommended value: 0.2

Physiological Metrics

--enable_phasic_bp: Beat-to-beat blood pressure inference
--enable_eda: Electrodermal activity measurement
--enable_micromotion: Subtle body movement detection (requires full body in frame)

Camera Configuration

--use_camera: Enable direct camera input (required for alternative IPC)
--camera_device_index: Camera device index (0, 1, 2, etc.)
--input_transform_mode: Camera rotation (None, ccw90, cw90, rot180)

Logging

--also_log_to_stderr: Display logs in terminal
--log_verbosity: Detail level (0=minimal, 1=detailed)
--log_dropped_frames: Log frame drops
--log_throughput_and_latency: Log FPS and latency metrics
--log_edge_core_transfer_times: Log Edge↔Core communication timing

IPC Backend Selection

--streaming_backend: Choose grpc, file, or redis
--filesystem_ipc_config_path: File IPC configuration (JSON)
--redis_config_path: Redis IPC configuration (JSON)

Overview

Full Example Client

Purpose

Server Configuration

Running the Example

Use Cases

Alternative IPC Example Client

Purpose

Server Configuration - File IPC

Server Configuration - Redis IPC

Running the Example

Use Cases

Redis IPC Metrics Saving Client

Purpose

Server Configuration - Standard

Server Configuration - Advanced (with Micromotion)

Running the Example

Output Files

Visualizing Collected Metrics

Use Cases

Comparison Matrix

Common Server Flags Reference

Core Metrics Control

Physiological Metrics

Camera Configuration

Logging

IPC Backend Selection

See Also