From 4d2f487ee1ac93098b90c3108b071f6e855c9e7f Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 21 Jan 2022 22:29:11 +1100 Subject: [PATCH] docs/library: Specify additional ADC methods and new ADCBlock class. The new ADC methods are: init(), read_uv() and block(). The new ADCBlock class has methods: init() and connect(). See related discussions in #3943, #4213. Signed-off-by: Damien George --- docs/library/machine.ADC.rst | 39 ++++++++++++++++++--- docs/library/machine.ADCBlock.rst | 58 +++++++++++++++++++++++++++++++ docs/library/machine.rst | 1 + 3 files changed, 94 insertions(+), 4 deletions(-) create mode 100644 docs/library/machine.ADCBlock.rst diff --git a/docs/library/machine.ADC.rst b/docs/library/machine.ADC.rst index 1404b454ae..eb538a4424 100644 --- a/docs/library/machine.ADC.rst +++ b/docs/library/machine.ADC.rst @@ -8,28 +8,59 @@ The ADC class provides an interface to analog-to-digital convertors, and represents a single endpoint that can sample a continuous voltage and convert it to a discretised value. +For extra control over ADC sampling see :ref:`machine.ADCBlock `. + Example usage:: - import machine + from machine import ADC - adc = machine.ADC(pin) # create an ADC object acting on a pin - val = adc.read_u16() # read a raw analog value in the range 0-65535 + adc = ADC(pin) # create an ADC object acting on a pin + val = adc.read_u16() # read a raw analog value in the range 0-65535 + val = adc.read_uv() # read an analog value in microvolts Constructors ------------ -.. class:: ADC(id) +.. class:: ADC(id, *, sample_ns, atten) Access the ADC associated with a source identified by *id*. This *id* may be an integer (usually specifying a channel number), a :ref:`Pin ` object, or other value supported by the underlying machine. + If additional keyword-arguments are given then they will configure + various aspects of the ADC. If not given, these settings will take + previous or default values. The settings are: + + - *sample_ns* is the sampling time in nanoseconds. + + - *atten* specifies the input attenuation. + Methods ------- +.. method:: ADC.init(*, sample_ns, atten) + + Apply the given settings to the ADC. Only those arguments that are + specified will be changed. See the ADC constructor above for what the + arguments are. + +.. method:: ADC.block() + + Return the :ref:`ADCBlock ` instance associated with + this ADC object. + + This method only exists if the port supports the + :ref:`ADCBlock ` class. + .. method:: ADC.read_u16() Take an analog reading and return an integer in the range 0-65535. The return value represents the raw reading taken by the ADC, scaled such that the minimum value is 0 and the maximum value is 65535. + +.. method:: ADC.read_uv() + + Take an analog reading and return an integer value with units of + microvolts. It is up to the particular port whether or not this value + is calibrated, and how calibration is done. diff --git a/docs/library/machine.ADCBlock.rst b/docs/library/machine.ADCBlock.rst new file mode 100644 index 0000000000..56a468dd62 --- /dev/null +++ b/docs/library/machine.ADCBlock.rst @@ -0,0 +1,58 @@ +.. currentmodule:: machine +.. _machine.ADCBlock: + +class ADCBlock -- control ADC peripherals +========================================= + +The ADCBlock class provides access to an ADC peripheral which has a +number of channels that can be used to sample analog values. It allows +finer control over configuration of :ref:`machine.ADC ` +objects, which do the actual sampling. + +This class is not always available. + +Example usage:: + + from machine import ADCBlock + + block = ADCBlock(id, bits=12) # create an ADCBlock with 12-bit resolution + adc = block.connect(4, pin) # connect channel 4 to the given pin + val = adc.read_uv() # read an analog value + +Constructors +------------ + +.. class:: ADCBlock(id, *, bits) + + Access the ADC peripheral identified by *id*, which may be an integer + or string. + + The *bits* argument, if given, sets the resolution in bits of the + conversion process. If not specified then the previous or default + resolution is used. + +Methods +------- + +.. method:: ADCBlock.init(*, bits) + + Configure the ADC peripheral. *bits* will set the resolution of the + conversion process. + +.. method:: ADCBlock.connect(channel) + ADCBlock.connect(source) + ADCBlock.connect(channel, source) + + Connect up a channel on the ADC peripheral so it is ready for sampling, + and return an :ref:`ADC ` object that represents that connection. + + The *channel* argument must be an integer, and *source* must be an object + (for example a :ref:`Pin `) which can be connected up for sampling. + + If only *channel* is given then it is configured for sampling. + + If only *source* is given then that object is connected to a default + channel ready for sampling. + + If both *channel* and *source* are given then they are connected together + and made ready for sampling. diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 5f45168ed6..d66423d0d4 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -199,6 +199,7 @@ Classes machine.Pin.rst machine.Signal.rst machine.ADC.rst + machine.ADCBlock.rst machine.PWM.rst machine.UART.rst machine.SPI.rst