Comedi Documentation: Libcomedi Reference

Next Previous Contents

1.1 Constants and Macros

RANGE_LENGTH() (deprecated)

RANGE_LENGTH(rangetype)

Rangetype values are library-internal tokens that represent an array of range information structures. These numbers are primarily used for communication between the kernel and library.

The RANGE_LENGTH() macro returns the length of the array that is specified by the rangetype token.

The RANGE_LENGTH() macro is deprecated, and should not be used in new applications. It is scheduled to be removed from the header file at version 1.0. Binary compatibility may be broken for version 1.1.

1.2 Data Types and Structures

comedi_t

The data type comedi_t is used to represent an open Comedi device. A valid comedi_t pointer is returned by a successful call to comedi_open(), and should be used for subsequent access to the device. It is a transparent type, and pointers to type comedi_t should not be dereferenced.

sampl_t

The data type sampl_t is one of the generic types used to represent data values in libcomedi. It is used in a few places where a shorter data type is useful, but is limited to 16 bits on the i386 architecture.

lsampl_t

The data type lsampl_t is one of the generic types used to represent data values in libcomedi. It is currently defined to be unsigned int.

comedi_trig_struct (deprecated)

The comedi_trig structure


struct comedi_trig_struct{
        unsigned int subdev;            /* subdevice */
        unsigned int mode;              /* mode */
        unsigned int flags;
        unsigned int n_chan;            /* number of channels */
        unsigned int *chanlist;         /* channel/range list */
        sampl_t *data;                  /* data list, size depends on subd flags */
        unsigned int n;                 /* number of scans */
        unsigned int trigsrc;
        unsigned int trigvar;
        unsigned int trigvar1;
        unsigned int data_len;
        unsigned int unused[3];
}

The comedi_trig structure is a control structure used by the COMEDI_TRIG ioctl, an older method of communicating instructions to the driver and hardware. Use of Comedi triggers is deprecated, and should not be used in new applications.

comedi_sv_t


struct comedi_sv_struct{
        comedi_t *dev;
        unsigned int subdevice;
        unsigned int chan;

        /* range policy */
        int range;
        int aref;
        
        /* number of measurements to average (for ai) */
        int n;

        lsampl_t maxdata;
}

The comedi_sv_t structure is used by the comedi_sv_*() functions to provide a simple method of accurately measuring slowly varying inputs. See the relevant section for more details.

1.3 Functions

comedi_close()

void comedi_close(comedi_t *it);

Closes a device previously opened by comedi_open().

The return type of this function will change to int, in order to match fclose.

Source: /lib/comedi.c

comedi_data_read()

int comedi_data_read(comedi_t *it,unsigned int subd,unsigned int chan, unsigned int range,unsigned int aref,lsampl_t *data);

Reads a single sample on the channel that is specified by the comedi device it, the subdevice subd, and the channel chan. For the A/D conversion (if appropriate), the device is configured to use range specification range and (if appropriate) analog reference type aref. Analog reference types that are not supported by the device are silently ignored.

comedi_data_read() reads one data value from the specified channel and places the data value that is read in the location pointed to by data.

On sucess, comedi_data_read() returns 0. If there is an error, -1 is returned.

Valid analog reference numbers are:

AREF_GROUND Reference to analog ground
AREF_COMMON Reference to analog common
AREF_DIFF Differential reference
AREF_OTHER Board-specific meaning

Valid data values returned by these function is an unsigned integer less than or equal to maxdata, which is channel-dependent. Conversion of these data value to physical units can be performed by comedi_to_phys().

Source: /lib/data.c

comedi_data_write()

int comedi_data_write(comedi_t *it,unsigned int subd,unsigned int chan, unsigned int range,unsigned int aref,lsampl_t data);

Writes a single sample on the channel that is specified by the comedi device it, the subdevice subd, and the channel chan. For the D/A conversion (if appropriate), the device is configured to use range specification range and (if appropriate) analog reference type aref. Analog reference types that are not supported by the device are silently ignored.

comedi_data_write() writes the data value specified by the argument data to the specified channel.

On sucess, comedi_data_write() returns 0. If there is an error, -1 is returned.

Valid analog reference numbers are:

AREF_GROUND Reference to analog ground
AREF_COMMON Reference to analog common
AREF_DIFF Differential reference
AREF_OTHER Board-specific meaning

Valid data values used by these functions is an unsigned integer less than or equal to maxdata, which is channel-dependent. Conversion of physical units to these data value can be performed by comedi_from_phys().

Source: /lib/data.c

comedi_dio_bitfield();

int comedi_dio_bitfield(comedi_t *it,unsigned int subd,unsigned int write_mask,unsigned int *bits);

