hil_write :: Quanser C Functions

navigation bar

hil_write

Writes to analog, PWM, digital and/or other outputs immediately.

Description

The hil_write function writes to the specified output channels immediately. The function does not return until the data has been written.

Warning Many cards allow the digital I/O lines to be programmed as inputs or outputs. The digital I/O lines are configured as inputs or outputs using the hil_set_digital_directions function. All the channels which will be used as digital outputs must be configured as outputs using this function. Failure to configure the digital I/O may result in the hil_write function failing to write those outputs.

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 hil_set_pwm_mode function for details.

Prototype

t_error hil_write(t_card card,
                  const t_uint32 analog_channels[],  t_uint32 num_analog_channels,
                  const t_uint32 pwm_channels[],     t_uint32 num_pwm_channels,
                  const t_uint32 digital_channels[], t_uint32 num_digital_channels,
                  const t_uint32 other_channels[],   t_uint32 num_other_channels,
                  const t_double  analog_buffer[],
                  const t_double  pwm_buffer[],
                  const t_boolean digital_buffer[],
                  const t_double  other_buffer[]);

Parameters

t_card card

A handle to the board, as returned by hil_open .

const t_uint32 [] analog_channels

An array containing the channel numbers of the analog outputs to be written.

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

If no analog channels are required then this parameter may be NULL. In this case, num_analog_channels must be zero.

t_uint32 num_analog_channels

The number of channels specified in the analog_channels array. This parameter may be zero.

const t_uint [] pwm_channels

An array containing the channel numbers of the PWM outputs to be written.

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

If no PWM channels are required then this parameter may be NULL. In this case, num_pwm_channels must be zero.

t_uint32 num_pwm_channels

The number of channels specified in the pwm_channels array. This parameter may be zero.

const t_uint32 [] digital_channels

An array containing the channel numbers of the digital outputs to be written.

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

If no digital channels are required then this parameter may be NULL. In this case, num_digital_channels must be zero.

t_uint32 num_digital_channels

The number of channels specified in the digital_channels array.

const t_uint32 [] other_channels

An array containing the channel numbers of the other outputs to be written.

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

If no other channels are required then this parameter may be NULL. In this case, num_other_channels must be zero.

t_uint32 num_other_channels

The number of channels specified in the other_channels array. This parameter may be zero.

const t_double [] analog_buffer

An array containing the voltage values to write to the analog outputs. The array must contain num_analog_channels elements. Each element in the analog_buffer array corresponds to the same element in the analog_channels array.

If no analog channels were specified then this parameter may be NULL.

const t_double [] pwm_buffer

An array containing the values to write to the PWM outputs. How these values are interpreted depends on the PWM mode. The PWM mode is configured using the hil_set_pwm_mode function. The array must contain num_pwm_channels elements. Each element in the pwm_buffer array corresponds to the same element in the pwm_channels array.

If no PWM channels were specified then this parameter may be NULL.

const t_boolean [] digital_buffer

An array containing the binary values to write to the digital outputs. The array must contain num_digital_channels elements. Each element in the digital_buffer array corresponds to the same element in the digital_channels array.

If no digital channels were specified then this parameter may be NULL.

const t_double [] other_buffer

An array containing the values to write to the other outputs. The array must contain num_other_channels elements. Each element in the other_buffer array corresponds to the same element in the other_channels array.

If no other channels were specified then this parameter may be NULL.

Return value

The return value is 0 if the outputs are written successfully. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message .

Error codes

QERR_HIL_WRITE_NOT_SUPPORTED

This function is not supported by the board-specific HIL driver for this board type.

QERR_INVALID_CARD_HANDLE

An invalid card handle was passed as an argument. Once a card has been closed using hil_close the card handle is invalid.

QERR_MISSING_ANALOG_OUTPUTS

The analog_channels argument is NULL. If the number of channels is greater than zero then a channel vector must be provided.

QERR_MISSING_ANALOG_OUTPUT_BUFFER

The analog_buffer argument is NULL. If the number of channels is greater than zero then a buffer must be provided.

QERR_TOO_MANY_ANALOG_OUTPUT_CHANNELS

Too many analog output channels were specified.

