Documentation

Integration Options

MEDWEAR schemas are available in two formats. Choose based on your application: JSON Schemas for general data storage and validation, or ROS 2 messages for real-time streaming and robotics middleware.

git clone https://github.com/SCAI-Lab/ord_schemas

{
  "schema_id": "org.medwear.biosignal.ecg",
  "version": "1.0",
  "data": {
    "ecg": [0.12, 0.15, 0.11],
    "sample_rate": 250,
    "units": "mV"
  },
  "metadata": {
    "device_id": "device1234",
    "timestamp": "2025-06-30T15:30:00Z"
  }
}

import json
from jsonschema import validate

with open('ecg_schema.json') as f:
    schema = json.load(f)
with open('ecg_data.json') as f:
    data = json.load(f)

validate(instance=data, schema=schema)
print("Data is valid.")

# Add GPG key
sudo curl -fsSL \
  https://scai-lab.github.io/healthcare_msgs/humble-amd64/KEY.gpg \
  -o /etc/apt/trusted.gpg.d/healthcare-msgs.gpg

# Add APT source
echo "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/healthcare-msgs.gpg] \
  https://scai-lab.github.io/healthcare_msgs/humble-amd64 humble-jammy main" \
  | sudo tee /etc/apt/sources.list.d/healthcare-msgs.list

# Install
sudo apt update && sudo apt install ros-humble-healthcare-msgs

Streaming & Conversion Tools

Command-line tools and notebooks are available to convert CSV, JSON, and raw wearable files into MEDWEAR-compliant format. You can also use the provided libraries to stream the messages in MQTT(S), UDP, websockets or BLE. These tools are ideal for testing, prototyping, and integrating MEDWEAR schemas into existing workflows.

Explore conversion tools on GitHub

Resources

External References

• JSON Schema documentation
• Open mHealth

Overview

MED-API is the backend service of the MEDWEAR platform - a secure REST API for ingesting, querying, and managing wearable health data. It runs alongside MinIO, InfluxDB, PostgreSQL, Keycloak, Dagster, Grafana, and pgAdmin as a single-server Docker stack. For the full API reference, see the MED-API page.

Installation

Clone the MEDWEAR platform repository from GitHub:

git clone https://github.com/SCAI-Lab/medwear
cd medwear

Quick Setup

./setup.sh

This will automatically:

• Generate random secure credentials for all services (PostgreSQL, MinIO, Grafana, Keycloak, InfluxDB)
• Create .env and .env.medwear files
• Start all Docker services
• Initialize InfluxDB and PostgreSQL tables
• Save all generated credentials to .credentials.txt

After setup, view your credentials:

cat .credentials.txt

PostgreSQL     : medwear / xK7mP2qR9nL4wY8j
MinIO root     : minioadmin / hT3vB6cN1mX5pQ2r
MinIO API key  : medwear-api / dF8yA4kW7nJ2mR6s...
Keycloak admin : admin / hJ9nQ3vB6cN1mX5p
InfluxDB       : admin / wY8jxK7mP2qR9nL4
Grafana        : admin / T3vB6cN1mX5pQ2rd
pgAdmin        : admin@medwear.local / F8yA4kW7nJ2mR6s

Note: Do not commit .credentials.txt to version control. It is already listed in .gitignore.

Start & Stop

# First time or after code changes
docker compose -f docker-compose.medwear-minimal.yml build
docker compose -f docker-compose.medwear-minimal.yml up -d

# Subsequent runs (no code changes)
docker compose -f docker-compose.medwear-minimal.yml up -d

After starting, Keycloak takes ~30 seconds to be ready.

# Restart a single service (e.g. after API code change)
docker compose -f docker-compose.medwear-minimal.yml restart med-api

# Stop all services
docker compose -f docker-compose.medwear-minimal.yml down

Service Access

The MedWear platform is deployed at https://172.20.83.11. Frontend and API are accessible directly. Admin services require SSH tunnel or direct server access.

ssh -L 443:localhost:443 \
    -L 80:localhost:80 \
    -L 8180:localhost:8180 \
    -L 9001:localhost:9001 \
    -L 8086:localhost:8086 \
    -L 3001:localhost:3001 \
    -L 5050:localhost:5050 \
    user@your-server.com

Authentication

All endpoints require a Keycloak JWT token.

curl -k -X POST https://localhost/v1/data/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<pass>"}'

curl -X POST http://localhost:8180/realms/medwear/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id=med-api&client_secret=<secret>&username=<user>&password=<pass>"

curl -k -H "Authorization: Bearer <access_token>" https://localhost/v1/me

curl -k https://localhost/v1/health

Testing

cd /path/to/repo/medwear_med_api
source venv/bin/activate

python3 scripts/test_phase3.py   # Batch upload, CSV, validation
python3 scripts/test_phase4.py   # Query, delete, restore, admin, multi-project
python3 scripts/test_phase5.py   # Error handling: 46/46 tests

# 1. Get a token
TOKEN=$(curl -sk -X POST https://localhost/v1/data/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"<your-username>","password":"<your-password>"}' | jq -r .access_token)

# 2. Check health
curl -sk https://localhost/v1/health | jq .

# 3. Query recent batches
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost/v1/data?limit=5" | jq .

Backup

Backs up PostgreSQL, InfluxDB, and MinIO to a compressed archive. Backups older than 30 days are deleted automatically.

# Run manually
./scripts/backup.sh /opt/medwear_backups

# Add to crontab (daily at 2 AM)
0 2 * * * /path/to/med-api/scripts/backup.sh /opt/medwear_backups >> /var/log/medwear_backup.log 2>&1