# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Running the app

```bash
python main.py
```

No build step. Simulation mode default (no hardware needed).

## Dependencies

```bash
pip install PyQt6 pyqtgraph numpy pyserial
pip install nidaqmx        # optional — only for real NI hardware
pip install opencv-python  # optional — only for motion capture plugin
```

## Architecture

### Data flow

```
Hardware / Simulation
        ↓
  api_layers/          ArduinoLayer, NidaqmxLayer — low-level I/O, background threads
        ↓
  devices/             BaseDevice subclasses — wrap api_layers, expose read_channels() / write_channel()
        ↓
  core/acquisition.py  AcquisitionEngine — polls devices at 100 ms, fills ChannelBuffers, emits new_data signal
        ↓
  core/signal_processor.py  SignalProcessor — filters + derived channels, re-emits processed_data
        ↓
  ui/strip_chart.py    StripChartWidget — consumes processed_data, renders via pyqtgraph
```

Control widgets (left panel) go other direction: UI → `ControlWidget._write()` → `DeviceRegistry.get_instance()` → `device.write_channel()` → api_layer.

### Key design patterns

**Shared serial port** — `api_layers/port_registry.py` holds module-level `port_registry` singleton. Multiple devices sharing one Arduino (e.g. `AnalogInputDevice` + `DigitalIODevice` on same port) both call `port_registry.get_layer(port, baud)`, get same `ArduinoLayer` instance. Never construct `ArduinoLayer` directly in device code.

**Device auto-discovery** — `DeviceRegistry._discover()` scans `devices/` with `pkgutil`, imports every module, registers any class subclassing `BaseDevice`. New device type = drop file in `devices/`, no registration needed.

**Backend switching at runtime** — `AnalogInputDevice` and `DigitalIODevice` both have `switch_backend(backend, simulate, ...)` — disconnects, reconfigures, reconnects without restart. Called from "Apply & Reconnect" in config dialog.

**Profile persistence** — `core/profile.py` serialises full operator state (controls, plot layout, signal pipelines, derived channels) to `.labdaq` JSON files. `ProfileManager` handles save/load.

### Directory map

| Path | Purpose |
|------|---------|
| `api_layers/arduino_layer.py` | Serial protocol + simulation; `ARDUINO_FIRMWARE` string is the uploadable sketch |
| `api_layers/nidaqmx_layer.py` | NI-DAQmx wrapper with simulation fallback |
| `api_layers/port_registry.py` | Shared `ArduinoLayer` singleton per (port, baud) |
| `devices/base_device.py` | `BaseDevice`, `ChannelConfig`, `DeviceInfo`, `DeviceStatus` |
| `devices/analog_input.py` | Analog input — NI or Arduino backend |
| `devices/digital_io.py` | Digital I/O — NI or Arduino backend |
| `devices/serial_device.py` | Generic UART device |
| `core/acquisition.py` | `AcquisitionEngine` + `ChannelBuffer` |
| `core/signal_processor.py` | Filter chain + derived/virtual channels |
| `core/profile.py` | `.labdaq` profile save/load |
| `ui/main_window.py` | Top-level window, toolbar, demo device init, plugin lifecycle |
| `ui/control_panel.py` | Left panel output widgets (`OnOffSwitch`, `MotorControl`, etc.) |
| `ui/strip_chart.py` | Live pyqtgraph chart, config-driven by `LayoutConfig` |
| `ui/add_device_dialog.py` | Add Device dialog; `_PANELS` dict extended by plugins |
| `ui/windows/plot_window.py` | Plot Builder: BSP tree, `LayoutCanvas` drag-drop, `LayoutConfig` |
| `ui/windows/` | Floating tool windows (Devices, Signals, Plot, Settings) |
| `ui/style_dark.qss` / `style_light.qss` | Full app theme |
| `plugins/base_plugin.py` | `LabPlugin` ABC, `PluginAction`, `PluginContext` |
| `plugins/plugin_manager.py` | Discovery, load/unload, `enabled.json` persistence |
| `plugins/motion_capture/` | Camera device plugin — adds Camera type to Add Device dialog |

### Arduino firmware

Firmware embedded as `ARDUINO_FIRMWARE` in `api_layers/arduino_layer.py`. When editing: set `N_DIG_OUT` to match digital output pins in use (default 0 — leaves pins in INPUT mode, causes inverted write behaviour). Upload via Arduino IDE.

Serial protocol: `A0:3.14,D2:1\n` stream from Arduino; `W:D7:1\n` / `P:D9:128\n` commands from PC.

### Plot layout — BSP tree

`ui/windows/plot_window.py` stores the subplot arrangement as a binary space-partition tree of plain dicts:

```
{"kind": "leaf",   "pane": <int>}
{"kind": "hsplit", "ratio": <float>, "first": <node>, "second": <node>}  # left/right
{"kind": "vsplit", "ratio": <float>, "first": <node>, "second": <node>}  # top/bottom
```

Key tree functions (all in `plot_window.py`): `_tree_insert`, `_tree_remove`, `_tree_swap`, `_tree_reindex`, `_tree_equalize_ratios`. `tree_to_grid()` converts the tree to pyqtgraph `addItem(row, col, rowspan, colspan)` coordinates. `_tree_grid_size()` returns the LCM of all split denominators — the minimum grid size that expresses all ratios as integers.

`LayoutCanvas` (also in `plot_window.py`) is the drag-and-drop tile editor. Drop zones detected in `_zone_at()`: outer 1/3 of tile = split (bisect), gap between tiles = squeeze (insert-between), center = swap. `_do_drop()` executes the tree mutation.

### Plugin system

Plugins live in `plugins/<id>/` with a `manifest.json` and entry point module. The plugin directory is added to `sys.path` on load, so intra-plugin imports use bare names (`from tracker import CameraTracker`). Cross-plugin imports use the full path (`from ui.add_device_dialog import _PANELS`).

`PluginContext` passed to `on_load(context)`:
```python
context.registry    # DeviceRegistry
context.engine      # AcquisitionEngine
context.processor   # SignalProcessor
context.main_window # MainWindow
```

Optional hooks a plugin can implement:
- `get_devices() → list[BaseDevice]` — auto-registered into acquisition engine
- `get_filter_classes() → dict` — added to `SignalProcessor` filter registry
- `get_toolbar_actions() → list[PluginAction]` — buttons inserted in main toolbar
- `get_settings_widget() → QWidget` — shown in Settings → Plugins panel
- `get_save_state() / apply_save_state(dict)` — persisted in `.labdaq` profiles

**Extending Add Device dialog from a plugin**: `ui/add_device_dialog._PANELS` is a module-level dict `{type_name: (PanelClass, id_prefix)}`. Plugins add/remove entries in `on_load`/`on_unload`. Each panel class needs a `build_device(device_id) → BaseDevice` method.

### Adding a new device type

1. Subclass `BaseDevice` in new file under `devices/`
2. Implement: `connect()`, `disconnect()`, `read_channels() → Dict[str, float]`, `write_channel(channel_id, value) → bool`, `get_config_widget() → QWidget`
3. Include `switch_backend()` if device supports runtime reconfiguration
4. `DeviceRegistry` discovers it automatically on next run