f47f9c05aa
This adds basic API description for ADC and DAC peripherals. External ADC/DAC controllers are listed as well. Signed-off-by: Michal Lenc <michallenc@seznam.cz>
143 lines
4.5 KiB
ReStructuredText
143 lines
4.5 KiB
ReStructuredText
===========
|
|
ADC Drivers
|
|
===========
|
|
|
|
- ``include/nuttx/analog/adc.h``. All structures and APIs needed
|
|
to work with ADC drivers are provided in this header file. This
|
|
header file includes:
|
|
|
|
#. Structures and interface descriptions needed to develop a
|
|
low-level, architecture-specific, ADC driver.
|
|
#. To register the ADC driver with a common ADC character
|
|
driver.
|
|
#. Interfaces needed for interfacing user programs with the
|
|
common ADC character driver.
|
|
|
|
- ``drivers/analog/adc.c``. The implementation of the common ADC
|
|
character driver.
|
|
|
|
Application Programming Interface
|
|
=================================
|
|
|
|
The first necessary thing to be done in order to use the ADC driver from an
|
|
application is to include the correct header filer. It contains the
|
|
Application Programming Interface to the ADC driver. To do so, include:
|
|
|
|
|
|
.. code-block:: c
|
|
|
|
#include <nuttx/analog/adc.h>
|
|
|
|
ADC driver is registered as a POSIX character device file into ``/dev``
|
|
namespace. It is necessary to open the device to get a file descriptor for
|
|
further operations. This can be done with standard POSIX ``open()`` call.
|
|
|
|
Standard POSIX ``read()`` operation may be used to read the measured data from
|
|
the controller. The driver utilizes FIFO queue for received measurements
|
|
and ``read()`` operation gets data from this queue. Structure ``adc_msg_s``
|
|
(or array of these structures) should be passed to buffer parameter of
|
|
``read()`` call. This structure represents one ADC measurement.
|
|
|
|
.. c:struct:: adc_msg_s
|
|
.. code-block:: c
|
|
|
|
begin_packed_struct struct adc_msg_s
|
|
{
|
|
/* The 8-bit ADC Channel */
|
|
uint8_t am_channel;
|
|
/* ADC convert result (4 bytes) */
|
|
int32_t am_data;
|
|
} end_packed_struct;
|
|
|
|
User may perform polling operation on the driver with ``poll()`` call.
|
|
The controller also may be configured/controlled at run time with numerous
|
|
``ioctl()`` calls. Following commands are supported:
|
|
|
|
* :c:macro:`ANIOC_TRIGGER`
|
|
* :c:macro:`ANIOC_WDOG_UPPER`
|
|
* :c:macro:`ANIOC_WDOG_LOWER`
|
|
* :c:macro:`ANIOC_GET_NCHANNELS`
|
|
* :c:macro:`ANIOC_RESET_FIFO`
|
|
* :c:macro:`ANIOC_SAMPLES_ON_READ`
|
|
|
|
.. c:macro:: ANIOC_TRIGGER
|
|
|
|
The ``ANIOC_TRIGGER`` command triggers one conversion. This call is used
|
|
when software trigger conversion is configured. The opposite to software
|
|
trigger is a hardware trigger. This may be some timer driver for example.
|
|
|
|
.. c:macro:: ANIOC_WDOG_UPPER
|
|
|
|
This command is used to set the upper threshold for the watchdog.
|
|
|
|
.. c:macro:: ANIOC_WDOG_LOWER
|
|
|
|
This command is used to set the lower threshold for the watchdog.
|
|
|
|
.. c:macro:: ANIOC_GET_NCHANNELS
|
|
|
|
The ``ANIOC_GET_NCHANNELS`` gets the number of used/configured channels
|
|
for given opened instance. This is the only portable way how to get
|
|
the number of channels from the driver.
|
|
|
|
.. c:macro:: ANIOC_RESET_FIFO
|
|
|
|
This ``ioctl`` command clears the FIFO queue in which measured data are stored.
|
|
|
|
.. c:macro:: ANIOC_SAMPLES_ON_READ
|
|
|
|
The ``ANIOC_SAMPLES_ON_READ`` returns number of samples/measured data waiting
|
|
in the FIFO queue to be read.
|
|
|
|
It is possible for a controller to support its specific ioctl commands. These
|
|
should be described in controller specific documentation.
|
|
|
|
Application Example
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
An example application can be found in ``nuttx-apps`` repository under
|
|
path ``examples/adc``. It is an example application that reads the data
|
|
from the defined number of channels.
|
|
|
|
.. code-block :: bash
|
|
|
|
nsh> adc
|
|
Sample:
|
|
1: channel: 0 value 951
|
|
2: channel: 1 value 1879
|
|
Sample:
|
|
1: channel: 0 value 952
|
|
2: channel: 1 value 1880
|
|
Sample:
|
|
1: channel: 0 value 942
|
|
2: channel: 1 value 1800
|
|
|
|
Configuration
|
|
=============
|
|
|
|
This section describes ADC driver configuration in ``Kconfig``. The reader
|
|
should refer to target documentation for target specific configuration.
|
|
|
|
ADC peripheral is enabled by ``CONFIG_ANALOG`` and ``CONFIG_ADC`` options,
|
|
respectively. The user can configure FIFO queue size with configuration
|
|
option ``CONFIG_ADC_FIFOSIZE``. This variable defines the size of the
|
|
ADC ring buffer that is used to queue received ADC data until they can be
|
|
retrieved by the application by reading from the ADC character device. Since
|
|
this is a ring buffer, the actual number of bytes that can be
|
|
retained in buffer is (``CONFIG_ADC_FIFOSIZE - 1``).
|
|
|
|
Configuration option ``CONFIG_ADC_NPOLLWAITERS`` defines number of
|
|
threads that can be waiting on poll.
|
|
|
|
External Devices
|
|
================
|
|
|
|
NuttX also provides support for various external ADC devices. These usually
|
|
communicates with MCU with I2C or SPI peripherals.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:glob:
|
|
|
|
*/*
|