1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
= Canonical Device Interfaces
////
ATTENTION TRANSLATORS before translating this document copy the base document
into this copy to get the latest version. Untranslated documents are not kept
up to date with the English documents.
Do not translate anchors or links, translate only the text of a link after the
comma.
Anchor [[anchor-name]]
Link <<anchor-name,text after the comma can be translated>>
Make sure the documents build after translating.
////
.Note
*********************************************************************
By version 2.1, the HAL drivers should have all been updated to
match these specs. Send an email if you spot any problems.
*********************************************************************
[[cha: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 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.
== Digital Input[[sec:CanonDigIn]]
The canonical digital input (I/O type field: `digin`) is quite simple.
=== Pins
- (bit) *in* -- State of the hardware input.
- (bit) *in-not* -- Inverted state of the input.
=== Parameters
- None
=== Functions
- (funct) *read* -- Read hardware and set `in` and `in-not` HAL pins.
== Digital Output[[sec:CanonDigOut]]
The canonical digital output (I/O type field: `digout`) is also very
simple.
=== Pins
- (bit) *out* -- Value to be written (possibly inverted) to the hardware
output.
=== Parameters
- (bit) *invert* -- If TRUE, *out* is inverted before writing to the
hardware.
=== Functions
- (funct) *write* -- Read *out* and *invert*, and set hardware output
accordingly.
== 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.
=== Pins
- (float) *value* -- The hardware reading, scaled according to the
*scale* and *offset* parameters. *Value* = ((input reading, in
hardware-dependent units) * *scale*) - *offset*
=== 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).
=== 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
== 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.
=== 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.
=== 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.
=== 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.
|
