Skip to content

Raspberry Pi Digital Patient

Use this guide when you want the SDK to keep a virtual patient running continuously on a Raspberry Pi.

Before this page: Installation if the edge SDK profile is not installed yet.

After this page: Remote Deploy & Pi Connect for laptop-to-Pi setup, or Maker Faire Pi Mode for event use.

The Raspberry Pi digital-patient workflow gives you: - a persistent virtual patient runtime - SQLite-backed state on disk - a lightweight dashboard for the live glucose view - exportable run bundles for later workstation-side analysis - optional auto-start through systemd

If your main goal is a booth-ready startup routine, jump to Maker Faire Pi Mode. If your main goal is preparing a Pi remotely from your laptop, jump to Remote Deploy & Pi Connect.

Recommended starting setup: - Raspberry Pi 5 with 8 GB RAM - active cooling - Raspberry Pi OS Bookworm Desktop - Raspberry Pi Connect enabled - Python 3.10+

Why this setup works well: - Raspberry Pi 5 has enough headroom for the runtime and dashboard - Desktop edition makes browser-based presentation and remote viewing simpler - Raspberry Pi Connect makes it easy to present the Pi from another machine

Runtime Command Set

The recommended Raspberry Pi flow is now CLI-first through the iints edge ... namespace.

Common commands:

iints edge doctor --board raspberry_pi
iints edge setup --board raspberry_pi
iints edge deploy --host raspberrypi.local --user pi
iints edge offline-bundle --output iints_offline.tar.gz
iints edge study --algo algorithms/example_algorithm.py --seeds 1,2,3,4,5
iints edge long-study --config edge_long_study.yaml --project-dir .
iints edge study-snapshot --project-dir . --input-dir results/long_study
iints edge study-export --project-dir . --input-dir results/long_study --output results/long_study_export.zip
iints edge up
iints edge status
iints edge kiosk
iints edge reset
iints edge stop
iints edge service
iints edge bundle
iints edge update
iints makerfaire up
iints patient inject-meal
iints patient pause
iints patient resume
iints patient scenarios
iints patient review

Fastest Setup

Start from a clean project directory on the Pi:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -U "iints-sdk-python35[edge,mdmp]"

iints edge doctor --board raspberry_pi
iints edge setup --output-dir iints_pi_demo --board raspberry_pi
cd iints_pi_demo
iints edge up --project-dir .
iints edge status --project-dir .
iints edge kiosk --project-dir .

iints edge doctor --board raspberry_pi is the friendly preflight check. It tells you what is ready, what is optional, and the exact next command to run.

That starts: - the persistent simulation loop - the SQLite runtime store - the local dashboard API - a run-like bundle under patient_runtime/live_bundle/ - a fullscreen-friendly kiosk view at /kiosk

Offline Install Bundle

If the venue Wi-Fi is unreliable, create a USB-friendly offline bundle ahead of time:

iints edge offline-bundle --output iints_offline.tar.gz

That bundle contains:

  • a wheelhouse with the edge SDK and dependency wheels
  • an install_offline_edge.sh installer
  • a ready-to-run edge project scaffold

Generate it on a machine with internet access first, then move the tarball to the Pi over USB.

Multi-Seed Study On The Pi

You can now generate a reproducible study bundle directly on the Pi itself:

iints edge study \
  --algo algorithms/example_algorithm.py \
  --seeds 1,2,3,4,5 \
  --output-dir results/pi_study

That writes:

  • a full study bundle
  • a protocol matrix
  • aggregated study summaries
  • edge_study_metadata.json describing the machine that generated the results

Multi-Week Long Study On The Pi

If you want the Pi to act as an autonomous research rig for days or weeks, use the generated YAML config from iints edge setup:

iints edge long-study \
  --project-dir . \
  --config edge_long_study.yaml

If the Pi reboots in the middle of the study, resume from the next incomplete day:

iints edge long-study \
  --project-dir . \
  --config edge_long_study.yaml \
  --resume

That flow gives you:

  • rolling weekday/weekend scenario profiles across multiple days
  • nested file-based outputs under results/long_study/
  • local snapshots under results/long_study/snapshots/
  • export-friendly CSV and JSON artifacts instead of locking the study into a single database file
  • scratch-first writes under /tmp before the day is synced to the final output location

For the safest long studies, keep the OS on the Pi SD card but point the study output itself at a USB SSD:

output_dir: /media/pi/usb_ssd/results/long_study
scratch_dir: /tmp/iints_edge_long_study

Typical generated layout:

results/long_study/
  protocol/
  days/
  snapshots/
  algorithms/<algorithm>/seed_<seed>/day_<nn>_<profile>/
  long_study_index.csv
  study_summary.json

The default template includes realistic weekly variation such as:

  • school_day
  • sport_day
  • bad_carb_count
  • relaxed_day

Create an extra snapshot whenever you want:

iints edge study-snapshot --project-dir . --input-dir results/long_study

Package the whole study for another device:

iints edge study-export \
  --project-dir . \
  --input-dir results/long_study \
  --output results/long_study_export.zip

Analyze the copied study later on your laptop:

iints analyze results/long_study

Security defaults:

  • the dashboard/API listens on 127.0.0.1 by default
  • mutating dashboard actions require the internal IINTS control header
  • if you enable token protection, dashboard reads also require auth

Day-To-Day Runtime Operations

Check status:

iints edge status --project-dir .

List built-in day profiles:

iints patient scenarios

Inject a meal during a live session:

iints patient inject-meal --carbs 60 --workspace patient_runtime

Pause and resume the runtime:

iints patient pause --workspace patient_runtime
iints patient resume --workspace patient_runtime

Reset to the prepared presentation profile:

