diff options
Diffstat (limited to 'docs/source/arduino/analogread.rst')
| -rw-r--r-- | docs/source/arduino/analogread.rst | 109 |
1 files changed, 62 insertions, 47 deletions
diff --git a/docs/source/arduino/analogread.rst b/docs/source/arduino/analogread.rst index d0fa5a1..9577c62 100644 --- a/docs/source/arduino/analogread.rst +++ b/docs/source/arduino/analogread.rst @@ -5,15 +5,18 @@ analogRead() ============ +Used to perform ADC conversion. -Signature ---------- +.. contents:: Contents + :local: -``int analogRead(int pin);`` +Library Documentation +--------------------- +.. doxygenfunction:: analogRead -Description ------------ +Discussion +---------- Reads the value from the specified analog pin. The Maple board contains a 16-channel, 12-bit analog to digital converter. This means @@ -24,36 +27,26 @@ 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`. +configured for analog input, using :ref:`arduino-pinMode` (you only +have to do this once, so it's usually done in :ref:`arduino-setup`\ ). 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]_. +1.3 million samples per second\ [#fsamp]_. -Parameters ----------- +Parameter Discussion +-------------------- -**pin** +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: - 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. + 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 ---- @@ -61,7 +54,7 @@ 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.). +the board, etc.) in a seemingly random way. Example @@ -70,43 +63,65 @@ Example :: - int analogPin = 3; // potentiometer wiper (middle terminal) connected to analog pin 3 - // outside leads to ground and +3.3V + 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(); + pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input + SerialUSB.begin(); // set up usb virtual COM port } void loop() { val = analogRead(analogPin); // read the input pin - SerialUSB.println(val); // debug value + SerialUSB.println(val); // print the value, for debugging with + // a serial monitor } -Arduino Compatibility Note --------------------------- +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. 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. +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 <arduino-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; + +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, opamps and other powered components can also be used if +greater precision is required. + +Finally, On the Arduino, it takes significantly longer to read analog +input: about 100 microseconds (0.0001 s), so the maximum reading rate +is 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>`_ |