Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,10 @@ settings.local.json
# misc
.codegraph/
delay_capture*/
/hardware_captures/

# Audio latency test outputs (large XDF recordings, plots, CLI logs)
scripts/audio_latency_test/recordings/

# Python cache
__pycache__/
__pycache__/
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,8 @@ sudo dnsmasq -d --port=0 --interface=en10 --bind-interfaces \

`--port=0` disables dnsmasq's DNS server, so it only hands out the one address; `-d` keeps it in the foreground (Ctrl+C stops it). The amplifier picks the lease up within a minute, without a restart, and it must be running whenever the amplifier powers up.

A DHCP-only example for an isolated amplifier link is provided in `scripts/na500_dhcp.conf`. Set the adapter to `10.10.10.61/24` and update the example's interface (`en10`) to match your adapter. On macOS with Homebrew, run `sudo /opt/homebrew/sbin/dnsmasq --no-daemon --conf-file="$PWD/scripts/na500_dhcp.conf"` from the repository root and leave it running during testing. It leases `10.10.10.62` and advertises neither a gateway nor a DNS server.

Differences from the NA400 that this app handles automatically:

- **Scaling**: 0.044703 µV/bit (±375 mV over 24 bits, matching the GES 500 datasheet and Net Station 6).
Expand All @@ -154,6 +156,7 @@ Differences from the NA400 that this app handles automatically:
- **Front end**: the NA500's EEG reads full scale until its buffered reference is switched on, every `cmd_Stop` switches it off, and switch commands sent within ~20 ms of power-on are lost; the app waits briefly after power-on and enables the buffered reference before each `cmd_Start`.
- **Physio16**: the NA500 never reports whether a Physio16 is attached, so the app always streams its 16 physio channels (PIB1-16) after the EEG. Physio gains persist on the amplifier, so the app sets them to 12, the power-on default, before each start; the physio is then scaled like the EEG (±375 mV range) and needs no realignment delay.
- **Triggers**: the app enables the NA500's DB9 digital inputs (without that they read as all 16 active) and its BNC input. Each rising edge on BNC in appears in the `_DIN` stream as bit 16 (value `0x10000`) for 1 ms, alongside the 16 DB9 bits. The EEG trails a BNC-in event by about 1.5 samples (the ADC filter's delay); no correction is applied, as in Net Station.
- **BNC input blanking**: the connector defaults to TMS blanking (mode 2), which also creates input events. At stream setup it sends `cmd_SetBlankingPulseWidth` = 1000 µs before `cmd_SetBncInMode` = 2, including when joining an already-running amplifier; reinitialization reapplies both. Blanking stays enabled between pulses. Mode and width are fixed in the connector, with no additional setting required. Modes 0, 1 and 3 disable blanking. Setup fails if either command is rejected. The mock preserves BNC events in mode 2 but does not simulate analog EEG gating.
- **BNC output trigger**: the GUI's *BNC Trigger* button (enabled while linked to an NA500) and the remote control `trigger` command send a TTL pulse (0 to 5 V) on the BNC output: 1 ms by default, or 100-1600 µs via `trigger <width_us>`. The amplifier makes each pulse about 6.7% longer than set (a 1 ms setting measures 1.07 ms); the app sends the width as is, as Net Station does. Cable BNC out to BNC in to see each pulse in the `_DIN` stream. The mock (`--amp-type NA500`) loops its BNC output back to its BNC input.
- **Clock**: the NA500 stamps packets with its own clock, which is not synchronized; the app sets it with `cmd_SetAmpTime` at power-on, as Net Station does.
- **Single client**: while Net Station (or any other client) is linked to the NA500, this app's connections are accepted but not serviced — and vice versa. Unlink Net Station before using this app; concurrent monitoring is not possible on the NA500 (unlike the NA400).
Expand Down
59 changes: 59 additions & 0 deletions docs/NA500_AmpServer.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,3 +139,62 @@ lost if its command is sent the instant the notification port connects, before t
buffered; the gap shows in the packet counter. Read the data port continuously.
- With no net attached the net code is 255. Digital inputs read 0 until `cmd_SetDinEnable`, then idle at
`0xFFFF` (active low). The first reserved byte read 3 at idle on the unit we measured.

## BNC input blanking

The FPGA needs `cmd_SetBlankingPulseWidth` (100–1600 µs) before
`cmd_SetBncInMode` = 2 to enable TMS blanking. Modes 0, 1 and 3 disable it.
Mode 2 remains armed between pulses and still produces BNC input events
(bit 2 of the first reserved byte, exposed by the connector as DIN bit 16).
The connector applies a fixed default of 1000 µs and mode 2 during stream setup,
including when joining an already-running amplifier, and after reinitialization.

### Hardware comparison, 2026-11-15

Tested serial 0001 (firmware 0.4.9, FPGA 0.6.1.f0, PCB 4.1.0.0) with BNC OUT
cabled to BNC IN, open EEG inputs, and no external signal source. Recorded all
256 EEG channels at 4000 Hz native, without LSL processing. In each recording,
the mode sequence was 1 → 2 → 2 → 1; output pulses stayed at a 1000 µs setting,
spaced 0.5 seconds apart. The blanking width was sent before each mode change.

