Contributions:MicroLeadsADC

Introduction

MicroLeadsADC is a source module that allows for utilization of the Micro-Leads StimZ recording and stimulation device within BCI2000.

Versioning

Authors

• Dhruva Mehta (mehta@neurotechcenter.org)

Version History

• 2/10/2023 Initial Creation and Setup

Source Code Revisions

• Initial development:
• Tested under:
• Known to compile under:
• Broken since: --

Using the MicroLeads ADC

To use the MicroLeads ADC, you will need to have been provided with the basic hardware from Micro-Leads. Below we will go over the mandatory and optional hardware/software parts necessary to ensure a smooth use of the MicroLeads ADC.

Setting up the Hardware

Included Hardware

The following is a list of the hardware that should have been provided to you:

• Wireless Implant
  • This is the implantable device that can record and stimulate wirelessly.
• Powerpad with power cable
  • This is the device that allows for wireless charging of the implantable device.
• Basestation with power cable
  • This is the device that communicates with the implant and the powerpad by sending commands, receiving information and data, and then relaying it to the router.
• Wireless Router with power cable
  • The router is require for creating an ethernet sub-network for base station ethernet communication
• Two Ethernet cables
  • Required to connect the basestation to the router and the router to the computer.
• Ethernet to USB adapter
  • Optional adapter if the computer you are using does not have an ethernet port. Will be needed for verification with the Micro-Leads provided laptop.
• Laptop with Micro-Leads Interface Software
  • This laptop should have the interface executable to use for initial device verification. It should also have the ***stimZ_config.ini*** that has the device information and properties.

Below are figures detailing what each device looks like with labels.

Hardware Setup

• 
  Figure 1: Hardware Setup Overview

Considering how many cables and devices there are, it is helpful to have a step-by-step procedure to ensure that everything is set up smoothly.

Laptop

The first thing to set up is the laptop. Ensure that the laptop charger is plugged into an outlet and that the charger is plugged into the laptop.

Router

The next step is to set up the router.

First, plug the power adapter for the router into an outlet and then plug the power adapter into the router. Ensure that the router turns on.

Next, plug the ethernet to USB adapter into an open USB port on the laptop.

Finally, we will use one of the ethernet cables to connect the router and the laptop. Plug one end of the cable into the open port on the ethernet to USB adapter. Plug the other end of the cable into one of the 4 available black ports on the router. Do not plug it into the blue port.

Basestation

Next we will set up the basestation.

First, ensure that the antenna is securely attached to the basestation. Use the shorter antenna.

Next, plug the power adapter into the outlet and then into the micro-usb port of the basestation.

Finally, we will use the other ethernet cable to connect the router to the basestation. Plug one end of the cable into the open ethernet port on the basestation. Then, similarly to the previous step, plug the other end of the cable into one of the 3 remaining available black ports on the router. Once again, do not plug it into the blue port.

Powerpad

Next we will set up the powerpad.

First, screw the power adapter onto the powerpad, ensuring that it is tightly attached.

Next, plug the power adapter into a wall outlet.

Test to see if the powerpad turns on by pressing the rubber power switch located on one of the short sides of the pad. The switch should light up blue when it is on. A square should also light up green, located to the left of the switch and the right of the location to screw the power adapter on.

Finally, attach the longer antenna to the powerpad by screwing it on.

With this, your initial setup should be complete! You should keep the powerpad and implant decently close to the basestation to ensure proper communication, but they don't need to be right next to each other.

• 
  Figure 2: Example setup

System Level Setup

This section is only relevant to users with multiple devices.

The Micro-Leads system has capabilities for multiple device integration. You would follow the same steps as previous for each device.

However, there are limitations to the system overall when using multiple devices:

• There can only be one router per laptop at a time.
• There can only be one basestation per router at a time.
• A basestation can connect to up to 7 powerpads simulataneously.
• A basestation can connect to up to 7 implants simultaneously.
• A powerpad can connect to only one basestation at a time.
• An implant can connect to only one basestation at a time.
• A basestation can only stream recording data from one implant at a time.
• When a basestation is streaming recording data, it cannot communicate with any other powerpads or implants.
• Two implants cannot share the same frequency/channel.

In essence, if you would like to stream recording data for multiple devices at once you need another full setup. This is because a basestation can only stream recording data from one implant at a time.

Otherwise, you may just need more powerpads and implants if you would like to switch between which device you are streaming recording data from.

Currently, MicroLeads ADC only supports one hardware setup at a time. However, if you have multiple hardware setups, you can still use BCI2000 with each. You would just need to have a PC with BCI2000 installed for each of them.

Verifying with Micro-Leads Software

At this point, all of the hardware should be set up to allow for communication and verification.

