2.2.1 MIT

🚀 The Transition to 100% Open Source (MIT)

Effective with this release, Smartphone-Based-Chest-Monitoring is transitioning from a hybrid licensing model to the pure, permissive MIT License.

The goal of this project has always been to push the boundaries of computational architecture. By removing commercial licensing friction, this technology is now completely open for unrestricted adoption, integration, and scaling by the broader research and enterprise community.

💼 Enterprise Consulting & Integration

While the core frameworks are now freely available, deploying complex architectures at an enterprise level requires precision.

If your organization requires custom scaling, proprietary integration, or dedicated technical consulting to deploy these models into your tech stack, I am officially opening my calendar for commercial consulting.

Contact for implementation and advisory roles: dfeen87@gmail.com

2.2.0

Smartphone-Based-Chest-Monitoring — v2.2.0 Release Notes

Overview

Version 2.2.0 delivers a major reproducibility and scientific‑rigor upgrade to the respiratory analysis pipeline. This release introduces a unified one‑command reproduction workflow, manuscript‑grade figure generation, fully documented motion‑gating thresholds, vectorized operators, and explicit parameterization of all perturbation constants. The repo is now reviewer‑ready, deterministic, and aligned with the revised manuscript.

This is a backward‑compatible minor version bump that strengthens clarity, stability, and scientific transparency without altering the public API.

---

New in v2.2.0

1. One‑Command Reproducibility (reproduce_all.sh)

A new top‑level script provides a single entry point for regenerating all respiratory results:

• Reproduces all 4 manuscript figures
• Reproduces both CSV results tables
• Fully offline (no internet, no PhysioNet login)
• Optional --physionet flag enables real‑data mode

This guarantees deterministic, reviewer‑friendly reproduction of every result in the paper.

---

2. Manuscript‑Grade Plotting Improvements

validation/plots.py now produces publication‑quality figures:

• DPI increased from 150 → 300
• Enabled constrained_layout=True
• Removed conflicting plt.tight_layout() call

Figures now render cleanly and consistently across all environments.

---

3. Vectorized Causal Rolling Mean

validation/pipeline.py replaces the Python loop with a cumulative‑sum formulation:

• Identical numerical output
• Zero Python‑level loop overhead
• Derivation documented inline

This improves performance and clarity while preserving scientific correctness.

---

4. Perturbation Constants Parameterized & Documented

validation/perturbations.py now exposes all previously inline constants as named parameters:

• DRIFT_RATIO = 1.6
• PAUSE_AMPLITUDE = 0.03
• PAUSE_DURATION_S = 8.0

Each constant includes a full rationale comment explaining its physiological or simulation basis.

---

5. Dependency Safety via Version Caps

validation/requirements.txt now includes upper major‑version bounds:

• Prevents silent API breakage
• Ensures long‑term reproducibility
• Includes explanatory comments for reviewers

This stabilizes the environment for future manuscript revisions.

---

6. Motion‑Gating Logic Fully Documented & Cleaned

core/respirosync_core.cpp now contains explicit, physically grounded constants:

• PEAK_THRESHOLD_MULTIPLIER
• APNEA_THRESHOLD_MS
• BREATH_CYCLE_MIN_MS / BREATH_CYCLE_MAX_MS
• GRAVITY_ALPHA

All remaining inline magic numbers removed.
All thresholds now include scientific rationale and cross‑references to Python defaults.

---

7. README Overhaul for Reviewer Clarity

A new “Reproduce All Figures (Reviewer Quick‑Start)” section appears immediately after the citation:

• One‑command reproduction instructions
• Output file table cross‑referenced to PAPER.md
• Explicit determinism guarantees (seeds, operator parameters, version caps)
• Real‑data mode instructions

This dramatically improves first‑impression clarity for reviewers and collaborators.

---

Compatibility

• No breaking API changes
• All existing scripts and operators continue to function
• All improvements are additive and reproducibility‑focused

---

Summary

v2.2.0 transforms the respiratory pipeline into a clean, deterministic, reviewer‑ready system with unified reproduction, documented thresholds, and manuscript‑grade outputs. This release strengthens scientific transparency and prepares the repo for the next manuscript revision cycle.

2.1.0

Smartphone‑Based‑Chest‑Monitoring v2.1.0 — Security, Validation & Platform Hardening Release

This release strengthens production‑mode security, improves API validation, hardens the signal‑processing pipeline, and adds clearer architectural structure across the Python and mobile layers. CodeQL reports 0 security alerts, and all existing functionality remains backward‑compatible.

---

Security Hardening

Production Startup Guard

