Online Change of Stimulation (OCS) for tACS Using MatNIC PRO

If you need to modify tACS phase, frequency, or amplitude in real time from MATLAB while a protocol is running in NIC, this article walks you through the required setup and call sequence.

In this article you will learn how to configure and run Online Change of Stimulation (OCS) — real-time modification of stimulation parameters during an active session — for tACS (transcranial Alternating Current Stimulation) using the MatNIC  PRO Toolkit.

We want to make sure that:

• Your MATLAB session connects to NIC and loads a protocol successfully
• Phase, frequency, and amplitude changes are applied in the correct order
• Current stays balanced across all channels throughout the session

For this procedure you will need:

• Starstim device (confirm your exact model, as channel count affects your parameter arrays)
• NIC software Latest Version
• MATLAB with the MatNIC PRO Toolkit

Section 1: Create a Blank tACS Protocol in NIC

OCS requires a protocol already loaded in NIC before MATLAB can modify it. Start from a blank (zero-current) tACS protocol — a template where every channel begins at 0 µA, 0 Hz, and 0º.

1. Open NIC.
2. Navigate to Protocols.
3. Create a new tACS stimulation protocol.
4. For each active channel, set frequency, phase, and amplitude to 0.
5. Save the protocol with a clear, identifiable name (for example, Blank-tACS-Protocol).

→ If the protocol saves successfully: continue to Section 2. → If NIC does not allow you to save with all values at 0: contact support@neuroelectrics.com.

Section 2: Connect to NIC and Load the Protocol from MATLAB

1. Connect to NIC from MATLAB:
   [ret, status, socket] = MatNICConnect('localhost');
2. Set up the MatNIC environment:
   [ret, version, n_channels, deviceSettings] = MatNICSetUp(socket);
3. Load the blank tACS protocol saved in NIC:
   ret = MatNICLoadProtocol('Blank-tACS-Protocol', socket);
4. Start the protocol:
   ret = MatNICStartProtocol(socket);

Each function returns a ret value confirming whether the call succeeded.

→ If ret equals 0 after each call: proceed to Section 3. → If ret is negative (for example, if the protocol name is not found): run MatNICQueryStatus(socket) to check NIC's current status, correct the issue, and retry the failed step. → If ret remains negative after retrying: contact support@neuroelectrics.com.

Section 3: Follow the Required Call Order for OCS Functions

tACS OCS functions must be called in this order: phase, then frequency, then amplitude. Calling them out of order can produce unexpected stimulation behavior.

3.1 Set Phase — MatNICOnlinePtacsChange

[ret] = MatNICOnlinePtacsChange(phaseArray, n_channels, socket);

3.2 Set Frequency — MatNICOnlineFtacsChange

[ret] = MatNICOnlineFtacsChange(frequencyArray, n_channels, socket);

3.3 Set Amplitude — MatNICOnlineAtacsChange

[ret] = MatNICOnlineAtacsChange(amplitudeArray, n_channels, transition, socket);

Amplitude must always be set last, after phase and frequency are confirmed.

3.4 Set All Parameters at Once (Optional) — MatNICOnlinetACSChange

[ret] = MatNICOnlinetACSChange(amplitudeArray, frequencyArray, phaseArray, n_channels, transition, socket);

This function updates amplitude, frequency, and phase in a single call. The same ordering rule still applies underneath: if phase and frequency have never been set in the template, call MatNICOnlinePtacsChange and MatNICOnlineFtacsChange individually first.

→ If all ret values return 0: proceed to Section 4. → If any ret value is negative: check that phase and frequency were initialized before this call, then retry.

Section 4: Run a Complete OCS Sequence

This example uses two channels: Channel 1 is the active electrode, Channel 2 is the return channel (set to 180º phase in the NIC template).

1. Connect and set up:
   [ret, status, socket] = MatNICConnect('localhost');[ret, version, n_channels, deviceSettings] = MatNICSetUp(socket);
   
   
2. Load and start the blank tACS protocol:
   ret = MatNICLoadProtocol('Blank-tACS-Protocol', socket);ret = MatNICStartProtocol(socket);
   
   
3. Initialize the parameter arrays:
   phaseArray = zeros(1, n_channels);frequencyArray = zeros(1, n_channels);amplitudeArray = zeros(1, n_channels);
   
   
4. Set phase first (in degrees):
   phaseArray(1) = 0; % Channel 1: 0 degreesphaseArray(2) = 180; % Channel 2: 180 degrees (return)ret = MatNICOnlinePtacsChange(phaseArray, n_channels, socket);
   
   
5. Set frequency second (in Hz):
   frequencyArray(1) = 10;frequencyArray(2) = 10;ret = MatNICOnlineFtacsChange(frequencyArray, n_channels, socket);
   
   
6. Set amplitude last (in µA), with a 1000 ms ramp:
   amplitudeArray(1) = 1000;amplitudeArray(2) = 1000;ret = MatNICOnlineAtacsChange(amplitudeArray, n_channels, 1000, socket);
   
   
7. Hold stimulation at these settings for 20 seconds:
   pause(20);
   
   
8. Ramp amplitude back to 0 before ending the session:
   amplitudeArray(:) = 0;ret = MatNICOnlineAtacsChange(amplitudeArray, n_channels, 1000, socket);
9. Stop the protocol and disconnect:
   ret = MatNICAbortProtocol(socket);ret = MatNICDisconnect(socket);

→ If every ret value returned 0 throughout: your session ran correctly. → If any step returned a negative ret: stop the sequence, run MatNICQueryStatus(socket), and do not proceed to the next parameter change until the issue is resolved.

Section 5: Maintain Current Conservation at All Times

The sum of currents across all channels must always equal zero. MatNIC does not enforce this automatically — if NIC detects a violation, it will silently ignore the request rather than return an error.

1. Check whether your protocol uses a return channel.
2. If you have a return channel: configure it in NIC's advanced channel settings. Current balance is then handled automatically.
3. If you do not have a return channel: manually ensure the sum of all values in amplitudeArray equals zero at every point in your script.
4. Confirm that no individual channel — including the return channel — exceeds 2000 µA.

→ If your amplitude values are balanced and within limits: your session is compliant with current conservation. → If you are unsure whether a request was silently ignored: verify the applied values with MatNICQueryStatus(socket) before continuing, or contact support@neuroelectrics.com.

If the issue persists after completing all sections, contact support@neuroelectrics.com.

Please include:

• Your MATLAB script
• The ret values returned at the point of failure
• Your NIC version number
• The Protocol used