| Blanking width | Mode 1 input events | Mode 2 input events |
|---|---:|---:|
| 1000 µs | 40/40 | 40/40 |
| 1600 µs | 20/20 | 20/20 |

All comparison blocks had contiguous packet counters and 250 µs timestamp
increments. None of the 120 analyzed event windows showed EEG saturation.
Mode 1 stayed near its roughly 1 µV background variation. Mode 2 produced a
repeatable transient, with the median absolute EEG response across channels and
events peaking around 1 mV at +0.5 ms. The later portion of the response moved
later at 1600 µs, while the output pulse width stayed unchanged. The effect
appeared in both mode-2 blocks and disappeared on return to mode 1.

![Mode 1 versus mode 2 at two blanking widths](measurements/na500_bnc_blanking_20261115.png)

These measurements demonstrate a width-dependent response in the EEG hardware
path and preserved input events. The open-input waveform is a switching
transient; this does not establish suppression of a known input signal or TMS
artifact. Its duration must not be interpreted as the exact analog gate width.
A driven-input test or direct gate measurement is still needed for those checks.

The [measurement summary](measurements/na500_bnc_blanking_20261115.json) includes
per-block event counts and continuity checks. To repeat the experiment, unlink
other AmpServer clients and run from the repository root:

```bash
python scripts/bnc_blanking_capture.py --host 10.10.10.62 \
--out hardware_captures/bnc-1000us
python scripts/bnc_blanking_analyze.py hardware_captures/bnc-1000us
python scripts/bnc_blanking_capture.py --host 10.10.10.62 --width 1600 --pulses 10 \
--out hardware_captures/bnc-1600us
python scripts/bnc_blanking_analyze.py hardware_captures/bnc-1600us
```