Initial Setup

First we will open up the interface executable on the provided laptop. This may be called Stim-Z-GUI or RHD2000Interface.

You should now see a GUI that looks similar to this:

• 
  Figure ?: Hardware Setup Overview

Next, we will connect to the basestation. Click the pulldown menu that says "Select Base Station", and then click connect once you have it selected.

Next, click on the button in the lower left corner that says "Select Devices". A pop-up menu should appear that looks like this:

• 
  Figure ?: Hardware Setup Overview

In this menu, select the devices on the left and click the middle arrow button. The devices should appear in the columns on the right like this:

• 
  Figure ?: Hardware Setup Overview

Click "Confirm" to close the pop-up.

Next, click the "Pair Devices" button. Another pop-up menu should appear that looks like this:

• 
  Figure ?: Hardware Setup Overview

On this menu, click the box labeled "Enable Charging". Then click "Scan". The scan will take a few seconds and take multiple tries to discover all devices. Discovered devices will be highlighted green while unverified devices will show up as red. If your implant has no charge, it may show up red for some time. In this case, you will need to charge the device which is discussed here.

At this time, you should be able to test your implant device.

Charging the Device

First, we will make sure that the device is charged. There are two ways to do this. The first way is through the Micro-Leads GUI while the second one is through the Micro-Leads Python API.

Proper Charging

To ensure that the implant will be charging properly, make sure that the device is positioned as shown in the following diagram:

• 
  Figure ?: Hardware Setup Overview

There may be dead zones on the powerpad, so there might be some trial and error required for optimal placement.

Micro-Leads GUI

In the Micro-Leads GUI, click on the "Charge All" tab. Here, you can charge the devices that are connected to the base station. To do this, click "Start Monitor".

You should be able to hear a dull whirring noise from the powerpad if it is charging your device.

Clicking on a device will query its statement of health.

There is a bug where sometimes the powerpad stops charging, despite showing it is within the GUI. If that happens, click "Stop Monitor" and "Start Monitor" again. This may require some supervision as a result. If you have access to the Python API, however, there is a method to make sure the powerpad continues to charge, described next.

Python API

If you have access to the Python API, you can use a Powershell script to ensure charging. You must also have

First, make sure that the wheel file you received is installed in a python environment properly.

Next open a Powershell terminal and navigate to your python environment. You will need to know the address and channel for the powerpad. This can be found from the config.ini file. Details on where to find that are here

Run the "charge enable" function. An example looks like this:

python -m stimZscripts.example_charge_enable -a 192.168.1.10 -z 10 -c 70

Next, we will be running a script that queries "statements of health" from the powerpad. This is required because if a statement of health is not queried within a certain time period, the powerpad will turn off. And example of this script is shown below:

for ($je1; $j -le 100; $j++) {
python -m stimZscripts.example_soh -a 192.168.1.10 -z 10 -d powerpad -c 70
Sleep(60);
}

Verifying Device Properties

To verify the device works properly, we need to test the leads. I used an oscilloscope and breadboard to test, but you may use another method if you wish.

First I will discuss the device layout and the leads themselves.

The top of the device has the white leads to the right of the blue leads. The bottom will show an inverse. It should match the following image:

• 
  Figure ?: Device Orientation

Next, we will identify the electrodes. The white wires correspond to "ENG0/Stim0" and "EMG0". The blue wires correspond to "ENG1/Stim1" and "EMG1". The ENG/Stim wires are connected to 300 micrometer bipolar cuff electrodes. EMG1 is connected to a bipolar EUS electrode while EMG0 is not connected.

Note: The wires haven't been labeled by Micro-Leads. Determining which wire corresponds to which channel, as well as which wires are the reference wires will need to be determined through trial and error.

Once you have determined which wires correspond to which channel, we can test them to confirm they work properly.

I used a Tek-tronic Oscilloscope to verify the stimulation output matched the parameters set in the MicroLeads GUI

How to set up with BCI2000

Now we will set up the research PC. First, follow the BCI2000 installation guide found here

Creating a Batch File

Although it is not necessary, it is convenient to create a batch file to run BCI2000 with the MicroLeadsADC. To create the batch file, start out with a copy of a suitable batch file in BCI2000/batch/, and open it in a text editor.

Towards the end of the file, you will see a sequence of lines beginning with

start executable 

These lines are responsible for starting up source, signal processing, and application module, in that sequence. To use the MicroleadsADC module, you will need to replace the executable name in the first entry, e.g.

start executable SignalGenerator --local

becomes

start executable MicroLeadsADC --local

For more information, see this page.

Using MicroLeads ADC

To set up your experiment using BCI2000, there are a list of parameters that you may set during configuration.

