ezmsg.blackrock

Interface for Blackrock Cerebus ecosystem (incl. Neuroport) using pycbsdk

NOTE: Currently only supports spikes, but a PR for continuous data as ezmsg.util.messages.axisarray.AxisArray wouldn't be a heavy lift and a readily accepted PR :D

Installation

pip install git+https://github.com/CerebusOSS/ezmsg-blackrock

Dependencies

• pycbsdk, which requires Python >=3.9
• ezmsg-sigproc

Setup (Development)

1. Install ezmsg either using pip install ezmsg or set up the repo for development as described in the ezmsg readme.
2. cd to this directory and run pip install -e .
3. Blackrock components are available under import ezmsg.blackrock

Setup Notes

IMPORTANT NOTE: pycbsdk is only compatible with Central Neuroport/Cerebus Suite/NSP Firmware 7.0.6+, built using cbhwlib/hardware library/network protocol 3.11+. Anything older is not supported by pycbsdk. Check this requirement in Central by navigating to Help > About Central

Blackrock Neuroport/Cerebus uses UDP multicast traffic to deliver upwards of 30000 packets/sec of data with low latency. There are better ways to do this now, but back when this hardware was made, the engineers were dealing with the limitations of the hardware they had. UDP comes with no packet delivery guarantee, but dropped packets can be catastrophic when interfacing with the Blackrock hardware. As such, do your best to locate the highest quality networking equipment you can find, and have a high tolerance for blaming ethernet adapters and/or your router/switch for errors during troubleshooting.

The NSP startup procedure involves blasting several thousand UDP packets from the NSP to the interfacing computer in a few milliseconds. Many low-quality adapters and network switches will simply drop some of these UDP packets, but this will result in errors during startup.

Hardware Setup

This setup describes a setup with a Legacy NSP, a Windows PC (called "Central PC") running Central Suite that can configure the NSP, and a third machine (Windows, MacOS, or Linux) that will be running ezmsg-blackrock, henceforth forward referred to as the "Client PC". The documentation highlights the differences when using Blockrock's newer ("Gemini") NSP and Hubs.

Central cannot run on the same PC simultaneously as ezmsg-blackrock because pycbsdk exclusively binds the port that central would use to communicate with the NSP. The NSP has too many settings to implement in ezmsg-blackrock, so in practice, we use Central to configure the NSP then acquire live data thereafter. If you want to, you can use ezmsg-blackrock on the Central PC once you've configured the NSP and closed Central. When you do this, the Central PC and the Client PC are the same PC/IP address. Its assumed that this PC is running windows because Central Suite is only available on Windows.

Find the highest quality ethernet (yes, wired) network switch or router that you can. Look for 1+ Gigabit speed ratings (2.5 Gigabit better, 10 Gigabit is best), and features like QoS (Quality of Service) that can guarantee packet delivery. Ensure both the Central PC and the Client PC have high quality ethernet network adapters. Not every ethernet adapter will work, due to packet buffering requirements. High quality ethernet cables are also important; aim for Cat6E or better.

1. Attach the NSP, Central PC, and Client PC to the router or switch using ethernet cables.
2. Blackrock NSP and Gemini Hubs use hard-coded static IP addresses.
   • If using a router (recommended), configure the router to sit at 192.168.137.254 and configure static DHCP assignments (mapping adapter MAC addresses to preset IP addresses) for:
     • NSP (Legacy or Gemini) -- 192.168.137.128
     • Gemini Hub1 -- 192.168.137.200
     • Gemini Hub2 -- 192.168.137.201
     • Central PC -- 192.168.137.1 (Central likes to run on IP addresses below 192.168.137.16)
     • Client PC -- 192.168.137.32 (Arbitrary address within subnet)
   • If using a network switch, configure the network adapters on the Central PC and Client PC to the aforementioned IP addresses