• The server now refuses to start in production (FLASK_ENV=production or RESPIROSYNC_ENV=production) if default JWT_SECRET or API_KEY values are detected.
• In development mode, a clear warning is emitted when defaults are in use.

Configuration Exposure Reduction

• Removed default_key_active from the unauthenticated /ping route.
• This information is now only available via authenticated /api/status.

Strict Range Validation for /api/config

The following parameters now enforce strict bounds and return 400 Bad Request when violated:

• memory_samples: [10, 10000]
• alpha: [1.0, 10.0]
• baseline_samples: [10, 10000]
• fs: [1.0, 1000.0]

Constant‑Time API Key Comparison

• Replaced != with hmac.compare_digest() to eliminate timing‑based side‑channel leakage.

Sanitized Error Messages

• All three exception handlers now return generic messages:
  • "Internal server error"
  • "Email delivery failed"
• Full details remain logged server‑side.

Strict JSON Parsing

• Removed all force=True flags from get_json() calls.
• Requests must now send Content-Type: application/json.

---

Robustness

OOM Protection

• /api/run now clamps duration_s to [1.0, 3600.0].

Signal Processing Validation

• bandpass_filter now validates:
  • fs > 0
  • 0 < lo < hi < fs/2
  • non‑empty signal arrays

Pipeline Validation

• run_pipeline now enforces:
  • M >= 1
  • alpha > 0
  • baseline_samples >= 1

NaN/Inf Guards

• physionet_loader.py now raises ValueError if all samples are NaN or Inf.

Mobile Platform Safety

• Added NULL‑handle guards to all Android JNI entry points.
• Added null check for respiro_create() return value on iOS.

---

Architecture

Shared Perturbation Logic

• Extracted _apply_drift and _apply_pause into validation/perturbations.py.
• Both validate_bidmc.py and multi_record_validation.py now import from this shared module.

CI Improvements

• Added Python CI job to .github/workflows/ci.yml with contents: read permissions.

Versioning

• Version bumped to 1.1.0 across:
  • core/respirosync_core.h
  • server/app.py (now reads from VERSION file)
  • tests/test_core.cpp
• Added new top‑level VERSION file.

---

Consistency

• Added __init__.py to both validation/ and server/ directories for proper module structure.

---

Summary

v2.1.0 is a comprehensive hardening release that improves production security, enforces strict API validation, strengthens mobile platform safety, and introduces cleaner architectural boundaries. The system is now more resilient, predictable, and secure for real‑world respiratory monitoring deployments.

2.0.0

RespiroSync v2.0.0 — Public REST API, Global Node Architecture, and Deterministic Operator Integration

Overview

This release marks the transition from a local research prototype to a globally accessible, API‑driven respiratory monitoring service. It introduces a public REST interface, a distributed node architecture, and the first production‑ready integration of the deterministic phase‑memory operator.

---

New Features

Public REST API

• Added authenticated REST endpoints for respiratory signal submission, operator execution, and result retrieval.
• Standardized JSON schemas for requests and responses.
• Enabled cross‑platform access from mobile apps, web dashboards, and external research tools.

Global Node Architecture

• Introduced a multi‑node execution model supporting distributed operator evaluation.
• Added node registration, heartbeat monitoring, and load‑balanced task dispatch.
• Ensured deterministic behavior across heterogeneous hardware.

Deterministic Phase‑Memory Operator (ΔΦ)

• Integrated the full ΔΦ operator pipeline into the service layer.
• Added drift, pause, and control‑segment detection modes.
• Ensured reproducible outputs across all nodes with strict numerical consistency.

---

Infrastructure & Reliability

Security & Authentication

• Added JWT‑based authentication for all API endpoints.
• Introduced per‑node API keys and request‑signing logic.
• Hardened request validation and error handling.

Logging & Observability

• Added structured logs for operator runs, node events, and API calls.
• Introduced trace IDs for multi‑node request correlation.
• Added lightweight metrics for latency, throughput, and operator performance.

---

Developer Experience

• Added a complete API reference with example requests.
• Introduced local development scripts for running nodes and the coordinator.
• Improved error messages and validation feedback for malformed inputs.

---

Bug Fixes

• Fixed numerical drift in operator initialization under certain sampling rates.
• Corrected edge‑case handling for short control segments.
• Improved stability of long‑running node processes.

---

Notes

This release establishes the foundation for the v2.x line, which focuses on dashboard integration, quantitative validation, and manuscript‑ready analytics.

Version 1.3.0 — Release Notes

Overview

Version 1.3.0 delivers a production‑ready upgrade to the entire RespiroSync codebase. This release resolves all identified bugs, strengthens JNI stability, improves numerical safety, introduces advanced signal‑quality metrics, and adds a complete testing and documentation suite. The system is now suitable for deployment in consumer‑grade respiratory monitoring applications.

