Troubleshooting

Start with the symptom that best matches what you see. Change one thing at a time, then repeat the same test so you know which change fixed the problem.

Quick Diagnostic Sequence

1. Disconnect external projects. Test with only the Knight Board, supplied USB cable, headset electrodes, and ear clip connected.

2. Confirm the serial device. Connect the board and identify the new port in the EXG Visualizer or your operating system.

3. Use one program at a time. Close other visualizers, BrainFlow scripts, serial monitors, and LSL applications that might hold the port.

4. Test one known channel. Use the common reference montage, move that channel’s switch away from the header, enable it at gain 12, and add it to RLD with the required command delays.

5. Verify contact. Secure the headset, part hair beneath the dry spike, and attach the ear clip to prepared skin.

6. Run the jaw-clench test. A clear transient confirms that the electrode, channel path, reference, and stream can detect a large biopotential signal.

If the single channel works, add the remaining channels one at a time. This separates a connection problem from a specific electrode, cable, or channel.

Board Is Not Detected

Symptoms: no new serial port appears, the EXG Visualizer port list does not change, or BrainFlow reports that the port cannot be opened.

1. Disconnect and reconnect the USB-C cable, then refresh the port list.
2. Try another USB port directly on the computer rather than an unpowered hub.
3. Try a known data-capable USB cable. Some USB-C cables supply power only.
4. Confirm the controller board is fully seated and locked into the Knight Board.
5. Close every other program that may be using the serial port.
6. On Windows, compare Device Manager before and after connecting the board.
7. On Linux, confirm your user has permission to access the /dev/ttyACM* or /dev/ttyUSB* device. Log out and back in after changing group membership.
8. On macOS, use the /dev/cu.* device corresponding to the board.

If the board appears on another computer, the issue is likely the original computer’s cable, USB port, permissions, or software configuration.

The Port Exists but Connection Fails

Symptoms: prepare_session() raises a serial or board-session exception, or the visualizer disconnects immediately.

• Confirm that the configured serial port exactly matches the current device. Port numbers can change after reconnecting.
• Select BoardIds.NEUROPAWN_KNIGHT_BOARD for the standard board or BoardIds.NEUROPAWN_KNIGHT_BOARD_IMU for the IMU variant.
• Do not run the EXG Visualizer and a BrainFlow script simultaneously.
• Remove custom BrainFlowInputParams values until only serial_port remains.
• Power-cycle the board, wait for the serial port to reappear, and retry.
• Enable BrainFlow logging to capture the underlying error:

from brainflow.board_shim import BoardShim

BoardShim.enable_dev_board_logger()

When requesting support, include the final relevant logger lines rather than the entire log.

Connected, but EEG Is Empty or Flat

The board can transmit packets while all EEG channels remain disabled. A valid connection alone does not activate the signal inputs.

Verify all four requirements:

1. The desired physical channel switch is away from the header for a common reference montage.
2. The electrode is connected to that channel’s positive (P) input.
3. The reference electrode is connected to COMM.
4. A chon_{channel}_{gain} command is sent after start_stream().

Use a delayed startup sequence:

import time

board.start_stream()
time.sleep(2)

for channel in range(1, 9):
    board.config_board(f"chon_{channel}_12")
    time.sleep(1)
    board.config_board(f"rldadd_{channel}")
    time.sleep(1)

Caution

Commands sent back-to-back can be silently dropped. If some channels are absent, repeat the startup sequence with pauses before changing the wiring or replacing hardware.

Only One or Two Channels Are Missing

Swap components methodically:

1. Move a working electrode cable to the failing channel input.
2. Move the failing electrode cable to a working channel input.
3. Repeat the same chon_ and rldadd_ sequence with delays.
4. Check that the electrode tip reaches the scalp rather than resting on hair.
5. Inspect the connector and board header for a loose or offset connection.

If the problem follows the electrode or cable, inspect that component. If it stays with the board channel, recheck the physical switch, header position, and software command for that channel.

Signal Is Noisy or Drifts

Start with the signal path before adding filters:

• Part the hair and reseat each dry spike electrode against the scalp.
• Prepare the earlobe and reattach the COMM reference securely.
• Connect RLD and add only the active channels to the RLD network.
• Switch off and disconnect unused channels.
• Support the USB and electrode cables so they do not pull or move.
• Relax the jaw, face, neck, and shoulders during EEG recording.
• Move away from power supplies, AC cables, fluorescent lights, motors, and displays that noticeably affect the trace.
• If using paste or gel, prevent neighboring electrodes from being bridged by excess conductive material.

Large spikes synchronized with blinking, jaw clenching, cable movement, or head movement are usually physiological or motion artifacts, not random electronic noise. Filtering can reduce some frequencies but cannot reconstruct clean EEG hidden by clipping or poor contact.

Strong 50 or 60 Hz Interference

Power-line contamination usually appears as a regular oscillation across several channels.

1. Improve the COMM reference and scalp contacts first.
2. Enable RLD for the active channels.
3. Run the computer from battery temporarily to test whether its charger is the source.
4. Move the setup away from mains cables and powered equipment.
5. Apply a 50 or 60 Hz notch filter only after the physical setup is stable.

Choose the notch frequency used by the local electrical grid. Do not apply both without a specific reason, and remember that a notch filter also removes neural or muscle content near that frequency.