3. At this point, it's handy to make sure you can ping the NSP and Client PC from the Central PC and that you can ping the NSP and the Central PC from the Client PC. Adjust firewall settings accordingly, enabling multicast UDP traffic on the ethernet adapters, and all TCP/UDP traffic on ports 51001 and 51002.
4. Download and install the Central Suite on the Central PC from the Blackrock Support site:
   • The public "Cerebus Central Suite" will not function with the FDA approved Neuroport system, which will instead require the "Neuroport Central Suite". Acquiring this installer will require you to submit a ticket to Blackrock Support because the download is NOT public.

Emulate an NSP (Useful for development without an NSP)

It is possible to emulate Blackrock hardware while playing back previously recorded data using a software tool called "nPlayServer". The publicly-available and supported nPlayServer is only available on Windows but unsupported Mac and Linux binaries (x86 or ARM) are available. Open an issue to ask.

1. Power down the NSP if you already have it on the switch/router.
2. Download and extract the "Real Sample Data" from the Blackrock Support site. Extract the *.ns6 file somewhere memorable in the filesystem (like Documents)
3. Run nPlayServer. On Windows, use the nPlayServer shortcut on the desktop to start Central and use the nPlay control window to navigate to the *.ns6 file directory, select the file to replay, and start replaying it. Then close Central/nPlayServer. This is important for using the -L flag with nPlayServer.exe later.
4. Navigate to the installation directory (e.g., "C:\Program Files\Blackrock Microsystems\Cerebus Central Suite") and locate the nPlayServer.exe executable. Right click it and create a shortcut on the desktop.
5. Rename the shortcut to "Simulate NSP" or another friendly name.

If your intention is to only test on 'localhost' (i.e., ezmsg-blackrock and nPlayServer on the same machine), then there is nothing more to be done. However, if your intention is for the emulation PC to be a different machine than the client PC, nPlayServer must be configured to work over the network.

1. Reconfigure the emulation host PC to have an IP address matching the emulated device (see addresses listed above).
2. Right click the shortcut and go to "Properties". Set the "Target" line to: "C:\Program Files (x86)\Blackrock Microsystems\Neuroport Central Suite\nPlayServer.exe" --network bcast=192.168.137.255:51002 --network inst=192.168.137.128:51001 -L, adjusting for the actual install path of your Central suite.
   • bcast address is .255 because that's the UDP multicast address.
   • inst address is .128 to emulate Legacy NSP. See the list above for Gemini hardware. Also, Gemini hardware requires the instrument port to be set to 51002.
   • -L uses the last .nsX file for replay. You can also manually specify an .nsX file for replay, but be aware nothing will replay when using -L if you've never replayed a file using nPlayServer, or if that file has moved or no longer exists.

Software Setup

• Use Central to set up the NSP hardware.
• If running Central and ezmsg-blackrock on the same PC, shut down Central
• Assuming pycbsdk is installed in your python environment (which it should be, considering it's a dependency of ezmsg-blackrock that automatically gets installed with a pip install -e .), you should have the pycbsdk_print_rates command on your path. Test the connection and hardware/software setup using pycbsdk_print_rates --inst_addr 192.168.137.128 --inst_port 51001 --protocol 3.11
  • Note that this command line is for Legacy NSP with hard-coded address 192.168.137.128 running on port 51001
  • Also note that network protocol is not automatically detected. Our old hardware can only be updated to firmware 7.0.6 which uses hardware library/protocol 3.11. This can be checked by opening Central and navigating to "About Central" which will tell you which hardware library the firmware is running (assuming your NSP's firmware and Central version match). As of this writing, most Gemini hardware should be using protocol 4.1 (default).

Troubleshooting

• When in doubt, restart equipment.
• Try software multiple times. If you get different results every time you run, you might have ethernet adapters/network equipment of insufficient quality (it might be dropping packets, especially during configuration).
• Make sure the Central PC and the Client PC can ping each other and the NSP.
• Ensure NSP Firmware matches Central version.
• Ensure the protocol version you specify matches the firmware's protocol version.
• pycbsdk_print_rates and Wireshark + a dissector are your friends. Godspeed.