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.

function PsoWaveformConfigureMode($axis as axis, $waveformMode as PsoWaveformMode)

Selects the output mode of the waveform module.

Arguments

$axis The axis on which to select the output mode of the waveform module.

$waveformMode Mode selection for the waveform module output.

Refer to the PsoWaveformMode enumeration that follows.

Enabling Waveform Generation

By default, the PSO Waveform module is disabled and will 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 will trigger a waveform based on the active parameters.

function PsoWaveformOn($axis as axis)

Enables the waveform module, allowing PSO events to trigger it.

Arguments

$axis The axis on which to enable the waveform module.

function PsoWaveformOff($axis as axis)

Disables the waveform module, preventing PSO events from triggering it.

Arguments

$axis The axis on which to disable the waveform module.

Controlling Waveform Activation

By default, the PSO Waveform module, if enabled, will generate the configured waveform (pulse, PWM, or toggle) immediately when it receives an output event from the PSO Event module. If desired, you can use the PsoWaveformConfigureDelay() function to specify a time delay from the reception of the output event to the start of the waveform generation. Specify the desired delay, in microseconds, using the $delayTime argument.

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

function PsoWaveformConfigureDelay($axis as axis, $delayTime as real)

Configures the waveform module to wait for the specified time after a PSO event before beginning to output a waveform.

Arguments

$axis The axis on which to configure the waveform output delay.

$delayTime The delay time in microseconds.

You can also use the PsoWaveformExternalSyncOn() function to synchronize waveform generation with an external synchronization signal. When you activate this feature, the PSO Waveform module will not generate the configured waveform when an output event is received until the rising edge of the synchronization signal occurs.

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, iXC4, XC4, iXC4e, XC4e, iXC6e, XC6e, iXI4, XI4, XL4s, iXL5e, XL5e, iXR3, XR3.

function PsoWaveformExternalSyncOn($axis as axis)

Configures the waveform module to wait for the rising edge of the external sync signal before beginning to output a waveform.

Arguments

$axis The axis on which to enable external sync option.

If already enabled, use the PsoWaveformExternalSyncOff() function to allow waveform generation to occur without waiting for the rising edge of the synchronization signal.

function PsoWaveformExternalSyncOff($axis as axis)

Disables the external sync option for the waveform module.

Arguments

$axis The axis on which to disable external sync option.

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.

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.

function PsoWaveformExternalSyncConfigureDelayMode($axis as axis, $delayMode as PsoWaveformExternalSyncDelayMode)

Configures the delay mode of the waveform module when you use the external synchronization signal.

Arguments

$axis The axis on which to configure the external sync delay mode.

$delayMode The external sync delay mode.

Refer to the PsoWaveformExternalSyncDelayMode enumeration that follows.

enum PsoWaveformExternalSyncDelayMode
AfterExternalSync = 0
BeforeExternalSync = 1
end

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. Use the $scalingMode argument to select the Waveform parameter(s) to which to apply the scaling configuration. Use the $scalingInput argument to select the input to the scaling operation. Use the $inputRange argument to specify the valid range of input values for the scaling operation.

For the DrivePulseStreamVelocity input option, specify this 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 this 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 or Configuring PWM Mode Parameters sections on this page for more information.

function PsoWaveformScalingConfigure($axis as axis, $scalingMode as PsoWaveformScalingMode, $scalingInput as PsoWaveformScalingInput, $inputRange[2] as real, $scaleFactorRange[2] as real)

Specifies the configuration of the optional PSO waveform scaling feature.

Arguments

$axis The axis on which to configure PSO waveform scaling.

$scalingMode Specifies the waveform parameters to which to apply the PSO waveform scaling.

$scalingInput Specifies the input to the PSO waveform scaling.

$inputRange Specifies the range of values in which the configured input will be used to calculate the scale factor to apply to the waveform parameters.

$scaleFactorRange Specifies the valid range of scale factor outputs from the PSO waveform scaling feature.

Refer to the PsoWaveformScalingMode and PsoWaveformScalingInput enumerations that follow.

To activate the Waveform Scaling feature, use the PsoWaveformScalingOn() function.

function PsoWaveformScalingOn($axis as axis)

Activates PSO waveform scaling.

Arguments

$axis The axis on which to activate PSO waveform scaling.

To deactivate the Waveform Scaling feature, use the PsoWaveformScalingOff() function. This function does not clear any configuration specified by the PsoWaveformScalingConfigure() function.

function PsoWaveformScalingOff($axis as axis)

Deactivates PSO waveform scaling.

Arguments

$axis The axis on which to deactivate PSO waveform scaling.

Pulse Mode

Configuring Pulse Mode Parameters

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 will be 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 are not required to use fixed values or drive array values for all parameters simultaneously. They can be mixed and matched as desired, but you must configure each parameter individually. To specify fixed values for a parameter, use the PsoWaveformConfigurePulseFixedTotalTime(), PsoWaveformConfigurePulseFixedOnTime(), or PsoWaveformConfigurePulseFixedCount() function. When the module is configured to use a fixed value for a parameter, the module will apply the value of the parameter to each generated waveform.

function PsoWaveformConfigurePulseFixedTotalTime($axis as axis, $totalTime as real)

Configures the fixed total time of the waveform module output in pulse mode, which will be applied to all pulses. The total time specifies the full period of the pulse.

Arguments

$axis The axis on which to configure the total time.

$totalTime The total time in microseconds.

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.

function PsoWaveformConfigurePulseFixedOnTime($axis as axis, $onTime as real)

