Contributions:KeysightGenerator

2024-10-28T21:21:21Z

Nkbryson: /* Usage */

==Synopsis==
An extension allowing the user to program a waveform to be triggered through a state change (using a Keysight EDU33212A).

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/KeysightGenerator

==Versioning==
===Author===
Robert Ellis (ellis@neurotechcenter.org)
===Version History===
* 07/18/2023 Initial release

==Functional Description==

This extension gives the user near full control over the 2 channels on a Keysight EDU33212A. It allows the user to configure a waveform for each channel and define states to both trigger and halt the waveform for both channels. There are several parameters that can create and adjust the waveforms for each channel, which will be further explained in the parameter section.

==Integration into BCI2000==

In the CMake configuration window, check off "EXTENSIONS_KEYSIGHTGENERATOR", then generate the project. In the Visual Studio window, rebuild the signal source module you wish to use.

After rebuilding, to enable it, append --LogKeysight=1 to the same command line as the source module.

==Usage==

Prior to working with the Keysight EDU33212A, the drivers and API must be installed onto your local machine. Navigate to this link https://www.keysight.com/us/en/lib/software-detail/computer-software/keysight-instrument-control-bundle-download-1184883.html and download the IO libraries suite and the Command Expert software. Use the default installations of these tools. Note, these tools are only configured for windows platforms, so the Keysight Extension is only available on windows machines as of now.

On the EDU33212A, press "System". In the right-hand side of the display there will be 5 options, press the button next to the second (I/O Config). Record the VISA address under whichever connection method will be employed.

Connect the EDU33212A to your computer. The extension should work through either a USB or LAN connection. After following the steps mentioned above to integrate the extension into BCI2000, there should be a section in the configuration window labelled "Keysight", with the first parameter labelled "Address". In this field, enter the VISA Address recorded previously. You may then configure the waveform for both channels before use, as will be further explained.

==Parameters==

For each channel, there are 14 sections in the Keysight configuration window. Each window serves a different function for the waveform. The first 7 serve to initialize the carrier waveform, while the remaining serve to modify it. The rest of this section will be divided by each of the 14 windows, each section applying to both channels. Some parameters will have limits determined by other parameters. However, when the signal is getting initialized the validity of each parameter will be checked, and an error, along with a message, will be thrown if the specifications are invalid.

===Channel===
This section defines the shape of the carrier waveform.

'''UsingCh:'''
This parameter lets the system know to execute commands on the specified channel. If this is left unchecked, none of the parameters for the channel will be read and the waveform will not be generated.

'''Load:'''
Sets expected output termination. Should equal the load impedance attached to the output.

'''Function:'''
Allows the user to select from a sinusoid, square, triangle, ramp, pulse, noise, DC, pseudo-random binary sequence, or a "User" function, which can be defined by the user in a subsequent window.

'''Phase:'''
Sets the phase of the waveform (degrees). For User waveforms this applies by shifting the indices of the inserted data to mimic a phase shift, however the user can also manually adjust the order of their data to attain the same results. A phase of 0 will result in a wave that is not offset.

'''Frequency:'''
Sets the frequency of the output (Hz). For user functions, it adjusts the sampling rate to attain the specified frequency.

'''Voltage:'''
Sets the amplitude of the waveform (V)

'''Voltage Offset:'''
Adjusts the offset of the waveform (V)

'''HighVoltage:'''
Introduces a limit to the maximum voltage the waveform can generate (V). An error will be thrown if the other parameters specify a waveform with voltage exceeding this parameter. To disable, enter 0 in this field, as well as in the "LowVoltage" field.

'''LowVoltage:'''
Introduces a limit to the lowest voltage the waveform can generate (V). An error will be thrown if the other parameters specify a waveform with voltage exceeding this parameter. To disable, enter 0 in this field, as well as in the "HighVoltage" field.

'''TriggerOnState:'''
Name of the state that will be read to determine when the waveform is generated.

'''TriggerOnValue:'''
Value of the specified state (TriggerOnState) which, when attained, will turn the channel on.

'''TriggerOffState:'''
Name of the state that will be read to determine when generation of the waveform is stopped.

'''TriggerOffValue:'''
Value of the specified state (TriggerOffState) which, when attained, will turn the channel off.

===Square===
This section is only read when "Square" is selected as the function in the Channel window

'''SquareDutyCycle:'''
Adjusts the percent of the cycle in which the voltage spike occurs (default is 50%)
<gallery mode="packed" widths=550px heights=425px>
File:Sqdutycycle.PNG|Square wave with duty cycle of 25%
</gallery>

