Baud: 12000000
Data bits: 8
Stop bits: 1
Byte order: Little endian
Terminator: Line Feed (not used)
Flow control: none
Parity: none
DTR (Data terminal ready): off
RTS (Request to send): on (AKA CTS / clear to send)
Output Buffer Size: Preferably >100kB
Pulse Pal uses a one-byte op-code to specify each operation. Some operations may expect more data to follow. When this is true, the following convention is used for datatypes:
RED: 8-bit unsigned integer (1 byte)
BLUE: 32-bit unsigned integer (4 bytes)
Pulse train parameters are explained in depth in the parameter guide.
All transmissions must begin with the Op menu byte: 213.
Next, an op code byte must follow.
The op code bytes are:
72 (character 'H'): Handshake
Pulse Pal returns byte 75 (character 'K')
Pulse Pal then returns a 32-bit integer specifying the firmware build number.
73: Program Pulse Pal (ALL parameters, ALL channels)
Pulse Pal expects the following bytes next:
Output channel 1, Phase1Duration (Bytes 3-6, units = cycles***)
Output channel 1, InterPhaseInterval (Bytes 7-10, units = cycles***)
Output channel 1, Phase2Duration (Bytes 11-14, units = cycles***)
Output channel 1, InterPulseInterval (Bytes 15-18, units = cycles***)
Output channel 1, BurstDuration (Bytes 19-22, units = cycles***)
Output channel 1, InterBurstInterval (Bytes 23-26, units = cycles***)
Output channel 1, PulseTrainDuration (Bytes 27-30, units = cycles***)
Output channel 1, PulseTrainDelay (Bytes 31-34, units = cycles***)
Output channel 2, Phase1Duration ... PulseTrainDelay (Bytes 35-66, units = cycles***)
Output channel 3, Phase1Duration ... PulseTrainDelay (Bytes 67-98, units = cycles***)
Output channel 4, Phase1Duration ... PulseTrainDelay (Bytes 99-130, units = cycles***)
Output channel 1, isBiphasic (Byte 131)
Output channel 1, Phase1Voltage (Byte 132, units: [0:255 = -10V:+10V])
Output channel 1, Phase2Voltage (Byte 133, units: [0:255 = -10V:+10V])
Output channel 1, CustomTrainID (Byte 134)
Output channel 1, CustomTrainTarget (Byte 135)
Output channel 1, CustomTrainLoop (Byte 136)
Output channel 1, RestingVoltage (Byte 137)
Output channel 2, isBiphasic ... RestingVoltage (Bytes 138-455)
Output channel 3, isBiphasic ... RestingVoltage (Bytes 145-151)
Output channel 4, isBiphasic ... RestingVoltage (Bytes 152-158)
Trigger channel 1, Trigger Link Bytes 1-4 (bytes 159-162, bytes specify output channels linked to input ch1 i.e. 1 0 1 0 = link to output channels 1 and 3)
Trigger channel 2, Trigger Link Bytes 1-4 (bytes 163-166)
Trigger channel 1, TriggerMode (byte 167)
Trigger channel 2, TriggerMode (byte 168)
Pulse Pal returns 1 if transmission was successful.
74: Program Pulse Pal (ONE parameter on ONE channel)
Pulse Pal expects the following bytes next:
Parameter code (byte 3, see parameter code table in the MATLAB client documentation)
Output channel (byte 4, valid values = 1-4)
If the parameter contains time data (codes 4-11)
Parameter (bytes 5-8)
Otherwise
Parameter (byte 5)
Pulse Pal returns 1 if transmission was successful.
75: Program custom pulse train 1
Pulse Pal expects the following bytes next:
USBPacketCorrectionByte (Byte 3. The firmware uses this byte to correct for an issue with the LeafLabs maple driver. See below* for discussion & example)
nPulses (Bytes 4-7, specifying the number of pulses in the custom pulse train)
PulseTimes (Bytes 8 to [7+(nPulses*4)], units = cycles***)
Voltages (Bytes [7+(nPulses*4)] to [7+(nPulses*4)] + nPulses-1, units: [0:255 = -10V:+10V])
Pulse Pal returns 1 if transmission was successful.
76: Program custom pulse train 2 (Same byte sequence as custom pulse train 1)
77: Soft-trigger Pulse Pal output channels
Pulse Pal expects the following bytes next:
Trigger Link Byte (byte 3, bits specify output channels targeted i.e. 5 = 0101 = output channels 1 and 3)
78: Write text to Pulse Pal oLED display
Pulse Pal expects the following bytes next:
ASCII bytes for text on row 1 of the display (up to 16 characters)
Optional: Line break byte (254)
Optional: ASCII bytes for text on row 2 of the display (up to 16 characters)
79: Set a fixed voltage on an output channel
Pulse Pal expects the following bytes next:
Target channel (byte 3, values = 1-4)
Voltage (Byte 4, units: [0:255 = -10V:+10V])
80: Abort all ongoing pulse trains (no subsequent bytes required)
81: Disconnect from software client and store all current parameters to EEPROM memory (no subsequent bytes required)
82: Set a channel to loop the current pulse train indefinitely without being triggered
Pulse Pal expects the following bytes next:
Target channel (byte 3, values = 1-4)
Loop status (0 = normal operation, 1 = indefinite loop)
The following commands require an in-depth knowledge of Pulse Pal's circuitry and firmware to avoid causing malfunctions.
These functions should not be included in a typical software client, and are provided for development and hardware debugging purposes only.
83: Clear stored parameters from non-volatile (EEPROM) memory (no subsequent bytes required)
84: Write a page of data to EEPROM memory (Be sure to avoid over-writing a 32-byte page boundary!)
Pulse Pal expects the following bytes next:
Memory address (byte 3, where to begin writing data, = Memory page number *31)
nBytesToWrite (byte 4, Total length of subsequent data in bytes, up to one page length)
Data (bytes 5 to [4+nBytesToWrite))
85: Read data from EEPROM memory (page boundaries irrelevant)
Pulse Pal expects the following bytes next:
Memory address (byte 3, where to begin reading data)
nBytesToWrite (byte 4, number of bytes to read)
Pulse Pal will return the bytes requested.
86: Set logic level of a digital i/o line on the Maple microcontroller
87: Read logic level of a digital i/o line on the Maple microcontroller
Pulse Pal expects the following bytes next:
If the pin mode is set for output, pulse pal will reconfigure it for input before reading the line.
Pulse Pal will return the state of the line (0 = low/0V, 1 = high/3.3V)
88: Read voltage of an analog i/o line on the Maple microcontroller**
Pulse Pal expects the following bytes next:
Target I/O line (more info about the i/o lines here, note that not all lines can be read as analog)
Pulse Pal will configure the target i/o line for analog input.
Pulse Pal will return the voltage on the pin (0-3.3V).
89: Send 6 character client ID string (displayed on top line of oLED display while connected to software client, i.e. "MATLAB" or "PYTHON")
Pulse Pal expects the following bytes next:
Characters 1-6
___________________________________________________________________________________________________________________________________________________
*USBPacketCorrectionByte
The firmware uses this byte to correct for a standing issue with the LeafLabs maple driver.
In Windows XP only, sending LeafLabs Maple a USB packet message of length 64 bytes will cause its client to freeze. Messages longer than 200 bytes appear to be sent as full packets, and the system will freeze if the remainder packet is 64 bytes in length.
When sending custom pulse times and voltages, many pulse train lengths would thus result in a software crash. To compensate for this, a Windows XP compatible client must send an extra pulse after messages that would cause a 64-byte packet to be sent, which the firmware then knows to ignore if you set USBPacketCorrectionByte equal to 1. Clients written for Windows 7 and Unix based systems can always set USBPacketCorrectionByte equal to "0" if desired. An example of how USBPacketCorrectionByte and the extra byte is implemented in the Pulse Pal MATLAB client is shown below:
if nStamps < 200
USBPacketLengthCorrectionByte = uint8((rem(nStamps, 16) == 0));
else
nFullPackets = ceil(length(Output)/200) - 1;
RemainderMessageLength = nStamps - (nFullPackets*200);
if uint8((rem(RemainderMessageLength, 16) == 0)) || (uint8((rem(nStamps, 16) == 0)))
USBPacketLengthCorrectionByte = 1;
else
USBPacketLengthCorrectionByte = 0;
end
end
fwrite(PulsePalSystem.SerialPort, USBPacketLengthCorrectionByte, 'uint8');
if USBPacketLengthCorrectionByte == 1
fwrite(PulsePalSystem.SerialPort, nStamps+1, 'uint32');
else
fwrite(PulsePalSystem.SerialPort, nStamps, 'uint32');
end
% In the remainder of the code, an extra timestamp and voltage are added to the intended pulse train if USBPacketLengthCorrectionByte = 1, and the values are sent.
** Analog reads on Pulse Pal
The trigger channel pins on Maple are capable of analog reads. However, they are protected by a digital optical isolator IC which distorts analog signals.
*** cycles = time expressed as a number of consecutive 50μs cycles (e.g. 1ms = 20 cycles)