The function comedi_dio_bitfield() allows multiple channels to be read simultaneously from a digital input or digital I/O device. The parameter write_mask and the value pointed to by bits are interpreted as bit fields, with the least significant bit representing channel 0. For each bit in write_mask that is set, the cooresponding bit in *bits is written to the digital output channel. Each digital input channel is read, and the result placed in the approprate bits in *bits.

The current implementation reads and writes bits using separate system calls, which is not ideal. When the kernel driver supports simultaneous reading/writing, this will be fixed in the library.

It should be noted that it is not possible to access channels greater than 31 using this function.

Source: /lib/dio.c

comedi_dio_config()

int comedi_dio_config(comedi_t *it,unsigned int subd,unsigned int chan,unsigned int dir);

The function comedi_dio_config configures individual channels in a digital I/O subdevice to be either input or output, depending on the value of parameter dir. Depending on the capabilities of the hardware device, multiple channels may be affected by a single call to comedi_dio_config.

Valid directions are:

COMEDI_INPUT
COMEDI_OUTPUT

Source: /lib/dio.c

comedi_dio_read()

int comedi_dio_read(comedi_t *it,unsigned int subd,unsigned int chan,unsigned int *bit);

The function reads the status of channel chan belonging to the digital input subdevice subd of device it. The result, 0 or 1, is stored in bit. Returns -1 on failure.

This function is equivalent to comedi_data_read(it,subd,chan,0,0,bit).

Source: /lib/dio.c

comedi_dio_write()

int comedi_dio_write(comedi_t *it,unsigned int subd,unsigned int chan,unsigned int bit);

The function writes the value of bit, 0 or 1, to channel chan, belonging to the digital output device subd of device it. Returns -1 on failure.

Source: /lib/dio.c

comedi_fileno()

int comedi_fileno(comedi_t *it);

The function comedi_fileno returns the integer descriptor for the handle it. It is equivalent to the standard function fileno. If it is an invalid comedi_t pointer, the function returns -1 and sets the appropriate libcomedi error value.

Source: /lib/comedi.c

comedi_find_range()

int comedi_find_range(comedi_t *it, unsigned int subdevice, unsigned int chan, unsigned int unit, double min, double max);

The function comedi_find_range tries to locate the optimal (smallest) range for the channel chan belonging to a subdevice of the comedi device it, that includes both min and max in units. If it finds a matching range, it returns its index. If no matching range is available, it returns -1.

Valid units are:

UNIT_volt
UNIT_mA
UNIT_none

Source: /lib/range.c

comedi_errno()

int comedi_errno(void);

The function comedi_errno() returns an integer describing the most recent comedilib error. This integer may be used as the errnum parameter for comedi_strerror().

When a libcomedi function fails, it usually returns -1 or NULL, depending on the return type. An internal library variable stores an error number, which can be retrieved with comedi_errno(). This error number can be converted to a human-readable form by the functions comedi_perror() and comedi_strerror().

These functions are intended to mimic the behavior of the standard C library functions perror(), strerror, and errno(). In particular, libcomedi functions sometimes return an error that is generated by the C library; the Comedi error message in this case is the same as the C library.

Source: /lib/error.c

comedi_find_subdevice_by_type()

int comedi_find_subdevice_by_type(comedi_t *it,int type,unsigned int start_subdevice);

The function comedi_find_subdevice_by_type tries to locate a subdevice belonging to comedi device it, having type type, starting with the subdevice start_subdevice. If it finds the requested subdevice, it returns its index. If it does not locate the requested subdevice, it returns -1 and sets the comedi error number to "subdevice not found". If there is an error, the function returns -1 and sets the appropriate error.

For subdevice types, see the manual page for the function comedi_get_subdevice_type().

Source: /lib/get.c

comedi_from_phys()

lsampl_t comedi_from_phys(double data, comedi_range *rng, lsampl_t maxdata);

Converts data given in physical units (data) into sample values (lsampl_t, between 0 and maxdata). The parameter rng represents the conversion information to use, and the parameter maxdata represents the maximum possible data value for the channel that the data will be written to.

Source: /lib/range.c

comedi_get_board_name()

char *comedi_get_board_name(comedi_t *it);

The function comedi_get_board_name returns a pointer to a string containing the name of the device. This pointer is valid until the comedi descriptor it is closed. This function returns NULL if there is an error.

Source: /lib/get.c

comedi_get_driver_name()

char *comedi_get_driver_name(comedi_t *it);

The function comedi_get_driver_name returns a pointer to a string containing the name of the driver being used by comedi for the comedi device represented by it. This pointer is valid until the comedi descriptor it is closed. This function returns NULL if there is an error.

Source: /lib/get.c

comedi_get_maxdata()