The capture utility saves complete raw PacketFormat2 payloads, command replies,
notifications and block boundaries. Analysis saves event epochs, metrics and a
plot; it needs NumPy and Matplotlib from `scripts/requirements.txt`. Acquisition
is stopped and powered down after capture. The last test width and mode 2 are
programmed before stopping; the connector reapplies its 1000 µs default on the
next stream setup. Large local recordings under `hardware_captures/` are ignored
by Git.
202 changes: 202 additions & 0 deletions docs/measurements/na500_bnc_blanking_20261115.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
[
{
"amplifier_details": "(sendCommand_return (status complete) (amp_details (serial_number 0001) (amp_type NA500) (legacy_board false) (packet_format 2) (system_version 0.4.9) (fpga_version 0.6.1.f0) (pcb_version 4.1.0.0) (number_of_channels 256) (feature_flags 0))",
"complete": true,
"capture_errors": [],
"sample_count": 196456,
"bytes": 248320384,
"requested_rate_hz": 4000,
"blocks": [
{
"block": 1,
"mode": 1,
"sent": 20,
"events": 20,
"samples": 44272,
"usable_epochs": 20,
"gate_normalized_increment": 1.0341614906832297,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
},
{
"block": 2,
"mode": 2,
"sent": 20,
"events": 20,
"samples": 44216,
"usable_epochs": 20,
"gate_normalized_increment": 265.86692176870747,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
},
{
"block": 3,
"mode": 2,
"sent": 20,
"events": 20,
"samples": 44248,
"usable_epochs": 20,
"gate_normalized_increment": 269.9619584675976,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
},
{
"block": 4,
"mode": 1,
"sent": 20,
"events": 20,
"samples": 44216,
"usable_epochs": 20,
"gate_normalized_increment": 0.9853896103896103,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
}
],
"usable_epochs": 80,
"useful_channels": 256,
"plotted_channel": 231,
"overall_epoch_rail_fraction": 0.0,
"modes": {
"1": {
"events": 40,
"median_baseline_abs_increment_counts": 22.0,
"gate_0_5_to_2ms_normalized_increment_median": 1.0,
"gate_0_5_to_2ms_normalized_increment_q25_q75": [
0.9143668831168831,
1.1358901515151516
],
"gate_exact_repeat_fraction": 0.013671875,
"baseline_exact_repeat_fraction": 0.013568239795918367
},
"2": {
"events": 40,
"median_baseline_abs_increment_counts": 21.0,
"gate_0_5_to_2ms_normalized_increment_median": 265.86692176870747,
"gate_0_5_to_2ms_normalized_increment_q25_q75": [
171.7729591836735,
305.0119047619048
],
"gate_exact_repeat_fraction": 0.0001255580357142857,
"baseline_exact_repeat_fraction": 0.014198022959183673
}
},
"absolute_response": {
"1": {
"peak_of_median_absolute_eeg_uv": 0.9748096368750749,
"peak_time_ms": 5.75,
"median_abs_baseline_uv": 0.8516469780279666,
"last_time_median_response_exceeds_5uv_ms": null
},
"2": {
"peak_of_median_absolute_eeg_uv": 988.5304132286383,
"peak_time_ms": 0.5,
"median_abs_baseline_uv": 0.8240494192862995,
"last_time_median_response_exceeds_5uv_ms": 2.0
}
}
},
{
"amplifier_details": "(sendCommand_return (status complete) (amp_details (serial_number 0001) (amp_type NA500) (legacy_board false) (packet_format 2) (system_version 0.4.9) (fpga_version 0.6.1.f0) (pcb_version 4.1.0.0) (number_of_channels 256) (feature_flags 0))",
"complete": true,
"capture_errors": [],
"sample_count": 115992,
"bytes": 146613888,
"requested_rate_hz": 4000,
"blocks": [
{
"block": 1,
"mode": 1,
"sent": 10,
"events": 10,
"samples": 24144,
"usable_epochs": 10,
"gate_normalized_increment": 1.0050112930547714,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
},
{
"block": 2,
"mode": 2,
"sent": 10,
"events": 10,
"samples": 24136,
"usable_epochs": 10,
"gate_normalized_increment": 226.27023809523808,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
},
{
"block": 3,
"mode": 2,
"sent": 10,
"events": 10,
"samples": 24072,
"usable_epochs": 10,
"gate_normalized_increment": 267.8337585034013,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
},
{
"block": 4,
"mode": 1,
"sent": 10,
"events": 10,
"samples": 24144,
"usable_epochs": 10,
"gate_normalized_increment": 1.0616883116883118,
"counter_discontinuities": 0,
"median_timestamp_step_us": 250.0,
"timestamp_discontinuities": 0
}
],
"usable_epochs": 40,
"useful_channels": 256,
"plotted_channel": 231,
"overall_epoch_rail_fraction": 0.0,
"modes": {
"1": {
"events": 20,
"median_baseline_abs_increment_counts": 22.0,
"gate_0_5_to_2ms_normalized_increment_median": 1.0553359683794468,
"gate_0_5_to_2ms_normalized_increment_q25_q75": [
0.9318181818181819,
1.1002628324056896
],
"gate_exact_repeat_fraction": 0.012388392857142856,
"baseline_exact_repeat_fraction": 0.01329719387755102
},
"2": {
"events": 20,
"median_baseline_abs_increment_counts": 20.5,
"gate_0_5_to_2ms_normalized_increment_median": 236.04183673469387,
"gate_0_5_to_2ms_normalized_increment_q25_q75": [
189.994489063568,
304.6768707482993
],
"gate_exact_repeat_fraction": 0.0017578125,
"baseline_exact_repeat_fraction": 0.014182079081632652
}
},
"absolute_response": {
"1": {
"peak_of_median_absolute_eeg_uv": 1.0938668737606123,
"peak_time_ms": 1.5,
"median_abs_baseline_uv": 0.8641913229105427,
"last_time_median_response_exceeds_5uv_ms": null
},
"2": {
"peak_of_median_absolute_eeg_uv": 1048.3299895208709,
"peak_time_ms": 0.5,
"median_abs_baseline_uv": 0.8188036023354046,
"last_time_median_response_exceeds_5uv_ms": 2.75
}
}
}
]
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion mock/include/NA500Server.h
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ class NA500Server {
std::atomic<bool> stopping_{false};
std::atomic<bool> streaming_{false};
std::atomic<bool> dinEnabled_{false};
std::atomic<bool> bncInEvents_{false}; // cmd_SetBncInMode 1; reset when the session ends
std::atomic<bool> bncInEvents_{false}; // cmd_SetBncInMode 1 or 2; reset when the session ends
// BNC out: cmd_SetBncOutMode 1 (manual) arms cmd_SetTriggerBncManualOut;
// reset when the session ends, like the BNC input. Each pulse is looped back to the BNC input,
// as if a cable joined the two, so it shows up in the data stream.
Expand Down
8 changes: 4 additions & 4 deletions mock/src/NA500Server.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ std::vector<std::string> NA500Server::execute(const std::string& name, long long
return {OK};
}
if (name == "cmd_SetBncInMode") {
bncInEvents_ = value == 1;
bncInEvents_ = value == 1 || value == 2;
return {OK};
}
if (name == "cmd_SetBncOutMode") {
Expand Down Expand Up @@ -382,9 +382,9 @@ void NA500Server::streamLoop() {
// drive is on (the NA500 impedance state runs with it off).
std::fill(std::begin(packet.eegData), std::end(packet.eegData), -8388608);
}
// BNC in (event mode) reports a 1 ms event at each rising edge; the mock
// drives it from the test-jig pulse that also pulls DIN 1 low, and from
// BNC out pulses (looped back).
// BNC in (event or TMS blanking mode) reports a 1 ms event at each
// rising edge; the mock drives it from the test-jig pulse that also
// pulls DIN 1 low, and from BNC out pulses (looped back).
const uint16_t din = packet.digitalInputs;
const bool bncOutPulse = bncOutPulses_.exchange(0) > 0;
if (bncInEvents_ && (((prevDin & 1) && !(din & 1)) || bncOutPulse)) {
Expand Down
Loading
Loading