First you will need to locate the configuration file on the laptop provided to you by MicroLeads. Navigate to the GUI configuration file, located at <user>/AppData/Roaming/RHD2000interface/config/stimZ_config.ini. Here you will see a list of configurations for the various devices in the system.

The file should look like this:

• Figure ?: Device Orientation
  Figure ?: Device Orientation

Specifically look for the sections for the "PowerPad" and the "Remote". For each of these, note down the "stimZ_addr" and the "radio_addr". These will be used for BCI2000.

Once you have started compiled the MicroLeadsADC module, you can begin collecting data with BCI2000 by following the steps below.

1. Double click BCI2000/batch/DummyApplication_MicroLeadsADC.bat - the batch file that was created in the previous section - to start BCI2000.
2. Click the "Configure" button.
3. Set the appropriate parameters. The MicroLeadsADC module is initialized with a number of parameters that can be configured from the "Source" tab. A summary and description of these parameters can be found below. Importantly, make sure to enter the numbers that you noted down from the previous step for the corresponding device!

• Figure ?: Device Orientation
  Figure ?: Device Orientation

1. Click "Set Config".
2. Click "Start" to begin your experiment.

Understanding how it works

Communication Protocol

Communication between the various devices in the MicroLeads system is governed by the basestation. The base station will initiate Stim-Z wireless communications, while the implants and chargers respond to the commands they received from the base station. For any data to be transferred, the basestation must request it from the respective device; no unsolicited information will be transmitted.

To facilitate this, 3 different ports are used. The command packet relay is done through TCP port 3031, while data streaming is done through UDP ports 2020 and 2323. UDP port 2323 is used to listen for a data streaming request while UDP port 2020 is the port that data is sent to.

Command Packet Structure

Commands are sent in a specific structure. They consist of a four-byte packet header, followed by a data payload, followed by a packet ender.

Header

Byte[0]: Start byte, value is always 0x7e
Byte[1]: OP byte (packet type).  Range is 0x00 to 0xff
Byte[2]: Sequence/Address byte.
Byte[3]: Packet data payload length in bytes.

Data

The data payload structure depends specifically on the packet type. If you need to manipulate this during debugging, please refer to the Stim-Z_API provided by MicroLeads.

Ender

The ender for commands is calculated from the following CRC8 polynomial

x^8 + x^7 + x^6 + x^3 + x^2 + 1

The second byte is always 0x0a.

Data Packet Structure

Similar to the command packets, data packets also have a specific structure, consisting of the following:

Header:  4 bytes
Payload: 960 + 8 + 16 = 984 bytes
CRC:     4 bytes

Header

The header matches the same specification of the command packet. However, importantly, the second byte indicates the FEC decoder status of the packet:

0x40: The FEC decoder marked the packet bad (undecodeable)
0x20: The FEC decoder corrected bits in the packet and got a valid checksum
0x10: The FEC decoder corrected bits in the packet, but the packet checksum is still bad

Data

The data payload includes 960 bytes of recording data and 24 bytes of out-of-band data.

The 960 bytes of recording data are split into 160 smaller tuples like so:

sample[0]: ENG0 sample
sample[1]: EMG0 sample
sample[2]: ENG1 sample
sample[3]: ENG0 sample
sample[4]: EMG1 sample
sample[5]: ENG1 sample

Since the ENG channels record at twice the frequency of the EMG channels, there are twice as many samples. The OOB data has not been implemented with BCI2000.

Debugging

Debugging with the MicroLeads system is a relatively straightforward process. This section assumes that you have API access and the documentation provided from MicroLeads.

First, please make sure that the devices are functioning properly with the MicroLeads software and that the device issue lies with BCI2000 rather than an error within the device or experiment implementation.

Next, download Wireshark on your research PC here. Wireshark is a network protocol analysis tool that we will use to analyze the commands that are sent from the basestation through BCI2000 as well as verify that we are receiving data.

Now open up Wireshark and click on the Ethernet network, shown below:

• Figure ?: Wireshark Main Page
  Figure ?: Wireshark Main Page

Run through BCI2000 process.

Analyze packets and make sure that header and data payloads make sense

Check to see if data is being received on UDP port 2020.

Can create separate files to test other functions if necessary for your experiment.

Parameters

SourceCh

The total number of digitized and stored channels. Because of device limitations, this is set to 4 channels explicitly.

SampleBlockSize

Samples per channel per digitized block. Together with the sampling rate, this parameter determines how often per second data are collected, processed, and feedback is updated. For example, at 1000 Hz sampling and a SampleBlockSize of 20, the system (e.g., source signal display, signal processing, and stimulus presentation) will be updated 50 times per second.

SamplingRate