Configures the fixed on time of the waveform module output in pulse mode, which will be applied to all pulses. The on time specifies the active portion of the pulse period.

Arguments

$axis The axis on which to configure the on time.

$onTime The on time in 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.

function PsoWaveformConfigurePulseFixedCount($axis as axis, $pulseCount as integer)

Configures the fixed pulse count of the waveform module output in pulse mode, which will be applied to all pulses. The pulse count specifies the number of periods that will be generated from a single PSO event.

Arguments

$axis The axis on which to configure the number of pulses.

$pulseCount The integer number of pulses.

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

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.

function PsoWaveformConfigurePulseArrayTotalTimes($axis as axis, $driveArrayStartAddress as integer, $numberOfPoints as integer, $enableRepeat as integer)

Configures an array of total times for a sequence of waveform module outputs in pulse mode. The total time specifies the full period of the pulse.

Arguments

$axis The axis on which to configure the total times.

$driveArrayStartAddress The byte-addressable index of the drive array where the first total time is stored.

$numberOfPoints The number of total times to be read from the drive array.

$enableRepeat Configures PSO to continue to use total times after the last total time in the array is used, starting over at the first total time.

function PsoWaveformConfigurePulseArrayOnTimes($axis as axis, $driveArrayStartAddress as integer, $numberOfPoints as integer, $enableRepeat as integer)

Configures an array of on times for a sequence of waveform module outputs in pulse mode. The on time specifies the active portion of the pulse period.

Arguments

$axis The axis on which to configure the on times.

$driveArrayStartAddress The byte-addressable index of the drive array where the first on time is stored.

$numberOfPoints The number of on times to be read from the drive array.

$enableRepeat Configures PSO to continue to use on times after the last on time in the array is used, starting over at the first on time.

function PsoWaveformConfigurePulseArrayCounts($axis as axis, $driveArrayStartAddress as integer, $numberOfPoints as integer, $enableRepeat as integer)

Configures an array of pulse counts for a sequence of waveform module outputs in pulse mode. The pulse count specifies the number of periods that will be generated from a single PSO event.

Arguments

$axis The axis on which to configure the pulse counts.

$driveArrayStartAddress The byte-addressable index of the drive array where the first pulse count is stored.

$numberOfPoints The number of pulse counts to be read from the drive array.

$enableRepeat Configures PSO to continue to use pulse counts after the last pulse count in the array is used, starting over at the first pulse count.

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.

function PsoWaveformApplyPulseConfiguration($axis as axis)

Checks for a valid configuration of pulse mode parameters and applies the configuration to the waveform module.

Arguments

$axis The axis on which to apply the pulse configuration.

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 on when the output can be driven. You can specify multiple condition options simultaneously. To do this, set the $pulseMask argument to the bitwise OR of all desired condition options, as defined in the PsoWaveformPulseMask enumeration. All condition options that you specify must be simultaneously active in order for the pulse module output to be active.

function PsoWaveformConfigurePulseMask($axis as axis, $pulseMask as integer)

Configures additional conditions to disable the PSO waveform output in pulse mode.

Arguments

$axis The axis on which to configure PSO waveform pulse mode masking options.

$pulseMask A bitmask of PSO waveform pulse mode masking options. Use the values from the PsoWaveformPulseMask enum.

Refer to the PsoWaveformPulseMask enumeration that follows.

Configuring Pulse Truncation

By default, the PSO Waveform module output in Pulse mode can be immediately turned off prior to the completion of the active period. This can occur in two cases: 1) if the PsoOutputOff() function is issued, or 2) if the PSO Waveform Pulse mask feature is activated and one or more mask conditions become inactive. If you want to ensure 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.

function PsoWaveformConfigurePulseTruncation($axis as axis, $preventTruncation as integer)

Allows or prevents the waveform module from outputting truncated waveform outputs in pulse mode.

Arguments

$axis The axis on which to configure the pulse truncation prevention feature.

$preventTruncation Configures the waveform module to not allow the generation of truncated waveform outputs in pulse mode.

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.

function PsoWaveformConfigurePulseEventQueue($axis as axis, $maxQueuedEvents as integer)

Configures the maximum number of events in the queue. Each event in the queue will cause a PSO waveform pulse generation to occur after the active waveform period completes.

Arguments

$axis The axis on which to configure the queue for the PSO waveform pulse event.

$maxQueuedEvents The maximum number of events to put in the queue.

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.

function PsoWaveformConfigurePwmTotalTime($axis as axis, $totalTime as real)

Configures the fixed total time of the waveform module output in PWM mode. The total time specifies the full period of the PWM signal.

Arguments

$axis The axis on which to configure the total time.

$totalTime The total time in microseconds.

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.

function PsoWaveformConfigurePwmOnTimes($axis as axis, $driveArrayStartAddress as integer, $numberOfPoints as integer, $enableRepeat as integer)

Configures an array of on times for a sequence of waveform module outputs in PWM mode. The on time specifies the variable active portion of the PWM signal.

Arguments

$axis The axis on which to configure the on times.

$driveArrayStartAddress The byte-addressable index of the drive array where the first on time is stored.

$numberOfPoints The number of on times to be read from the drive array.

$enableRepeat Configures PSO to continue to use on times after the last on time in the array is used, starting over at the first on time.

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.

function PsoWaveformApplyPwmConfiguration($axis as axis)

Checks for a valid configuration of PWM mode parameters and applies the configuration to the waveform module.

Arguments

$axis The axis on which to apply the PWM configuration.