CommanderPho
diff --git a/‎.cursor/lr_mainwindow_snip.cpp‎
Lines changed: 722 additions & 0 deletions b/‎.cursor/lr_mainwindow_snip.cpp‎
Lines changed: 722 additions & 0 deletions
diff --git a/‎.cursor/plans/cfg-driven_xdf_naming_f561cd45.plan.md‎
Lines changed: 72 additions & 0 deletions b/‎.cursor/plans/cfg-driven_xdf_naming_f561cd45.plan.md‎
Lines changed: 72 additions & 0 deletions
diff --git a/‎.cursor/plans/emotiv_connection_status_15557b9c.plan.md‎
Lines changed: 72 additions & 0 deletions b/‎.cursor/plans/emotiv_connection_status_15557b9c.plan.md‎
Lines changed: 72 additions & 0 deletions
diff --git a/‎.cursor/plans/emotiv_reconnect_loop_e48b5b3b.plan.md‎
Lines changed: 86 additions & 0 deletions b/‎.cursor/plans/emotiv_reconnect_loop_e48b5b3b.plan.md‎
Lines changed: 86 additions & 0 deletions
@@ -0,0 +1,72 @@
+---
+name: CFG-driven XDF naming
+overview: When `--record` is omitted, resolve an XDF output path from the bundled `LSLTemplate.cfg` by extending `AppConfig` and `ConfigManager::load()` with a new `[Recording]` section (enabled flag, output subdirectory, filename template with placeholders). `--record <path>` continues to override. Executable-relative paths and `create_directories` ensure the file can be created.
+todos:
+  - id: extend-appconfig-recording
+    content: Add recording fields to AppConfig; section-aware load/save in Config.cpp
+    status: completed
+  - id: resolve-recording-path
+    content: Implement resolveRecordingOutputPath + expose exe dir helper; update LSLTemplate.cfg [Recording]
+    status: completed
+  - id: emotiv-main-wireup
+    content: "emotiv main.cpp: findConfigFile + resolve when --record absent"
+    status: completed
+  - id: readme-emotiv-cfg
+    content: Document cfg-driven XDF naming and override behavior in README
+    status: completed
+isProject: false
+---
+
+# CFG-driven default XDF filenames for emotiv_lsl
+
+## Current behavior
+
+- [`src/emotiv/main.cpp`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/src/emotiv/main.cpp) only sets `record_file` when `--record <path>` is present; otherwise recording is off ([`emotiv_base.cpp`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/src/emotiv/emotiv_base.cpp) gates on `!record_file.empty()`).
+- The repo already ships [`LSLTemplate.cfg`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/LSLTemplate.cfg) with `[Stream]` / `[Device]`, and [`src/core/src/Config.cpp`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/src/core/src/Config.cpp) implements `lsltemplate::ConfigManager::load` / `findConfigFile`. `emotiv_lsl` already links `LSLTemplate::core` but does not use this config for recording.
+
+## Desired behavior
+
+| CLI | Result |
+|-----|--------|
+| `--record C:\foo\bar.xdf` | Use that path (unchanged override). |
+| No `--record` | If `[Recording]` in the loaded cfg enables auto recording, build a unique path from template; otherwise no XDF (same as today). |
+
+## Design
+
+1. **Extend [`AppConfig`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/src/core/include/lsltemplate/Config.hpp)** with optional recording fields, for example:
+   - `bool recording_auto_enabled = false`
+   - `std::string recording_directory = "recordings"` (subdirectory under the executable directory when relative)
+   - `std::string recording_filename_template = "{stream_name}_{date}_{time}.xdf"`
+
+2. **Section-aware parsing in `ConfigManager::load`** ([`Config.cpp`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/src/core/src/Config.cpp)): today `current_section` is read but ignored, so keys are global. Refactor so:
+   - `[Stream]` keys (`name`, `type`, `channels`, `sample_rate`, …) only apply when `current_section == "Stream"` (case-sensitive or normalized to match existing files).
+   - `[Device]` keys (`device_param`, …) only when section is `Device`.
+   - New `[Recording]` keys (`enabled`, `directory`, `filename_template`, optional `basename` to override `stream_name` for filenames only) only when section is `Recording`.
+
+   This avoids collisions if someone adds a `name` under `[Recording]` later.
+
+3. **Append `[Recording]` to [`LSLTemplate.cfg`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/LSLTemplate.cfg)** with commented defaults: `enabled=0` so existing behavior is preserved until the user opts in.
+
+4. **Path resolution helper** (small function in `Config.cpp` + declaration in `Config.hpp`, or a dedicated `.cpp` under `src/emotiv` if you prefer to keep core generic — recommendation: keep **`resolveRecordingOutputPath(const AppConfig&, const std::filesystem::path& exe_dir)`** in `lsltemplate` next to config so the GUI/CLI could reuse it later):
+
+   - If `!recording_auto_enabled`, return `nullopt`.
+   - Build base dir = `exe_dir / recording_directory` (if `recording_directory` is absolute, use it as-is per `std::filesystem` rules).
+   - Expand template: replace `{stream_name}` with `AppConfig.stream_name`, optional `{basename}` if added, `{date}` → local `YYYY-MM-DD`, `{time}` → `HH-MM-SS` (filesystem-safe). Sanitize or reject path components if needed (minimal: avoid `:` on Windows in the filename only by using `-` for time).
+   - `create_directories` for the parent of the final `.xdf` path.
+   - Return absolute path string (or `path`) for `record_file`.
+
+   Reuse the same executable-directory logic already used in [`emotiv_lsl_log_config.cpp`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/src/emotiv/emotiv_lsl_log_config.cpp) — either export a shared `exe_parent_dir()` from a small shared helper or duplicate the minimal call via `lsltemplate::ConfigManager` / existing `getExecutablePath` in `Config.cpp` (already has `getExecutablePath()` in anonymous namespace; consider exposing a public `getExecutableDirectory()` on `ConfigManager` to avoid duplication).
+
+5. **`main.cpp` (emotiv)** after argv parsing:
+   - If `record_file` non-empty → keep as today.
+   - Else → `findConfigFile("LSLTemplate.cfg")`, `load`, then `resolveRecordingOutputPath`. If result is set, assign to `record_file` and print the same “Recording natively to XDF file: …” line as manual `--record`.
+
+6. **`ConfigManager::save`**: Update to write `[Recording]` with the new fields so the GUI “Save” does not strip recording options (optional but recommended for consistency).
+
+7. **Docs**: Short paragraph in [`README.md`](C:/Users/pho/repos/EmotivEpoc/ACTIVE_DEV/emotiv-lsl-cpp/README.md) under the emotiv section: `--record` overrides; otherwise enable `[Recording]` in `LSLTemplate.cfg` next to the executable, placeholders, and example.
+
+## Testing
+
+- No `--record`, default cfg `enabled=0`: no recording (no regression).
+- Set `enabled=1` in cfg, run without `--confirm`: file appears under `exe_dir/recordings/…`, logs show resolved path.
+- `--record` explicit path: cfg ignored for path choice.
@@ -0,0 +1,72 @@
+---
+name: Emotiv connection status
+overview: Clarify console status so "USB receiver open" is not confused with "headset streaming," and add a paced read loop plus counters so you can distinguish no dongle, dongle idle (waiting for headset), and active EEG/motion packets.
+todos:
+  - id: reword-connect
+    content: Change post-open log to USB receiver + waiting semantics; optionally print serial once
+    status: completed
+  - id: hid-read-timeout
+    content: Use hid_read_timeout in inner loop with small ms timeout for periodic status
+    status: completed
+  - id: stream-detection
+    content: Track raw reports vs first has_eeg||has_motion; throttle waiting/diagnostic messages
+    status: completed
+  - id: retry-message
+    content: Clarify find_open_emotiv_device failure message (dongle/receiver not detected)
+    status: completed
+  - id: manual-test
+    content: Build Release; test no dongle / dongle only / full headset scenarios
+    status: completed
+isProject: false
+---
+
+# Distinct status: dongle vs headset vs streaming
+
+## What goes wrong today
+
+- In [`EmotivBase::main_loop()`](src/emotiv/emotiv_base.cpp), after `find_open_emotiv_device()` succeeds, the code prints **"Connected to Emotiv device: " + `device_name`** (line ~180). `device_name` is the product string from the subclass (e.g. Epoc X in [`emotiv_epoc_x.cpp`](src/emotiv/emotiv_epoc_x.cpp)), not live link state.
+- The inner loop uses **`hid_read`** with no timeout ([`emotiv_base.cpp`](src/emotiv/emotiv_base.cpp) ~196–202). On `bytes_read == 0` it **`continue`s with no log**, so there is no feedback while the dongle is present but the headset is off or not yet sending EEG/motion frames.
+- **Valid streaming signal**: Treat **`result.has_eeg || result.has_motion`** as "headset is sending usable stream data." Do **not** use `has_quality` alone for that: in [`EmotivEpocX::decode_data()`](src/emotiv/emotiv_epoc_x.cpp), quality is filled from fixed byte indices whenever decryption runs and can look "present" without a real EEG stream.
+
+## Proposed behavior (console)
+
+| Situation | User-visible behavior |
+|-----------|------------------------|
+| No Emotiv HID interface | Keep retry loop; **reword** message to something like **no USB receiver / dongle detected** (same code path as today: `find_open_emotiv_device()` returns null). |
+| HID opened, no EEG/motion yet | One line on connect: **USB receiver open** (include `device_name` and serial if you want). Then **rate-limited** lines (e.g. every 3–5 s): **waiting for headset data** (no valid EEG/motion decoded yet). |
+| First EEG or motion sample | One line: **streaming** (EEG and/or motion as applicable). |
+| USB reports arrive but 0 EEG/motion after N packets | Optional single diagnostic (or same bucket as "waiting"): **reports received but no EEG/motion — check headset power/pairing** (avoids implying the dongle is "broken" when the radio link is down). |
+| `hid_read` error | Keep existing **disconnect / reconnect** message. |
+
+## Implementation (minimal surface area)
+
+**File: [`src/emotiv/emotiv_base.cpp`](src/emotiv/emotiv_base.cpp)** (and only if needed, tiny constants in an anonymous namespace—no header change required unless you extract a small helper).
+
+1. **Replace the connect log** so it does not say "Connected to Emotiv device" in the misleading sense. Example intent: *USB receiver connected — waiting for headset (EEG/motion)…*
+
+2. **Switch the read path to `hid_read_timeout()`** (hidapi already linked) with a modest timeout (e.g. 250–500 ms). This yields:
+   - Predictable wakeups for status printing without busy-spinning on `bytes_read == 0`.
+   - Same handling for `bytes_read < 0` (reconnect) and `> 0` (process packet).
+
+3. **Per HID session state** (reset each time a new `device` is opened after the inner loop `break`):
+   - `bool saw_streaming = false` (set when first `has_eeg || has_motion`).
+   - `uint64_t raw_hid_reports` (increment for each `bytes_read > 0`).
+   - `steady_clock` last status print time for throttling.
+
+4. **In the inner loop**, when `bytes_read == 0` **or** when data did not yield EEG/motion:
+   - If `!saw_streaming` and throttle elapsed, print the **waiting** line (and optionally mention `raw_hid_reports` if > 0 to distinguish "silent dongle" vs "reports but no decode").
+
+5. **Optional polish**: Log **serial_number** once on USB connect (already populated in `find_open_emotiv_device()`) to make support/debugging easier.
+
+## Out of scope (unless you ask)
+
+- **GUI / LSL metadata**: mirroring status in [`src/gui/`](src/gui/) or LSL stream description.
+- **New CLI flags** (`--verbose` / JSON): easy to add later if you want machine-readable status.
+- **Stricter packet validation** in `validate_data()` (e.g. magic bytes): only if empirical capture shows we need it to avoid counting garbage as "reports."
+
+## Verification
+
+- **No dongle**: paced "no receiver" retry message; process stays up (existing reconnect behavior).
+- **Dongle only, headset off**: USB-connected line, then repeating **waiting** lines; no "streaming" until EEG/motion.
+- **Headset on**: **waiting** stops being relevant after first stream line; outlets behave as today.
+- **Unplug mid-run**: existing disconnect path unchanged.
@@ -0,0 +1,86 @@
+---
+name: Emotiv reconnect loop
+overview: Keep the `emotiv_lsl` console process alive by wrapping HID connect and the read loop in an infinite reconnect cycle with paced retries, resetting LSL outlets between sessions. Fatal errors (e.g. HID init failure) can still exit via the existing `main()` exception handler; normal Ctrl+C / closing the console window still terminate the process without extra code.
+todos:
+  - id: extract-find-open
+    content: Add find_open_emotiv_device() (no init/exit, nullptr if missing); refactor get_hid_device() to use it
+    status: completed
+  - id: restructure-main-loop
+    content: hid_init once; outer reconnect loop with sleep; inner read loop; close device + reset outlets + has_motion_data; hid_exit at end
+    status: completed
+  - id: header-decl
+    content: Declare find_open_emotiv_device in emotiv_base.h
+    status: completed
+  - id: verify-build
+    content: Configure/build emotiv_lsl and sanity-check no dongle / unplug scenarios
+    status: completed
+isProject: false
+---
+
+# Continuous headset reconnect for `emotiv_lsl`
+
+## Current behavior (why the app exits)
+
+1. **Startup**: [`get_hid_device()`](src/emotiv/emotiv_base.cpp) throws `std::runtime_error("Emotiv headset not found")` (or HID init failure). [`main()`](src/emotiv/main.cpp) catches, prints, returns `1` → process exits.
+
+2. **After connect**: [`main_loop()`](src/emotiv/emotiv_base.cpp) reads in a `while (true)` loop. On `hid_read` &lt; 0 it logs, **breaks**, calls `requestStop()` on the recorder if any, `hid_close`, `hid_exit`, and **returns** → `main()` returns `0` → process exits.
+
+```mermaid
+flowchart TD
+  start[main] --> ml[main_loop]
+  ml --> gh[get_hid_device throws if missing]
+  gh --> read[read loop]
+  read -->|bytes_read lt 0| cleanup[hid_close hid_exit return]
+  read -->|forever| read
+  cleanup --> exit[process exits]
+```
+
+## Target behavior
+
+- **Outer infinite loop** in `EmotivBase::main_loop()` (until the OS terminates the process on window close or Ctrl+C).
+- **Connect phase**: If no device, log once per retry and `sleep_for` a fixed interval (e.g. 1–2 s) to avoid a busy spin; repeat until open succeeds.
+- **Read phase**: Same logic as today; on `bytes_read < 0`, log that reconnect will be attempted, `hid_close` the handle, **reset** `eeg_outlet` / `motion_outlet` / `eeg_quality_outlet` so the next session creates fresh LSL streams, then continue the outer loop.
+- **HID lifecycle**: Call `hid_init()` once at the start of `main_loop()` (throw on failure — unchanged severity). Call `hid_exit()` only when `main_loop()` truly ends (in practice the process is usually killed first; this keeps the API balanced if the function ever returns).
+
+## Code changes (single focal file + small header touch)
+
+Primary implementation in [`src/emotiv/emotiv_base.cpp`](src/emotiv/emotiv_base.cpp):
+
+- Add `#include <thread>` for `std::this_thread::sleep_for`.
+- Introduce a **`constexpr` retry interval** (or `static const` duration) for “no device” and optionally reuse a short sleep after disconnect (same interval is fine).
+- **Extract** the enumeration/open logic from `get_hid_device()` into a new protected helper, e.g. `find_open_emotiv_device()`, that:
+  - **Does not** call `hid_init()` / `hid_exit()`.
+  - Returns `nullptr` if no Emotiv interface is found (no throw).
+- Refactor **`get_hid_device()`** (still used by [`get_crypto_key()`](src/emotiv/emotiv_epoc_x.cpp) when `serial_number` is empty) to: `hid_init()` → `find_open_emotiv_device()` → throw if null (preserve existing contract for that rare path).
+- Restructure **`main_loop()`** roughly as:
+  - `hid_init()` once; throw if nonzero.
+  - `while (true)` {
+    - `while (!device)` { `device = find_open_emotiv_device();` if null, log + sleep }
+    - log connected
+    - **First successful connect only**: if `record_file` non-empty and `!recorder`, build `watchfor` / construct `recording` (same as today, **after** device is open so `get_lsl_source_id()` still sees a populated `serial_number`).
+    - Inner read loop: existing decode / outlet creation / push logic.
+    - On read error: log, `break` inner loop.
+    - `if (recorder) recorder->requestStop();` — **same as today** when the session ends (see note below).
+    - `hid_close(device);` reset the three `unique_ptr` outlets; reset `has_motion_data = false` for sensible logging on the next session.
+  - }
+  - `hid_exit()` after the outer loop (unreachable in the normal “infinite” design unless you later add a shutdown flag).
+
+Declare `find_open_emotiv_device()` in [`src/emotiv/emotiv_base.h`](src/emotiv/emotiv_base.h) under `protected` next to `get_hid_device()`.
+
+[`src/emotiv/main.cpp`](src/emotiv/main.cpp): **No change required** for Ctrl+C / close — default process termination already applies. Keep the `try`/`catch` for genuine fatal exceptions (e.g. HID init failure).
+
+## `--record` / XDF behavior (explicit tradeoff)
+
+Today, `requestStop()` runs when the read loop exits, which **finalizes** the background recording. Keeping that call on each HID disconnect means **XDF recording will not resume** on reconnect without a larger redesign (new `recording` instance, file naming, etc.). The plan **preserves** this stop-on-disconnect recording semantics so reconnect work stays focused on **LSL streaming**, matching your stated problem (dongle unplug / connect). If you want recording to span disconnects, that should be a separate follow-up.
+
+## Out of scope
+
+- **GUI / template CLI** ([`src/gui/`](src/gui/), [`src/cli/`](src/cli/)): not the Emotiv dongle executable; unchanged unless you ask to mirror behavior there.
+- **Signal handlers** for graceful `hid_close` on Ctrl+C: not required for your stated exit paths; optional hardening later.
+
+## Verification
+
+- Build `emotiv_lsl`, run **without** dongle: console should repeat a clear “not found, retrying” message and stay running.
+- Plug dongle: should connect and stream as before.
+- Unplug while running: should log disconnect and return to retry loop without exiting.
+- With `--record`: first session records; after unplug, behavior matches chosen `requestStop` semantics above.