SmartSpiro: AI & IoT Enabled Portable Spirometer & Pulse Oximeter

SmartSpiro is a low-cost, portable, multi-modal respiratory screening device that combines differential pressure spirometry with photoplethysmographic (PPG) pulse oximetry and on-device Edge Machine Learning for early detection and risk classification of Chronic Obstructive Pulmonary Disease (COPD) and Asthma.

---

🌟 Key Highlights

• Dual-Sensor Integration: Synchronously captures high-speed expiratory differential pressure (HX710B + MPS20N0040D) and physiological vitals (MAX30102 for $\text{SpO}_2$ and Heart Rate).
• ATS/ERS 2019 Compliance: Implements real-time 2nd-order Butterworth filtering ($f_c = 25\text{ Hz}$), zero-flow calibration, adaptive maneuver onset detection ($\mu + 5\sigma$), back-extrapolation volume correction ($V_\text{extrap}$), and plateau termination criteria.
• Edge AI Risk Classifier: On-device Decision Tree engine evaluates a 14-dimensional feature vector in $<15\ \mu\text{s}$ to classify patients into Normal, Mild Airflow Obstruction, and Significant Obstruction (COPD/Asthma) with 97.8% accuracy (Macro ROC-AUC: 0.999).
• Interactive Multi-Screen OLED UI: Visual blow gauge, real-time exhalation progress, multi-screen results presentation, and diagnostic risk feedback on a 0.96" SSD1306 OLED.
• Real-Time Web Serial Dashboard: Browser-based interactive dashboard (Web Serial API) rendering live Flow-Volume loops ($Q$ vs. $V$) and Volume-Time curves ($V$ vs. $t$) with instant ATS/ERS grading and CSV export.
• Ultra Low Cost (< $30 USD): Accessible diagnostic screening solution designed for low-to-middle-income countries and remote healthcare settings aligned with UN SDGs 3, 9, and 10.

---

📁 Repository Structure

SmartSpiro/
├── firmware/
│   └── SmartSpiro/
│       ├── SmartSpiro.ino          # Main ESP32-S3 firmware & FreeRTOS/state machine
│       ├── Config.h                # Pin mappings, calibration constants & ATS/ERS parameters
│       ├── HX710B_Driver.h         # 24-bit differential pressure ADC driver & zero calibration
│       ├── MAX30102_Driver.h       # PPG pulse oximeter driver (SpO2 & Heart Rate)
│       ├── SignalProcessing.h      # Butterworth LPF, integration, ATS/ERS parameter derivation
│       ├── EdgeML_Classifier.h     # Native C++ Edge Decision Tree inference engine
│       ├── OLED_UI.h               # SSD1306 graphical UI screens & live exhalation gauges
│       └── Telemetry.h             # JSON and ASCII clinical report telemetry streamer
│
├── ml_pipeline/
│   ├── dataset_generator.py        # 1,200-sample multi-modal dataset generator (ATS/ERS & GLI-2012)
│   ├── train_classifiers.py        # 5-Classifier training suite (LR, SVM, DT, RF, HistGB) with 5-Fold CV
│   ├── evaluate_models.py          # ROC-AUC curves, Confusion Matrices & Feature Importance plots
│   ├── export_c_model.py           # Compiles scikit-learn models into standalone C++ header
│   └── requirements.txt            # Python dependencies
│
├── dashboard/
│   ├── index.html                  # Web Serial UI with live Flow-Volume & Volume-Time plotting
│   ├── dashboard.js                # Web Serial API driver, Chart.js engine & simulator
│   └── style.css                   # Responsive dark-theme medical UI stylesheet
│
├── paper/
│   ├── main.tex                    # Full LaTeX research paper source
│   ├── references.bib              # Complete BibTeX bibliography
│   ├── figures/                    # System diagrams, circuit layouts & response curves
│   └── smartspiro.pdf              # Compiled research paper document
│
├── docs/
│   ├── HARDWARE_SCHEMATICS.md      # Pinout table, wiring diagrams & Bill of Materials
│   ├── SIGNAL_PROCESSING.md        # Mathematical derivations, orifice equations & filter specs
│   └── ML_METHODOLOGY.md           # 14-feature vector definition & ML benchmark comparison
│
├── .gitignore                      # Git ignore rules for Arduino, Python, and LaTeX
├── LICENSE                         # MIT License
├── CONTRIBUTING.md                 # Contribution guidelines
└── README.md                       # Main documentation

---

🔬 Mathematical Modeling & Signal Processing

1. Volumetric Flow Calculation

$$Q(t) = C_d \cdot A \cdot \sqrt{\frac{2 \cdot \Delta P(t)}{\rho}}$$

• $C_d = 0.87$ (calibrated discharge coefficient)
• $A = \pi \cdot (0.004\text{ m})^2 \approx 5.0265 \times 10^{-5}\text{ m}^2$ (orifice area)
• $\rho = 1.20\text{ kg/m}^3$ (ambient air density)