lsampl_t comedi_get_maxdata(comedi_t *it,unsigned int subdevice,unsigned int chan);

The function comedi_get_maxdata() returns the maximum valid data value for channel chan of subdevice subdevice belonging to the comedi device it This function returns 0 on error.

Source: /lib/get.c

comedi_get_n_channels()

int comedi_get_n_channels(comedi_t *it,unsigned int subdevice);

The function comedi_get_n_channels() returns the number of channels of the subdevice belonging to the comedi device it and having index subdevice. This function returns -1 on error.

Source: /lib/get.c

comedi_get_n_ranges()

int comedi_get_n_ranges(comedi_t *it,unsigned int subdevice, unsigned int chan);

The function comedi_get_n_ranges() returns the number of ranges of the channel chan belonging to the subdevice of the comedi device it. This function returns -1 on error.

Source: /lib/range.c

comedi_get_n_subdevices()

int comedi_get_n_subdevices(comedi_t *it);

The function comedi_get_n_subdevices returns the number of subdevices associated with the comedi descriptor it, or -1 if there is an error.

Source: /lib/get.c

comedi_get_range()

comedi_range * comedi_get_range(comedi_t *it,unsigned int subdevice,unsigned int chan,unsigned int range);

The function comedi_get_range returns a pointer to a comedi_range structure that contains information that can be used to convert sample values to or from physical units. The pointer is valid until the comedi device it is closed. If there is an error, NULL is returned.

Source: /lib/get.c

comedi_get_rangetype()

int comedi_get_rangetype(comedi_t *it,unsigned int subdevice,unsigned int chan);

The function comedi_get_rangetype() returns an integer that represents the number of range specifications available for a particular channel chan of the subdevice subdevice, as well as a conversion table to convert sample values to/from physical units.

The macro RANGE_LENGTH(rangetype) can be used to determine the number of range specifications for a given range type.

Source: /lib/get.c

comedi_get_subdevice_type()

int comedi_get_subdevice_type(comedi_t *it,unsigned int subdevice);

The function comedi_get_subdevice_type() returns an integer describing the type of subdevice that belongs to the comedi device it and has the index subdevice. The function returns -1 is there is an error.

Valid subdevice types are:

COMEDI_SUBD_UNUSED Subdevice has no functionality, i.e., a place-holder.
COMEDI_SUBD_AI Analog input
COMEDI_SUBD_AO Analog output
COMEDI_SUBD_DI Digital input
COMEDI_SUBD_DO Digital output
COMEDI_SUBD_DIO Digital input/output. Channels are configurable as to whether they are inputs or outputs.
COMEDI_SUBD_COUNTER Counter
COMEDI_SUBD_TIMER Timer
COMEDI_SUBD_MEMORY Memory, e.g., EEPROM or dual-ported RAM
COMEDI_SUBD_CALIB Calibration DACs
COMEDI_SUBD_PROC Processor or DSP

Source: /lib/get.c

comedi_get_timer() (deprecated)

int comedi_get_timer(comedi_t *it,unsigned int subdev, double freq,unsigned int *trigvar, double *actual_freq);

The function comedi_get_timer converts the frequency freq to a number suitable to send to the driver in a comedi_trig structure. This function remains for compatibility with very old versions of Comedi, that converted sampling rates to timer values in the libary. This conversion is now done in the kernel, and every device has the timer type nanosec_timer, indicating that timer values are simply a time specified in nanoseconds.

This function is deprecated and should not be used in new applications.

Source: /lib/timer.c

comedi_get_version_code()

int comedi_get_version_code(comedi_t *it);

The function comedi_get_version_code() returns the version code of the currently running comedi module. The version code is of the form 0x01072b, which is the version code for version 1.7.43.

This function is of limited usefulness. A typical mis-application of this function is to use it to determine if a certain feature is supported. If the application needs to know of the existence of a particular feature, an existence test function should be written and put in the libcomedi source.

Source: /lib/get.c

comedi_loglevel()

int comedi_loglevel(int loglevel);

This function affects the output of debugging and error messages from libcomedi. By increasing the loglevel, additional debugging information will be printed. This function returns the previous loglevel. Error messages and debugging are printed to the stream stderr. The loglevel can also be affected by the environment variable COMEDI_LOGLEVEL.

In order to conserve resources, some debugging information is disabled when libcomedi is compiled.

The meaning of the loglevels is as follows:

COMEDILIB_LOGLEVEL=0 Comedilib prints nothing.
COMEDILIB_LOGLEVEL=1 (default) Comedilib only prints error messages when there is a self-consistency error (i.e., internal bug).
COMEDILIB_LOGLEVEL=2 Comedilib prints an error message when an invalid parameter is passed to comedilib.
COMEDILIB_LOGLEVEL=3 Comedilib prints an error message whenever an error is generated in the comedilib library or is generated in the C library when called by comedilib.
COMEDILIB_LOGLEVEL=4 Comedilib prints a lot of debugging messages.