---

Critical Bugs Fixed (6)

Division‑by‑Zero Protection

• Added safeguards in all breathing‑rate and respiratory‑signal calculations
• Prevents runtime crashes under low‑motion or flatline sensor conditions

Android JNI Crash (Signature Mismatch)

• Fixed incorrect JNI method signature that caused a 100% crash rate on Android
• Ensures stable cross‑language communication between C++ and Java layers

Input Validation for Sensor Data

• Added NaN and infinity rejection
• Prevents invalid sensor packets from corrupting downstream metrics

JNI Exception Handling

• Added structured exception handling for all JNI calls
• Prevents silent failures and ensures predictable error propagation

JNI Memory Leaks

• Fixed missing local reference cleanup
• Eliminates memory leaks during high‑frequency sensor polling

Type Mismatches (bool vs int)

• Corrected mismatched types in Android integration layer
• Ensures consistent behavior across platforms

---

High‑Priority Improvements (5)

• Added epsilon‑based floating‑point comparisons
• Implemented timestamp monotonicity checks
• Added buffer bounds validation for all signal windows
• Improved const‑correctness across the codebase
• Added range‑clamping for all respiratory metrics

---

Advanced Features Added (4)

Signal Quality Assessment

• Introduced a 5‑level quality indicator for real‑time feedback

Signal‑to‑Noise Ratio (SNR)

• Added quantitative SNR metric for sensor reliability scoring

Structured Error Codes

• Added unified error‑reporting system for all API calls

Version API

• Added runtime version‑querying for integration environments

---

Testing Infrastructure

• Added comprehensive test suite (10 tests, 100% passing)
• Introduced a professional Makefile‑based build system
• Updated CI workflow with automated testing and strict compilation flags
• All builds compile cleanly with:
  -Wall -Wextra -Werror -pedantic

---

Documentation

• PRODUCTION_IMPROVEMENTS.md — detailed changelog (9.5 KB)
• PRODUCTION_READY.md — deployment summary (7.7 KB)
• QUICK_REFERENCE.md — developer guide (6.8 KB)
• Enhanced API documentation in all public headers
• Added Android JNI migration guide

---

Security

• CodeQL scan: zero C++ vulnerabilities
• Code review: three issues found and fixed
• All input validated
• Exception‑safe error handling throughout
• No buffer overflows, resource leaks, or undefined behavior detected

---

Validation

• Compiles with zero warnings
• 10/10 unit tests passing
• No security vulnerabilities
• Fully integrated CI/CD pipeline
• Production‑ready build system

---

Summary

Version 1.3.0 transforms RespiroSync into a stable, secure, and production‑grade respiratory monitoring system. With strengthened JNI reliability, improved numerical safety, advanced signal‑quality metrics, and complete documentation, the codebase is now ready for deployment in consumer applications.

v1.2.0 — Accelerometer Pipeline Performance Optimization

Motivation

• Reduce per-sample CPU overhead by avoiding repeated full-buffer scans when computing accelerometer variance.
• Eliminate redundant square-root computations by reusing computed magnitudes across gravity removal and movement metrics.

Description

• Added a cached magnitude buffer (accel_magnitude_buffer) along with running accumulators (accel_magnitude_sum and accel_magnitude_sum_squares) to efficiently track recent accelerometer magnitudes.
• Updated removeGravity to accept a precomputed magnitude (float removeGravity(float magnitude)), ensuring magnitude is computed only once per sample.
• Modified feedAccelerometer to:
  • Push and evict magnitudes from the buffer,
  • Maintain running sums on buffer eviction,
  • Reuse the precomputed magnitude for gravity removal and peak / bandpass processing.
• Replaced the previous O(n) variance scan over the accelerometer buffer with an O(1) variance calculation using the running sums to compute movement_variance.

Impact

• Lower per-sample CPU cost in the accelerometer hot path.
• Improved numerical efficiency by removing redundant sqrt calls.
• Identical external behavior with improved runtime scalability, especially for higher sample rates.

Compatibility

• No API changes.
• Fully backward compatible.

Testing

• Existing runtime behavior validated through normal pipeline execution.
• No new unit tests added for this release.

RespiroSync v1.1.0 — Core Type Alignment & C API Hardening

Release Type: Minor
Focus: ABI safety, FFI robustness, and internal type consistency

Motivation

• Ensure the core implementation reuses the public type definitions and header declarations to avoid ODR and type mismatches between the core library and language bindings.
• Harden the C API entry points against null handles and null output pointers to prevent crashes when invoked from higher-level runtimes (e.g., Python, Rust, Swift).
• Clean up unused local constants and ensure required headers are included for safe memory operations.

