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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
.. highlight:: c
.. _libmaple-adc:
``<libmaple/adc.h>``
====================
:ref:`Analog to Digital Conversion <adc>` (ADC) support.
A common API for basic ADC functionality is available, but the
characteristics of the ADC peripherals vary slightly across
targets. To manage this, each target defines a small set of datatypes
expressing its capabilities (namely :ref:`adc_extsel_event
<adc-adc_extsel_event>`, :ref:`adc_smp_rate <adc-adc_smp_rate>`, and
:ref:`adc_prescaler <adc-adc_prescaler>`).
.. contents:: Contents
:local:
:depth: 2
Devices
-------
The individual ADC peripherals have the following device struct.
.. doxygenstruct:: adc_dev
The available ADC peripherals vary by target. The complete list is
``ADC1``, ``ADC2``, and ``ADC3``.
.. doxygenvariable:: ADC1
.. doxygenvariable:: ADC2
.. doxygenvariable:: ADC3
Functions
---------
Activation and Deactivation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``adc_enable_single_swstart()`` is simple, portable function, which
enables an ADC and sets it up for its basic usage: performing single
conversions using :ref:`adc_read() <adc-adc_read>`.
.. _adc-adc_enable_single_swstart:
.. doxygenfunction:: adc_enable_single_swstart
The precise software sequence used varies by target, so this is a good
function to use if your program needs to support multiple MCUs. By
default, Wirish calls ``adc_enable_single_swstart()`` on all available
ADCs at ``init()`` time, so Wirish users don't have to call this
function.
There are several other lower-level routines used for activating and
deactivating ADCs:
.. _adc-adc_init:
.. doxygenfunction:: adc_init
.. _adc-adc_enable:
.. doxygenfunction:: adc_enable
.. _adc-adc_disable:
.. doxygenfunction:: adc_disable
.. _adc-adc_disable_all:
.. doxygenfunction:: adc_disable_all
ADC Conversion
~~~~~~~~~~~~~~
``adc_read()`` is a simple function which starts conversion on a
single ADC channel, blocks until it has completed, and returns the
converted result. Don't use the ADC device for any other purpose while
it's running.
.. _adc-adc_read:
.. doxygenfunction:: adc_read
To use ``adc_read()``, the device must be configured appropriately.
You can do this with :ref:`adc_enable_single_swstart()
<adc-adc_enable_single_swstart>`.
Note that for an ADC device to perform conversion on a GPIO input
(which is the usual case; the notable exception being taking
temperature reading), the pin must be configured for analog
conversion. Do this with :ref:`adc_config_gpio()
<adc-adc_config_gpio>`.
Other routines helpful for ADC conversion:
.. _adc-adc_set_reg_seqlen:
.. doxygenfunction:: adc_set_reg_seqlen
.. _adc-adc_set_extsel:
.. doxygenfunction:: adc_set_extsel
.. _adc-adc_extsel_event:
The last of these, :ref:`adc_set_extsel() <adc-adc_set_extsel>`, takes
a target-dependent ``adc_extsel_event`` argument.
STM32F1 Targets
+++++++++++++++
.. doxygenenum:: stm32f1::adc_extsel_event
STM32F2 Targets
+++++++++++++++
.. doxygenenum:: stm32f2::adc_extsel_event
ADC Clock Prescaler
~~~~~~~~~~~~~~~~~~~
``adc_set_prescaler()`` is available for setting the prescaler which
determines the common ADC clock rate. (Wirish sets a sensible default
for this, so Wirish users ordinarily don't need to call this
function.)
.. warning:: Increasing the ADC clock rate does speed conversion time,
but the ADC peripherals have a maximum clock rate which must not be
exceeded. Make sure to configure your system and ADC clocks to
respect your device's maximum rate.
.. _adc_adc_set_prescaler:
.. doxygenfunction:: adc_set_prescaler
.. _adc-adc_prescaler:
ADC prescaler values are target-dependent.
STM32F1 Targets
+++++++++++++++
.. doxygenenum:: stm32f1::adc_prescaler
STM32F2 Targets
+++++++++++++++
.. doxygenenum:: stm32f2::adc_prescaler
.. _adc-adc_set_sample_rate:
ADC Sample Time
~~~~~~~~~~~~~~~
You can control the sampling time (in ADC cycles) for an entire ADC
device using ``adc_set_sample_rate()`` [#fchansamp]_. This function
**only controls the sample rate**; the total conversion time is equal
to the sample time plus an additional number of ADC cycles. Consult
the reference manual for your chip for more details.
.. warning:: Decreasing ADC sample time speeds conversion, but it also
decreases the maximum allowable impedance of the voltage source you
are measuring. If your voltage source has a high impedance
(e.g. you're measuring Vcc through a potentiometer), and your
sample time is too low, you will get inaccurate results. Consult
the datasheet for your target for more details.
.. note:: Wirish sets a sensible default sample rate to allow for
high-impedance inputs at ``init()`` time, but Wirish users who know
what they're doing may want to call this function to speed up ADC
conversion.
.. doxygenfunction:: adc_set_sample_rate
.. _adc-adc_smp_rate:
The ``adc_smp_rate`` argument to :ref:`adc_set_sample_rate()
<adc-adc_set_sample_rate>` is target-dependent.
STM32F1 Targets
+++++++++++++++
.. doxygenenum:: stm32f1::adc_smp_rate
STM32F2 Targets
+++++++++++++++
.. doxygenenum:: stm32f2::adc_smp_rate
Miscellaneous
~~~~~~~~~~~~~
.. FIXME [0.0.13] why don't adc_config_gpio()'s docs show up?
.. _adc-adc_foreach:
.. doxygenfunction:: adc_foreach
.. _adc-adc_config_gpio:
.. doxygenfunction:: adc_config_gpio
STM32F1 only
~~~~~~~~~~~~
The following routines are available only on STM32F1 targets.
.. _adc-adc_set_exttrig:
.. doxygenfunction:: adc_set_exttrig
``adc_calibrate()`` performs calibration necessary on STM32F1 before
using an ADC. Note that on STM32F1 targets,
:ref:`adc_enable_single_swstart() <adc-adc_enable_single_swstart>`
calls ``adc_calibrate()``, so there's no need to do it separately.
.. _adc-adc_calibrate:
.. doxygenfunction:: adc_calibrate
Register Maps
-------------
Individual ADC peripherals have the following register map. The base
pointers are ``ADC1_BASE``, ``ADC2_BASE``, and ``ADC3_BASE``.
.. _adc-adc_reg_map:
.. doxygenstruct:: adc_reg_map
On **STM32F2 targets**, there is an additional common set of registers
shared by all ADC peripherals. Its base pointer is
``ADC_COMMON_BASE``.
.. _adc-adc_common_reg_map:
.. doxygenstruct:: stm32f2::adc_common_reg_map
Register Bit Definitions
------------------------
.. TODO [0.0.13]
TODO
.. rubric:: Footnotes
.. [#fchansamp] Per-channel sample time configuration is possible,
but currently unsupported.
|