Bugs: Libcomedi doesn't currently have much debugging information.

Source: /lib/error.c

comedi_open()

comedi_t *comedi_open(char *filename);

Opens a comedi device specified by the filename filename. Returns NULL on error. On sucess, it returns a handle that is given as a parameter to other libcomedi functions.

You are not supposed to have access to the internals of the comedi_t structure.

Bugs: Not strictly identical to fopen

Source: /lib/comedi.c

comedi_perror()

void comedi_perror(const char *s);

When a comedilib function fails, it usually returns -1 or NULL, depending on the return type. An internal library variable stores an error number, which can be retrieved with comedi_errno(). This error number can be converted to a human-readable form by the functions comedi_perror() and comedi_strerror().

These functions are intended to mimic the behavior of the standard C library functions perror(), strerror, and errno(). In particular, comedilib functions sometimes return an error that is generated inside the C library; the comedi error message in this case is the same as the C library.

The function comedi_perror() prints an error message to stderr. The error message consists of the argument string, a colon, a space, a description of the error condition, and a new line.

Bugs: Does not support internationalization.

Source: /lib/error.c

comedi_strerror()

*comedi_strerror(int errnum);

The function comedi_strerror() returns a pointer to a character string describing the comedilib error errnum. The persistence of the returned pointer is undefined, and should not be trusted after the next libcomedi call. An unrecognized error number will return a pointer to the string "undefined error", or similar.

Bugs: Does not support internationalization.

Source: /lib/error.c

comedi_sv_init()

int comedi_sv_init(comedi_sv_t *sv,comedi_t *dev,unsigned int subd, unsigned int chan);

comedi_sv_init initializes the slow varying comedi structure sv of the device dev, the subdevice subd (analog input) and the channel chan. The slow varying comedi structure sv of type comedi_sv_t specifies the signal measurement. The default number of averaged samples is 100. Returns zero on success, -1 on error.

Bugs: comedi_sv_* was very poorly designed.

Source: /lib/sv.c

comedi_sv_update()

int comedi_sv_update(comedi_sv_t *sv);

The function comedi_sv_update updates the slow varying comedi structure sv. Returns zero on success, -1 on error.

Source: /lib/sv.c

int comedi_sv_measure()

int comedi_sv_measure(comedi_sv_t *it,double *data);

comedi_sv_measure measures the slow variing signal. The measurement is specified by the slow varying comedi structure sv, the result is stored in data. On success returns the number of samples, -1 on error.

Source: /lib/sv.c

comedi_to_phys()

double comedi_to_phys(lsampl_t data, comedi_range *rng, lsampl_t maxdata);

Converts data given in sample values (lsampl_t, between 0 and maxdata) into physical units (double). The parameter rng represents the conversion information to use, and the parameter maxdata represents the maximum possible data value for the channel that the data was read.

Source: /lib/range.c

comedi_trigger() (deprecated)

int comedi_trigger(comedi_t *it,comedi_trig *trig);

The function comedi_trigger instructs comedi to perform the command specified by the trigger structure trig. Results depend on the particular command being issued. If there is an error, -1 is returned.

Lifetime: removal at 1.0.

Source: /lib/comedi.c

comedi_get_timer()


int comedi_get_timer(comedi_t *it,unsigned int subdev,double freq,unsigned int *trigvar,
        double *actual_freq);

Next Previous Contents

1. Libcomedi Reference

1.1 Constants and Macros

RANGE_LENGTH() (deprecated)

1.2 Data Types and Structures

comedi_t

sampl_t

lsampl_t

comedi_trig_struct (deprecated)

comedi_sv_t

1.3 Functions

comedi_close()

comedi_data_read()

comedi_data_write()

comedi_dio_bitfield();

comedi_dio_config()

comedi_dio_read()

comedi_dio_write()

comedi_fileno()

comedi_find_range()

comedi_errno()

comedi_find_subdevice_by_type()

comedi_from_phys()

comedi_get_board_name()

comedi_get_driver_name()

comedi_get_maxdata()

comedi_get_n_channels()

comedi_get_n_ranges()

comedi_get_n_subdevices()

comedi_get_range()

comedi_get_rangetype()

comedi_get_subdevice_type()

comedi_get_timer() (deprecated)

comedi_get_version_code()

comedi_loglevel()

comedi_open()

comedi_perror()

comedi_strerror()

comedi_sv_init()

comedi_sv_update()

int comedi_sv_measure()

comedi_to_phys()

comedi_trigger() (deprecated)

comedi_get_timer()