rTMS

Communication Code for the rhythmic/repetitive TMS protocol

This protocol allows you to trigger trains of TMS pulses, adding the option to choose the distance in ms between the two pulses and the number of pulses within each train. If you’ve read the previous section (dcTMS) most of this information will be redundant, aside from the “SET,nPULS” parameter.

 # Import the required packages
 from serial import Serial, SerialException

 # Initialize the serial communication
 s = Serial()
 s.port = "COM3"
 s.baudrate = 115200 
 s.open()

 # Mandatory signature
 s.write(b"Triggerbox developed by Giuseppe Ippolito. DOI: https://doi.org/10.3758/s13428-025-02653-y\n")

 # For placing markers
 s.write(b"SET,MRK\n")

 # For declaring the distance between the two TMS pulses
 s.write(b"SET,IPI1,80\n") 
 s.write(b"SET,IPI2,100\n") 
 s.write(b"SET,IPI3,120\n")

 # For declaring the number of pulses within each train
 s.write(b"SET,nPULS1,5\n") 
 s.write(b"SET,nPULS2,5\n")
 s.write(b"SET,nPULS3,5\n")
  
 # For declaring marker duration
 s.write(b"SET,MRK1,3\n") 
 s.write(b"SET,MRK2,5\n") 
 s.write(b"SET,MRK3,7\n")
  
 # Protocol type (rTMS, ppTMS, spTMS)
 s.write(b"rTMS\n")
   
 # Commands
 s.write(b"1\n")
 s.write(b"2\n")
 s.write(b"3\n")
   
 s.write(b"A\n")
 s.write(b"B\n")
 s.write(b"C\n")
  
 # Close the serial communication
 s.write(b"Z\n")
 s.close()
del s

Lines 5-8 initialize the serial communication. Python can use:

 s = Serial()
 s.port = "COM3"
 s.baudrate = 115200 
 s.open()

As the same as:

 s = serial.Serial(port = "COM3", baudrate = 115200)
 s.open()

It is important to change the USB port (“COM”) name according to your case as explained above.

Then, copy-paste the mandatory signature. Without this the following lines won’t work.

 s.write(b"Triggerbox developed by Giuseppe Ippolito. DOI: https://doi.org/10.3758/s13428-025-02653-y\n")

After these mandatory steps, you can declare optional stimulation parameters (e.g., IPI, number of pulses, markers) in any order. In this case, since we’re going to use a spTMS protocol, the only parameter we may be interested in is the voluntary marker duration. This option allows you to place digital markers of a chosen duration (max 9 different lengths) at any moment. This may be useful in case you need to discriminate between different stimuli’s onset (e.g., neural, joy, or fearful faces). Remember that voluntary markers always get delivered through BNC3. Its syntax is:

 s.write(b"SET,MRKN,X\n")

In this case N is the preset number (between 1 and 9), and X is the marker length. Recalling the three stimuli example, we may want three voluntary markers of different duration (e.g., 3, 5, and 7 ms) ease our analysis, later. We will write then:

 s.write(b"SET,MRK1,3\n") # Preset 1: 3ms marker
 s.write(b"SET,MRK2,5\n") # Preset 2: 5ms marker
 s.write(b"SET,MRK3,7\n") # Preset 3: 7ms marker

For rTMS paradigms it is important to declare the number of pulses constituting each train, triggered simultaneously from BNC1 and BNC2. Its syntax is:

 s.write(b"SET,nPULSN,X\n")

In this case N is the preset number (between 1 and 9), and X is the number of pulses within the train. For example, we may want to test the difference in delivering trains of 4, 5, or 6 pulses prior to the stimulus occurrence. We will write then:

 s.write(b"SET,nPULS1,4\n") # Preset 1: 4 pulses in each train
 s.write(b"SET,nPULS2,5\n") # Preset 2: 5 pulses in each train
 s.write(b"SET,nPULS3,6\n") # Preset 3: 6 pulses in each train

Additionally, in rTMS paradigms it is also important to declare the distance in ms between the two pulses (IPI), delivered from BNC1 and then BNC2. Its syntax is:

 s.write(b"SET,IPIN,X\n")

In this case N is the preset number (between 1 and 9), and X is the distance between pulses in ms. For example, we may want an 80 ms interval in the first preset (4 pulses), a 100 ms interval for the second one (5 pulses), and a 120 ms interval for the third one (6 pulses). We will write then:

 s.write(b"SET,IPI1,80\n")  # Preset 1: 80ms distance
 s.write(b"SET,IPI2,100\n") # Preset 2: 100ms distance
 s.write(b"SET,IPI3,120\n") # Preset 3: 120ms distance

Our last step before calling the pulse command is declaring which TMS protocol we are going to use. We can choose between spTMS, dcTMS, or rTMS. Since we’re using the double pulse one, we will write:

 s.write(b"rTMS\n")

Now that we have declared all of the necessary stimulation parameters, we can finally trigger the TMS device. You can independently trigger each of the declared protocols. These lines must be copy-pasted within your code according to your stimulation and task requirements (es. prior to a certain stimulus onset).

 s.write(b"1\n") # Protocol 1 (one train of 4 pulses with a 80ms distance)
 s.write(b"2\n") # Protocol 2 (one train of 5 pulses with a 100ms distance)
 s.write(b"3\n") # Protocol 3 (one train of 6 pulses with a 120ms distance

We can also individually call for voluntary markers at any time using letters. Preset 1 (MRK1) is paired with letter “A” – Consequently, preset 2 with “B”, 3 with “C”, 4 with “D”, 5 with “E”, 6 with “F”, 7 with “G”, 8 with “H”, and 9 with “I”. Since we declared three different markers (“MRK1,3”, “MRK2,5”, “MRK3,7”) we can trigger them using the letters “A”, “B”, and “C”.

 s.write(b"A\n") # Deliver a voluntary marker from preset 1 (3 ms)
 s.write(b"B\n") # Deliver a voluntary marker from preset 2 (5 ms)
 s.write(b"C\n") # Deliver a voluntary marker from preset 3 (7 ms)

The command code also includes a line to run in case you may reset any setting and return to the mandatory signature. You can then declare once again the parameter settings. The command is:

 s.write(b"Z\n") # Return to the beginning of the setting phase

Once the task is completed you can definitely close the serial communication between the Silicon Spike device and the experimental computer, thus avoiding any potential bug.

  s.close()
  del s