Contents MAGSTIM RAPID2 STIMULATOR...2 SERIAL CONNECTION FOR CONTROLLING MAGSTIM RAPID 2...3 MATLAB TOOLBOX FOR CONTROLLING MAGSTIM RAPID2 STIMULATOR...4 THE FORMAT OF COMMANDS FOR CONTROLLING RAPID 2...4 SERIAL PORT INITIALISATION IN MATLAB...4 FUNCTION RAPID2_MAINTAINCOMMUNICATION...5 FUNCTION RAPID2_DELAY...5 FUNCTION RAPID2_ARMSTIMULATOR...6 FUNCTION RAPID2_SETPOWERLEVEL...6 FUNCTION RAPID2_IGNORECOILSAFETYSWITCH...7 FUNCTION RAPID2_TRIGGERPULSE...8 FUNCTION RAPID2_GETCOILTEMPERATURE...9 FUNCTION RAPID2_DISARMSTIMULATOR...9 EXAMPLE PROGRAM...10
Magstim Rapid2 Stimulator The Magstim company (Withland, UK, www.magstim.com) pioneered manufacturing magnetic stimulators and, ever since, they have been widely used in a variety of research settings [6]. The latest model, the Magstim Rapid 2 stimulator, provides options for both single and repetitive stimulation modes. A touch-screen user interface allows the experimenter to specify the stimulation mode (single or repetitive) and pulse intensity. A pulse can be delivered either by pushing on a foot pedal or pressing a button on the touch-screen user interface. The touch-screen can also be connected to a computer via a parallel port which enables a TMS pulse to be triggered with a temporal precision of less than a couple of milliseconds. However, the parallel port connection can be used only to trigger pulses and it presents no options for varying the pulse intensity from the computer. This limitation can be bypassed by using a serial connection to control both pulse intensity and pulse delivery from a computer. Previously, LabView graphical programming environment (National Instruments, Austin, TX) has been used to control earlier models of Magstim stimulators via computer [7,8]. For example, LabView generated "virtual instruments" were used to control Magstim BiStim 2 TMS system via a serial connection [8]. Those virtual instruments were also employed in a staircase procedure to programmatically vary the pulse intensity and automatically estimate motor threshold. We are, however, not aware of a published procedure that used Matlab to control Magstim transcranial magnetic stimulators. The Matlab toolbox we describe here allows fully controlling the Magstim Rapid 2 stimulator via a serial connection.
Serial Connection for Controlling Magstim Rapid 2 The Magstim Rapid 2 stimulator is equipped with 26-pin serial port (nomenclature: 26-pin D type connector) that is normally connected to the touchscreen user interface. To control the stimulator from the computer, the touch screen user interface should be disconnected from the stimulator and the serial port of the stimulator should be connected to the computerʼs serial port (Figure 1A). The computer typically has a 9-pin serial port (nomenclature: 9-pin D type connector or DE-9). Serial connection from the computer to the stimulator requires three pins to be enabled. The cable is not wired "straight thru": pin 2 (receive data, RxD) of the computer serial port connects with the stimulatorʼs pin 13; pin 3 (transmit data, TxD) on the computer should connect to pin 12 on the stimulator; and pin 5 (ground, SG) on the computer should connect to pin 11 on the stimulator. The diagram of the connection is provided in Figure 1B.
Matlab Toolbox for Controlling Magstim Rapid2 Stimulator The Format of Commands for Controlling Rapid 2 The Magstim Rapid 2 stimulator is controlled via a serial interface using commands which consist of strings of ASCII characters. Each command consists of three parts: command character (e.g., to set the power level), one or more data characters (e.g., the power level), and a character which is the checksum of the first two parts. For example, when the stimulator receives the ASCII string @050*, it will set the stimulation power level to 50%. The complete list of commands can be obtained by contacting Magstim (www.magstim.com). Serial Port Initialisation in Matlab The serial port on the computer should be set to have the following parameters: Baud Rate 9600; Data 8 bits; Stop 1 bit; Parity None; Flow Control None. To initialise a serial port object with these parameters in Matlab, the function serial is used: serialportobj = serial('com1', 'BaudRate', 9600, 'DataBits', 8, 'StopBits', 1, 'Parity', 'none', 'FlowControl', 'none', 'Terminator', '?'); COM1 is the name of the serial port that is connected to the stimulator. Terminator is a symbol that indicates the end of the sequence of ASCII characters: the Rapid 2 stimulator uses a question mark for this symbol. The rest of the parameters are set according to Magstim requirements for the Rapid 2 stimulator. The function serial returns handle to the serial port object.
Function Rapid2_MaintainCommunication The remote control of the stimulator is initiated using the command ʻenable remote controlʼ. The function Rapid2_MaintainCommunication sends the ʻenable remote controlʼ command to the stimulator. According to the stimulatorʼs documentation, this command should be issued every 500 ms or the stimulator will revert to standby mode. The serial port object created using serial allows periodic execution of a given function (called a callback function) at a certain time interval. Rapid2_MaintainCommunication requires the serial port object handler as an argument. The following Matlab code sets up executing Rapid2_MaintainCommunication function every 500 ms. % TimerPeriod variable of the object serialportobj specifies the period for executing the callback function in seconds. serialportobj.timerperiod = 0.5; % Open serial port for communication fopen(serialportobj); % TimerFcn variable of the object serialportobj contains the name of the callback function that should be periodically executed at a given interval (500 ms in this case) serialportobj.timerfcn = {'Rapid2_MaintainCommunication'}; Function Rapid2_Delay After issuing a command, stimulator may require a delay to process and execute the command. Any delay that is longer than 500 ms may prevent execution of the callback function and send the stimulator into offline mode. The function
Rapid2_Delay halts execution of the Matlab script for a requested time while maintaining communication with the stimulator by periodically executing Rapi2_MaintainCommunication callback function. Rapid2_Delay accepts two parameters: the delay specified in milliseconds and the serial port object. Below is an example of using the Rapid2_Delay function: % Halt execution of the Matlab script for 1000 ms without interfering with the execution of the callback function Rapid2_Delay(1000, serialportobj); Function Rapid2_ArmStimulator The function Rapid2_ArmStimulator sets the stimulator in ready mode to deliver a pulse. Once armed, the stimulator has to receive the ʻenable remote controlʼ command every 500 ms or else it will automatically disarm and revert to standby mode. Setting up the callback function as described earlier ensures that the stimulator will remain in armed mode for as long as necessary. The serial port object handler needs to be passed as an argument to this function. Rapid2_ArmStimulator returns 1 upon successfully arming the stimulator or 0 otherwise. Here is an example of using the function: success = Rapid2_ArmStimulator(serialPortObj); Function Rapid2_SetPowerLevel The function Rapid2_SetPowerLevel sets the power level as a percentage of stimulatorʼs maximum output and requires three arguments. The first argument is the handle of the serial port object. The second is the power level expressed as a percentage of stimulatorʼs output. For example, setting this argument to 60 will set
the stimulatorʼs output level to 60%. The third argument can be either 0 or 1 and determines whether the function should wait for the response from the stimulator. This third argument serves as a safety switch to prevent looping in the function for more than 1 sec which will hinder the execution of the callback function resulting in the stimulator switching to standby mode. To ensure periodic execution of the callback function, it is advisable to set the third parameter to 1. Here is an example of using the function: success = Rapid2_SetPowerLevel(serialPortObj, 60, 1); After setting the power level, it is necessary to give the stimulator time to charge or discharge capacitors before triggering the pulse or else the stimulator will stall and require disarming and arming to reset it. For example, decreasing the power level from 100% to 1% will take about 10 sec. Introducing 50 ms delay for each 1% of power level change is usually sufficient to avoid stalling the stimulator. Function Rapid2_IgnoreCoilSafetySwitch The safety switch on the coil should be pressed down, by default, to deliver a pulse. When running experiments, however, it is preferable to disable the coil safety switch. The function Rapid2_IgnoreCoilSafetySwitch deactivates the coil safety switch. The only argument this function requires is the serial port object handler. If successful, the function will return 1, otherwise 0. Example: success = Rapid2_IgnoreCoilSafetySwitch(serialPortObj);
Function Rapid2_TriggerPulse Calling the function Rapid2_TriggerPulse triggers a pulse. This function accepts two arguments. The first argument is the serial port object handler. The second argument controls reading the stimulatorʼs response after triggering the pulse. Setting the second argument to 0 ensures that the stimulatorʼs response is read. Setting the second argument to 1 skips reading the stimulatorʼs response and avoids forcing Matlab to loop for more than a second. It is recommended to set the second argument to 1 (0 is usually used for debugging). The function Rapid2_TriggerPulse returns 1 when the pulse was triggered successfully or 0 in the case of a failure. Example of use: success = Rapid2_TriggerPulse(serialPortObj, 1); It is important to note that the design of Magstim Rapid 2 serial interface imposes limitations on the temporal precision of triggering a pulse via a serial interface. The stimulator processes each byte of commands sent via the serial connection every 2 ms - the command will remain in the stimulatorʼs buffer and then be executed after sufficient cycles of the 2 ms loop. For example, the Rapid2_TriggerPulse function contains three bytes and therefore requires three cycles of the stimulatorʼs 2 ms loop; allowing an additional cycle of the loop to act upon the command, the stimulator will deliver the pulse somewhere between 6 and 8ms. It is possible to trigger the pulse with high temporal precision by sending either a +5V current to pin 5 or -5V to pin 6 of the stimulatorʼs serial interface. This, however, should be implemented using the parallel port of a PC because the serial port usually delivers currents well above/below ±5 V. It is possible to control the stimulator using the toolbox and trigger the pulse accurately by preparing a
combined cable where parallel and serial connection wires are merged into the 26- pin connector linked to the TMS. Recently, we have also succeeded in triggering pulse with high temporal precision using an external USB serial port attached to a MacBook (Apple Inc., CA) as OS X operating system provides no support for parallel port connection. Function Rapid2_GetCoilTemperature Rapid 2 stimulator automatically disarms when the coil temperature reaches 40 0 C (104 0 F). Stimulation can only be continued when the coil temperature drops below 40 0 C. The function Rapid2_GetCoilTemperature reports the coilʼs temperature. The only input argument is the serial port object handler. The function returns two values. The first value is 1 when the function is successful or 0 otherwise. The second value is the coil temperature in Celsius. Example of use: [success, temperature] = Rapid2_GetCoilTemperature(serialPortObj); Function Rapid2_DisarmStimulator Rapid2_DisarmStimulator switches the stimulator from armed to disarmed (standby) mode. The function requires the serial port object handler as the only input argument. The function returns 1 if disarming was successful and 0 otherwise. Example: success = Rapid2_DisarmStimulator(serialPortObj);
Example Program An example Matlab program to control Magstim Rapid 2 stimulator via a serial interface is provided at http://www.psych.usyd.edu.au/tmslab. The program initialises the COM1 port and sets up a callback function to maintain communication with the stimulator. Pressing 1 on the keyboard arms the stimulator; pressing 0 disarms the stimulator. The Left Shift and Right Shift keys increase or decrease the power level, respectively. Pressing the Spacebar triggers a pulse. The example program is designed to assist setting up a serial connection. The example program has only been tested on our lab computer. You may consider downloading REPT to test the serial connection as REPT has been through a rigorous testing and was found to work smoothly on at least 3 different PCs as well as on a 13 Macbook Pro (using USB to serial adapter).