doc/comedilib-6.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3 <HEAD>
   4  <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
   5  <TITLE>Comedi Documentation: Comedilib reference</TITLE>
   6  <LINK HREF="comedilib-5.html" REL=previous>
   7  <LINK HREF="comedilib.html#toc6" REL=contents>
   8 </HEAD>
   9 <BODY>
  10 Next
  11 <A HREF="comedilib-5.html">Previous</A>
  12 <A HREF="comedilib.html#toc6">Contents</A>
  13 <HR>
  14 <H2><A NAME="s6">6. Comedilib reference</A></H2>
  15
  16 <P>Reference of structures:
  17 <P>
  18 <BLOCKQUOTE><CODE>
  19 <PRE>
  20 typedef struct comedi_t_struct comedi_t;
  21
  22 typedef struct{
  23         double min;
  24         double max;
  25         unsigned int unit;
  26 }comedi_range;
  27
  28 typedef struct comedi_sv_struct{
  29         comedi_t *dev;
  30         unsigned int subdevice;
  31         unsigned int chan;
  32
  33         /* range policy */
  34         int range;
  35         int aref;
  36
  37         /* number of measurements to average (for ai) */
  38         int n;
  39
  40         lsampl_t maxdata;
  41 }comedi_sv_t;
  42 </PRE>
  43 </CODE></BLOCKQUOTE>
  44 <P>
  45 <H2><A NAME="ss6.1">6.1 comedi_loglevel()</A>
  46 </H2>
  47
  48 <P>
  49 <P>int comedi_loglevel(int loglevel);
  50 <P>
  51 <P>
  52 <P>This function affects the output of debugging and error messages
  53 from comedlib.  By increasing the loglevel, additional debugging
  54 information will be printed.  This function returns the previous
  55 loglevel.  Some debugging information will only be printed if
  56 comedilib was compiled with this debugging information included.
  57 The loglevel can also be affected by the environment
  58 variable COMEDI_LOGLEVEL.  The meaning of the loglevels is as
  59 follows:
  60 <P>COMEDILIB_LOGLEVEL=0
  61 <P>Comedilib prints nothing.
  62 <P>COMEDILIB_LOGLEVEL=1  (default)
  63 <P>Comedilib only prints error messages when there is a
  64 self-consistency error.
  65 <P>COMEDILIB_LOGLEVEL=2
  66 <P>Comedilib prints an error message whenever an invalid
  67 parameter is passed to comedilib.
  68 <P>COMEDILIB_LOGLEVEL=3
  69 <P>Comedilib prints an error message whenever an error is generated
  70 in the comedilib library or is generated in the C library when
  71 called by comedilib.
  72 <P>COMEDILIB_LOGLEVEL=4
  73 <P>Comedilib prints a lot of debugging messages.
  74 <P>
  75 <P>
  76 <P>
  77 <H2><A NAME="ss6.2">6.2 comedi_open</A>
  78 </H2>
  79
  80 <P>
  81 <P>comedi_t *comedi_open(char *fn);
  82 <P>Opens a comedi device specified by the filename fn.  Returns NULL
  83 on error.  Returns a handle that is given as a parameter to other
  84 comedilib functions.
  85 <P>You are not supposed to have access to the structure comedi_t.
  86 <P>void comedi_close(comedi_t *it);
  87 <P>Closes a device previously opened by comedi_open().
  88 <P>void comedi_perror(const char *s);
  89 char *comedi_strerror(int errnum);
  90 int comedi_errno(void);
  91 <P>When a comedilib function fails, it usually returns -1 or
  92 NULL, depending on the return type.  An internal library
  93 variable stores an error number, which can be retrieved with
  94 <CODE>comedi_errno()</CODE>.  This error number can be
  95 converted to a human-readable form by the functions
  96 <CODE>comedi_perror()</CODE> and <CODE>comedi_strerror()</CODE>.
  97 <P>These functions are intended to mimic the behavior of the
  98 standard C library functions <CODE>perror()</CODE>,
  99 <CODE>strerror</CODE>, and <CODE>errno()</CODE>.  In particular,
 100 comedilib functions sometimes return an error that is generated
 101 inside the C library; the comedi error message in this case
 102 is the same as the C library.
 103 <P>The function <CODE>comedi_perror()</CODE> prints an error
 104 message to stderr.  The error message consists of the
 105 argument string, a colon, a space, a description of the error
 106 condition, and a new line.
 107 <P>The function <CODE>comedi_strerror()</CODE> returns a pointer to a
 108 character string
 109 describing the comedilib error <CODE>errnum</CODE>.  The persistence
 110 of the returned pointer is undefined, and should not be trusted
 111 after the next comedilib call.  An unrecognized error number will
 112 return a pointer to the string "undefined error", or similar.
 113 <P>The function <CODE>comedi_errno()</CODE>
 114 returns an integer describing the most recent comedilib error.  This
 115 integer may be used as the <CODE>errnum</CODE> parameter for
 116 <CODE>comedi_strerror()</CODE>.
 117 <P>
 118 <P>
 119 <H2><A NAME="ss6.3">6.3 comedi_fileno()</A>
 120 </H2>
 121
 122 <P>
 123 <P>int comedi_fileno(comedi_t *it);
 124 <P>The function <CODE>comedi_fileno</CODE>
 125 returns the integer descriptor for the handle <CODE>it</CODE>.  If
 126 <CODE>it</CODE> is an invalid <CODE>comedi_t</CODE> pointer, the function
 127 returns -1 and sets the appropriate comedilib error value.
 128 <P>
 129 <P>
 130 <P>
 131 <H2><A NAME="ss6.4">6.4 comedi_get_n_subdevices()</A>
 132 </H2>
 133
 134 <P>
 135 <P>int comedi_get_n_subdevices(comedi_t *it);
 136 <P>The function <CODE>comedi_get_n_subdevices</CODE> returns the
 137 number of subdevices associated with the comedi descriptor
 138 <CODE>it</CODE>, or -1 if there is an error.
 139 <P>
 140 <P>
 141 <H2><A NAME="ss6.5">6.5 comedi_get_version_code()</A>
 142 </H2>
 143
 144 <P>
 145 <P>int comedi_get_version_code(comedi_t *it);
 146 <P>The function <CODE>comedi_get_version_code()</CODE> returns the
 147 version code of the currently running comedi module.  The version
 148 code is of the form 0x010203, which is the version code for
 149 version 1.2.3.
 150 <P>
 151 <P>
 152 <H2><A NAME="ss6.6">6.6 comedi_get_driver_name()</A>
 153 </H2>
 154
 155 <P>
 156 <P>char *comedi_get_driver_name(comedi_t *it);
 157 <P>The function <CODE>comedi_get_driver_name</CODE> returns a pointer
 158 to a string containing the name of the driver being used by comedi
 159 for the comedi device represented by <CODE>it</CODE>.  This pointer is
 160 valid until the comedi descriptor <CODE>it</CODE> is closed.  This
 161 function returns NULL if there is an error.
 162 <P>
 163 <P>
 164 <H2><A NAME="ss6.7">6.7 comedi_get_board_name()</A>
 165 </H2>
 166
 167 <P>
 168 <P>char *comedi_get_board_name(comedi_t *it);
 169 <P>The function <CODE>comedi_get_board_name</CODE> returns a pointer
 170 to a string containing the name of the device.  This pointer is
 171 valid until the comedi descriptor <CODE>it</CODE> is closed.  This
 172 function returns NULL if there is an error.
 173 <P>
 174 <P>
 175 <H2><A NAME="ss6.8">6.8 comedi_get_subdevice_type()</A>
 176 </H2>
 177
 178 <P>
 179 <P>int comedi_get_subdevice_type(comedi_t *it,unsigned int subdevice);
 180 <P>The function <CODE>comedi_get_subdevice_type()</CODE> returns an
 181 integer describing the type of subdevice that belongs to the comedi
 182 device <CODE>it</CODE> and has the index <CODE>subdevice</CODE>.  The
 183 function returns -1 is there is an error.
 184 <P>Valid subdevice types are:
 185 <P>
 186 <UL>
 187 <LI><CODE>COMEDI_SUBD_UNUSED</CODE>
 188 Subdevice has no functionality, i.e., a place-holder.</LI>
 189 <LI><CODE>COMEDI_SUBD_AI</CODE> Analog input</LI>
 190 <LI><CODE>COMEDI_SUBD_AO</CODE> Analog output</LI>
 191 <LI><CODE>COMEDI_SUBD_DI</CODE> Digital input</LI>
 192 <LI><CODE>COMEDI_SUBD_DO</CODE> Digital output</LI>
 193 <LI><CODE>COMEDI_SUBD_DIO</CODE>
 194 Digital input/output.  Channels are configurable as to whether they
 195 are inputs or outputs.</LI>
 196 <LI><CODE>COMEDI_SUBD_COUNTER</CODE>    Counter</LI>
 197 <LI><CODE>COMEDI_SUBD_TIMER</CODE>      Timer</LI>
 198 <LI><CODE>COMEDI_SUBD_MEMORY</CODE>
 199 Memory, e.g., EEPROM or dual-ported RAM</LI>
 200 <LI><CODE>COMEDI_SUBD_CALIB</CODE>
 201 Calibration DACs</LI>
 202 <LI><CODE>COMEDI_SUBD_PROC</CODE>
 203 Processor or DSP</LI>
 204 </UL>
 205 <P>
 206 <P>
 207 <P>
 208 <H2><A NAME="ss6.9">6.9 comedi_find_subdevice_by_type()</A>
 209 </H2>
 210
 211 <P>
 212 <P>int comedi_find_subdevice_by_type(comedi_t *it,int type,unsigned int start_subdevice)
 213 <P>The function <CODE>comedi_find_subdevice_by_type</CODE> tries to
 214 locate a subdevice belonging to comedi device <CODE>it</CODE>,
 215 having type <CODE>type</CODE>, starting with the subdevice
 216 <CODE>start_subdevice</CODE>.  If it finds the requested subdevice,
 217 it returns its index.  If it does not locate the requested
 218 subdevice, it returns -1 and sets the comedi error number to
 219 "subdevice not found".  If there is an error, the function
 220 returns -1 and sets the appropriate error.
 221 <P>For subdevice types, see the manual page for the function
 222 <CODE>comedi_get_subdevice_type()</CODE>.
 223 <P>
 224 <P>
 225 <H2><A NAME="ss6.10">6.10 comedi_get_n_channels()</A>
 226 </H2>
 227
 228 <P>
 229 <P>
 230 <P>int comedi_get_n_channels(comedi_t *it,unsigned int subdevice);
 231 <P>The function <CODE>comedi_get_n_channels()</CODE> returns the number
 232 of channels of the subdevice belonging to the comedi device <CODE>it</CODE>
 233 and having index <CODE>subdevice</CODE>.  This function returns -1 on error.
 234 <P>
 235 <P>
 236 <H2><A NAME="ss6.11">6.11 comedi_get_maxdata()</A>
 237 </H2>
 238
 239 <P>
 240 <P>lsampl_t comedi_get_maxdata(comedi_t *it,unsigned int subdevice,unsigned int chan);
 241 <P>The function <CODE>comedi_get_maxdata()</CODE> returns the maximum
 242 valid data value for channel <CODE>chan</CODE> of subdevice
 243 <CODE>subdevice</CODE> belonging to the comedi device <CODE>it</CODE>
 244 This function returns 0 on error.
 245 <P>
 246 <P>
 247 <H2><A NAME="ss6.12">6.12 comedi_get_rangetype()</A>
 248 </H2>
 249
 250 <P>
 251 <P>int comedi_get_rangetype(comedi_t *it,unsigned int subdevice,unsigned int chan);
 252 <P>The function <CODE>comedi_get_rangetype()</CODE> returns an integer
 253 that represents the number of range specifications available for a
 254 particular channel, as well as a conversion table to convert sample
 255 values to/from physical units.  The macro
 256 <CODE>RANGE_LENGTH(rangetype)</CODE>
 257 can be used to determine the number of range specifications for a given
 258 range type.
 259 <P>
 260 <P>
 261 <H2><A NAME="ss6.13">6.13 comedi_get_range()</A>
 262 </H2>
 263
 264 <P>
 265 <P>comedi_range * comedi_get_range(comedi_t *it,unsigned int subdevice,unsigned int chan,unsigned int range);
 266 <P>The function <CODE>comedi_get_range</CODE> returns a pointer to a
 267 comedi_range structure that contains information that can be used to
 268 convert sample values to or from physical units.  The pointer is valid
 269 until the comedi device <CODE>it</CODE> is closed.  If there is an
 270 error, NULL is returned.
 271 <P>
 272 <P>
 273 <H2><A NAME="ss6.14">6.14 comedi_trigger()</A>
 274 </H2>
 275
 276 <P>
 277 <P>int comedi_trigger(comedi_t *it,comedi_trig *trig);
 278 <P>The function <CODE>comedi_trigger()</CODE> instructs comedi to
 279 perform the command specified by the trigger structure
 280 <CODE>trig</CODE>.  Results depend on the particular command
 281 being issued.  If there is an error, -1 is returned.
 282 <P>Complete information about comedi commands is given in the
 283 manual page comedi(8).
 284 <P>double comedi_to_phys(lsampl_t data,comedi_range *rng,lsampl_t maxdata);
 285 lsampl_t comedi_from_phys(double data,comedi_range *rng,lsampl_t maxdata);
 286 <P>The functions <CODE>comedi_to_phys()</CODE> and
 287 <CODE>comedi_from_phys()</CODE> convert sample values to/from physical
 288 units.  The parameter <CODE>rng</CODE> represents the conversion
 289 information to use, and the parameter <CODE>maxdata</CODE> represents
 290 the maximum possible data value for the channel that the data was read/
 291 will be written to.
 292 <P>
 293 <P>
 294 <P>
 295 <H2><A NAME="ss6.15">6.15 comedi_data_read()</A>
 296 </H2>
 297
 298 <P>
 299 <P>int comedi_data_read(comedi_t *it,unsigned int subd,unsigned int chan,
 300 unsigned int range,unsigned int aref,lsampl_t *data);
 301 int comedi_data_write(comedi_t *it,unsigned int subd,unsigned int chan,
 302 unsigned int range,unsigned int aref,lsampl_t data);
 303 <P>These functions read or write a single sample on the channel that
 304 is specified by the comedi device <CODE>it</CODE>, the
 305 subdevice <CODE>subd</CODE>, and the channel <CODE>chan</CODE>.
 306 For the operation,
 307 the device is configured to use range specification
 308 <CODE>range</CODE> and (if appropriate) analog reference type
 309 <CODE>aref</CODE>.  Analog reference types that are not supported
 310 by the device are silently ignored.
 311 <P>The function <CODE>comedi_data_read()</CODE> reads one data value from
 312 the specified channel and places the
 313 data value that is read in the location pointed to by
 314 <CODE>data</CODE>.
 315 <P>The function <CODE>comedi_data_write()</CODE> writes the data value
 316 specified by the argument <CODE>data</CODE> to
 317 the specified channel.
 318 <P>On sucess, these functions return 0.  If there is an error, -1 is
 319 returned.
 320 <P>Valid analog reference numbers are:
 321 <P>
 322 <UL>
 323 <LI>AREF_GROUND Reference to analog ground</LI>
 324 <LI>AREF_COMMON Reference to analog common</LI>
 325 <LI>AREF_DIFF           Differential reference</LI>
 326 <LI>AREF_OTHER  Board-specific meaning</LI>
 327 </UL>
 328 <P>Valid data values used by these functions is an unsigned integer
 329 less than or equal to <CODE>maxdata</CODE>, which is channel-dependent.
 330 Conversion of these data values to physical units can be performed
 331 by <CODE>comedi_to_phys()</CODE> and <CODE>comedi_from_phys()</CODE>.
 332 <P>
 333 <P>
 334 <P>
 335 <H2><A NAME="ss6.16">6.16 comedi_sv_init()</A>
 336 </H2>
 337
 338 <P>
 339 <P>
 340 <BLOCKQUOTE><CODE>
 341 <PRE>
 342 int comedi_sv_init(comedi_sv_t *it,comedi_t *dev,unsigned int subd,unsigned int chan);
 343 int comedi_sv_update(comedi_sv_t *it);
 344 int comedi_sv_measure(comedi_sv_t *it,double *data);
 345 </PRE>
 346 </CODE></BLOCKQUOTE>
 347 <P>The special functions <CODE>comedi_sv_*()</CODE> are designed to
 348 make it easy to accurately measure slowly varying analog inputs.
 349 A slowly
 350 varying input is one that is effectively constant over the course
 351 of approximately 100 A/D conversions.  However, since these
 352 conversions can sometimes be pre-empted by scheduling, for most
 353 purposes, a slowly varying signal should be effectively constant
 354 for greater than 20 ms (the default Linux timeslice).
 355 <P>By averaging many A/D conversions of a relatively constant
 356 signal, it is possible to get a better measurement of the signal
 357 than a single A/D conversion.  In general, the uncertainty of the
 358 measurement decreases as the square root of the number of samples.
 359 This is limited by the rate that which the signal varies, and
 360 ultimately by the spurious free dynamic range of the A/D converter.
 361 <P>
 362 <P>
 363 <P>
 364 <H2><A NAME="ss6.17">6.17 comedi_get_timer()</A>
 365 </H2>
 366
 367 <P>
 368 <P>
 369 <BLOCKQUOTE><CODE>
 370 <PRE>
 371 int comedi_get_timer(comedi_t *it,unsigned int subdev,double freq,unsigned int *trigvar,
 372         double *actual_freq);
 373 </PRE>
 374 </CODE></BLOCKQUOTE>
 375 <P>
 376 <P>
 377 <P>
 378 <P>
 379 <HR>
 380 Next
 381 <A HREF="comedilib-5.html">Previous</A>
 382 <A HREF="comedilib.html#toc6">Contents</A>
 383 </BODY>
 384 </HTML>