Creates a task for writing to PWM outputs.

Namespace:  Quanser.Hardware
Assembly:  Quanser.Hardware.Hil (in Quanser.Hardware.Hil.dll)

Syntax

Visual Basic (Declaration)
Public Function TaskCreatePwmWriter ( _
	samplesInBuffer As Integer, _
	channels As Integer() _
) As Hil..::.Task
C#
public Hil..::.Task TaskCreatePwmWriter(
	int samplesInBuffer,
	int[] channels
)
Visual C++
public:
Hil..::.Task^ TaskCreatePwmWriter(
	int samplesInBuffer, 
	array<int>^ channels
)
JavaScript
function taskCreatePwmWriter(samplesInBuffer, channels);

Parameters

samplesInBuffer
Type: System..::.Int32

The number of samples in the task buffer. The WritePwm(Int32, array<Double>[]()[]) method cannot write more samples than this in a single call. If the task buffer underflows because WritePwm(Int32, array<Double>[]()[]) has not been called in time to add data to the task buffer then the next call to WritePwm(Int32, array<Double>[]()[]) will throw a HilException exception. See Hil..::.Task for more information on task buffers.

channels
Type: array< System..::.Int32 >[]()[]

An array containing the numbers of the PWM output channels to be written by the task. Channel numbers are zero-based. Thus, channel 0 is the first channel, channel 1 the second channel, etc.

Select a board type from the list for board-specific details: .

Return Value

Returns a Hil..::.Task interface for manipulating the task, including starting and stopping the task, and for writing the samples output by the task "in the background".

Remarks

The TaskCreatePwmWriter method creates a task for writing to the specified PWM output channels. The task allows other operations to be performed while the PWM outputs are being written "in the background". The data written to the PWM outputs is read from an internal circular "task buffer". This data may be written into the task buffer at any time using the WritePwm(Int32, array<Double>[]()[]) method. The size of this task buffer is determined by the samplesInBuffer parameter.

The task does not actually start writing to the PWM outputs until the Start(Hil..::.Clock, Double, Int32) method is called. In order for data to be available in the task buffer as soon as the task starts, store data in the buffer using WritePwm(Int32, array<Double>[]()[]) prior to starting the task. Since the task writes to the PWM outputs at the sampling rate specified when the task is started, it will be reading data from the task buffer at that rate. Thus, WritePwm(Int32, array<Double>[]()[]) must be called to add more data to the task buffer before all the data in the buffer is depleted. Otherwise the task will have no data to write to the PWM outputs and will throw a HilException the next time WritePwm(Int32, array<Double>[]()[]) is called. See Hil..::.Task for more information on tasks.

The interpretation of the PWM samples to be written depends upon the PWM mode. Typically the data is interpreted as a duty cycle, in which a magnitude of 0.0 denotes a 0% duty cycle and magnitude of 1.0 indicates a 100% duty cycle. The sign determines the polarity of the output for those boards supporting bidirectional PWM outputs. However, other PWM modes are possible with some boards. Refer to the SetPwmMode(array<Int32>[]()[], array<Hil..::.PwmMode>[]()[]) method for details.

Examples

This example illustrates how to write PWM outputs using a task. The task writes PWM channels 0-1 every millisecond using a hardware clock. The data to write is computed every 0.1 seconds, with 100 samples being computed at a time. The task runs for 5 seconds before stopping. Exceptions are ignored for simplicity.
C# Copy Code
int [] channels        = { 0, 1 };
double frequency       = 1000;
int    samples         = 5000;
int    samplesInBuffer = frequency;
int    samplesToWrite  = 100;

double [] buffer = new double [samplesToWrite * channels.Length];
Hil.Task task;

/* ... fill buffer with samplesToWrite samples ... */

/* Create task */
task = Hil.TaskCreatePwmWriter(samplesInBuffer, channels);

/* Preload task buffer with first samplesToWrite samples prior to starting task */
task.WritePwm(samplesToWrite, buffer);

/* Start task */
task.Start(Hil.Clock.Hardware0, frequency, samples);
for (int index = samples; index < samples; index += samples_to_write) {
    /* ... fill buffer with next samplesToWrite samples ... */

    /*
        Block (if necessary) waiting to write next samplesToWrite samples.
        However, it only waits for space in the task buffer (which can contain
        samplesInBuffer samples), not for the data to actually be written to
        the hardware. Hence, it will not block until the task buffer is full
        (a little over one second in this example since samplesInBuffer is 1000).
    */
    task.WritePwm(samplesToWrite, buffer);
}

/* Flush to make sure all data has been written to the hardware before stopping task */
task.Flush();
task.Stop();
Visual Basic Copy Code
Dim channels() As Integer = {0, 1}
Dim frequency as Double = 1000
Dim samples As Integer = 5000
Dim samplesInBuffer As Integer = frequency
Dim samplesToWrite As Integer = 100

Dim buffer(samplesToWrite * channels.Length - 1) As Double
Dim task As Hil.Task
Dim index As Integer

' ... fill buffer with samplesToWrite samples ...

' Create task
task = card.TaskCreatePwmWriter(samplesInBuffer, channels)

' Preload task buffer with first samplesToWrite samples prior to starting task
task.WritePwm(samplesToWrite, buffer)

' Start task
task.Start(Hil.Clock.Hardware0, frequency, samples)
For index = 0 To samples - 1 Step samplesToWrite
    ' ... fill buffer with next samplesToWrite sample ...

    ' Block (if necessary) waiting to write next samplesToWrite samples.
    ' However, it only waits for space in the task buffer (which can contain
    ' samplesInBuffer samples), not for the data to actually be written to
    ' the hardware. Hence, it will not block until the task buffer is full
    ' (a little over one second in this example since samplesInBuffer is 1000).
    task.WritePwm(samplesToWrite, buffer)
Next

' Flush to make sure all data has been written to the hardware before stopping task
task.Flush()
task.Stop()
Visual C++ Copy Code
array<int>^ channels        = { 0, 1 };
double      frequency       = 1000;
int         samples         = 5000;
int         samplesInBuffer = frequency;
int         samplesToWrite  = 100;

array<double>^ buffer = gcnew array<double>(samplesToWrite * channels->Length);
Hil::Task^ task;

/* ... fill buffer with samplesToWrite samples ... */

/* Create task */
task = card->TaskCreatePwmWriter(samplesInBuffer, channels);

/* Preload task buffer with first samplesToWrite samples prior to starting task */
task->WritePwm(samplesToWrite, buffer);

/* Start task */
task->Start(Hil::Clock::Hardware0, frequency, samples);
for (int index = 0; index < samples; index += samplesToWrite) {
    /* ... fill buffer with next samplesToWrite samples ... */

    /*
        Block (if necessary) waiting to write next samplesToWrite samples.
        However, it only waits for space in the task buffer (which can contain
        samplesInBuffer samples), not for the data to actually be written to
        the hardware. Hence, it will not block until the task buffer is full
        (a little over one second in this example since samplesInBuffer is 1000).
    */
    task->WritePwm(samplesToWrite, buffer);
}

/* Flush to make sure all data has been written to the hardware before stopping task */
task->Flush();
task->Stop();

Exceptions

ExceptionCondition
Quanser.Hardware..::.HilException If the task cannot be created then an exception is thrown. This situtation typically arises if the board does not support PWM outputs or tasks.

See Also