How rd7597/belloscope-ui works
1. Overall shape
BelloScope is a Raspberry Pi–oriented, local-first medical device application. The main app is a Python + PySide2/QML desktop UI that sits on top of hardware drivers, signal-processing code, and a few connectivity services.
2. App entry and UI shell
The visible application starts from main.py and main.qml. The QML side provides the shell, navigation, and visual design; the Python side provides the data and device operations that those pages consume.
3. Page-driven UI structure
The repository is organized as a set of feature pages rather than a single screen: home, splash, settings, Wi‑Fi, Bluetooth, brightness, volume, shutdown, updates, QR, device info, profile, diagnosis, notes, and about. The medical workflows are separated into domain-specific QML groups such as heartQML, hrateQML, spo2QML, temperatureQML, skinQML, entQML, consultQML, and widgetsQML.
4. Reusable UI components
widgetsQML contains shared building blocks like progress bars, battery icons, camera streamer UI, swipe/swap containers, text fields, and busy indicators. These are the presentation boundary between the shell and each feature page.
5. Sensor and measurement layer
The Python modules under modules/ and top-level scripts implement hardware access for the core measurements:
- modules/sensors/max30102.py for pulse/SpO2 sensing
- modules/sensors/mlx90614.py and modules/temperature.py for infrared temperature sensing
- modules/ads_1115.py / ads1115_battery.py for analog/battery readings
- modules/battery.py for power status
- i2cread.py and modules/sensors/spo2helpers.py for low-level I2C and algorithm support
These modules feed measurement values into the UI pages.
6. Signal processing and analysis boundary
Heart-rate and SpO2 are not just raw sensor reads; they pass through processing code such as hrcalc.py, spo2.py, features.py, and modules/sensors/spo2helpers.py. The repo also includes copies of external analysis libraries under maindata/New/heartrate_analysis_python-master and maindata/New/max30102*-master, showing that the app relies on algorithmic post-processing before displaying results.
7. Audio subsystem
Audio capture and playback are handled by scripts like sound_recording.py, modules/recorder.py, modules/test_audio.py, and the vendored SoundCard-master tree. The app stores recordings such as output.wav and per-session files under HR_recording/, which suggests the UI can record, review, and analyze heart sounds or microphone input.
8. Camera and streaming subsystem
Video/camera functionality is split across modules/camera.py, streamer.py, modules/streamer.py, streamtest.py, and the vendored picamera2-main repository. This indicates a separate media path for previewing, recording, or streaming camera frames, likely used by the QML CameraStreamer widget and related pages.
9. Connectivity and device provisioning
The app has multiple outbound/inbound communication paths:
- BLE.py, BLE_on_off.py, modules/qrserialble.py, and modules/bluetooth-server.py handle Bluetooth/BLE pairing or data exchange
- modules/ConnectWifi.py and the various ConnectWifi.py copies handle Wi‑Fi setup
- mqttclient.py and modules/mqttclient.py indicate MQTT-based messaging or upload
- modules/qrgen.py plus the PageQR UI imply QR-based device provisioning or session handoff
The aws_certificates/ folder shows a TLS-backed cloud connection path, likely for secure MQTT or device authentication.
10. Local state and flat-file storage
The app keeps some operational state in simple files rather than a database: users.txt, config.txt, adc_data.txt, response_data.csv, and recording folders under maindata/. That points to a lightweight embedded architecture where local files hold user profiles, calibration/configuration, and measurement output.
11. Update, device, and maintenance flow
Pages like PageUpdates, PageUpdate2, PageDeviceinfo, PageDiagnose, and PageShutdown form the maintenance/admin side of the product. These screens likely read system state from the Python backend and expose device lifecycle operations separate from the measurement workflow.
12. Repo layout and dependency boundary
The root contains the active app, but there are also many archived or vendor trees under maindata/New/ and modules/:
- third-party source mirrors for camera, audio, and heart-rate processing
- older application snapshots and test recordings
- QML feature variants and experiments
For an architecture diagram, treat these as supporting libraries and historical branches, not as a single runtime subsystem.
13. Runtime and platform assumptions
The project is built around Python 3, PySide2/Qt Quick, and Raspberry Pi hardware access via I2C, audio, camera, and wireless modules. The README’s dependency list confirms that the UI and hardware layers are tightly coupled to the Qt/QML stack and Raspberry Pi device libraries.
Main entry points: main.qml main.qml · backend.py backend.py · hrcalc.py Analysis · camera.py Media
Components 22
UI shell
Qt/QML application shell and shared presentation widgets.
- main.py · Python entrypoint that boots the Qt runtime and backend bridge.
main.py - main.qml · Top-level Qt Quick shell that drives navigation and app layout.
main.qml - widgetsQML · Reusable QML controls used across feature pages.
widgetsQML
Clinical flows
Feature pages for measurement and device workflows.
- Home · Landing page for the main user flows.
PageHome.qml - Settings · Settings, pairing, brightness, volume, Wi‑Fi, and shutdown pages.
PageSettings.qml - Maintenance · Update, device info, diagnostics, and shutdown workflows.
PageUpdates.qml - Identity · QR, profile, note, pair, and related user/session pages.
PageQR.qml - Heart pages · Heart and lung measurement screens.
heartQML/PageHeart_Lungs1.qml - HR pages · Heart-rate workflow pages.
hrateQML/PageHR1.qml - SpO2 pages · Pulse oximetry workflow pages.
spo2QML/PageSPO21.qml - Temp pages · Temperature workflow pages.
temperatureQML/PageTemperature1.qml - Skin/ENT pages · Specialty examination pages for skin, ENT, body, ear, face, and throat.
skinQML/PageSkin1.qml - Consultation · Consultation and clinical review pages.
consultQML/PageConsultation1.qml
Device services
Python backend, hardware drivers, and connectivity services.
- backend.py · Python bridge exposing state and device actions to QML.
backend.py - Sensors · Core sensor drivers for pulse, temperature, battery, and ADC inputs.
modules/sensors/max30102.py - Connectivity · Wi‑Fi, Bluetooth, QR handoff, and MQTT communication paths.
modules/ConnectWifi.py - Media · Camera preview/streaming and audio capture/playback services.
modules/camera.py - Local state · Text, CSV, and recording files used for local session and measurement storage.
users.txt
Signal processing
Measurement algorithms and post-processing layers.
- Analysis · Heart-rate and SpO2 processing plus feature extraction.
maindata/New/hrcalc.py
Vendored support
Embedded upstream code and archived runtime examples.
- HeartPy copy · Bundled heart-rate analysis library used for processing support.
maindata/New/heartrate_analysis_python-master/heartpy/heartpy.py - Picamera2 copy · Bundled camera library and examples for Pi camera integration.
maindata/New/picamera2-main/picamera2/picamera2.py - SoundCard copy · Bundled sound-card backend used for audio capture and playback support.
maindata/New/SoundCard-master/soundcard/__init__.py
Connections 26
- main.py → main.qml: loads · Python boots the QML UI shell.
- main.py → backend.py: exposes · Main process publishes backend objects to QML.
- main.qml → widgetsQML: composes · Shell assembles shared UI controls into pages.
- main.qml → Home: navigates · Shell routes into the home dashboard.
- main.qml → Settings: navigates · Shell routes into device settings pages.
- main.qml → Maintenance: navigates · Shell routes into maintenance/admin flows.
- main.qml → Identity: navigates · Shell routes into user identity and provisioning pages.
- main.qml → Heart pages: navigates · Shell routes into heart workflow pages.
- main.qml → HR pages: navigates · Shell routes into heart-rate workflow pages.
- main.qml → SpO2 pages: navigates · Shell routes into SpO2 workflow pages.
- main.qml → Temp pages: navigates · Shell routes into temperature workflow pages.
- main.qml → Skin/ENT pages: navigates · Shell routes into specialty clinical pages.
- main.qml → Consultation: navigates · Shell routes into consultation pages.
- backend.py → Sensors: reads · Backend pulls measurement and power data from hardware drivers.
- backend.py → Connectivity: controls · Backend manages wireless setup, pairing, and messaging.
- backend.py → Media: controls · Backend starts camera and audio workflows.
- backend.py → Local state: persists · Backend reads and writes local state and recordings.
- Sensors → Analysis: feeds · Raw sensor streams are passed into analysis code.
- Analysis → Heart pages: results · Processed heart metrics are rendered by workflow pages.
- Analysis → SpO2 pages: results · Processed SpO2 metrics are rendered by workflow pages.
- Media → widgetsQML: renders · Camera preview is embedded through shared QML widgets.
- Local state → Identity: supplies · Local user/session files support provisioning and identity pages.
- Connectivity → Maintenance: supports · Network paths enable update and device-management flows.
- HeartPy copy → Analysis: supports · Vendored heart-rate library underpins analysis logic.
- Picamera2 copy → Media: supports · Vendored camera stack underpins capture and streaming.
- SoundCard copy → Media: supports · Vendored audio stack underpins recording and playback.