diff options
Diffstat (limited to 'source/libmaple/api/adc.rst')
| -rw-r--r-- | source/libmaple/api/adc.rst | 231 |
1 files changed, 0 insertions, 231 deletions
diff --git a/source/libmaple/api/adc.rst b/source/libmaple/api/adc.rst deleted file mode 100644 index 2f06926..0000000 --- a/source/libmaple/api/adc.rst +++ /dev/null @@ -1,231 +0,0 @@ -.. 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. |