:lang: en
:toc:

[[cha:hal-canonical-device-interfaces]]
= Canonical Device Interfaces(((HAL Canonical Device Interfaces)))

== Introduction

The following sections show the pins, parameters, and functions that
are supplied by "canonical devices". All HAL device drivers should
supply the same pins and parameters, and implement the same behavior.

Note that only the `<io-type>` and `<specific-name>` fields are
defined for a canonical device. The `<device-name>`, `<device-num>`,
and `<chan-num>` fields are set based on the characteristics of the
real device.

[[sec:hal-cdi:digital-in]]
== Digital Input(((HAL Digital Input)))

The canonical digital input (I/O type field: `digin`) is quite simple.

[[sub:hal-cdi:di:pins]]
=== Pins(((HAL Digital Input Pins)))

(bit) *in*:: State of the hardware input.
(bit) *in-not*:: Inverted state of the input.

[[sub:hal-cdi:di:parameters]]
=== Parameters(((HAL Digital Input Parameters)))

None

[[sub:hal-cdi:di:functions]]
=== Functions(((HAL Digital Input Functions)))

(funct) *read*:: Read hardware and set `in` and `in-not` HAL pins.

[[sec:hal-cdi:digital-out]]
== Digital Output(((HAL Digital Output)))

The canonical digital output (I/O type field: `digout`) is also very
simple.

[[sub:hal-cdi:do:pins]]
=== Pins(((HAL Digital Output Pins)))

(bit) *out*:: Value to be written (possibly inverted) to the hardware output.

[[sub:hal-cdi:do:parameters]]
=== Parameters(((HAL Digital Output Parameters)))

(bit) *invert*:: If TRUE, *out* is inverted before writing to the hardware.

[[sub:hal-cdi:do:functions]]
=== Functions(((HAL Digital Output Functions)))

(funct) *write*:: Read *out* and *invert*, and set hardware output accordingly.

[[sec:hal-cdi:analog-in]]
== Analog Input(((HAL Analog Input)))

The canonical analog input (I/O type: `adcin`). This is expected to
be used for analog to digital converters, which convert e.g. voltage to a
continuous range of values.

[[sub:hal-cdi:ai:pins]]
=== Pins(((HAL Analog Input Pins)))

(float) *value*:: The hardware reading, scaled according to the
  *scale* and *offset* parameters. +
  *value* = ((input reading, in hardware-dependent units) * *scale*) - *offset*

[[sub:hal-cdi:ai:parameters]]
=== Parameters(((HAL Analog Input Parameters)))

(float) *scale*:: The input voltage (or current) will be multiplied
  by *scale* before being output to *value*.
(float) *offset*:: This will be subtracted from the hardware input
  voltage (or current) after the scale multiplier has been applied.
(float) *bit_weight*:: The value of one least significant bit (LSB).
  This is effectively the granularity of the input reading.
(float) *hw_offset*:: The value present on the input when 0 volts is
  applied to the input pin(s).

[[sub:hal-cdi:ai:functions]]
=== Functions(((HAL Analog Input Functions)))

(funct) *read*:: Read the values of this analog input channel.
  This may be used for individual channel reads, or it may cause all channels to be read

[[sec:hal-cdi:analog-out]]
== Analog Output(((HAL Analog Output)))

The canonical analog output (I/O Type: *adcout*). This is intended
for any kind of hardware that can output a more-or-less continuous range
of values. Examples are digital to analog converters or PWM generators.

[[sub:hal-cdi:ao:pins]]
=== Pins(((HAL Analog Output Pins)))

(float) *value*:: The value to be written. The actual value output
  to the hardware will depend on the scale and offset parameters.
(bit) *enable*:: If false, then output 0 to the hardware, regardless
  of the *value* pin.

[[sub:hal-cdi:ao:parameters]]
=== Parameters(((HAL Analog Output Parameters)))

(float) *offset*:: This will be added to the *value* before the hardware is updated.
(float) *scale*:: This should be set so that an input of 1 on the *value* pin will cause the analog output pin to read 1 volt.
(float) *high_limit* (optional):: When calculating the value to output to the hardware,
  if *value* + *offset* is greater than *high_limit*, then *high_limit* will be used instead.
(float) *low_limit* (optional):: When calculating the value to output to the hardware,
  if *value* + *offset* is less than *low_limit*, then *low_limit* will be used instead.
(float) *bit_weight* (optional):: The value of one least significant bit (LSB), in volts (or mA, for current outputs).
(float) *hw_offset*  (optional):: The actual voltage (or current) that will be output if 0 is written to the hardware.

[[sub:hal-cdi:ao:functions]]
=== Functions(((HAL Analog Output Functions)))

(funct) *write*::
  This causes the calculated value to be output to the hardware.
  If enable is false, then the output will be 0, regardless of *value*, *scale*, and *offset*.
  The meaning of "0" is dependent on the hardware.
  For example, a bipolar 12-bit A/D may need to write 0x1FF (mid scale) to the D/A get 0 volts from the hardware pin.
  If enable is true, read scale, offset and value and output to the adc (*scale* * *value*) + *offset*.
  If enable is false, then output 0.

// vim: set syntax=asciidoc:
