SmartSpectra OnPrem - Quick Start Guide

Goal: Get SmartSpectra OnPrem running in 5 minutes.

Prerequisites

• Ubuntu 22.04 (or compatible)
• Python 3.11 installed
• OnPrem package downloaded and extracted
• Webcam connected

5-Minute Setup

1. Install System Packages (60 seconds)

cd /path/to/extracted/onprem-package
 
# Install .deb packages in this exact order
sudo apt install ./libopencv-dev_*.deb
sudo apt install ./libphysiologyedge-dev-*.deb
sudo apt install ./libsmartspectra-dev-*.deb

2. Create Python Environment (30 seconds)

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

3. Install Python Packages (45 seconds)

# Install protobuf wheels
pip install physiology_edge_protobuf-*.whl
pip install smartspectra_protobuf-*.whl
pip install physiology_core-*.whl
pip install smartspectra_ipc-*.whl
 
# Install sample dependencies
cd samples
pip install -r requirements.txt
cd ..

4. Start the Server (15 seconds)

# Copy grpc_core_server.py to current directory
cp grpc_core_server.py .
 
# Start physiology_server
physiology_server --also_log_to_stderr --port 50051 --venv_directory .venv --buffer_duration 0.2

You should see:

[INFO] Physiology Server starting on port 50051...
[INFO] Ready to accept connections

5. Run Hello World Example (15 seconds)

Open a new terminal:

cd /path/to/extracted/onprem-package
source .venv/bin/activate
cd samples
 
python hello_world_on_prem_client.py

What to expect:

1. Camera window opens showing video feed
2. Press s to start recording

3. Metrics print to console:

   Heart rate: 72.5 BPM
   Breathing rate: 16.2 RPM

4. Press q to quit

✅ Success

You're now running SmartSpectra OnPrem!

Next Steps

View Full Documentation

Open the included HTML documentation:

# Open in browser
xdg-open docs/index.html  # Linux
open docs/index.html       # macOS

Navigate to SmartSpectra OnPrem section for complete guides.

Try Advanced Examples

# Full-featured example with all controls
python samples/full_example_on_prem_client.py
 
# Redis-based metrics collection
# (requires redis-server running)
python samples/redis_ipc_metrics_saving_client.py

Explore Web Dashboards

# React dashboard (Recommended)
cd typescript/samples/react-dashboard
./run_dashboard.sh
 
# Note: A vanilla JS alternative is also available in javascript_frontend/
# but the React dashboard is recommended for production use

Common Issues

"physiology_server: command not found"

Fix: The .deb packages didn't install correctly or aren't in PATH.

# Verify installation
which physiology_server
# Should show: /usr/local/bin/physiology_server
 
# If not found, reinstall .deb packages
sudo apt install --reinstall ./libsmartspectra-dev-*.deb

"Cannot find grpc_core_server.py"

Fix: Copy it to your working directory:

cp /path/to/onprem-package/grpc_core_server.py .

"Failed to start Core server"

Fix: Ensure grpc_core_server.py is in the same directory where you run physiology_server, and that your virtual environment is activated.

# Check these:
ls grpc_core_server.py          # Should exist
echo $VIRTUAL_ENV                # Should show .venv path

"Camera not detected"

Fix: Camera might be in use or have wrong permissions.

# Check camera access
ls -l /dev/video*
# Should show readable devices
 
# Test camera
python3 -c "import cv2; cap = cv2.VideoCapture(0); print('Camera OK' if cap.isOpened() else 'Camera FAIL')"

ImportError: No module named 'smartspectra'

Fix: Protobuf wheels not installed in virtual environment.

source .venv/bin/activate
pip install smartspectra_protobuf-*.whl physiology_edge_protobuf-*.whl

Getting Help

• Documentation: Open docs/index.html in browser
• Python Examples: See samples/README.md
• TypeScript Examples: See typescript/README.md
• Support: Contact support@presagetech.com

What's Included

onprem-package/
├── docs/                              # HTML documentation (START HERE)
│   └── index.html                     # Open this in browser
├── docs_markdown/                     # Raw markdown docs (for LLMs & terminal)
│   ├── typescript.md                  # TypeScript SDK guide
│   ├── redis_ipc.md                   # Redis backend config
│   ├── smartspectra_ipc.md           # MetricsCollector API
│   └── ...                            # + 6 more guides
├── samples/                           # Python examples
│   ├── README.md                      # Examples guide
│   ├── hello_world_on_prem_client.py  # Start here
│   ├── full_example_on_prem_client.py
│   ├── redis_ipc_metrics_saving_client.py
│   └── requirements.txt
├── typescript/                        # Web dashboards
│   ├── packages/                      # NPM packages
│   └── samples/                       # React dashboard (recommended)
├── QUICKSTART.md                      # This file
├── README.md                          # Full user guide
├── grpc_core_server.py               # Core server (copy to working dir)
├── *.deb                              # System libraries
└── *.whl                              # Python packages

Production Checklist

Before deploying to production:

• Review security considerations in full documentation

• Configure appropriate buffer_duration for your use case

• Set up proper logging and monitoring

• Test with your target camera and lighting conditions

• Implement proper error handling in your client code

• Consider using Redis IPC for distributed deployments

• Set up automated backups of collected data

• Document your specific configuration and deployment

---

Ready for More? Open docs/index.html for the complete documentation, including:

• Advanced Features (Alternative IPC backends, TypeScript SDKs)
• Architecture Deep Dive
• API Reference
• Troubleshooting Guide
• Example Walkthroughs