The sample rate of the system. This parameter cannot be edited, and will default to the sampling rate available from the implant which is 21500 Hz. In case you are experiencing problems by higher sampling rates (e.g., data loss, jerky display, etc.), increase the SampleBlockSize so that you are updating the system less frequently (usually, updating the system 20-30 times per second is sufficient for most applications).

SourceChOffset

Offset for each channel.

SourceChGain

Gain for each channel.

ChannelNames

Names of each channel.

ReferenceCh

This list defines what channels will be used as reference. This list is uploaded to the device and set in hardware, effecting the raw bio-signal data that is recorded by BCI2000. If you do not want to effect the raw bio-signal data that is recorded, you can use the spatial filter. If this parameter is set to auto, no reference channels are used.

Device Parameters

These parameters can be found in the "Device Settings" tab of the BCI2000 config window. These settings are provided to you from MicroLeads and are set for each device.

Implant StimZ address

This parameter sets sets the StimZ address of the implant for use with BCI2000. This parameter is necessary to ensure that commands sent through BCI2000 are actually sent.

The possible values for this parameter are 0-13, and it will not be the same as the Powerpad StimZ address.

Powerpad StimZ address

This parameter sets sets the StimZ address of the powerpad for use with BCI2000. This parameter is necessary to ensure that commands sent through BCI2000 are actually sent.

The possible values for this parameter are 0-13, and it will not be the same as the Implant StimZ address.

Implant Radio Frequency Channel

This parameter sets sets the radio frequency channel of the implant for use with BCI2000. This parameter is necessary to ensure that commands sent through BCI2000 are actually sent.

The possible values for this parameter are 10, 20, 30, ... 80, and it will not be the same as the Powerpad Radio Frequency Channel.

Powerpad Radio Frequency Channel

This parameter sets sets the radio frequency channel of the powerpad for use with BCI2000. This parameter is necessary to ensure that commands sent through BCI2000 are actually sent.

The possible values for this parameter are 10, 20, 30, ... 80, and it will not be the same as the Implant Radio Frequency Channel.

Stimulation Parameters

These parameters can be found in the "Stimulation" tab of the BCI2000 config window.

Enable STIM0

This parameter enables/disables stimulation for the STIM0 channel.

Enable STIM1

This parameter enables/disables stimulation for the STIM1 channel.

Enable Recording

This parameter enables/disables streaming of neural data.

Supply Voltage

This parameter sets the supply voltage from a range of 4V to 9V. When the user is recording only, the voltage must be 4V. When the user is stimulating at all, the voltage must be 9V.

Stimulation Pulse Settings

This group of parameters define the shape of the charge balanced stimulation pulses, as described in Fig 1. Limitations will be detailed for each parameter. [[File: |600px|thumb|center|upright=2.5|Figure 1. Pulse definition]]

Phase1 Duration

This parameter sets the length of the Phase 1 Duration in counts of 11.6 microseconds. To obtain the proper value, divide your duration by 11.6 microseconds.

Interphase Duration

This parameter sets the length of the Interphase Duration in counts of 11.6 microseconds. To obtain the proper value, divide your duration by 11.6 microseconds.

Phase2 Duration

This parameter sets the length of the Phase 2 Duration in counts of 11.6 microseconds. To obtain the proper value, divide your duration by 11.6 microseconds.

Phase1 STIM0 Amplitude counts

This parameter sets the Phase 1 amplitude for the STIM0 channel in counts of 10 microAmps. To obtain the proper value, divide your amplitude by 10 microAmps.

Phase1 STIM1 Amplitude counts

This parameter sets the Phase 1 amplitude for the STIM1 channel in counts of 10 microAmps. To obtain the proper value, divide your amplitude by 10 microAmps.

Phase2 STIM0 Amplitude count

This parameter sets the Phase 2 amplitude for the STIM0 channel in counts of 10 microAmps. To obtain the proper value, divide your amplitude by 10 microAmps.

Phase2 STIM1 Amplitude count

This parameter sets the Phase 2 amplitude for the STIM1 channel in counts of 10 microAmps. To obtain the proper value, divide your amplitude by 10 microAmps.

Charge Recovery Counts

This parameter sets the length of the Charge Recovery Duration in counts of 11.6 microseconds. To obtain the proper value, divide your duration by 11.6 microseconds.

Stim Period Counts

This parameter sets the length of the Stim Period Duation in counts of 11.6 microseconds. To obtain the proper value, divide your duration by 11.6 microseconds.

ADC Gain

This parameter sets the ADC Gain. When recording only, set the parameter to 0. When stimulating, set the parameter to 1.

Exfil_Iface

This parameter sets the exfil settings. When recording only, set the parameter to 2. When stimulating, set the parameter to 0.

See also

User Reference:Filters, Contributions:ADCs