hil_read_encoder_buffer :: Quanser C Functions

navigation bar

hil_read_encoder_buffer

Reads the specified number of samples from the encoder channels at the indicated sampling rate.

Description

The hil_read_encoder_buffer function reads the specified number of samples from the encoder input channels at the given sampling rate. The function does not return until the data has been read.

Prototype

t_error 
hil_read_encoder_buffer(t_card card, t_clock clock, t_double frequency, t_uint32 num_samples,
                        const t_uint32 encoder_channels[], t_uint32 num_channels, t_int32 buffer[]);

Parameters

t_card card

A handle to the board, as returned by hil_open

t_clock clock

The clock used to time the operation. Note that some clocks allow faster sampling rates than others. See Clocks for more information on clocks.

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

t_double frequency

The frequency in Hertz at which to sample the encoder input channels. For example, if frequency is set to 1000, then the hil_read_encoder_buffer function will read all the selected channels every millisecond.

t_uint32 num_samples

The number of samples to collect. Each "sample" consists of all the encoder input channels specified. For example, if frequency is set to 1000 and num_samples is set to 5000, then the hil_read_encoder_buffer function will return after 5 seconds with 5000 samples. If 3 channels have been selected, then the output buffer will contain 15,000 elements.

const t_uint32 [] encoder_channels

An array containing the channel numbers of the encoder inputs to be read.

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

t_uint32 num_channels

The number of channels specified in the encoder_channels array.

t_int32 [] buffer

An array for receiving the counter values read from the encoder inputs. The array must contain num_channels * num_samples elements. The array is organized as a linear array of samples, with each sample consisting of a group of channels. For example, if encoder input channels 0, 1 and 3 are being read, than the data appears in the array as follows, where the numbers correspond to channel numbers:

...

This ordering is equivalent to defining the buffer as:

t_int32 buffer[num_samples][num_channels];

If the buffer is defined this way then pass the buffer as the buffer argument using the syntax: &buffer[0][0].

Return value

The return value is the number of samples successfully read. 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_READ_ENCODER_BUFFER_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_TOO_MANY_ENCODER_INPUT_CHANNELS

Too many encoder input channels were specified.

QERR_INVALID_ENCODER_INPUT_CHANNEL

One of the encoder input 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.

QERR_OUT_OF_MEMORY

There is not enough memory to perform the operation.

Requirements

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

Examples


/*
* Reads 5000 samples at 1 kHz from the first four encoder input channels, using SYSTEM_CLOCK_1.
*/

t_uint32 channels[] = { 0, 1, 2, 3 };
t_double frequency  = 1000;
t_uint32 samples    = 5000;

static t_int32 buffer[5000][4];
t_error result = hil_read_encoder_buffer(board, SYSTEM_CLOCK_1, frequency, samples,
                                         channels, ARRAY_LENGTH(channels), &buffer[0][0]);

navigation bar