Trace Is Clipped, Flat at a Limit, or Unusually Large

The amplifier or ADC may be saturated. This is common when paste or gel lowers contact impedance while the channel remains at gain 12, or when recording EMG or ECG with an EEG-oriented gain.

1. Reduce gain to 6 or 4 and reconnect the session.
2. Use the same value in BrainFlowInputParams.other_info and the chon_ command.
3. Check for excess paste bridging two contacts.
4. Confirm that electrode leads are connected to the intended positive, negative, COMM, and RLD pins.

params.other_info = '{"gain": 4}'
board.config_board("chon_1_4")

Increase gain only after the unclipped signal has been verified.

Microvolt Values Look Incorrect

BrainFlow scales raw counts using the gain supplied in other_info. The firmware gain applied by chon_ must match it. For example, scaling for gain 12 while the hardware channel uses gain 4 produces incorrect microvolt values.

Also verify that custom parsers:

• decode each channel as a signed 16-bit, big-endian integer;
• use the correct gain in the scale factor;
• synchronize on packet start byte 0xA0 and end byte 0xC0;
• treat BrainFlow output as already converted to physical units.

See Knight Board Data Format before comparing a custom parser with BrainFlow.

Samples Repeat, Disappear, or Arrive in Uneven Blocks

BrainFlow stores stream data in a ring buffer:

• get_current_board_data(N) copies up to the latest N samples without removing them. Overlapping calls naturally contain repeated samples.
• get_board_data() returns available samples and clears them. Calling it in multiple parts of a program can make another consumer see an empty buffer.

For a live sliding window, use get_current_board_data(). For incremental processing, use one owner for get_board_data() and pass each retrieved block to the rest of the application. Do not let several functions independently flush the same board buffer.

An initial request may contain fewer samples than requested because the stream has not been running long enough. Wait for at least one complete analysis window before classifying.

Sample Rate or Timing Looks Wrong

The board supports 125, 250, and 500 SPS, and examples commonly assume the default 125 SPS. Retrieve the configured rate instead of hard-coding it:

sampling_rate = BoardShim.get_sampling_rate(board_id)

For timing-sensitive experiments, inspect the BrainFlow timestamp row. Use the same sample rate, filter design, epoch length, and window length during data collection, model training, and live inference.

IMU Channels Are Missing

Use BoardIds.NEUROPAWN_KNIGHT_BOARD_IMU. The standard Knight Board ID exposes the eight ExG channels but not the accelerometer, gyroscope, or magnetometer rows. Query the relevant BrainFlow channel getters rather than assuming row numbers in application code.

See Knight Board IMU for the current channel mapping.

EXG Visualizer Is Blocked by the Operating System

• Windows: choose More info, verify the downloaded application, then select Run anyway in the SmartScreen prompt.
• macOS: open System Settings → Privacy & Security, find the blocked app, and select Open Anyway after verifying the download.
• Linux: make the downloaded application executable if required by its package format, then launch it from a terminal to see missing-library errors.

Download a fresh copy from the official page if the file is incomplete or the operating system reports that it is damaged.

Download the EXG Visualizer

Python Cannot Import BrainFlow or a Project Module

Activate the same virtual environment used to install the dependencies, then run the command from the repository root:

.\.venv\Scripts\Activate.ps1
python -m pip show brainflow
python your_script.py

Use python -m pip when checking or installing packages so pip and python refer to the same interpreter. For tutorial repositories, the root directory is usually the folder containing the main scripts and local packages.

An LSL Stream Does Not Appear

1. Confirm that the NeuroPawn LSL application is connected to the correct board and actively streaming.
2. Close duplicate outlet applications so stream names are unambiguous.
3. Allow the application through the operating-system firewall on private networks.
4. Run the outlet and inlet on the same computer to separate signal problems from network discovery problems.
5. Check the stream name, type, channel count, and sample rate expected by the receiving application.

If local discovery works but another computer cannot see the stream, check that both devices are on the same network and that client isolation or firewall rules are not blocking LSL discovery traffic.

A Tutorial Model Trains but Fails Live

A successful training command does not prove that the model generalizes. Verify:

• electrode locations and channel order match the calibration session;
• preprocessing, filter bands, sample rate, and window length are identical;
• the user performs the same task used to create the labels;
• the loaded model artifacts came from the current dataset;
• cross-validation or held-out results are reasonable, not only an in-sample training report;
• live windows contain enough new samples before inference begins.

Recalibrate after changing electrode placement, channel order, cue behavior, or preprocessing. Thresholds and smoothing can stabilize a valid model but cannot repair incompatible inputs.

Before Requesting Support

Collect the following information:

• Knight Board variant: standard or IMU
• operating system and version
• application or repository being used
• BrainFlow and Python versions, if applicable
• serial port and selected board ID
• channel wiring, physical switch positions, and electrode montage
• gain in both other_info and chon_ commands
• whether the basic jaw-clench test works
• exact error text and the smallest script that reproduces it

Read the FAQ

Join the NeuroPawn Discord

Contact NeuroPawn

Note

Do not post private recordings, access tokens, personal file paths, or other sensitive information in a public support channel. Share only the minimum log and signal data needed to reproduce the issue.