Contributions:MicroLeadsADC
Introduction
MicroLeadsADC is a source module that allows for utilization of the Micro-Leads StimZ recording and stimulation device within BCI2000.
Video Overview
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: --
Known Issues
There are a few known issues with the MicroLeads device system.
Sometimes when the device has been commanded to stop recording or stimulating, further commands to it will not work as the device is unresponsive. The solution for this has been to let the device lose power completely, and then recharge it.
There are some issues with getting consistent data from stimulation. At times, the stimulation will abruptly stop as well. When using the associated GUI from MicroLeads, this was usually accompanied by a "Compliance" error.
Communication for commands is not consistent either. It may take several attempts to get the device to start working.
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
-
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.
-
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:
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.
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:
Click "Confirm" to close the pop-up.
Next, click the "Pair Devices" button. Another pop-up menu should appear that looks like this:
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 next.
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:
-
Charging Position Guide
Essentially, you want to make sure there is enough surface area for the implant relative to the powerpad to be able to charge. You also want to make sure that the implant is not too far from the powerpad to be able to charge. 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.
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:
-
Implant Position Guide
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 Tektronix TDS2014C Oscilloscope to verify the stimulation output matched the parameters set in the MicroLeads GUI.
First, we must set our parameters within the MicroLeads GUI. Click the “Select Stimulation Parameters” button.
The meaning of each parameter corresponds to the following diagram.
-
Pulse Definition
- Period is the overall frequency of repetition of the pulse waveform
- Phase Durations (1&2) are the durations of positive and negative stimulationcurrent.
- Phase Amplitudes (1&2) are the amplitudes of the stimulation current.
- Interpulse Duration is the period between the two phases of current pulses.
- Charge Recovery Duration is the duration after the current phases when the stimulation channel is grounded to clear any residual unbalanced charge.
For verification, set the parameters to your desired values. If you don’t have values for your experiment yet, feel free to match the values shown here.
Check STIM0 and/or STIM1 if stimulation is needed. Check “Enable Recording” if streaming neural data is needed.
- If stimulation is used (with or without recording), set “Supply Voltage” to 9V
- If Recording only is used (no stimulation) set “Supply Voltage” to 4V
Now, click “Verify Stimulation Parameters” and close the dialogue box.
You can now run the recording and use your preferred method to verify that pulses are being generated.
How to set up with BCI2000
Now we will set up the research PC. First, follow the BCI2000 installation guide found here to install BCI2000 and compile the solution on your PC.
Connecting to the Devices
when using BCI2000, the research PC will replace the provided laptop from MicroLeads. First, we will have to connect the PC to the devices using the ethernet adapter. Simply plug it in to an empty USB port.
Next, we have to make sure that the ethernet connection is on the same network subnet mask and that the IPv4 address is able to communicate with the basestation.
To do this, first open up a command prompt and type
ipconfig /all
A list of IP connections should show up now. Scroll and find the connection that lists ethernet and might have Realtek USB controller as the connection.
Check to see if the IPv4 configuration starts with 192.168.1.X where X is any number. Also check to make sure that the default gateway is set.
If it does, great! You can move on to the next step. If not, all we need to do is change the IPv4 configuration.
In the Windows toolbar, search control panel. Then click on Network and Internet. Then click on Network and Sharing Center.
On the left hand side, you should see "Change adapter settings". Click on that, and then right click on the Ethernet connection associated with the adapter. It should say "Realtek USB controller" or something similar. Click on "Properties" in the popup.
Find "Internet Protocol Version 4 (TCP/IPv4)" and double-click. Toggle the section "Use the following IP address" on.
For IP address, use any IP address that isn't in use currently and starts with 192.168.1 . For subnet mask, use 255.255.255.0. For default gateway, use 192.168.1.1.
Make sure no warnings popup after validating, and you should be able to continue!
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:
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 compiled the MicroLeadsADC module, you can begin collecting data with BCI2000 by following the steps below.
- Double click BCI2000/batch/DummyApplication_MicroLeadsADC.bat - the batch file that was created in the previous section - to start BCI2000.
- Click the "Configure" button.
- 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!
- Click "Set Config".
- 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:
Now, you may run the experiment through BCI2000 following the previously discussed procedure here.
At this time, you should see more requests appearing through Wireshark. After some time, you can stop BCI2000 as well as stop the recording on Wireshark.
There are two main things to learn from the Wireshark data. First, we can manually verify the packets and headers sent to and from the basestation to see if they match up with what is expected in the API. Second, we should be able to see a constant stream of data coming from UDP port 2020.
If either of these do not occur, there is most likely an issue with the stimulation device. The solution to this is to let the implant lose power, and then recharge it to reset communication with the basestation.
If both of these do occur, there may have been a communication error with BCI2000. In this case, try to rerun the experiment settings multiple times to be able to visualize the data stream in BCI2000.
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.