psychopy-aurora 0.1.0
PsychoPy plugin providing Builder components for NIRx Aurora API integration.
Requires Python: >=3.8
Keywords: psychopy, aurora, nirx, fnirs, builder, plugin

# PsychoPy Aurora Plugin (`psychopy-aurora`)

A PsychoPy **Builder plugin** that allows you to control **NIRx Aurora** data acquisition directly from your PsychoPy experiment — without custom scripting.

The plugin provides Builder components to:

- Connect to the Aurora Data Acquisition API
- Run basic setup (device/config selection and signal optimization)
- Start and stop recordings at routine boundaries
- Send event triggers (1–255) via Aurora’s REST API or via LSL markers

---

## Features

### Builder Components

#### 1. AuroraRecorder
- Discovers and connects to Aurora via LSL
- Initializes device and configuration
- Runs signal optimization
- Sets subject and experiment metadata
- Optionally starts/stops recording at routine boundaries

#### 2. AuroraTrigger (REST)
- Sends triggers to Aurora via:
  ```
  POST /api/v1/recording/trigger
  ```
- Uses the active global Aurora connection
- Trigger ID can be a number or PsychoPy variable (e.g., from a conditions file)
- Supports trigger on routine **begin** or **end**

#### 3. AuroraTriggerLSL
- Creates an LSL marker outlet
- Uses the `trigger_in_stream_name` from the selected Aurora configuration
- Pushes `int32` trigger samples at routine begin/end
- Useful for LSL-based synchronization pipelines

---

## Requirements

- Python >= 3.8
- PsychoPy (recent versions recommended)
- Aurora Data Acquisition API running on the same network
- LSL installed and working

Runtime dependencies:
- requests
- pydantic
- pylsl
- rich

---

## Installation

### Install from source (recommended for development)

    pip install -e .

### Build wheel

    python -m build
    pip install dist/psychopy_aurora-*.whl

---

## How It Works

### 1. Aurora Discovery

The plugin searches for an LSL stream named:

    Aurora_API

It then verifies connectivity using:

    GET /api/v1/ping

Once connected, all communication is done via:

    http://<ip>:<port>/api/v1

---

## Typical Experiment Workflow

### Step 1 – Setup Routine
Add **AuroraRecorder**:
- Connect to Aurora
- Select device and configuration
- Run signal optimization
- (Optional) Start recording

### Step 2 – Task Routine(s)
Add one of:
- **AuroraTrigger** (REST-based triggers)
- **AuroraTriggerLSL** (LSL marker triggers)

Place trigger component at stimulus onset routine.

### Step 3 – End Routine
Use **AuroraRecorder** with:
- “Stop recording” enabled

---

## Example Trigger Usage

If using a conditions file with a column:

    trigger

Set Trigger ID to:

    trigger

If using a fixed trigger:

    9

---

## Troubleshooting

### “No Aurora instance found”
- Ensure Aurora API is running
- Ensure LSL is active
- Verify network connectivity

### Triggers not appearing
- REST: Ensure recording is active
- LSL: Ensure outlet was successfully created

### Output directory
Current implementation sets output directory to:

    %USERPROFILE%/Documents/AuroraTest

Consider making this configurable in future versions.

---

## Development

Install dev dependencies:

    pip install -e .[dev]

Project uses setuptools packaging.

---

## License

GNU General Public License v3.0
© NIRx Medizintechnik GmbH