View source for Contributions:KeysightGenerator

==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==

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.

== Supported Platforms ==

* Windows XP, Windows Vista, Windows 7 32-bit, Windows 7 64-bit

==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%)

===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%)

===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. 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)

===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.

===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.

'''PRBSTransition:'''
Sets the leading and trailing edge transition time

===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))

===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))

===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))

===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:'''

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

===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.

===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:'''

===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.

==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.

==See also==