plasma-app 2.2.0__tar.gz → 2.2.3__tar.gz

{plasma_app-2.2.0 → plasma_app-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plasma-app
-Version: 2.2.0
+Version: 2.2.3
 Summary: PLASMA — Platform for LSL-based Acquisition of Sensor Metrics and Analytics
 License: MIT
 Project-URL: Homepage, https://github.com/YuyiChang/PLASMA
@@ -56,6 +56,13 @@ from faults.
 
 ## quickstart
 
+**macOS: `brew install --cask yuyichang/plasma/plasma`** is the recommended
+way to get PLASMA — no Python, no `liblsl`, no Gatekeeper dance. See
+[Install & first launch](https://yuyichang.github.io/PLASMA/playbook/install/)
+for that and every other install path (prebuilt binaries, PyPI, from source).
+
+To run from source instead:
+
 - `conda create -n plasma python=3.12`
 - `conda activate plasma`
 - `pip install -e ".[all]"` — or a lean subset, e.g. `".[msense]"` / `".[qb2,pupil]"`
@@ -94,7 +101,7 @@ plugins: `msense`, `qb2`, `pupil`, `shimmer`, `obs` (and `all`).
 - [x] linux aarch64 build — `PLASMA_Linux_arm64` for Jetson Orin (JetPack 6); CI job `build-linux-arm64`
 - [ ] infrequent stream (e.g., PLASMA journaler) shows green after recording stop
 - [ ] doc for msense workflow with better screenshots
-- [ ] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
+- [x] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
 
 ## developing a sensor plugin
 

{plasma_app-2.2.0 → plasma_app-2.2.3}/README.md

@@ -8,6 +8,13 @@ from faults.
 
 ## quickstart
 
+**macOS: `brew install --cask yuyichang/plasma/plasma`** is the recommended
+way to get PLASMA — no Python, no `liblsl`, no Gatekeeper dance. See
+[Install & first launch](https://yuyichang.github.io/PLASMA/playbook/install/)
+for that and every other install path (prebuilt binaries, PyPI, from source).
+
+To run from source instead:
+
 - `conda create -n plasma python=3.12`
 - `conda activate plasma`
 - `pip install -e ".[all]"` — or a lean subset, e.g. `".[msense]"` / `".[qb2,pupil]"`
@@ -46,7 +53,7 @@ plugins: `msense`, `qb2`, `pupil`, `shimmer`, `obs` (and `all`).
 - [x] linux aarch64 build — `PLASMA_Linux_arm64` for Jetson Orin (JetPack 6); CI job `build-linux-arm64`
 - [ ] infrequent stream (e.g., PLASMA journaler) shows green after recording stop
 - [ ] doc for msense workflow with better screenshots
-- [ ] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
+- [x] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
 
 ## developing a sensor plugin
 

{plasma_app-2.2.0 → plasma_app-2.2.3}/plasma/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.2.0"
+__version__ = "2.2.3"
 
 # Short git commit hash baked in by CI (.github/workflows/build.yml) just
 # before a release build is frozen with PyInstaller — a frozen bundle ships no

{plasma_app-2.2.0 → plasma_app-2.2.3}/plasma/app_context.py

@@ -36,7 +36,7 @@ import os
 import sys
 from dataclasses import dataclass, replace
 
-__all__ = ["AppContext", "app_context", "configure", "reset"]
+__all__ = ["AppContext", "app_context", "configure", "reset", "user_data_dir"]
 
 
 @dataclass(frozen=True)
@@ -71,8 +71,13 @@ _ctx: AppContext | None = None
 _DEFAULT_APP_DIR = "PLASMA"
 
 
-def _user_data_dir(app: str = _DEFAULT_APP_DIR) -> str:
-    """Per-user, per-OS application-data directory (stdlib, no platformdirs)."""
+def user_data_dir(app: str = _DEFAULT_APP_DIR) -> str:
+    """Per-user, per-OS application-data directory (stdlib, no platformdirs).
+
+    Public so other entry points (e.g. ``plasma.desktop_shortcut``) can target
+    the same directory a frozen build would resolve to, without themselves
+    running frozen.
+    """
     if sys.platform == "win32":
         base = os.environ.get("LOCALAPPDATA") or os.path.join(
             os.path.expanduser("~"), "AppData", "Local")
@@ -95,7 +100,7 @@ def _from_env() -> AppContext:
     if env:
         return AppContext(home=env)
     if _is_frozen():
-        return AppContext(home=_user_data_dir())
+        return AppContext(home=user_data_dir())
     return AppContext(home=os.getcwd())
 
 

{plasma_app-2.2.0 → plasma_app-2.2.3}/plasma/desktop_shortcut.py

@@ -14,9 +14,19 @@ Points the shortcut directly at *this* environment's ``plasma`` console-script
 than re-deriving a `python -m ...` invocation — see the pyshortcuts prototype
 notes in the packaging discussion for why.
 
+The shortcut's working directory is pinned to the same per-OS app-data dir a
+frozen PyInstaller build resolves to (``plasma.app_context.user_data_dir``),
+not left to whatever the OS defaults a new shortcut to (``$HOME`` on
+Windows/Linux; an unspecified Terminal default on macOS). Since
+``plasma.app_context`` falls back to the working directory for a non-frozen
+process, this keeps the Desktop-icon launch and a downloaded prebuilt binary
+reading/writing config from the same place.
+
     plasma-install-shortcut [--name NAME] [--no-terminal] [--no-startmenu]
 
-Requires the ``desktop`` extra (``pip install plasma-app[desktop]``).
+Requires the ``desktop`` extra (``pip install "plasma-app[desktop]"`` —
+quote it, or zsh's glob expansion on ``[...]`` will fail with "no matches
+found").
 """
 from __future__ import annotations
 
@@ -26,6 +36,8 @@ import shutil
 import sys
 from pathlib import Path
 
+from plasma.app_context import user_data_dir
+
 _ICON_DIR = Path(__file__).parent / "resources" / "icons"
 
 
@@ -60,6 +72,35 @@ def _plasma_executable() -> str:
     )
 
 
+def _target_home() -> str:
+    """Where the shortcut should run PLASMA from — the same per-OS app-data
+    dir a frozen build resolves to (``$PLASMA_HOME`` still wins if set,
+    matching ``app_context``'s own precedence)."""
+    return os.environ.get("PLASMA_HOME") or user_data_dir()
+
+
+def _launch_script(target_home: str) -> str:
+    """Path handed to pyshortcuts as the thing to run.
+
+    On Windows/Linux, pyshortcuts writes ``target_home`` into the shortcut
+    itself (the ``.lnk`` ``WorkingDirectory`` / the ``.desktop`` ``Path=``
+    key), so the plain console-script is enough. On macOS, pyshortcuts'
+    Terminal/Automator launcher never applies ``working_dir`` at all — so we
+    wrap the console-script in a tiny shell script that ``cd``s first.
+    """
+    exe = _plasma_executable()
+    if sys.platform != "darwin":
+        return exe
+    wrapper = Path(target_home) / "plasma-launch.sh"
+    wrapper.write_text(
+        "#!/bin/sh\n"
+        f'cd "{target_home}" || exit 1\n'
+        f'exec "{exe}"\n'
+    )
+    wrapper.chmod(0o755)
+    return str(wrapper)
+
+
 def install_shortcut(name="PLASMA", terminal=True, startmenu=True, folder=None):
     """Create the Desktop (+ Start Menu, if requested) shortcut. Returns the
     ``pyshortcuts.Shortcut`` namedtuple describing what was written.
@@ -76,19 +117,23 @@ def install_shortcut(name="PLASMA", terminal=True, startmenu=True, folder=None):
     except ImportError as e:
         raise ImportError(
             "pyshortcuts is required to create a desktop shortcut — install "
-            "it with `pip install plasma-app[desktop]`."
+            'it with `pip install "plasma-app[desktop]"`.'
         ) from e
 
+    target_home = _target_home()
+    os.makedirs(target_home, exist_ok=True)
+
     return make_shortcut(
-        script=_plasma_executable(),
+        script=_launch_script(target_home),
         name=name,
         description="PLASMA sensor acquisition dashboard",
         icon=_icon_path(),
         terminal=terminal,
         desktop=True,
         startmenu=startmenu,  # pyshortcuts itself no-ops this on macOS
+        working_dir=target_home,
         folder=folder,
-        noexe=True,  # script is already a standalone console-script binary
+        noexe=True,  # script is already a standalone console-script/wrapper
     )
 
 
@@ -114,7 +159,13 @@ def main(argv=None):
         startmenu=not args.no_startmenu,
     )
     print(f"Created shortcut: {scut.target}")
-    print(f"  runs:    {scut.script}")
+    # NOTE: not scut.script/scut.full_script — pyshortcuts splits `script` on
+    # its first space to separate a script from trailing arguments, which
+    # mangles this when the path itself contains a space (e.g. macOS's
+    # "Application Support"). The shortcut it writes is still correct; only
+    # the returned namedtuple's script fields are truncated for display.
+    print(f"  runs:    {_plasma_executable()}")
+    print(f"  in:      {scut.working_dir}")
     print(f"  desktop: {scut.desktop_dir}")
     if scut.startmenu_dir:
         print(f"  menu:    {scut.startmenu_dir}")

{plasma_app-2.2.0 → plasma_app-2.2.3}/plasma/devices/msense/config.py

@@ -46,7 +46,12 @@ def merge_msense_records(existing, scanned, overwrite):
 
     ``overwrite=True``  → one fresh record per scanned device, nothing kept.
     ``overwrite=False`` → ``existing`` plus a record for every scanned address
-    not already listed (case-insensitive on "UUID / MAC Address").
+    not already listed (case-insensitive on "UUID / MAC Address"). A scanned
+    address that IS already listed has that record's Name refreshed to the
+    freshly advertised name instead — Nickname/Enabled/IMU Stream are left
+    alone — so a firmware update that changes the advertised name reaches the
+    table via Append without needing Overwrite (which would also reset those
+    per-device toggles for every other configured wristband).
 
     Fresh records use the advertised name as Name, blank Nickname, Enabled on,
     IMU Stream off. Returns ``(records, summary_str)``.
@@ -64,13 +69,30 @@ def merge_msense_records(existing, scanned, overwrite):
         records = [_fresh(dev) for dev in scanned]
         return records, f"Overwrote table with {len(records)} scanned wristband(s)"
 
+    scanned_by_addr = {dev["address"].strip().upper(): dev for dev in scanned}
+    records = []
+    renamed = 0
+    for rec in existing:
+        dev = scanned_by_addr.get(str(rec.get("UUID / MAC Address", "")).strip().upper())
+        if dev and dev["name"] != rec.get("Name", ""):
+            rec = {**rec, "Name": dev["name"]}
+            renamed += 1
+        records.append(rec)
+
     have = {str(rec.get("UUID / MAC Address", "")).strip().upper() for rec in existing}
     added = [_fresh(dev) for dev in scanned if dev["address"].strip().upper() not in have]
-    skipped = len(scanned) - len(added)
-    msg = f"Appended {len(added)} new wristband(s)"
-    if skipped:
-        msg += f" ({skipped} already listed)"
-    return list(existing) + added, msg
+    records += added
+
+    unchanged = len(scanned) - len(added) - renamed
+    parts = []
+    if added:
+        parts.append(f"{len(added)} new")
+    if renamed:
+        parts.append(f"{renamed} renamed")
+    if unchanged:
+        parts.append(f"{unchanged} unchanged")
+    msg = "Appended " + ", ".join(parts) if parts else "No changes"
+    return records, msg
 
 
 # ── device_info.json import (YAMS provisioning format) ───────────────────────

{plasma_app-2.2.0 → plasma_app-2.2.3}/plasma/devices/msense/device.py

@@ -74,6 +74,10 @@ BATTERY_CHAR_UUID = "00002a19-0000-1000-8000-00805f9b34fb"
 
 SQC_MIN_MTU = 128
 SQC_DEBUG = True  # emit per-notification telemetry (printed off the BLE thread)
+# devices with no active SQC/live session still get unsolicited NUS traffic
+# (boot chatter, or firmware that exposes the NUS char but doesn't speak the
+# SQC/live protocol) — coalesce that noise instead of one debug line/packet
+NUS_IDLE_LOG_WINDOW_S = 5.0
 
 # NOTE: the overall per-transaction backstop timeout stays DISABLED — the real
 # BLE data rate is far slower than the handoff doc's provisional 35/45 s
@@ -173,6 +177,11 @@ class MotionSenseHRV(PlasmaDevice):
         # addr -> live INFINITY-stream state (see _new_live_state); only ever
         # one NUS stream (SQC snapshot OR live) active per wristband at a time.
         self.live_state = {}
+        # addr -> {"count", "bytes", "window_start"} — coalesces the
+        # "ignored (no active stream)" debug line so a chatty/idle wristband
+        # doesn't flood the console one line per notification (see
+        # _log_nus_ignored / NUS_IDLE_LOG_WINDOW_S)
+        self._nus_idle_rx = {}
         # addr -> {"status": confirmed|unconfirmed|unverifiable|unknown,
         #          "checked_at": ts} — set by collection_ctl(addr, False), see
         # _confirm_acq_stopped. Cleared on the next collection_ctl(addr, True).
@@ -1325,7 +1334,7 @@ class MotionSenseHRV(PlasmaDevice):
             elif live and live.get("session") and not live["session"].is_terminal:
                 self._handle_live_notification(live, name, bytes(data), now, t_entry)
             else:
-                self._sqc_debug(name, f"rx {len(data)}B ignored (no active stream)")
+                self._log_nus_ignored(name, len(data))
         except Exception as e:
             self.info(f"Error handling NUS data from {name}: {e}")
 
@@ -1520,6 +1529,28 @@ class MotionSenseHRV(PlasmaDevice):
         except queue.Full:
             pass  # never block the BLE thread on a slow console
 
+    def _log_nus_ignored(self, name, nbytes):
+        # first notification in a window prints immediately (so isolated,
+        # one-off chatter is still visible); anything after that within
+        # NUS_IDLE_LOG_WINDOW_S is tallied silently and flushed as one
+        # rolled-up line — keeps a continuously-chattering/no-session
+        # wristband (e.g. firmware that exposes NUS but doesn't speak the
+        # SQC/live protocol) from spamming a line per packet
+        st = self._nus_idle_rx.setdefault(name, {"count": 0, "bytes": 0, "window_start": 0.0})
+        now = time.time()
+        st["count"] += 1
+        st["bytes"] += nbytes
+        if now - st["window_start"] < NUS_IDLE_LOG_WINDOW_S:
+            return
+        if st["count"] > 1:
+            self._sqc_debug(
+                name, f"rx {st['count']}x ({st['bytes']}B total) ignored (no active stream)")
+        else:
+            self._sqc_debug(name, f"rx {nbytes}B ignored (no active stream)")
+        st["count"] = 0
+        st["bytes"] = 0
+        st["window_start"] = now
+
     def _sqc_diag_summary(self, name, store=None):
         d = (store or self.sqc_state).get(name, {}).get("diag")
         if not d:

{plasma_app-2.2.0 → plasma_app-2.2.3}/plasma_app.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plasma-app
-Version: 2.2.0
+Version: 2.2.3
 Summary: PLASMA — Platform for LSL-based Acquisition of Sensor Metrics and Analytics
 License: MIT
 Project-URL: Homepage, https://github.com/YuyiChang/PLASMA
@@ -56,6 +56,13 @@ from faults.
 
 ## quickstart
 
+**macOS: `brew install --cask yuyichang/plasma/plasma`** is the recommended
+way to get PLASMA — no Python, no `liblsl`, no Gatekeeper dance. See
+[Install & first launch](https://yuyichang.github.io/PLASMA/playbook/install/)
+for that and every other install path (prebuilt binaries, PyPI, from source).
+
+To run from source instead:
+
 - `conda create -n plasma python=3.12`
 - `conda activate plasma`
 - `pip install -e ".[all]"` — or a lean subset, e.g. `".[msense]"` / `".[qb2,pupil]"`
@@ -94,7 +101,7 @@ plugins: `msense`, `qb2`, `pupil`, `shimmer`, `obs` (and `all`).
 - [x] linux aarch64 build — `PLASMA_Linux_arm64` for Jetson Orin (JetPack 6); CI job `build-linux-arm64`
 - [ ] infrequent stream (e.g., PLASMA journaler) shows green after recording stop
 - [ ] doc for msense workflow with better screenshots
-- [ ] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
+- [x] memo `stage` transition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
 
 ## developing a sensor plugin