iints edge reset --project-dir .

By default, expo-reset switches to the expo_hot_start profile so the runtime resumes in an already active scenario instead of a flat baseline.

Jump to a specific profile instead:

iints edge reset \
  --project-dir . \
  --scenario-profile sport_day

Stop the runtime:

iints edge stop --project-dir .

Export the live runtime for workstation-side analysis:

iints edge bundle --project-dir . --output results/edge_runtime_bundle.zip

Dashboard URLs

Default dashboard URL:

http://127.0.0.1:8765/dashboard

Fullscreen kiosk URL:

http://127.0.0.1:8765/kiosk

The dashboard is intentionally lightweight and focuses on: - current glucose - simulated clock - recent event history - certification badge - realism review status - live glucose curve - pause, resume, meal, and reset controls - quick scenario shortcuts

API Security Defaults

The safest Raspberry Pi presentation path is still:

  • keep the API on 127.0.0.1
  • open the dashboard locally on the Pi
  • use Raspberry Pi Connect to share that local browser window

That means you usually do not need a remotely reachable dashboard port at all.

If you do need another machine to talk directly to the dashboard API, opt in explicitly:

export IINTS_PATIENT_API_TOKEN="replace-this-with-a-random-secret"

iints patient start \
  --algo algorithms/example_algorithm.py \
  --workspace patient_runtime \
  --scenario-profile normal_day \
  --mode demo-time \
  --speed 60x \
  --api-host 0.0.0.0 \
  --allow-remote-api \
  --api-token-env IINTS_PATIENT_API_TOKEN

When token protection is enabled:

  • the browser can use http://<host>:8765/dashboard?token=<your-token>
  • scripts and tools should use Authorization: Bearer <token>
  • /dashboard, /kiosk, /status, /glucose/latest, and /glucose/history are protected too
  • the control endpoints still require the extra X-IINTS-Control: 1 header, which the built-in dashboard sends automatically

Recommendation:

  • use token-backed remote access only when you truly need it
  • for booth demos, classrooms, and Raspberry Pi Connect, prefer loopback-only mode

Scenario Profiles

Built-in profiles: - normal_day - school_day - sport_day - bad_carb_count - night_hypo_risk - relaxed_day - expo_hot_start

The first four represent general study or demo days. expo_hot_start is the fast-start presentation profile.

Each profile has a fixed default seed, so the same profile and algorithm can be reproduced more easily across sessions.

Override the default seed if needed:

iints edge setup --output-dir iints_pi_demo_seeded --board raspberry_pi --scenario-profile bad_carb_count --seed 7777
cd iints_pi_demo_seeded
iints edge up --project-dir . --reset

Remote Presentation With Raspberry Pi Connect

A simple remote presentation flow is:

  1. Start the patient runtime on the Pi.
  2. Open the dashboard in a browser on the Pi.
  3. Connect to the Pi from another machine with Raspberry Pi Connect.
  4. Share the Pi browser window.
  5. Use the dashboard controls or CLI commands during the session.

This keeps the actual runtime on the Pi while the laptop or workstation acts only as the remote presenter.

This is also the security-friendly route because it avoids opening the dashboard API to the LAN in the first place.

systemd Auto-Start

If the device should come back automatically after a reboot, export a systemd unit after the runtime has started once:

iints edge service --project-dir .

This writes: - patient_runtime/iints-digital-patient.service - patient_runtime/iints-digital-patient.INSTALL.txt

Install it on the Pi:

sudo cp patient_runtime/iints-digital-patient.service /etc/systemd/system/iints-digital-patient.service
sudo systemctl daemon-reload
sudo systemctl enable iints-digital-patient.service
sudo systemctl start iints-digital-patient.service
systemctl status iints-digital-patient.service

What Gets Stored

Inside patient_runtime/ you will see: - patient_state.db - patient_runtime_config.json - patient.log - simulator_snapshot.json - live_bundle/results.csv - live_bundle/run_manifest.json - live_bundle/run_metadata.json - live_bundle/audit/audit_summary.json

This means the digital patient is not just a display layer. It keeps a traceable runtime history that can be analyzed later with the wider SDK workflow.

Edge Setup And Update Helpers

Generate a Pi-friendly project scaffold with:

iints edge setup --output-dir iints_edge_demo --board raspberry_pi

That writes: - run_edge_patient.sh - launch_kiosk.sh - update_edge_runtime.sh - patient_runtime/iints-digital-patient.service - EDGE_SETUP.md

Generate an update helper later with:

iints edge update --output-script update_edge_runtime.sh

Optional AI Review

If Ollama and a local Ministral model are available, you can request a realism review of the live runtime:

iints patient review \
  --workspace patient_runtime \
  --model ministral-3:3b

Output goes to: - patient_runtime/live_bundle/ai/realism_review.md

Example Live Session

One simple live flow is:

  1. iints patient scenarios
  2. iints edge up --project-dir .
  3. open http://127.0.0.1:8765/dashboard
  4. explain the live glucose curve and current state
  5. run iints patient inject-meal --carbs 60 --workspace patient_runtime
  6. run iints edge reset --project-dir .
  7. optionally run iints patient review --workspace patient_runtime --model ministral-3:3b

Scope

  • built for Raspberry Pi demos, teaching, and long-running virtual patient studies
  • research use only
  • not a medical device
  • not a clinical treatment controller

Where To Go Next

If you want to... Continue with
deploy from a laptop Remote Deploy & Pi Connect
make the Pi booth-ready Maker Faire Pi Mode
run an event checklist Maker Faire Pi Checklist
add UNO Q hardware feedback Arduino UNO Q Setup
export/analyze edge results Study Analysis