QERR_INVALID_ANALOG_OUTPUT_CHANNEL

One of the analog output channels that was specified is not a valid channel number. Channel numbers range from 0 to one less than the number of channels.

QERR_MISSING_PWM_OUTPUTS

The pwm_channels argument is NULL. If the number of channels is greater than zero then a channel vector must be provided.

QERR_MISSING_PWM_OUTPUT_BUFFER

The pwm_buffer argument is NULL. If the number of channels is greater than zero then a buffer must be provided.

QERR_TOO_MANY_PWM_OUTPUT_CHANNELS

Too many PWM output channels were specified.

QERR_INVALID_PWM_OUTPUT_CHANNEL

One of the PWM output channels that was specified is not a valid channel number. Channel numbers range from 0 to one less than the number of channels.

QERR_HARDWARE_CLOCK_IN_USE

One of the PWM output channels is based on a hardware clock that is already in use for another operation and the board-specific HIL driver for this board does not permit sharing of the hardware clock.

QERR_WRONG_CLOCK_MODE

One of the PWM output channels is based on a hardware clock that is in the wrong mode for this operation. Use the hil_set_clock_mode function to change modes.

QERR_MISSING_DIGITAL_OUTPUTS

The digital_channels argument is NULL. If the number of channels is greater than zero then a channel vector must be provided.

QERR_MISSING_DIGITAL_OUTPUT_BUFFER

The digital_buffer argument is NULL. If the number of channels is greater than zero then a buffer must be provided.

QERR_TOO_MANY_DIGITAL_OUTPUT_CHANNELS

Too many digital output channels were specified.

QERR_INVALID_DIGITAL_OUTPUT_CHANNEL

One of the digital output channels that was specified is not a valid channel number. Channel numbers range from 0 to one less than the number of channels.

QERR_MISSING_OTHER_OUTPUTS

The other_channels argument is NULL. If the number of channels is greater than zero then a channel vector must be provided.

QERR_MISSING_OTHER_OUTPUT_BUFFER

The other_buffer argument is NULL. If the number of channels is greater than zero then a buffer must be provided.

QERR_TOO_MANY_OTHER_OUTPUT_CHANNELS

Too many other output channels were specified.

QERR_INVALID_OTHER_OUTPUT_CHANNEL

One of the other output channels that was specified is not a valid channel number. Channel numbers range from 0 to one less than the number of channels.

QERR_DRIVER_INCOMPATIBLE_WITH_BOARD_DLL

The board-specific HIL driver passed an invalid parameter to the operating system specific kernel-level driver for the board. The board-specific HIL driver is likely not compatible with the operating system specific kernel-level driver for the board. Make sure both are up-to-date and compatible versions.

QERR_INTERNAL_BUFFER_TOO_SMALL

The board-specific HIL driver used an internal buffer that was too small for the operating system specific kernel-level driver for the board. The board-specific HIL driver is likely not compatible with the operating system specific kernel-level driver for the board. Make sure both are up-to-date and compatible versions.

QERR_OUT_OF_REQUIRED_SYSTEM_RESOURCES

There are not enough system resources to perform the requested operation. Try rebooting, requesting fewer samples, or adding more memory to your machine.

Requirements

Include Files	Libraries
hil.h	hil.lib;quanser_runtime.lib;quanser_common.lib

Examples


/*
* Writes to two analog output channels, two PWM output channels and four digital output channels.
*/

t_uint32 analog_channels[]  = { 0, 1 };
t_uint32 pwm_channels[]     = { 0, 1 };
t_uint32 digital_channels[] = { 0, 1, 2, 3 };

t_double  analog_buffer[]  = { 0.5, -0.5 };
t_int32   pwm_buffer[]     = { -1000, 1000 };
t_boolean digital_buffer[] = { 0, 1, 0, 1 };

t_error result = hil_write(board
                         , analog_channels,  ARRAY_LENGTH(analog_channels)
                         , pwm_channels,     ARRAY_LENGTH(pwm_channels)
                         , digital_channels, ARRAY_LENGTH(digital_channels)
                         , NULL,             0   /* no other channels */
                         , analog_buffer
                         , pwm_buffer
                         , digital_buffer
                         , NULL
                         );

navigation bar