===Ramp===
This section is only read when "Square" is selected as the function in the Channel window

'''RampSymmetry:'''
Adjusts the shape of the ramp, determines what percent of the period the voltage rise occurs, and fills the remaining with a drop back to the specified voltage offset level. (a ramp waveform that increases in voltage over time is set at 100%, one that decreases over time is set at 0%, and a triangle-like waveform is set at 50%)

<gallery mode="packed" widths=550px heights=425px>
File:RampSym.PNG|Ramp with 33% symmetry (note that the peak occurs 33% of the way through the period)
</gallery>

===Pulse===
This section is only read when "Pulse" is selected as the function in the Channel window

'''PulseDutyCycle:'''
This sets the percent of the period the pulse will occur. Similar to duty cycle for a square wave. This is equivilent to "PulseWidth". Set to 0 if you'd rather define "PulseWidth".

'''PulsePeriod:'''
This is equivalent to the frequency. Set to 0 if you'd rather use the frequency parameter in the channel window.

'''PulseWidth:'''
Sets the duration for which the pulse will occur. This is equivilent to "PulseDutyCycle". Set to 0 if you'd rather define "PulseDutyCycle".

'''PulseLead:'''
Adjusts the pulse edge time on the leading edge(nanoseconds).

'''PulseTrail:'''
Adjusts the pulse edge time on the trailing edge (nanoseconds)

Photos are not very enlightening due to incredibly fast pulse edge times, so will be omitted.

===UserFunction===
This section is only read when "User" is selected as the function in the Channel window or any of the Modification windows.

'''UserData:'''
A list of data points describing the wave that will be generated. It is necessary for the data to follow the format of number, comma, space for each entry, or else the values will not be read.
Ex: (0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1) would generate a wave that looks like a ramp. Removing the spaces inbetween values would result in the list not being read.

