src/acquisition/README.md

Acquisition — cap → LSL bridge + simple 32-ch viewer

Backup in-house acquisition path (see research/Cerelog_adaptation_notes.md and research/OpenBCI_GUI_software_report.md). Everything is LSL-based, so LabRecorder, MNE-LSL, Timeflux, or a forked OpenBCI GUI can also consume the same stream.

[cap] --UDP/TCP--> udp_lsl_bridge.py --LSL 'Cap32'(EEG,32ch) + 'Cap32_Markers'--> viewer.py / LabRecorder

Files

file	what
cap_gui.py	Main acquisition GUI (direct UDP/TCP): control bar, 32-ch scope (CAR'd + filtered), live spectrum, quality panel, Record.
impedance_gui.py	Impedance head-map UI: sends %, shows per-electrode kΩ; falls back to passive contact proxy if the board doesn't inject; restores * on exit.
impedance.py	CLI impedance probe (sends %, prints per-ch kΩ + amp@31.2Hz, restores *).
probe.py	Socket-level probe (local IPs, init sequence, reframe, per-ch µV + common-mode test).
rt_filter.py	RealTimeEEGFilter — vendor-style Butterworth band/low-pass + 50 Hz iir-notch + baseline removal, stateful lfilter for live chunks.
synth.py	Synthetic 32-ch EEG so the GUI/pipeline run with no hardware.
udp_lsl_bridge.py	Alternative LSL path: cap → LSL 'Cap32' (for LabRecorder/MNE-LSL/Timeflux interop).
viewer.py	The LSL-based viewer (pairs with the bridge).

Two acquisition paths: cap_gui.py (self-contained, vendor-style — the main one now) or the LSL bridge + viewer (when you want LabRecorder→XDF or other LSL tools). Both share common/montage.py + the udp_lsl_bridge parser.

Use

conda activate eegmi

# preview the GUI with synthetic data (no hardware) — renders results/cap_gui_preview.png
python src/acquisition/cap_gui.py --screenshot results/cap_gui_preview.png
python src/acquisition/cap_gui.py --source synth                       # live, synthetic
python src/acquisition/cap_gui.py --source udp --host 192.168.4.1 --port 8086   # real cap (UDP)
python src/acquisition/cap_gui.py --source tcp --host 192.168.4.1 --port <tcp_port>  # loss-free

# alternative LSL path (LabRecorder→XDF / Timeflux):
python src/acquisition/udp_lsl_bridge.py --transport udp --host 192.168.4.1 --port 8086
python src/acquisition/viewer.py --source lsl
python src/acquisition/udp_lsl_bridge.py --dry-run                     # parse self-test

Filtering (mirrors the vendor RealTimeEEGFilter)

rt_filter.py: Butterworth order-4 band-pass (lowcut>0) or low-pass (lowcut=0) + optional 50 Hz iirnotch + baseline/drift removal (running-mean subtraction), all via stateful lfilter (zi) for live streaming. GUI defaults 0–40 Hz + notch on; set low=3 for a 3–40 Hz band-pass. The vendor app uses the exact same design (butter + iirnotch + running-mean).

Status (verified on the M5)

• Bridge parse self-test ✅ (±1000 counts → ±22.35 µV, sign + trigger correct).
• Viewer renders ✅ (results/cap_gui_preview.png).
• LSL two-process data flow ✅ (producer → consumer, 32 ch @ 250 Hz).

Protocol — CONFIRMED from the vendor app (fromprovider/main_ui)

Reverse-read from their PyInstaller build (utils.parse_24bit_signed, Controller.change_channels_nums, utils.UDPReceiver/TCPReceiver):

• FRAME_LEN = n_ch*3 + 9 → 32 ch = 105 B. [0]=0xA0, [1]=seq#(0-255), [2 : 2+3·n_ch] = n_ch × 3-byte big-endian signed samples, then 6 reserved/trigger bytes, [FRAME_LEN-1]=0xC0.
• µV = signed24 × 0.02235 (if v&0x800000: v-=16777216) — matches our scaling exactly.
• The bridge's PacketLayout + parse_24bit_signed now mirror this (dry-run verified).

Board commands (CONFIRMED from vendor utils.py/Controller.py — LOWERCASE!)

byte	meaning
b'b'	start streaming (manual's "B" is WRONG)
b's'	stop
b'1'/b'2'/b'3'	sample rate 250 / 500 / 1000 Hz
b'*'	EEG-wave mode (normal acquisition)
b'%'	impedance mode (injects AC current)

Init order that avoids the impedance-mode comb artifact: '*' (EEG mode) → rate → 'b' (start). Our board_init() does exactly this; the UDP socket also mirrors the vendor (bind local port 2244, connect to the board). If you connect and only send b (or uppercase B) without '*', the board stays injecting → every channel shows a regular waveform with an evenly-spaced harmonic comb in the FFT. DC offset is removed in software (running-mean + optional high-pass in rt_filter.py), not on the board.

Two things their code confirms:

1. TCP is already supported — their TCPReceiver uses TCP_NODELAY. So the loss-free path is available: run our bridge with --transport tcp once you know the TCP port (ask the vendor; their UDP port is 8086). No firmware change may even be needed.
2. Per-frame sequence counter (byte 1) → our bridge now reports dropped-frame % live and emits lost/N markers (same idea as their check_sequence_continuity).

Still worth asking the vendor: the exact sampling rate (default 250, options 500/1000), the TCP port, whether the 6 reserved bytes carry a real trigger (their UDP build passes trigger=0), and whether the impedance mode (change2Imp/ImpedanceMode + WidgetImpedancePlot exist in their app) actually returns valid readings on this cap.