Description

• Added #include "respirosync_core.h" and reordered/extended includes (including <cstring>) so the core implementation relies exclusively on shared public declarations and can safely use memset.
• Removed duplicated SleepStage and SleepMetrics definitions in the core and now explicitly use ::SleepStage and ::SleepMetrics from the public header to ensure type alignment.
• Eliminated the unused MIN_SAMPLES_FOR_BPM constant and removed dead local variables and comments related to unused filter tuning paths.
• Hardened C API wrappers with null checks:
  • respiro_destroy
  • respiro_start_session
  • respiro_feed_gyro
  • respiro_feed_accel
    These now return early when passed a null RespiroHandle.
• Updated respiro_get_metrics to:
  • Guard against a null out_metrics pointer.
  • Handle a null RespiroHandle by zeroing out_metrics and setting current_stage to UNKNOWN.
• Normalized the apnea field assignment in getCurrentMetrics to an explicit integer form (1 / 0) to match the C ABI expectations defined in the public header.

Compatibility

• No public API or ABI breaking changes.
• Existing callers and bindings remain fully compatible.
• Changes improve safety and correctness without altering external contracts.

Testing

• No automated tests were run as part of this change.
• Changes were validated via code inspection and API contract review.

RespiroSync v1.0.0 - Stable Core API & Documentation Release

This release marks the first stable public version of RespiroSync.

v1.0.0 formalizes the project’s architecture, public API, and documentation, establishing a clear and intentional foundation for future development. There are no functional or algorithmic changes in this release.

What’s Included

• Stable C API (v1.0.0)

• Defined, versioned public interface for the core engine

• Opaque handle design for long-term ABI stability

• Cross-platform compatibility (Android / iOS)

• Portable C++ Core Engine

• Chest-mounted respiratory signal processing

• Breath cycle detection and respiratory rate estimation

• Heuristic sleep-stage classification and movement analysis

Thin Platform Bindings

• Android JNI bridge

• iOS Objective-C++ bridge

• No platform-side signal processing

Comprehensive Documentation

• README.md — project overview and usage

• docs/ARCHITECTURE.md — system design and data flow

• docs/SIGNALS.md — sensor assumptions and signal semantics

• docs/PLATFORMS.md — platform integration boundaries

Clear Licensing & Attribution

MIT License with attribution requirements

Commercial use permitted

Scope & Guarantees

As of v1.0.0:

• The C API is considered stable

• Internal implementation details may evolve

• All processing is performed on-device

• Metrics are heuristic and non-diagnostic

This release prioritizes clarity, correctness, and portability over feature expansion.

Who This Release Is For

• Developers integrating respiratory metrics into mobile apps

• Researchers exploring low-cost respiratory monitoring

• Product teams evaluating chest-mounted sensing approaches

• Contributors interested in extending the core engine responsibly

What’s Next

• Future releases may include:

• Extended APIs for generic respiratory signals

• Improved filtering and peak detection

• Advanced sleep-stage models

• Validation tooling and benchmarks

These are not part of the v1.0.0 contract.

Release Notes

• No breaking changes (first stable release)

• No new features (alignment and formalization release)

Thank you to everyone who has explored, cloned, and provided feedback on RespiroSync so far. This release establishes a solid foundation for what comes next.

RespiroSync — v0.1.1

Repository Structure & Project Foundation Update

This release formalizes RespiroSync as an early-stage but intentional project, focused on clarity, portability, and long-term maintainability.

What Changed

• Repository structure cleaned and normalized

• Documentation consolidated under docs/

• Platform code organized into core/, android/, and ios/ boundaries

No functional changes

• Core respiratory engine logic remains unchanged

• Android and iOS demo scaffolding preserved as-is

Licensing clarified

• Attribution and usage terms refined to better reflect intended use

This update is purely structural and organizational, intended to make the project easier to understand, extend, and collaborate on as it matures.

Current Project State

• RespiroSync currently consists of:

• A cross-platform C++ core for respiratory signal processing

• Android JNI bindings and a minimal Kotlin engine wrapper

• iOS bridge code with a lightweight Swift demo view

• Early documentation outlining setup and intent

The project is intentionally minimal at this stage, prioritizing correctness and architectural clarity over feature breadth.

Near-Term Roadmap

Planned next steps include:

• Formalizing the core engine API and headers

• Improving signal validation and robustness

• Expanding platform documentation and examples

• Preparing the core for library-style consumption on mobile platforms

RespiroSync is in active, early development. This release establishes a stable foundation for future work rather than introducing new features.