Next Previous Contents

6. Comedilib reference

Reference of structures:

typedef struct comedi_t_struct comedi_t;

typedef struct{
        double min;
        double max;
        unsigned int unit;
}comedi_range;

typedef 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;
}comedi_sv_t;

6.1 comedi_loglevel()

int comedi_loglevel(int loglevel);

This function affects the output of debugging and error messages from comedlib. By increasing the loglevel, additional debugging information will be printed. This function returns the previous loglevel. Some debugging information will only be printed if comedilib was compiled with this debugging information included. The loglevel can also be affected by the environment variable COMEDI_LOGLEVEL. 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.

COMEDILIB_LOGLEVEL=2

Comedilib prints an error message whenever 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.

6.2 comedi_open

comedi_t *comedi_open(char *fn);

Opens a comedi device specified by the filename fn. Returns NULL on error. Returns a handle that is given as a parameter to other comedilib functions.

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

void comedi_close(comedi_t *it);

Closes a device previously opened by comedi_open().

void comedi_perror(const char *s); char *comedi_strerror(int errnum); int comedi_errno(void);

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.

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 comedilib call. An unrecognized error number will return a pointer to the string "undefined error", or similar.

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().

6.3 comedi_fileno()

int comedi_fileno(comedi_t *it);

The function comedi_fileno returns the integer descriptor for the handle it. If it is an invalid comedi_t pointer, the function returns -1 and sets the appropriate comedilib error value.

6.4 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.

6.5 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 0x010203, which is the version code for version 1.2.3.

6.6 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.

6.7 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.

6.8 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:

6.9 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().

6.10 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.

6.11 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.

6.12 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, 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.

6.13 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.

6.14 comedi_trigger()

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.

Complete information about comedi commands is given in the manual page comedi(8).

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

The functions comedi_to_phys() and comedi_from_phys() convert sample values to/from physical units. 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/ will be written to.

6.15 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); int comedi_data_write(comedi_t *it,unsigned int subd,unsigned int chan, unsigned int range,unsigned int aref,lsampl_t data);

These functions read or write a single sample on the channel that is specified by the comedi device it, the subdevice subd, and the channel chan. For the operation, 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.

The function 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.

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

On sucess, these functions return 0. If there is an error, -1 is returned.

Valid analog reference numbers are:

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

6.16 comedi_sv_init()

int comedi_sv_init(comedi_sv_t *it,comedi_t *dev,unsigned int subd,unsigned int chan);
int comedi_sv_update(comedi_sv_t *it);
int comedi_sv_measure(comedi_sv_t *it,double *data);

The special functions comedi_sv_*() are designed to make it easy to accurately measure slowly varying analog inputs. A slowly varying input is one that is effectively constant over the course of approximately 100 A/D conversions. However, since these conversions can sometimes be pre-empted by scheduling, for most purposes, a slowly varying signal should be effectively constant for greater than 20 ms (the default Linux timeslice).

By averaging many A/D conversions of a relatively constant signal, it is possible to get a better measurement of the signal than a single A/D conversion. In general, the uncertainty of the measurement decreases as the square root of the number of samples. This is limited by the rate that which the signal varies, and ultimately by the spurious free dynamic range of the A/D converter.

6.17 comedi_get_timer()

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


Next Previous Contents