PSO Waveform Functions

The PSO Waveform module lets you generate a configurable waveform that will be driven onto the PSO Waveform module output each time that the output event from the PSO Event module occurs. The PSO Waveform module can be configured in three different modes: Pulse, PWM, and Toggle.

The PSO Waveform module also contains a variety of advanced features, such as allowing you to specify a delay between event and waveform generation, or synchronizing the waveform generation with an external input.

Configuring Waveform Mode

Use the PsoWaveformConfigureMode() function to select one of these modes of operation for the PSO Waveform module:

Pulse mode: the waveform module outputs a configurable pulse stream on each event.
PWM mode: the waveform module outputs a configurable pulse width modulation signal, updating the duty cycle on each event.
Toggle mode: the PSO Waveform module output simply toggles between active and inactive on each event.

Refer to the enum PsoWaveformMode for the $waveformMode argument values.

Enabling Waveform Generation

By default, the PSO Waveform module is disabled and does not generate a waveform in response to an output event from the PSO Event module. To enable waveform generation, use the PsoWaveformOn() function. Once enabled, each event received from the PSO Event module triggers a waveform based on the active parameters.

Use the PsoWaveformOff() function to disable the waveform module, which prevents PSO events from triggering it.

Controlling Waveform Activation

By default, the PSO Waveform module, if enabled, generates the configured waveform (pulse, PWM, or toggle) immediately when it receives an output event from the PSO Event module. You can use the PsoWaveformConfigureDelay() function to specify a time delay from when the output event is received and when it starts. Specify the delay in microseconds with the $delayTime argument.

IMPORTANT: The delay that you specify cannot exceed the time between consecutive output events or waveform generation might not occur.

You can use the PsoWaveformExternalSyncOn() function to synchronize waveform generation with an external synchronization signal. When you activate this feature, the PSO Waveform module generates the configured waveform when the rising edge of the synchronization signal occurs, not immediately.

HARDWARE: The PSO Waveform External Sync feature requires a high speed input or dedicated PSO external sync signal. This feature is available only on the drives that follow: GI4, GL4, SI4, iXA4, XA4, iXC4, XC4, iXC4e, XC4e, iXC6e, XC6e, iXI4, XI4, XL4s, iXL5e, XL5e, iXR3, XR3.

Use the PsoWaveformExternalSyncOff() function to stop external synchronization enabled by the PsoWaveformExternalSyncOn() function.

You can use the PsoWaveformExternalSyncConfigureDelayMode() function to configure the interaction between the delay set in PsoWaveformConfigureDelay() and the external synchronization signal. To specify the delay mode, use the $delayMode argument.

Use the enum PsoWaveformExternalSyncDelayMode values to set the $delayMode argument. If you set the $delayMode argument to AfterExternalSync, then after an output event, the PSO Waveform module waits for the rising edge of the synchronization signal and then waits for the specified delay time before it generates the configured waveform. If you set the $delayMode argument to BeforeExternalSync, then after an output event, the PSO Waveform module waits for the specified delay time and then waits for the rising edge of the external synchronization signal before it generates the configured waveform.

Configuring Waveform Scaling

By default, the PSO Waveform module uses the values you specify for the Total Time and On Time waveform parameters to generate a waveform. You can optionally use the Waveform Scaling feature to linearly scale one or more of these parameters based on changes in a selected input. When configured, the Waveform Scaling feature monitors the value of the configured input. If the input value is equal to or less than the lower bound of the configured input range, the waveform parameter(s) will be multiplied by the value given as the lower bound of the scale factor range. If the input value is greater than or equal to the upper bound of the configured input range, the waveform parameter(s) will be multiplied by the value given as the upper bound of the scale factor range. If the input value falls within the configured input range, the waveform parameter(s) will be multiplied by the value calculated by the equation that follows:

To configure the Waveform Scaling feature, use the PsoWaveformScalingConfigure() function. The $scalingMode argument specifies the waveform parameter(s) to which to apply the PSO waveform scaling. Use the enum PsoWaveformScalingMode values to set this argument. The $scalingInput argument specifies the input to the PSO waveform scaling. Use the enum PsoWaveformScalingInput values to set this argument. Use the $inputRange argument to specify the valid range of input values for the scaling operation.