<gallery mode="packed" widths=550px heights=425px>
File:Arb.PNG|Generation of a [https://en.wikipedia.org/wiki/Bump_function bump] function using User wave
</gallery>

===PRBS===
This section is only read when "PRBS" is selected as the function in the Channel window or any of the Modification windows.

'''PRBSBitRate:'''
Sets the bit rate for the pseudo-random binary sequence (PRBS) sequence (akin to adjusting frequency) (bits/sec)

'''PRBSData:'''
Sets the PRBS type. The number after PN corresponds to the maximum shift register length in bits. Learn more [https://en.wikipedia.org/wiki/Pseudorandom_binary_sequence here].

'''PRBSTransition:'''
Sets the leading and trailing edge transition time (ns)
<gallery mode="packed" widths=550px heights=425px>
PRBS10bitsecPN7.PNG|PRBS wave using 10 bits/sec and PN7
</gallery>
<gallery mode="packed" widths=550px heights=425px>
PRBS50bitsecPN7.PNG|PRBS wave using 50 bits/sec and PN7
</gallery>

===AM===
Enables/adjusts amplitude modification of the carrier signal. If F(t) is our carrier wave and g(t) is the AM wave, the resulting wave resembles something like g(t)F(t)

'''ModulateAmplitude:'''
This parameter enables amplitude modification of the signal. If this is unchecked, the rest of the parameters will not be read.

'''AMFunction:'''
Selects the shape of the amplitude modification of the signal (similar to defining the shape of the "envelope").

'''AMDepth:'''
Sets the intensity at which the amplitude is modified. A higher percent gives the resulting signal a more defined envelope. (ex: 100% gives the signal a shape of |A|*C, while 50% gives a weaker envelope).

'''AMFrequency:'''
Adjusts the frequency of the envelope (can be though of as the frequency of g(t))
<gallery mode="packed" widths=550px heights=425px>
File:AM.PNG|3Hz sin amplitude modulation wave (with 100% depth) applied to 30Hz sin wave
</gallery>

===FM===
Enables/adjusts frequency modification of the carrier signal. If F(t) is our carrier wave and g(t) is the FM wave, the resulting wave resembles something like F(g(t)t)

'''ModulateFrequency:'''
This parameter enables frequency modification of the signal. If this is unchecked, the rest of the parameters will not be read.

'''FMFunction:'''
Selects the shape of the frequency modification of the signal.

'''FMDepth:'''
Sets the intensity at which the frequency is modified. A higher percent gives the resulting signal frequency character that looks more like this signal. (Can be thought of as the amplitude of g(t))

'''FMFrequency:'''
Adjusts the frequency of the modifying signal (can be thought of as the frequency of g(t))

<gallery mode="packed" widths=550px heights=425px>
File:FM15Hzcarrier10Hzfreqanddepthmodifier.PNG|10Hz sin frequency modulation wave (with 10Hz of depth) applied to 15Hz sin wave
</gallery>

===PM===
Enables/adjusts phase modification of the carrier signal. If F(t) is our carrier wave and g(t) is the FM wave, the resulting wave resembles something like F(t+g(t))

'''ModulatePhase:'''
This parameter enables phase modification of the signal. If this is unchecked, the rest of the parameters will not be read.

'''PMFunction:'''
Selects the shape of the phase modification of the signal.

'''PMDeviation:'''
Sets the intensity at which the phase is modified. A higher percent results in function giving more phase deviation to the carrier wave. (Can be thought of as the amplitude of g(t))

'''PMFrequency:'''
Adjusts the frequency of the modifying signal (can be thought of as the frequency of g(t))

<gallery mode="packed" widths=550px heights=425px>
File:PM.PNG|4Hz sin phase modulation wave (with 180 degrees of depth) applied to 10Hz sin wave
</gallery>

===PWM===

'''ModulatePulseWidth:'''
This parameter enables pulse width modification of the signal. If this is unchecked, the rest of the parameters will not be read.

'''PWMFunction:'''
Selects the shape of the pulse width modification of the signal.

'''PWMDutyCycle:'''
Sets the duty cycle deviation in the percent of the period (%)

'''PWMFrequency:'''
Adjusts the frequency of the modifying signal (can be thought of as the frequency of g(t)) (Hz)

<gallery mode="packed" widths=550px heights=425px>
File:PWM.PNG|200Hz pulse with 90% duty cycle pulse width modulated by 1Hz ramp with 50ns deviation and 15% duty cycle
</gallery>

===Sweep===
This section allows the user to modify the sweep functionality. This functionality varies the frequency of the signal from the frequency defined in the Channel window to another, higher frequency specified in this section.

'''Sweep:'''
This parameter enables the sweep functionality on the specified channel. If this is left unchecked, the rest of the parameters will not be read.

'''SweepEndFrequency:'''
Sets the frequency at which the signal attains when the process reaches its end.

'''SweepTime:'''
Sets the time required for the end frequency to be reached per cycle.

'''SweepHoldTime:'''
Sets the time for which the end frequency will be held once it is attained before starting a new cycle.

'''SweepLogSpacing:'''
When checked, this parameter changes the speed at which the frequency adjusts from being based on a linear scale to a logarithmic scale.

<gallery mode="packed" widths=550px heights=425px>
File:Sweep.PNG|Sweep starting at 10Hz, finishing at 50Hz (over 1s) and holding for 1s
</gallery>

===Burst===
This section allows the user to modify the burst functionality. This functionality executes a defined amount of cycles of the waveform before pausing for a set amount of time, then repeats.

'''Burst:'''
This parameter enables the burst functionality on the specified channel. If this is left unchecked, the rest of the parameters will not be read.

'''BurstCycles:'''
Specifies the number of periods the signal will be generated before entering a rest phase for the remainder of the burst.

'''BurstPeriod:'''
Specifies the time duration of each burst. This value must be greater than or equal to the time required to complete the specified amount of cycles for the waveform.

'''BurstPhase:'''
Adjusts the starting point of the burst, as well as the amplitude of the wave during the resting phase. For example, setting the BurstPhase to 90 for a sinusoidal wave will result in the resting phase coinciding with the peak of the wave, 0 will coincide with the midpoint, and 270 will coincide with the trough.

<gallery mode="packed" widths=550px heights=425px>
File:SinBurst.PNG|10 Cycle burst with a 20Hz sin wave
</gallery>

===Sync===
This section is the only section which effects both channels.

'''PhaseSync:'''
When enabled, this parameter will cause waveforms to be phase locked (up to the specified phase offset) when simultaneously generated. This also applies after one of the signals has been turned off then re-executed.
<gallery mode="packed" widths=550px heights=425px>
File:Sync.PNG|Two in sync sin waves
</gallery>

==Notes==
It does not appear that settings that modify functions (ramp's symmetry parameter, for example) affect modulation. However, one may generate data that resembles such a signal, then enter this in the "UserData" parameter and select "User" for the function in whatever modulation setting will be used.

For data stored in a MATLAB array, the following can be used to convert it into a format appropriate for use in the "UserData" parameter, and to copy it to your clipboard:

str="";
for i=1:length(data)
if i==length(data)
str=str+string(data(i));
else
str=str+string(data(i))+", ";
end
end
clipboard('copy', str)

==See also==

BCI2000 Wiki - User contributions [en]

Contributions:KeysightGenerator