aboutsummaryrefslogtreecommitdiffstats
path: root/source/lang/api/analogread.rst
blob: 7099b699455d3604926e3c342aeb43b1fb3a4b18 (plain)
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
.. highlight:: cpp

.. _lang-analogread:

.. _lang-api-analogread:

analogRead()
============

Used to perform ADC conversion.

.. contents:: Contents
   :local:

Library Documentation
---------------------

.. doxygenfunction:: analogRead

Discussion
----------

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:`lang-pinMode` (you only
have to do this once, so it's usually done in :ref:`lang-setup`\ ).

Parameter Discussion
--------------------

.. FIXME generalize Maple-specific information

The pin parameter is 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.

Note
----

If the analog input pin is not connected to anything, the value
returned by ``analogRead()`` will fluctuate due to a number of reasons
(like the values of the other analog inputs, how close your hand is to
the board, etc.) in a "random" way.


Example
-------

::

    int analogPin = 3;     // Potentiometer wiper (middle terminal) connected
                           // to analog pin 3. outside leads to ground and +3.3V.
                           // You may have to change this value if your board
                           // cannot perform ADC conversion on pin 3.

    int val = 0;           // variable to store the value read

    void setup() {
      pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input
    }

    void loop() {
      val = analogRead(analogPin);    // read the input pin
      SerialUSB.println(val);         // print the value, for debugging with
                                      // a serial monitor
    }


Arduino Compatibility
---------------------

The Arduino board contains a 6 channel (8 channels on the Mini and
Nano, 16 on the Mega), 10-bit analog to digital converter with an
input voltage range of 0V--5V. This means that it will map input
voltages between 0 and 5 volts (which is **larger** than Maple's range
of 0V-3.3V) into integer values between 0 and 1023 (which is
**smaller** than the Maple's range of 0--4095).

This yields a theoretical resolution between readings of: 5 volts /
1024 units or .0049 volts (4.9 mV) per unit on Arduino boards, which
is larger, and thus less precise, than Maple's 0.0008 volts (0.8 mV).

If your program expects Arduino-style 10-bit ADC, you can :ref:`right
shift <lang-bitshift>` the value of a Maple readout by 2, like so::

    // right shift means that the result will be between 0 and 1023;
    // be aware that you're losing a lot of precision if you do this
    int adc_reading = analogRead(pin) >> 2;

.. FIXME Mention Native can do analogReference(), when it's time

On the Arduino, the input range and resolution can be changed using
their implementation of `analogReference()
<http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
way its hardware (as of Rev 5) was designed, it's not possible to
implement analogReference on the Maple, so this function doesn't
exist.  If your inputs lie in a different voltage range than 0V--3.3V,
you'll need to bring them into that range before using
``analogRead()``.  Some basic tools to accomplish this are `resistor
dividers <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener
diodes
<http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
. However, `operational amplifiers
<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other
powered components can also be used if greater precision is required.

See also
--------

- :ref:`ADC tutorial <adc>`
- `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_

.. include:: cc-attribution.txt