rr-app 1.5.0__tar.gz

rr_app-1.5.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: rr-app
+Version: 1.5.0
+Summary: EMGS PyQt6 desktop application (BLE + asyncio).
+Author: rr_emg contributors
+License: Proprietary
+Project-URL: Homepage, https://github.com/o0fung/RR_EMG
+Project-URL: Repository, https://github.com/o0fung/RR_EMG
+Project-URL: Issues, https://github.com/o0fung/RR_EMG/issues
+Keywords: emg,ble,pyqt6,imu,sensor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyQt6==6.9.1
+Requires-Dist: qasync==0.27.1
+Requires-Dist: bleak==0.22.3
+Requires-Dist: pyqtgraph==0.13.7
+Requires-Dist: numpy==2.3.1
+Requires-Dist: rich==14.1.0
+Requires-Dist: pyobjc-core==10.3.2; platform_system == "Darwin"
+Requires-Dist: pyobjc-framework-Cocoa==10.3.2; platform_system == "Darwin"
+Requires-Dist: pyobjc-framework-CoreBluetooth==10.3.2; platform_system == "Darwin"
+Requires-Dist: pyobjc-framework-libdispatch==10.3.2; platform_system == "Darwin"
+Provides-Extra: ml
+Requires-Dist: scipy; extra == "ml"
+Requires-Dist: scikit-learn; extra == "ml"
+Requires-Dist: joblib; extra == "ml"
+
+# RR App (`rr_emg`)
+
+Language: **English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
+## Overview
+
+`rr_emg` is a desktop GUI for Bluetooth monitoring and control.
+
+It supports:
+- **EMGS devices** (EMG + IMU streaming)
+- **AKR-compatible devices** (including `rr_akr2` protocol behavior and other compatible devices such as EMGS-family products)
+
+Typical use:
+- scan and connect to devices,
+- monitor live data,
+- send control/configuration commands,
+- record sessions for analysis.
+
+## Audience
+
+- Operators and clinicians
+- R&D teams
+- Integrators and developers
+
+For operator-focused instructions, see `IFU.md`.
+
+## Requirements
+
+- Python `>=3.10,<3.14`
+- Bluetooth-capable host (macOS / Linux / Windows)
+
+## Installation
+
+### Option 1: Release packages (recommended for most operators)
+
+Download from [GitHub Releases](https://github.com/o0fung/RR_EMG/releases/latest).
+
+- Windows: `rr-app-<version>-setup.exe`
+- macOS: `rr-app-<version>-macos.dmg`
+
+On macOS, if Gatekeeper warns on unsigned builds, right-click the app and choose **Open**.
+
+### Option 2: PyPI / pipx
+
+```bash
+pip install rr-app
+```
+
+or
+
+```bash
+pipx install rr-app
+```
+
+### Option 3: From source (developer path)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Quick Start
+
+1. Turn on host Bluetooth.
+2. Power on target device(s).
+3. Launch:
+
+```bash
+rr
+```
+
+4. Scan and connect in the app.
+5. Use **Signals** tab for live monitoring.
+6. Use settings/control actions as needed.
+7. Start recording when session export is required.
+
+Simulation mode (no hardware):
+
+```bash
+RR_BACKEND=sim rr
+```
+
+## Device Compatibility Notes
+
+- EMGS discovery prefix: `EMGS`
+- AKR discovery prefixes: `AKR` and optional legacy `BT`
+- AKR BLE profile fallback is built-in (new profile first, legacy profile fallback)
+
+## Protocol and OTA Docs
+
+- AKR/BT CLI + telemetry: `doc/BT_AKR_DEVICE_PROTOCOL.md`
+- OTA CLI session protocol: `doc/OTA_PROTOCOL_CLI_SESSION.md`
+
+## Data and Logs
+
+- Startup logs:
+  - macOS: `~/Library/Logs/rr-app`
+  - Linux/Windows: `~/.rr-app/logs`
+- Default recording folder: `~/rr_data`
+
+## Project Links
+
+- Homepage: [RR_EMG](https://github.com/o0fung/RR_EMG)
+- Issues: [GitHub Issues](https://github.com/o0fung/RR_EMG/issues)
+

rr_app-1.5.0/README.md

@@ -0,0 +1,106 @@
+# RR App (`rr_emg`)
+
+Language: **English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
+## Overview
+
+`rr_emg` is a desktop GUI for Bluetooth monitoring and control.
+
+It supports:
+- **EMGS devices** (EMG + IMU streaming)
+- **AKR-compatible devices** (including `rr_akr2` protocol behavior and other compatible devices such as EMGS-family products)
+
+Typical use:
+- scan and connect to devices,
+- monitor live data,
+- send control/configuration commands,
+- record sessions for analysis.
+
+## Audience
+
+- Operators and clinicians
+- R&D teams
+- Integrators and developers
+
+For operator-focused instructions, see `IFU.md`.
+
+## Requirements
+
+- Python `>=3.10,<3.14`
+- Bluetooth-capable host (macOS / Linux / Windows)
+
+## Installation
+
+### Option 1: Release packages (recommended for most operators)
+
+Download from [GitHub Releases](https://github.com/o0fung/RR_EMG/releases/latest).
+
+- Windows: `rr-app-<version>-setup.exe`
+- macOS: `rr-app-<version>-macos.dmg`
+
+On macOS, if Gatekeeper warns on unsigned builds, right-click the app and choose **Open**.
+
+### Option 2: PyPI / pipx
+
+```bash
+pip install rr-app
+```
+
+or
+
+```bash
+pipx install rr-app
+```
+
+### Option 3: From source (developer path)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Quick Start
+
+1. Turn on host Bluetooth.
+2. Power on target device(s).
+3. Launch:
+
+```bash
+rr
+```
+
+4. Scan and connect in the app.
+5. Use **Signals** tab for live monitoring.
+6. Use settings/control actions as needed.
+7. Start recording when session export is required.
+
+Simulation mode (no hardware):
+
+```bash
+RR_BACKEND=sim rr
+```
+
+## Device Compatibility Notes
+
+- EMGS discovery prefix: `EMGS`
+- AKR discovery prefixes: `AKR` and optional legacy `BT`
+- AKR BLE profile fallback is built-in (new profile first, legacy profile fallback)
+
+## Protocol and OTA Docs
+
+- AKR/BT CLI + telemetry: `doc/BT_AKR_DEVICE_PROTOCOL.md`
+- OTA CLI session protocol: `doc/OTA_PROTOCOL_CLI_SESSION.md`
+
+## Data and Logs
+
+- Startup logs:
+  - macOS: `~/Library/Logs/rr-app`
+  - Linux/Windows: `~/.rr-app/logs`
+- Default recording folder: `~/rr_data`
+
+## Project Links
+
+- Homepage: [RR_EMG](https://github.com/o0fung/RR_EMG)
+- Issues: [GitHub Issues](https://github.com/o0fung/RR_EMG/issues)
+

rr_app-1.5.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rr-app"
+dynamic = ["version"]
+description = "EMGS PyQt6 desktop application (BLE + asyncio)."
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = { text = "Proprietary" }
+authors = [{ name = "rr_emg contributors" }]
+keywords = ["emg", "ble", "pyqt6", "imu", "sensor"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: Microsoft :: Windows",
+]
+
+# Keep the default install as the GUI app + BLE stack.
+dependencies = [
+  "PyQt6==6.9.1",
+  "qasync==0.27.1",
+  "bleak==0.22.3",
+  "pyqtgraph==0.13.7",
+  "numpy==2.3.1",
+  "rich==14.1.0",
+  # macOS BLE stack dependencies (only on Darwin)
+  "pyobjc-core==10.3.2; platform_system=='Darwin'",
+  "pyobjc-framework-Cocoa==10.3.2; platform_system=='Darwin'",
+  "pyobjc-framework-CoreBluetooth==10.3.2; platform_system=='Darwin'",
+  "pyobjc-framework-libdispatch==10.3.2; platform_system=='Darwin'",
+]
+
+[project.urls]
+Homepage = "https://github.com/o0fung/RR_EMG"
+Repository = "https://github.com/o0fung/RR_EMG"
+Issues = "https://github.com/o0fung/RR_EMG/issues"
+
+[project.optional-dependencies]
+# Offline analysis / ML (fatigue detection)
+ml = ["scipy", "scikit-learn", "joblib"]
+
+[project.scripts]
+rr = "rr_app.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+exclude = ["backup*", "doc*"]
+
+[tool.setuptools.dynamic]
+version = { attr = "rr_app.__version__" }
+
+[tool.setuptools.package-data]
+rr_app = ["resources/*.qss", "resources/languages.json"]
+

rr_app-1.5.0/rr_app/__init__.py

@@ -0,0 +1,36 @@
+"""RR App PyQt6 application (clean rewrite).
+
+Run with:
+    python -m rr_app
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = ["__version__"]
+
+# Safety: never write __pycache__/bytecode into the checked-out repo / installed package.
+# This avoids "accidental updates" to a git checkout when running `rr` or `python -m rr_app`.
+sys.dont_write_bytecode = True
+
+__version__ = "1.5.0"
+
+"""
+ v1.4.0:
+   - Added Signals preset profile (save/load)
+   - Updated Settings prompt button grid
+
+ v1.4.1:
+   - Added mutlilingual translation selector support
+
+ v1.4.3:
+   - Fixed data recording CSV format
+
+ v1.4.9:
+   - Can read new CPM telemetry (for remaining time)
+
+ v1.5.0:
+   - Fixed CPM target_deg to _rad; refactored the rr_app
+
+"""

rr_app-1.5.0/rr_app/__main__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+if __name__ == "__main__":
+    try:
+        from .cli import main
+    except ImportError:
+        from rr_app.cli import main
+
+    raise SystemExit(main())
+

rr_app-1.5.0/rr_app/analysis/__init__.py

@@ -0,0 +1,9 @@
+"""Signal processing and modeling utilities (offline).
+
+This package is intentionally GUI-agnostic so it can be used for:
+- offline feature extraction / training
+- lightweight runtime inference (optional)
+"""
+
+from __future__ import annotations
+

rr_app-1.5.0/rr_app/analysis/emg_features.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Iterable, Iterator
+
+import numpy as np
+
+
+def _require_scipy() -> "object":
+    try:
+        import scipy.signal  # type: ignore
+    except ModuleNotFoundError as e:  # pragma: no cover
+        raise ModuleNotFoundError(
+            "scipy is required for EMG filtering/PSD. Install with: pip install -r requirements.txt"
+        ) from e
+    return scipy.signal
+
+
+@dataclass(frozen=True, slots=True)
+class EmgPreprocessConfig:
+    fs_hz: float = 1000.0
+    bandpass_hz: tuple[float, float] | None = (20.0, 450.0)
+    notch_hz: float | None = None  # e.g. 50 or 60
+    notch_q: float = 30.0
+    detrend: bool = True
+
+
+def preprocess_emg(x: np.ndarray, cfg: EmgPreprocessConfig) -> np.ndarray:
+    """Basic EMG preprocessing (typical surface EMG defaults).
+
+    Notes:
+    - Keep this conservative: the goal is repeatable features, not maximal denoising.
+    - If you already have a clean pipeline, you can skip this and only use feature extraction.
+    """
+    scipy_signal = _require_scipy()
+
+    x = np.asarray(x, dtype=float).copy()
+    if x.ndim != 1:
+        raise ValueError(f"preprocess_emg expects 1D signal, got shape={x.shape}")
+
+    if cfg.detrend:
+        x = x - float(np.mean(x))
+
+    fs = float(cfg.fs_hz)
+
+    if cfg.notch_hz is not None:
+        w0 = float(cfg.notch_hz) / (fs / 2.0)
+        if 0.0 < w0 < 1.0:
+            b, a = scipy_signal.iirnotch(w0=w0, Q=float(cfg.notch_q))
+            x = scipy_signal.filtfilt(b, a, x, method="pad")
+
+    if cfg.bandpass_hz is not None:
+        lo, hi = cfg.bandpass_hz
+        lo = float(lo)
+        hi = float(hi)
+        if lo <= 0.0 or hi <= 0.0 or hi <= lo:
+            raise ValueError(f"Invalid bandpass_hz={cfg.bandpass_hz}")
+        wn = (lo / (fs / 2.0), hi / (fs / 2.0))
+        b, a = scipy_signal.butter(4, wn, btype="bandpass")
+        x = scipy_signal.filtfilt(b, a, x, method="pad")
+
+    return x
+
+
+@dataclass(frozen=True, slots=True)
+class WindowConfig:
+    fs_hz: float = 1000.0
+    window_s: float = 0.250
+    hop_s: float = 0.050
+
+    def window_n(self) -> int:
+        return max(8, int(round(float(self.window_s) * float(self.fs_hz))))
+
+    def hop_n(self) -> int:
+        return max(1, int(round(float(self.hop_s) * float(self.fs_hz))))
+
+
+def iterate_windows(x: np.ndarray, cfg: WindowConfig) -> Iterator[tuple[int, int, np.ndarray]]:
+    """Yield (start_idx, end_idx, window_signal)."""
+    x = np.asarray(x, dtype=float)
+    if x.ndim != 1:
+        raise ValueError(f"iterate_windows expects 1D signal, got shape={x.shape}")
+
+    n = int(x.size)
+    w = int(cfg.window_n())
+    hop = int(cfg.hop_n())
+    if n < w:
+        return
+    for start in range(0, n - w + 1, hop):
+        end = start + w
+        yield start, end, x[start:end]
+
+
+def _zc(x: np.ndarray, *, threshold: float = 0.0) -> float:
+    """Zero crossings count with dead-zone threshold."""
+    x = np.asarray(x, dtype=float)
+    if x.size < 2:
+        return 0.0
+    # Apply dead-zone
+    x1 = np.where(np.abs(x) < float(threshold), 0.0, x)
+    s = np.sign(x1)
+    return float(np.sum((s[1:] * s[:-1]) < 0))
+
+
+def _wamp(x: np.ndarray, *, threshold: float) -> float:
+    """Willison amplitude: count of |x[n]-x[n-1]| >= threshold."""
+    x = np.asarray(x, dtype=float)
+    if x.size < 2:
+        return 0.0
+    d = np.abs(np.diff(x))
+    return float(np.sum(d >= float(threshold)))
+
+
+def _waveform_length(x: np.ndarray) -> float:
+    x = np.asarray(x, dtype=float)
+    if x.size < 2:
+        return 0.0
+    return float(np.sum(np.abs(np.diff(x))))
+
+
+@dataclass(frozen=True, slots=True)
+class WelchConfig:
+    fs_hz: float = 1000.0
+    nperseg: int = 256
+    noverlap: int = 128
+    window: str = "hann"
+
+
+def welch_psd(x: np.ndarray, cfg: WelchConfig) -> tuple[np.ndarray, np.ndarray]:
+    """Welch PSD estimate (nonnegative) in units of power/Hz."""
+    scipy_signal = _require_scipy()
+    x = np.asarray(x, dtype=float)
+    if x.ndim != 1:
+        raise ValueError(f"welch_psd expects 1D signal, got shape={x.shape}")
+    f, pxx = scipy_signal.welch(
+        x,
+        fs=float(cfg.fs_hz),
+        window=str(cfg.window),
+        nperseg=int(cfg.nperseg),
+        noverlap=int(cfg.noverlap),
+        detrend=False,
+        scaling="density",
+        return_onesided=True,
+    )
+    return np.asarray(f, dtype=float), np.asarray(pxx, dtype=float)
+
+
+def spectral_features_from_psd(f_hz: np.ndarray, pxx: np.ndarray) -> dict[str, float]:
+    """Compute common fatigue-related spectral features from a PSD."""
+    f = np.asarray(f_hz, dtype=float)
+    p = np.asarray(pxx, dtype=float)
+    if f.size == 0 or p.size == 0 or f.size != p.size:
+        return {"mnf_hz": 0.0, "mdf_hz": 0.0, "tot_power": 0.0}
+
+    # Drop DC for fatigue features (EMG often has DC/artifact content).
+    if f.size > 1:
+        f = f[1:]
+        p = p[1:]
+
+    p = np.maximum(p, 0.0)
+    tot = float(np.trapezoid(p, f))
+    if not math.isfinite(tot) or tot <= 0.0:
+        return {"mnf_hz": 0.0, "mdf_hz": 0.0, "tot_power": 0.0}
+
+    # Mean frequency (MNF): first moment / total power.
+    mnf = float(np.trapezoid(f * p, f) / tot)
+
+    # Median frequency (MDF): frequency where cumulative power reaches 50%.
+    # Use cumulative trapezoid integration for robustness.
+    c = np.cumsum((p[1:] + p[:-1]) * (f[1:] - f[:-1]) * 0.5)
+    if c.size == 0:
+        mdf = float(f[0])
+    else:
+        idx = int(np.searchsorted(c, 0.5 * float(c[-1]), side="left"))
+        idx = max(0, min(idx, int(f.size - 2)))
+        mdf = float(f[idx + 1])
+
+    return {
+        "mnf_hz": float(mnf),
+        "mdf_hz": float(mdf),
+        "tot_power": float(tot),
+    }
+
+
+def bandpower(f_hz: np.ndarray, pxx: np.ndarray, band_hz: tuple[float, float]) -> float:
+    f = np.asarray(f_hz, dtype=float)
+    p = np.asarray(pxx, dtype=float)
+    lo, hi = float(band_hz[0]), float(band_hz[1])
+    if f.size == 0 or p.size == 0:
+        return 0.0
+    m = (f >= lo) & (f <= hi)
+    if not np.any(m):
+        return 0.0
+    return float(np.trapezoid(np.maximum(p[m], 0.0), f[m]))
+
+
+def time_features(x: np.ndarray, *, wamp_thresh: float | None = None, zc_thresh: float = 0.0) -> dict[str, float]:
+    x = np.asarray(x, dtype=float)
+    if x.size == 0:
+        return {"rms": 0.0, "iemg": 0.0, "wl": 0.0, "zc": 0.0, "wamp": 0.0}
+
+    rms = float(math.sqrt(max(0.0, float(np.mean(x * x)))))
+    iemg = float(np.sum(np.abs(x)))
+    wl = _waveform_length(x)
+    zc = _zc(x, threshold=float(zc_thresh))
+
+    if wamp_thresh is None:
+        # Common heuristic: threshold relative to signal scale (10% of RMS).
+        wamp_thresh = 0.1 * rms
+    wamp = _wamp(x, threshold=float(wamp_thresh))
+
+    return {"rms": rms, "iemg": iemg, "wl": wl, "zc": zc, "wamp": wamp}
+
+
+def extract_feature_rows(
+    x: np.ndarray,
+    *,
+    preprocess: EmgPreprocessConfig | None = None,
+    window: WindowConfig,
+    welch: WelchConfig | None = None,
+    bandpowers_hz: Iterable[tuple[str, tuple[float, float]]] = (("bp_20_60", (20.0, 60.0)), ("bp_60_150", (60.0, 150.0)), ("bp_150_300", (150.0, 300.0))),
+) -> tuple[np.ndarray, list[str], np.ndarray]:
+    """Return (X, feature_names, t_center_s) for a single recording.
+
+    X rows correspond to windows. t_center_s is window center time in seconds.
+    """
+    x_in = np.asarray(x, dtype=float)
+    if x_in.ndim != 1:
+        raise ValueError(f"extract_feature_rows expects 1D signal, got shape={x_in.shape}")
+
+    cfg_p = preprocess or EmgPreprocessConfig(fs_hz=float(window.fs_hz))
+    x0 = preprocess_emg(x_in, cfg_p) if preprocess is not None else x_in.astype(float)
+
+    cfg_welch = welch or WelchConfig(fs_hz=float(window.fs_hz), nperseg=min(256, window.window_n()), noverlap=min(128, max(0, window.window_n() // 2)))
+    names: list[str] = []
+    rows: list[list[float]] = []
+    t_centers: list[float] = []
+
+    for start, end, seg in iterate_windows(x0, window):
+        tf = time_features(seg)
+        f, pxx = welch_psd(seg, cfg_welch)
+        sf = spectral_features_from_psd(f, pxx)
+        bp: dict[str, float] = {name: bandpower(f, pxx, band) for name, band in bandpowers_hz}
+
+        feat: dict[str, float] = {}
+        feat.update(tf)
+        feat.update(sf)
+        feat.update(bp)
+
+        if not names:
+            names = list(feat.keys())
+        rows.append([float(feat[k]) for k in names])
+
+        t_center = (float(start) + float(end)) * 0.5 / float(window.fs_hz)
+        t_centers.append(float(t_center))
+
+    if not rows:
+        return np.zeros((0, 0), dtype=float), [], np.zeros((0,), dtype=float)
+    return np.asarray(rows, dtype=float), names, np.asarray(t_centers, dtype=float)
+