How to Parse through the Hex Code of BRN Data Files for Troubleshooting File Compatibility

There may be instances where users are unable to load Blackrock data files (.NSx, .NEV) properly in 3rd party software. Using a hex editor to view the files enables users to jump into the files and identify the source of the issue.

For example: A user wants to take an NEV file from their recording and filter the data in Matlab with the help of NPMK (Blackrock's Neural Processing Matlab Kit - Data loader for Blackrock data files in Matlab). After making the necessary edits in Matlab, the user wants to generate a new NEV file which can be uploaded into a spike sorting application (E.g. OFS, Spike2). The new NEV throws issues when uploaded, leading to jumbled, nonsensical data. This is a case where using a hex editor can help resolve the issue.

This guide is applicable for both Blackrock's continuous data files (.NSx - NS1, NS2, ..., NS6) and neural event files (.NEV) 

For Win 10, users can download the HxD Hex Editor from here: Downloads | mh-nexus

For Win 11, users will need to source another free, open source hex editor program online.

Use instructions for use LB-0023 (Research, 2.X file type) as the roadmap through the bytes of files recorded with Central's research (Cerebus) version or CerePlex Direct Central (File Spec 2.1, 2.2, 2.3, and 3.0 covered): LB-0023-Rev-8.docx

Use the instructions for use LB-0110 (Clinical, TOC file type) as the roadmap through the bytes of files recorded with Central's clinical (NeuroPort) version: LB-0110 TOC File Formats (File Spec 3.0) Specifications 7.0

Note: Users will need to source older versions of LB-0110 if parsing through older file specs (2.1, 2.2, 2.3) for the NeuroPort version of Central. Users can contact support@blackrockneuro.com for this resource.

Blackrock's files are formatted in Little Endian

Endian: the order bytes are stored for a multi-byte number.

Big Endian:

1. Most significant byte ("big end") first
2. Example: 0x12345678 → 12 34 56 78
3. Feels natural to humans (left to right, highest to lowest).

Little Endian:

1. Least significant byte ("little end") first
2. Example: 0x12345678 → 78 56 34 12
3. Common in CPUs (e.g., x86).

Here is an example NEV file (Research Central, 2.X, File Spec 2.3) opened with HxD Hex Editor:

Make sure the Byte Order (seen in the bottom right corner of the HxD Hex Editor example image) is set to "Little endian".

Steps for reading bytes and headers

1. Use the corresponding instructions for use (IFU) for your specific version of Central (Research/Cerebus or Clinical/NeuroPort) as your guide. The IFU lists each field in order of their appearance in the file. The following example images are of an NEV file with File Spec 2.3 recoded on the Research version of Central (LB-0023).
   
1. 
2. 
2. For the case of the File Type ID (Green, the first 8 bytes in the file), all 8 bytes have values. Some fields reserve more bytes than necessary to convey the necessary data (hence the presence of 00 bytes in some of the fields' reserved bytes). This is to allow extra bytes for future changes to fields.
   
1. See the second field, File Spec. File Spec reserves the next two bytes after the File Type ID field. Looking at the example above, the bytes that are associated with the File Spec are "02" and "03" under the column 08 and 09.
   
2. The third field, Additional Flags, reserves the next two bytes, "01" and "00". The Additional Flags field only requires 1 byte "01", but still reserves the next byte (under column 0B, "00") as future proofing.
   
3. This pattern of fields and reserved bytes continues on as listed in the IFU.
   
3. One of the most critical fields in the basic headers section is the "Bytes in Headers" field. The bytes for this field will point to the offset (see the "Offset (h)" column) created by the headers. As the IFU explains, this value is, "effectively a zero-indexed pointer to the first data packet". If this value is incorrect, third party programs won't be able to properly point to where in the file the neural data actually begins.
   
1. 
2. 
1. Recall that Blackrock data files are formatted in Little Endian. This means that the proper way to read the two bytes corresponding to the "Bytes in Headers" field is "1B D0", not "D0 1B". 

1. Note: Not all fields and/or bytes will have decoded text. 
3. 
1. For File Spec 2.3, the IFU indicates that the last table is TRACKOBJ. Data packets begin after TrackOBJ. In the example above, we see that the Offset (h) value before data packets begin is the same as the "Bytes in Headers" value stored near the beginning of the file.
   
2. Another useful marker for determining where data packets begin is to look at the Decoded text column. Once the decoded text transitions from legible words to "random values" (see horizontal red line in example image above), this indicates that the file has reached the end of the headers section.
   

1. Editing the file:
   
1. If you are making edits to the data file during troubleshooting (e.g. Deleting a duplicate header, adding missing bytes, etc.), you must ensure that the "Bytes in Header" field has the proper byte values to point to where the data packets begin.
   
2. If a third party program is unable to read modified Blackrock data files, it's possible that the headers have been modified. Examples include but are not limited to:
   
1. Byte values for one or more fields were changed unintentionally
   
2. Unintended header information was added or removed (e.g. A script modifies a users' BRN data files)
   
3. Data savvy users can compare a modified, "nonfunctional" file with a control, "functional" file to see what values were changed

Fixing Extended Headers with Hex Editor

In certain versions of Central, namely 7.5.x, the extended headers are not correctly populated for each file. This causes errors when loading the data due to the missing information.

To start this process, copy any files you intend to edit. You should always keep backups of any in-process files until you verify that you correctly fixed the extended header. Editing hex can seriously corrupt files, and is not always easily reversible.

Then you will need to record a file in a working version of Central. This file is where you copy the correct extended header information.

Next, you need to determine how many channels your file with missing extended headers has. This will be the number of channels' worth of extended headers you copy from the good file. The image below shows the start of an extended header at 43 43. 43 43 translates to CC, which you can reference in the Blackrock File Formats IFU in "Table 3-21: CC". These "CC" values are what separate each channel's location.

Copy the number of headers from your good file by dragging from the first 43 43 until the end of the last 43 43, but not including it. As you drag, count the number of "CC" sections you are grabbing on the right.

The last thing you will do is go back to your bad file and paste in the hex from the working file. You do this by making sure you are in insert mode and then pasting immediately after the hex that says channel count. In the example below, the 40 in 40 00 00 00 shows the channel count, and immediately after is where the extended headers need to be inserted. You can do this by selecting the 01, and it will paste to the left. 

40 in hex is 64 in decimal

Once you have pasted in the extended headers for all of your channels, they should load normally in NPMK.

• Related Articles

• nPlay Troubleshooting Guide

  Attached to this article is a PDF detailing troubleshooting steps regarding nPlay connectivity. If none of these tips are able to help resolve your issue, please send in an email to support@blackrockneuro.com to receive further assistance with your ...

• Loading Blackrock Event and Continuous Data Files into Plexon Offline Sorter (POS or OFS)

  Installation Note: Version 4.0+ of offline sorter can natively load .NEV files, so the steps below do not need to be followed. Note: Plexon's offline sorter is not compatible with Blackrock's File Spec 3.0 (Available on Central version 7.5.0 and ...

• NEV and NSx File Specifications

  See the attached PDF for the current file specifications. Below you'll find a screenshot of our short summaries for the currently available file specifications in Central 7.0.6:

• MATLAB Interfaces For Blackrock Microsystems Data Acquisition Systems

  Introduction Blackrock has several functions for looking at and interacting with data collected through our neural signal processors. These functions are available for post-recording processing (Neural Processing MATLAB Kit - NPMK) or for interacting ...

• Concatenating segmented files in NPMK

  Occasionally during recording sessions, users may encounter brief packet loss or they may pause and resume file recording themselves. When this happens, Central File Recording will write a new header to the file, causing the data to become segmented ...