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
|
.. highlight:: cpp
.. _arduino-analogread:
analogRead()
============
Signature
---------
``int analogRead(int pin);``
Description
-----------
Reads the value from the specified analog pin. The Maple board
contains a 16-channel, 12-bit analog to digital converter. This means
that it will map input voltages between 0 and 3.3 volts into integer
values between 0 and 4095. This yields a resolution between readings
of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors
interfere with getting full accuracy and precision. For more
information, see :ref:`adc`.
Before calling analogRead() on a pin, that pin must first be
configured for analog input, using :ref:`arduino-pinMode`.
The input range and resolution can be changed using
:ref:`arduino-analogReference`.
It takes about 0.8 microseconds (.0000008 seconds) to read an analog
input, so the maximum sample rate using this function is approximately
1.3 million samples per second [#fsamp]_.
Parameters
----------
**pin**
The number of the analog input pin to read from. Header pins on the
Maple with ADC functionality (marked as "AIN" on the silkscreen)
are:
0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28
Note that pins 3, 27, and 28 are not marked AIN on the silkscreen
for Maple revisions through Rev 5, however, they **do work** as
analog input pins.
Returns
-------
Converted input voltage as an ``int``, with value 0 to 4095, inclusive.
Note
----
If the analog input pin is not connected to anything, the value
returned by analogRead() will fluctuate based on a number of factors
(e.g. the values of the other analog inputs, how close your hand is to
the board, etc.).
Example
-------
::
int analogPin = 3; // potentiometer wiper (middle terminal) connected to analog pin 3
// outside leads to ground and +3.3V
int val = 0; // variable to store the value read
void setup() {
pinMode(analogPin, INPUT_ANALOG);
SerialUSB.begin();
}
void loop() {
val = analogRead(analogPin); // read the input pin
SerialUSB.println(val); // debug value
}
Arduino Compatibility Note
--------------------------
The Arduino board contains a 6 channel (8 channels on the Mini and
Nano, 16 on the Mega), 10-bit analog to digital converter. This means
that it will map input voltages between 0 and 5 volts into integer
values between 0 and 1023. This yields a resolution between readings
of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit. On the
Arduino, the input range and resolution can be changed using their
implementation of `analogReference()
<http://arduino.cc/en/Reference/AnalogReference>`_\ .
On the Arduino, it takes about 100 microseconds (0.0001 s) to read an
analog input, so the maximum reading rate is about 10,000 times a
second.
See also
--------
- :ref:`ADC note <adc>`
- :ref:`analogReference <arduino-analogreference>`
- `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
.. rubric:: Footnotes
.. [#fsamp] This is based on the current configuration of a 55.5 cycle
sample time, at 72 MHz. However, the minimum sample time *possible*
is 1.5 cycles, leading to a theoretical maximum of approximately 48
million samples per second (of course, doing anything with the
readings also consumes cycles, so this maximum can't be reached in
practice).
See the `STM32 Reference Manual <full-manual>`_, §§11.12.4--5
(pp. 225--226), for more information on the low-level bit twiddling
currently necessary to change the sample time. For examples of how
the ADCs are configured in libmaple, see `adc.h
<http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.h>`_
and `adc.c
<http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.c>`_\
. Be aware that changing the sample time has important
consequences related to the impedance of the device connected to
the input pin. If you want to make changes, as a minimum, you
should first read ST's application notes on `ADC modes
<stm32-adc-modes>`_ and `ADC oversampling
<stm32-adc-oversampling>`_.
|