For the DrivePulseStreamVelocity input option, specify the range in values of units per second. See the Pulse Stream section of the Device Functions topic for more information on the Drive Pulse Stream feature.

For the AnalogInput input options, specify the range in values of Volts. You must specify an input value range where the lower bound of the range is less than the upper bound of the range.

Use the $scaleFactorRange argument to specify the valid range of scale factors to apply to the active Waveform parameters. You must specify the scale factor range as a pair of real values. Additionally, the values of the Waveform parameters after scaling must still be valid values for those parameters. Refer to the Configuring Pulse Mode Parameters with Fixed Values or Configuring PWM Mode Parameters sections on this page for more information.

To activate waveform scaling, use the PsoWaveformScalingOn() function. To deactivate waveform scaling, use the PsoWaveformScalingOff() function. This function does not clear any configuration specified by the PsoWaveformScalingConfigure() function.

Pulse Mode

You can operate the PSO Waveform module in Pulse mode. This section shows how to configure the fundamental pulse parameters using either fixed or array-based values. It also includes how to apply conditions with a pulse mask, how to use pulse truncation, and how to manage incoming triggers with an event queue.

To operate the PSO Waveform module in Pulse mode you must specify these parameters:

Total Time (in microseconds)
On Time (in microseconds)
Pulse Count

When the output event occurs, a waveform is generated with a period equal to the specified Total Time (in microseconds), an active time equal to the specified On Time (in microseconds), and a number of periods equal to the specified Pulse Count. For each of these three parameters, you can configure the module to use a fixed value or to use a sequence of values from the drive array. You do have to use fixed values or drive array values for all parameters at the same time, but you must configure each parameter individually.

After configuring each pulse mode parameter to use the fixed or array option, use the PsoWaveformApplyPulseConfiguration() function to activate the parameters. No pulse mode parameter changes take effect until you issue this function. This function also allows you to change all or part of your pulse mode configuration after the pulse mode has already been activated.

Configuring Pulse Mode Parameters with Fixed Values

To specify fixed values for a parameter, use the PsoWaveformConfigurePulseFixedTotalTime(), PsoWaveformConfigurePulseFixedOnTime(), or PsoWaveformConfigurePulseFixedCount() function. When configured to use a fixed value for a parameter, the module applies the value of the parameter to each generated waveform.

The valid range for the $totalTime is 0.0 to 42,949,672.95 microseconds. The $totalTime argument has a resolution of 0.01 microseconds.

The valid range for the $onTime arguments to the PSO Waveform module functions is 0.0 to 42,949,672.95 microseconds. The $onTime arguments have a resolution of 0.01 microseconds.

The valid range for the $pulseCount argument to the PSO Waveform module functions is 1 to 4,294,967,295.

Configuring Pulse Mode Parameters with an Array of Values

To specify an array of parameter values, use the PsoWaveformConfigurePulseArrayTotalTimes(), PsoWaveformConfigurePulseArrayOnTimes(), or PsoWaveformConfigurePulseArrayCounts() function. Before you use one of these functions, make sure that you already wrote the desired parameter values to the drive array locations you specify with the $driveArrayStartIndex and $numberOfPoints arguments. To write values to the drive array to be used as pulse mode total times or on times, use the DriveArrayWrite() function and specify DriveArrayType.PsoPulseTimes as the $driveArrayType argument. To write values to the drive array to be used as pulse mode counts, use the DriveArrayWrite() function and specify DriveArrayType.PsoPulseCounts as the $driveArrayType argument.

For more information on writing values to the drive array, see the DriveArrayWrite() function in the Device Functions topic. When you use parameters from the drive array, the PSO Waveform module uses the first specified drive array value as the first parameter value. After a waveform is generated, the module uses the next drive array value as the next parameter value. The module continues using values in the drive array in this fashion until the configured number of parameters is reached. Important: if more than one parameter uses drive array values, you must ensure that the number of values you specify is the same for each parameter. You can also use the $enableRepeat argument to instruct the module to use an infinite number of drive array values. In this mode, the module will return to the value at the $driveArrayStartIndex and use the same set of values again after the module uses the last parameter value in the drive array.

