1. 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 the 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.

2. Digital Input

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

2.1. Pins

  • (bit) in — State of the hardware input.

  • (bit) in-not — Inverted state of the input.

2.2. Parameters

  • None

2.3. Functions

  • (funct) read — Read hardware and set in and in-not HAL pins.

3. Digital Output

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

3.1. Pins

  • (bit) out — Value to be written (possibly inverted) to the hardware output.

3.2. Parameters

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

3.3. Functions

  • (funct) write — Read out and invert, and set hardware output accordingly.

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

4.1. Pins

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

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

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

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

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

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

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