Contributions:RemoteBIC: Difference between revisions
Added RemoteBIC documentation |
|||
| Line 254: | Line 254: | ||
# Install the BIC RPC server on the server computer and plug the external unit into it. | # Install the BIC RPC server on the server computer and plug the external unit into it. | ||
# In <code>config.json</code>, set <code>address</code> to <code>0.0.0.0</code> and <code>port</code> to <code>50051</code>. With <code>127.0.0.1</code> the server would refuse connections from other computers. | # In <code>config.json</code>, set <code>address</code> to <code>0.0.0.0</code> and <code>port</code> to <code>50051</code>. With <code>127.0.0.1</code> the server would refuse connections from other computers. | ||
# | # It may be necessary to allow the server through the Windows firewall. If this is an issue you run into, open PowerShell with ''Run as administrator'' and run: | ||
<pre> | <pre> | ||
New-NetFirewallRule -DisplayName "bicRpcServer" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 50051 -Program "C:\Program Files\Cortec\bicRpcServer-setup\bicRpcServer.exe" -Profile Any | New-NetFirewallRule -DisplayName "bicRpcServer" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 50051 -Program "C:\Program Files\Cortec\bicRpcServer-setup\bicRpcServer.exe" -Profile Any | ||
Latest revision as of 20:02, 20 November 2026
RemoteBICSource is a source module that records from and stimulates through the CorTec Brain Interchange (BIC) implant over a network connection. Instead of talking to the hardware directly, as CortecADC does, BCI2000 connects to the CorTec BIC RPC server (bicRpcServer.exe), which owns the USB connection to the implant. The server and BCI2000 can run on the same computer or on two computers joined by a router.
This page is a step-by-step tutorial. It covers configuring the server, connecting BCI2000 to it, streaming data, and running the server and BCI2000 on separate computers. For the meaning of the individual stimulation parameters and implant states, refer to the CortecADC page.
Versioning
Authors
- Nicholas Luczak (luczak@neurotechcenter.org)
Tested With
| Component | Version |
|---|---|
| BIC RPC server | bicRpcServer.exe, build of 11/20/2025
|
| Implant firmware | 1.0.260 |
| Operating system | Windows 11, 64 bit |
Known Issues
- No encryption. RemoteBICSource opens an unencrypted gRPC channel. The server's
enableSslsetting must stayfalse, and the connection should only be used on a private, isolated network. - Volatile stimulation is not available. Only the Persistent Command and Persistent Functions stimulation modes work through the server.
- 64-bit Windows only. The module is not built on other platforms.
- Lost samples are marked in the
ImplantLostSamplestream and filled with the following valid sample. Handle them in offline analysis as described on the CortecADC page.
Overview
Three pieces are involved. The implant and its external unit are the hardware. The BIC RPC server is a CorTec program that opens the hardware and offers it on a TCP port. RemoteBICSource is the BCI2000 source module that connects to that port.
Implant <-- RF --> Head piece / external unit
|
USB
|
+---------------------------+ +---------------------------+
| Server computer | gRPC/TCP | BCI2000 computer |
| bicRpcServer.exe | <----------> | RemoteBICSource.exe |
| listens on port 50051 | port 50051 | ConnectionAddress |
+---------------------------+ +---------------------------+
When both programs run on one computer, the two boxes are the same machine and BCI2000 connects to localhost:50051. This is the default, and it is the setup described first.
Starting Point
This tutorial assumes the following:
- The BIC RPC server is installed in
C:\Program Files\Cortec\bicRpcServer-setup. - BCI2000 is installed in
C:\BCI2000. - The external unit is plugged into a USB port, the head piece sits over the implant, and the implant runs a current firmware version.
Check two things before continuing:
- The source module exists. Look for
C:\BCI2000\prog\RemoteBICSource.exe. If it is missing, BCI2000 was built without it. The module's source code is inBCI2000/src/private/SignalSource/RemoteBIC. Enable the CMake optionBUILD_REMOTEBIC_SOURCEand rebuild; the build downloads the gRPC libraries it needs, and copies the batch files andRemoteBIC.prmfrom that folder intobatchandparms/fragments/amplifiers. - Nothing else is using the implant. Close the CorTec BIC application and any BCI2000 instance running CortecADC. Only one program can open the external unit at a time.
Configuring the Server
The Server Folder
The server folder contains these files:
| File | Purpose |
|---|---|
bicRpcServer.exe
|
The server program |
config.json
|
Server settings: address, port, encryption, compression, logging |
bicapi.dll, ftd2xx.dll
|
CorTec API and USB driver library used to reach the external unit |
RemoteBIC.proto
|
Definition of the network interface. BCI2000 is built against the same file. |
session_logger.text
|
Text log of the requests the server receives. Written while the server runs. |
test.log
|
Binary CorTec log of the communication with the implant. Written while the server runs, and it grows quickly. |
config\selfTestConfigs
|
Configurations for the implant self-tests |
Editing config.json
Open config.json in a text editor. Editing files under Program Files requires an editor started with Run as administrator. The default file looks like this:
{
"root": {
"serverAddress": {
"address": "0.0.0.0",
"port": "50051"
},
"serverAuthentication": {
"enableSsl": "false",
"serverKeyPath": "none",
"serverCertificatePath": "none",
"rootcertificatePath": "none"
},
"serverCompression": {
"enableCompression": "false",
"compressionLevel": "0"
},
"serverLogging": {
"enableLogging": "true"
}
}
}
| Setting | Value to use | Explanation |
|---|---|---|
serverAddress.address
|
0.0.0.0
|
The network interface the server listens on. 0.0.0.0 means all interfaces, so the server is reachable both locally and from other computers. Use 127.0.0.1 to accept connections from the same computer only.
|
serverAddress.port
|
50051
|
The TCP port. It must match the port in the BCI2000 ConnectionAddress parameter.
|
serverAuthentication.enableSsl
|
false
|
Must be false. RemoteBICSource does not support encrypted connections. Leave the three path settings at none.
|
serverCompression.enableCompression
|
false
|
Leave compression off. |
serverLogging.enableLogging
|
true
|
Keeps session_logger.text up to date, which is the easiest way to see whether BCI2000 is reaching the server.
|
All values are written as quoted strings, including the port and the true/false settings. Keep the quotes.
Allowing the Server to Write its Logs
The server writes session_logger.text and test.log into its own folder. Standard users cannot write to Program Files, so do one of the following:
- Start the server with Run as administrator, or
- Give your user account Modify permission on the server folder: right-click the folder, choose Properties → Security → Edit, select your user, and tick Modify.
Starting the Server
- Open
C:\Program Files\Cortec\bicRpcServer-setupin the File Explorer. - Double-click
bicRpcServer.exe. Start it from its own folder, so that it findsconfig.jsonand the DLLs next to it. - A console window opens. Leave it open for the whole session; closing it stops the server.
- The first time the server starts, Windows may show a Windows Security firewall prompt. Click Allow. This matters only when BCI2000 runs on another computer (see below).
To confirm that the server started, open session_logger.text. A new line ending in Application construction with the current time appears at each start:
[INFO ][2026/10/27 14:06:39:207][...BICServerApplication.cpp:64][21124] Application construction
The server does not contact the implant at this point. It opens the external unit when BCI2000 connects.
Connecting BCI2000
Starting BCI2000 with RemoteBICSource
BCI2000 ships three batch files that use the module. They are in C:\BCI2000\batch:
CursorTask_RemoteBIC.batP3Speller_RemoteBIC.batStimulusPresentation_RemoteBIC.bat
Each one starts RemoteBICSource as the source module and loads the parameter fragment C:\BCI2000\parms\fragments\amplifiers\RemoteBIC.prm. To use the module in your own batch file, replace the source module line and load the fragment:
Start executable RemoteBICSource --local ... Wait for Connected Load parameterfile "../parms/fragments/amplifiers/RemoteBIC.prm"
- Make sure the server is running.
- Double-click one of the batch files, for example
StimulusPresentation_RemoteBIC.bat. - Wait until the Operator window shows that all modules are connected.
Source Parameters
Click Config and open the Source tab. The parameters specific to this module are in the RemoteBIC section.

ConnectionAddress
The address and port of the BIC RPC server, written as host:port. The default is localhost:50051, which is correct when the server runs on the same computer. For a server on another computer, enter its IP address, for example 192.168.1.10:50051.
Amplification
Amplification applied on the implant. 0: 57.5 dB, 1: 51.5 dB, 2: 45.5 dB, 3: 39.5 dB.
ReferenceCh
List of channels used as hardware reference, counted from 1. If set to auto, no reference channel is used.
UseGround
Enable to use the ground electrode as reference.
SourceCh, SamplingRate, SampleBlockSize
Leave these at auto. The channel count and sampling rate are read from the implant. Entering a sampling rate that differs from the implant's produces the error Set parameter SamplingRate to auto to match BIC hardware.
SourceChGain, SourceChOffset, ChannelNames
Leave these at auto. Samples arrive in microvolts regardless of the amplification, so the gain is set to 1 µV and the offset to 0. Channels are named CH0, CH1, and so on.
SaveInfoFile
Enable to save a text file next to the data file, named ..._info0.txt, containing the time stamp, amplification factor, and reference channels.
The Stimulation tab holds the same parameters as CortecADC: EnableStimulation, StimulationMode, MeasureImpedance, LogStimulationEvents, StimulationPulses, and StimulationTriggers. See CortecADC for details. StimulationMode must be 1 (Persistent Command) or 2 (Persistent Functions).
Streaming Data
- In the Storage tab, set
SubjectName,SubjectSession, andDataDirectoryas for any BCI2000 recording. - Click Set Config. BCI2000 now contacts the server, the server opens the external unit, powers the implant, and starts the measurement. This takes ten to fifteen seconds.
- Check the Operator log. Two messages confirm the connection:
- The following external units were discovered: followed by the external unit ID, type, and index.
- The implant information for to the EU at index: 0 followed by the device type, device ID, and firmware version.
- The source signal window opens and shows the implant channels. Data are now streaming from the implant, through the server, into BCI2000.
- Click Start to begin a run and write data to disk. Click Suspend to end the run.
- To finish, close BCI2000 first. On shutdown the module stops the measurement and switches off the implant power. Then close the server's console window.
On the server side, session_logger.text shows the same sequence. Each line is a request from BCI2000:
Request to get external unit info received. Response to get external unit info has been sent. Request to get implant info received. Response of implant info has been sent. Request to create implant object received. Response to create implant has been sent. Request to get device infos received.
If MeasureImpedance is enabled, the impedance of every channel is measured at Set Config, shown in a separate Cortec Impedances window, and saved to the info file.
Recorded States
Besides the signal, the module records the implant's telemetry as BCI2000 events: ImplantTemperature, ImplantVoltage, ImplantHumidity, ImplantControlValue, ImplantPrimaryCoilCurrent, ImplantStimulation, ImplantRfQuality, and ImplantLastStimulationID. It also records the ImplantLostSample stream and the RequestedStimulation and PauseStimulation states. Their units and multipliers are listed in the StateInfo parameter and explained on the CortecADC page.
Remote Setup Through a Router
The server and BCI2000 do not have to share a computer. In a remote setup, a small server computer stays with the implant and the external unit, and a second BCI2000 computer runs the experiment. A router connects the two. This is the arrangement used for the demonstration at the Mayo Clinic.
Implant <-- RF --> External unit
|
USB
|
+---------------------+ +----------+ +---------------------+
| Server computer | | | | BCI2000 computer |
| bicRpcServer.exe | <----> | Router | <----> | RemoteBICSource |
| 192.168.1.10 | | | | 192.168.1.20 |
+---------------------+ +----------+ +---------------------+
The addresses in this section are examples. Use the ones your router assigns.
Step 1: Build the Network
- Use a dedicated router that is not connected to the internet or to a hospital or university network. The data stream is not encrypted, and the server accepts any client that can reach its port.
- Connect both computers to the router. Use Ethernet cables where possible; a wireless link works but adds jitter and lost samples.
- Give the server computer a fixed address, so that it does not change between sessions. Either reserve an address for it in the router's DHCP settings, or set a static IPv4 address in Windows under Settings → Network & internet → Ethernet → IP assignment → Edit.
- On the server computer, open a PowerShell window and run
ipconfig. Note the IPv4 Address of the adapter connected to the router. An address beginning with169.254means the computer did not receive an address from the router.
Step 2: Configure the Server Computer
- Install the BIC RPC server on the server computer and plug the external unit into it.
- In
config.json, setaddressto0.0.0.0andportto50051. With127.0.0.1the server would refuse connections from other computers. - It may be necessary to allow the server through the Windows firewall. If this is an issue you run into, open PowerShell with Run as administrator and run:
New-NetFirewallRule -DisplayName "bicRpcServer" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 50051 -Program "C:\Program Files\Cortec\bicRpcServer-setup\bicRpcServer.exe" -Profile Any
- Windows assigns a new router network the Public profile. A rule that covers only Private networks will not apply to it, which is why the command uses
-Profile Any. If you clicked Allow on the firewall prompt at the first start, check under Windows Defender Firewall → Allowed apps that the box for the profile in use is ticked.
- Start
bicRpcServer.exe.
Step 3: Test the Connection
On the BCI2000 computer, open PowerShell and run:
Test-NetConnection 192.168.1.10 -Port 50051
The result must show TcpTestSucceeded : True. If it shows False, BCI2000 will not connect either. Check, in this order: that the server is running, the IP address, the firewall rule, and the cables.
Step 4: Connect BCI2000
- On the BCI2000 computer, start a RemoteBIC batch file.
- Click Config, open the Source tab, and set
ConnectionAddressto the server computer's address and port:192.168.1.10:50051. - Click Set Config and continue as described under Streaming Data.
To avoid typing the address at every start, save the configuration to a parameter file with Save Parameters, or add a line to your batch file after the parameter files are loaded:
Set parameter ConnectionAddress 192.168.1.10:50051
Notes on Remote Operation
- The BCI2000 computer needs neither the CorTec API nor the USB driver. Only the server computer talks to the hardware.
- Data files are written on the BCI2000 computer. The server computer keeps only its two log files.
- Someone must be able to start the server on the server computer, either in person or through remote desktop software.
- If the network connection drops during a run, samples stop arriving and the signal display goes blank. Suspend the run, restore the connection, and click Set Config again.
- Stimulation commands are uploaded to the implant at Set Config and only triggered over the network, so stimulation latency includes the network delay. Measure it for your own setup using the
RequestedStimulationandImplantStimulationstates, as described on the CortecADC page.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
Set Config fails with an error starting with RemoteBIC:
|
BCI2000 cannot reach the server. | Check that the server is running and that ConnectionAddress has the right address and port. For a remote server, run the Test-NetConnection test above.
|
| Could not create implant | The server is reachable but cannot open the implant. | Check that the external unit is plugged in, the head piece sits over the implant, and no other program is using the device. Try a different USB port. |
| Set parameter SamplingRate to auto to match BIC hardware | A sampling rate was entered by hand or loaded from another parameter file. | Set SamplingRate to auto, or load RemoteBIC.prm last.
|
| Volatile stimulation mode is not available with RemoteBIC | StimulationMode is 0.
|
Set StimulationMode to 1 or 2.
|
| ReferenceCh entry ... out of range | A reference channel is 0 or larger than the channel count. | Reference channels are counted from 1. |
| The signal display is blank during a run | No samples have arrived for more than a second. | The network link or the RF link to the implant is interrupted. Check the head piece position and the network, then click Set Config again. |
Many lost samples in ImplantLostSample
|
Poor coupling between head piece and implant. | Reposition the head piece and watch ImplantRfQuality and ImplantControlValue.
|
| The server window closes immediately | The server cannot find config.json, or the file is not valid JSON.
|
Start the server from its own folder and check the file for missing quotes or commas. |
session_logger.text does not change
|
The server cannot write to its folder, or logging is off. | Run the server as administrator or grant Modify permission on the folder, and set enableLogging to true.
|
RemoteBICSource.exe is missing from prog
|
BCI2000 was built without the module. | Enable BUILD_REMOTEBIC_SOURCE in CMake and rebuild.
|
See also
Contributions:CortecADC, CortecExperience, User Reference:Filters, Contributions:ADCs