2. Digital Filtering

A 2nd-order Butterworth IIR Low-Pass Filter ($f_c = 25\text{ Hz}$, $f_s = 500\text{ Hz}$) attenuates muscle tremor and sensor noise: $$H(z) = \frac{0.02008 + 0.04017 z^{-1} + 0.02008 z^{-2}}{1 - 1.56102 z^{-1} + 0.64135 z^{-2}}$$

3. Exhaled Volume Integration

$$V(t_N) = \sum_{k=1}^N \frac{Q(t_k) + Q(t_{k-1})}{2} \cdot \Delta t$$

4. Extracted Clinical Indices

• $\text{FEV}_1$: Forced Expiratory Volume in 1 second ($\text{L}$)
• $\text{FVC}$: Forced Vital Capacity ($\text{L}$)
• $\text{FEV}_1/\text{FVC}$: Tiffeneau Index (Diagnostic threshold $&lt; 0.70$)
• $\text{PEFR}$: Peak Expiratory Flow Rate ($\text{L/min}$ & $\text{L/s}$)
• $\text{FEF}_{25-75}$: Mid-expiratory flow rate ($\text{L/s}$)
• $A_{FV}$: Flow-Volume curve area ($\text{L}^2/\text{s}$)
• $V_\text{extrap}$: Back-extrapolation volume per ATS/ERS 2019 standards

---

🤖 Machine Learning Benchmarks

The ML pipeline was trained and evaluated on 1,200 records using 5-Fold Stratified Cross-Validation and a held-out test set:

Classifier	CV Accuracy	Test Accuracy	Precision	Recall	F1-Score	Macro ROC-AUC
Logistic Regression	97.8%	97.2%	0.980	0.972	0.975	0.998
Support Vector Machine (SVM)	97.6%	96.7%	0.976	0.966	0.970	0.998
Decision Tree (Embedded on ESP32)	98.0%	97.2%	0.978	0.970	0.973	0.980
Random Forest	98.7%	97.2%	0.978	0.970	0.973	0.997
Gradient Boosting	98.3%	97.8%	0.982	0.979	0.980	0.999

---

🔌 Hardware Setup & Pin Connections

Module	Pin Name	ESP32-S3 GPIO	Description
HX710B ADC	VCC / GND	3.3V / GND	Power & Ground
	DOUT	GPIO 46	24-bit ADC Data Out
	SCK	GPIO 5	Clock Out
SSD1306 OLED	SDA / SCL	GPIO 8 / GPIO 9	I2C Bus (0x3C, 400 kHz)
MAX30102 PPG	SDA / SCL	GPIO 8 / GPIO 9	I2C Bus (0x57, 400 kHz)
Li-Ion Battery	TP4056 Out	3.3V Rail	3.7V 2000 mAh Rechargeable Cell

For detailed schematics and pneumatic assembly instructions, see docs/HARDWARE_SCHEMATICS.md.

---

🚀 Quick Start Guide

1. Flashing Firmware (Arduino IDE / PlatformIO)

1. Open SmartSpiro/SmartSpiro.ino or firmware/SmartSpiro/SmartSpiro.ino in Arduino IDE.
2. Select Board: ESP32-S3 Dev Module.
3. Install required libraries via Library Manager:
   • Adafruit GFX Library
   • Adafruit SSD1306
4. Connect ESP32-S3 via USB and click Upload.

2. Launching the Web Dashboard

1. Open dashboard/index.html in Google Chrome or Microsoft Edge.
2. Click ⚡ Connect USB / Serial and select your ESP32-S3 COM port.
3. Perform a forced exhalation into the mouthpiece. Real-time Flow-Volume loops and AI diagnostic reports will stream dynamically! (Alternatively, click ▶ Run Clinical Simulation to test without hardware).

3. Training / Retraining ML Models

# 1. Install Python dependencies
pip install -r ml_pipeline/requirements.txt

# 2. Train classifiers & evaluate metrics
python ml_pipeline/dataset_generator.py
python ml_pipeline/train_classifiers.py
python ml_pipeline/evaluate_models.py

# 3. Export trained Edge ML C++ header for ESP32-S3
python ml_pipeline/export_c_model.py

---

📖 Project Citation & Attribution

If you use this project, hardware design, or firmware in your research, please cite:

@misc{smartspiro2026,
  author = {MD. Rakib Hassan Dipu},
  title = {SmartSpiro: A Cost-Effective Multi-Modal IoT Spirometer with Edge Machine Learning for Screening-Level Respiratory Monitoring},
  year = {2026},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/rakibdipu/spirometer_Github}}
}

---

👨‍💻 Author & Maintainer

• MD. Rakib Hassan Dipu (@rakibdipu)
• Email: rakibdipu007@gmail.com

---

📄 License

This project is licensed under the MIT License - Copyright (c) 2026 MD. Rakib Hassan Dipu.