8000 docs/library: Specify additional ADC methods and new ADCBlock class. · kattni/circuitpython@4d2f487 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4d2f487

Browse files
dpgeorgedpgeorge
committed
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 adafruit#3943, adafruit#4213. Signed-off-by: Damien George <damien@micropython.org>
1 parent 7d71ae2 commit 4d2f487

File tree

3 files changed

+94
-4
lines changed

3 files changed

+94
-4
lines changed

‎docs/library/machine.ADC.rst

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,28 +8,59 @@ The ADC class provides an interface to analog-to-digital convertors, and
88
represents a single endpoint that can sample a continuous voltage and
99
convert it to a discretised value.
1010

11+
For extra control over ADC sampling see :ref:`machine.ADCBlock <machine.ADCBlock>`.
12+
1113
Example usage::
1214

13-
import machine
15+
from machine import ADC
1416

15-
adc = machine.ADC(pin) # create an ADC object acting on a pin
16-
val = adc.read_u16() # read a raw analog value in the range 0-65535
17+
adc = ADC(pin) # create an ADC object acting on a pin
18+
val = adc.read_u16() # read a raw analog value in the range 0-65535
19+
val = adc.read_uv() # read an analog value in microvolts
1720

1821
Constructors
1922
------------
2023

21-
.. class:: ADC(id)
24+
.. class:: ADC(id, *, sample_ns, atten)
2225

2326
Access the ADC associated with a source identified by *id*. This
2427
*id* may be an integer (usually specifying a channel number), a
2528
:ref:`Pin <machine.Pin>` object, or other value supported by the
2629
underlying machine.
2730

31+
If additional keyword-arguments are given then they will configure
32+
various aspects of the ADC. If not given, these settings will take
33+
previous or default values. The settings are:
34+
35+
- *sample_ns* is the sampling time in nanoseconds.
36+
37+
- *atten* specifies the input attenuation.
38+
2839
Methods
2940
-------
3041

42+
.. method:: ADC.init(*, sample_ns, atten)
43+
44+
Apply the given settings to the ADC. Only those arguments that are
45+
specified will be changed. See the ADC constructor above for what the
46+
arguments are.
47+
48+
.. method:: ADC.block()
49+
50+
Return the :ref:`ADCBlock <machine.ADCBlock>` instance associated with
51+
this ADC object.
52+
53+
This method only exists if the port supports the
54+
:ref:`ADCBlock <machine.ADCBlock>` class.
55+
3156
.. method:: ADC.read_u16()
3257

3358
Take an analog reading and return an integer in the range 0-65535.
3459
The return value represents the raw reading taken by the ADC, scaled
3560
such that the minimum value is 0 and the maximum value is 65535.
61+
62+
.. method:: ADC.read_uv()
63+
64+
Take an analog reading and return an integer value with units of
65+
microvolts. It is up to the particular port whether or not this value
66+
is calibrated, and how calibration is done.

‎docs/library/machine.ADCBlock.rst

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. currentmodule:: machine
2+
.. _machine.ADCBlock:
3+
4+
class ADCBlock -- control ADC peripherals
5+
=========================================
6+
7+
The ADCBlock class provides access to an ADC peripheral which has a
8+
number of channels that can be used to sample analog values. It allows
9+
finer control over configuration of :ref:`machine.ADC <machine.ADC>`
10+
objects, which do the actual sampling.
11+
12+
This class is not always available.
13+
14+
Example usage::
15+
16+
from machine import ADCBlock
17+
18+
block = ADCBlock(id, bits=12) # create an ADCBlock with 12-bit resolution
19+
adc = block.connect(4, pin) # connect channel 4 to the given pin
20+
val = adc.read_uv() # read an analog value
21+
22+
Constructors
23+
------------
24+
25+
.. class:: ADCBlock(id, *, bits)
26+
27+
Access the ADC peripheral identified by *id*, which may be an integer
28+
or string.
29+
30+
The *bits* argument, if given, sets the resolution in bits of the
31+
conversion process. If not specified then the previous or default
32+
resolution is used.
33+
34+
Methods
35+
-------
36+
37+
.. method:: ADCBlock.init(*, bits)
38+
39+
Configure the ADC peripheral. *bits* will set the resolution of the
40+
conversion process.
41+
42+
.. method:: ADCBlock.connect(channel)
43+
ADCBlock.connect(source)
44+
ADCBlock.connect(channel, source)
45+
46+
Connect up a channel on the ADC peripheral so it is ready for sampling,
47+
and return an :ref:`ADC <machine.ADC>` object that represents that connection.
48+
49+
The *channel* argument must be an integer, and *source* must be an object
50+
(for example a :ref:`Pin <machine.Pin>`) which can be connected up for sampling.
51+
52+
If only *channel* is given then it is configured for sampling.
53+
54+
If only *source* is given then that object is connected to a default
55+
channel ready for sampling.
56+
57+
If both *channel* and *source* are given then they are connected together
58+
and made ready for sampling.

‎docs/library/machine.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,7 @@ Classes
199199
machine.Pin.rst
200200
machine.Signal.rst
201201
machine.ADC.rst
202+
machine.ADCBlock.rst
202203
machine.PWM.rst
203204
machine.UART.rst
204205
machine.SPI.rst

0 commit comments

Comments
 (0)
0