Configuring the Pulse Mask

By default, the PSO waveform module in Pulse mode drives any generated waveform onto its output. You can use the PsoWaveformConfigurePulseMask() function to specify conditions for when the output can be driven.

You can specify more than one condition options at the same time. To do this, set the $pulseMask argument to the bitwise OR the condition options as defined in the enum PsoWaveformPulseMask. All condition options that you specify must be active at the same time for the pulse module output to be active.

Configuring Pulse Truncation

By default, the PSO waveform module output in Pulse mode can be immediately turned off before the active period is complete. This occurs for two conditions:

If the PsoOutputOff() function is issued
If the PSO Waveform Pulse mask feature is activated and one or more mask conditions become inactive.

If you want to make sure that the active period of the pulse mode output completes before one of the previously described conditions would cause the output to otherwise be truncated, you can use the PsoWaveformConfigurePulseTruncation() function.

Configuring the Pulse Event Queue

By default, the PSO Waveform module in Pulse mode ignores events that occur while the module is actively generating a pulse. You can use the PsoWaveformConfigurePulseEventQueue() function to let the PSO Waveform module store events that occur during an active pulse period until it gets to the maximum number of events. After the active pulse period completes, the PSO Waveform module immediately generates pulse periods for each event in the pulse event queue. Each pulse period uses the pulse mode parameter values at the time the event was stored in the queue. The PSO Waveform module generates pulse periods until the queue is empty. Events that occur during the pulse periods caused by the pulse event queue are also stored in the queue and are limited to the specified maximum number of events.

Use the $maxQueuedEvents argument to specify the maximum number of events that can be stored in the queue. After you configure the pulse event queue, you can disable the queue by specifying 0 for the $maxQueuedEvents argument. The valid range for the $maxQueuedEvents argument is 0 to 15 events.

Configuring PWM Mode Parameters

To operate the PSO Waveform module in PWM mode you must specify these parameters:

Total Time (in microseconds)
On Time (in microseconds)

The PSO Waveform module requires that you specify two parameters for PWM mode operation: Total Time (in microseconds) and On Time (in microseconds). Unlike Pulse mode, the Total Time parameter will always be specified as a fixed value, and the On Time parameter will always be specified as an array of values from the drive array. When the first output event occurs, the waveform module will output a pulse width modulation signal with a period specified by the Total Time parameter and a duty cycle specified by the first array value used as the On Time parameter. On each subsequent output event, the duty cycle will update to the next on time array value at the conclusion of the active period. Use the PsoWaveformConfigurePwmTotalTime() function to specify the fixed period of the PWM mode output signal.

Use the PsoWaveformConfigurePwmOnTimes() function to specify an array of values to be used as the duty cycles of the PWM mode output signal. Before you use this function, ensure that you have already written the desired parameter values to the drive array locations you specify with the $driveArrayStartIndex and $numberOfPoints arguments. To write values to the drive array to be used as PWM mode on times, use the DriveArrayWrite() function and specify DriveArrayType.PsoPulseTimes as the $driveArrayType argument. For more information on writing values to the drive array, see the DriveArrayWrite() function in the Device Functions topic. When you use on times from the drive array, the PSO Waveform module uses the first specified drive array value as the first on time when the first output event occurs. After the next output event, the module uses the next drive array value as the next on time. The module continues using values in the drive array in this fashion until the configured number of on times is reached. You can also use the $enableRepeat argument to instruct the module to use an infinite number of drive array values. In this mode, the module will return to the value at the $driveArrayStartIndex and use the same set of values again after the module uses the last on time in the drive array.

After configuring each PWM mode parameter, use the PsoWaveformApplyPwmConfiguration() function to activate the parameters. No PWM mode parameter changes occur until you issue this function. This function also allows you to change all or part of your PWM mode configuration after the PWM mode has already been activated.

Related Help Pages

Position Synchronized Output (PSO)