1  [[cha:canonical-device-interfaces]]
  2  
  3  = Canonical Device Interfaces
  4  
  5  == Introduction
  6  
  7  The following sections show the pins, parameters, and functions that 
  8  are supplied by “canonical devices”. All HAL device drivers should 
  9  supply the same pins and parameters, and implement the same behavior.
 10  
 11  Note that the only the `<io-type>` and `<specific-name>` fields are 
 12  defined for a canonical device. The `<device-name>`, `<device-num>`, 
 13  and `<chan-num>` fields are set based on the characteristics of the 
 14  real device.
 15  
 16  == Digital Input
 17  
 18  The canonical digital input (I/O type field: `digin`) is quite simple.
 19  
 20  === Pins
 21  
 22   - (bit) *in* -- State of the hardware input.
 23   - (bit) *in-not* -- Inverted state of the input.
 24  
 25  === Parameters
 26  
 27   - None
 28  
 29  === Functions
 30  
 31   - (funct) *read* -- Read hardware and set `in` and `in-not` HAL pins.
 32  
 33  == Digital Output
 34  
 35  The canonical digital output (I/O type field: `digout`) is also very
 36  simple.
 37  
 38  === Pins
 39  
 40   -  (bit) *out* -- Value to be written (possibly inverted) to the hardware
 41     output.
 42  
 43  === Parameters
 44  
 45   -  (bit) *invert* -- If TRUE, *out* is inverted before writing to the
 46     hardware.
 47  
 48  === Functions
 49  
 50   -  (funct) *write* -- Read *out* and *invert*, and set hardware output
 51     accordingly.
 52  
 53  == Analog Input
 54  
 55  The canonical analog input (I/O type: `adcin` ). This is expected to
 56  be used for analog to digital converters, which
 57  convert e.g. voltage to a continuous range of values.
 58  
 59  === Pins
 60  
 61   - (float) *value* -- The hardware reading, scaled according to the
 62     *scale* and *offset* parameters. *Value* = ((input reading, in
 63     hardware-dependent units) * *scale*) - *offset*
 64  
 65  === Parameters
 66  
 67   - (float) *scale* -- The input voltage (or current) will be multiplied
 68     by *scale* before being output to *value*.
 69   - (float) *offset* -- This will be subtracted from the hardware input
 70     voltage (or current) after the scale multiplier has been applied.
 71   - (float) *bit_weight* -- The value of one least significant bit (LSB).
 72     This is effectively the granularity of the input reading.
 73   - (float) *hw_offset* -- The value present on the input when 0 volts is
 74     applied to the input pin(s).
 75  
 76  === Functions
 77  
 78   - (funct) *read* -- Read the values of this analog input channel. This
 79     may be used for
 80     individual channel reads, or it may cause all channels to be read
 81  
 82  == Analog Output
 83  
 84  The canonical analog output (I/O Type: *adcout*). This is intended
 85  for any kind of hardware that can output a 
 86  more-or-less continuous range of values. Examples are digital to analog
 87  converters or PWM generators.
 88  
 89  === Pins
 90  
 91   - (float) *value* -- The value to be written. The actual value output
 92     to the hardware will depend on the scale and offset parameters.
 93   - (bit) *enable* -- If false, then output 0 to the hardware, regardless
 94     of the *value* pin.
 95  
 96  === Parameters
 97  
 98   - (float) *offset* -- This will be added to the *value* before the
 99     hardware is updated
100   - (float) *scale* -- This should be set so that an input of 1 on the
101     *value* pin will cause the analog output pin to read 1 volt. 
102   - (float) *high_limit* (optional) -- When calculating the value to
103     output to the hardware, if *value* + *offset* is greater than
104     *high_limit*, then *high_limit* will be used instead.
105   - (float) *low_limit* (optional) -- When calculating the value to output
106     to the hardware, if *value* + *offset* is less than *low_limit*, then
107     *low_limit* will be used instead.
108   - (float) *bit_weight* (optional) -- The value of one least significant
109     bit (LSB), in volts (or mA, for current outputs)
110   - (float) *hw_offset*  (optional) -- The actual voltage (or current)
111     that will be output if 0 is written to the hardware.
112  
113  === Functions
114  
115  (funct) *write*  -- This causes the calculated value to be output to
116  the hardware. If enable is false, then the output will be 0, 
117  regardless of *value*, *scale*, and *offset*. 
118  The meaning of “0” is dependent on the hardware. For example, a
119  bipolar 12-bit A/D may need to write 0x1FF (mid scale) to the D/A get 0
120  volts from the hardware pin. If enable is true, read scale, offset and 
121  value and output to the adc (*scale* * *value*) + *offset*. If enable
122  is false, then output 0.
123  
124