pyb.ADC.rst 3.84 KB
Newer Older
1
2
.. _pyb.ADC:

3
4
class ADC -- analog to digital conversion: read analog values on a pin
======================================================================
5

6
.. only:: port_pyboard
7

8
9
10
11
12
13
14
15
16
17
18
19
    Usage::
    
        import pyb
    
        adc = pyb.ADC(pin)              # create an analog object from a pin
        val = adc.read()                # read an analog value
    
        adc = pyb.ADCAll(resolution)    # creale an ADCAll object
        val = adc.read_channel(channel) # read the given channel
        val = adc.read_core_temp()      # read MCU temperature
        val = adc.read_core_vbat()      # read MCU VBAT
        val = adc.read_core_vref()      # read MCU VREF
20

21
.. only:: port_wipy
22

23
24
25
    Usage::
    
       import pyb
26

27
28
       adc = pyb.ADC(channel)          # create an analog object on one of the 4 ADC channels
       val = adc.read()                # read an analog value
29
30
31
32

Constructors
------------

33
.. only:: port_pyboard
34

35
36
37
38
    .. class:: pyb.ADC(pin)
    
       Create an ADC object associated with the given pin.
       This allows you to then read analog values on that pin.
39

40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
.. only:: port_wipy

    .. class:: pyb.ADC(channel)
    
       Create an ADC object on the given channel. Each channel is associated
       to a specific pin. For more info check the `pinout and alternate functions
       table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ 
       This allows you to then read analog values on that pin.
       
       .. warning:: 
       
          ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it 
          can withstand). When GPIO2, GPIO3, GPIO4 or GPIO5 are remapped to the 
          ADC block, 1.8 V is the maximum. If these pins are used in digital mode, 
          then the maximum allowed input is 3.6V.
55
56
57
58
59
60
61
62
63

Methods
-------

.. method:: adc.read()

   Read the value on the analog pin and return it.  The returned value
   will be between 0 and 4095.

64
65
.. only:: port_pyboard

66
    .. method:: adc.read_timed(buf, timer)
67
    
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
       Read analog values into ``buf`` at a rate set by the ``timer`` object.

       ``buf`` can be bytearray or array.array for example.  The ADC values have
       12-bit resolution and are stored directly into ``buf`` if its element size is
       16 bits or greater.  If ``buf`` has only 8-bit elements (eg a bytearray) then
       the sample resolution will be reduced to 8 bits.

       ``timer`` should be a Timer object, and a sample is read each time the timer
       triggers.  The timer must already be initialised and running at the desired
       sampling frequency.

       To support previous behaviour of this function, ``timer`` can also be an
       integer which specifies the frequency (in Hz) to sample at.  In this case
       Timer(6) will be automatically configured to run at the given frequency.

       Example using a Timer object (preferred way)::

           adc = pyb.ADC(pyb.Pin.board.X19)    # create an ADC on pin X19
           tim = pyb.Timer(6, freq=10)         # create a timer running at 10Hz
           buf = bytearray(100)                # creat a buffer to store the samples
           adc.read_timed(buf, tim)            # sample 100 values, taking 10s

       Example using an integer for the frequency::

92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
           adc = pyb.ADC(pyb.Pin.board.X19)    # create an ADC on pin X19
           buf = bytearray(100)                # create a buffer of 100 bytes
           adc.read_timed(buf, 10)             # read analog values into buf at 10Hz
                                               #   this will take 10 seconds to finish
           for val in buf:                     # loop over all values
               print(val)                      # print the value out
       
       This function does not allocate any memory.

.. only:: port_wipy

   .. method:: adc.enable()

      Enable the ADC channel.

   .. method:: adc.disable()

      Disable the ADC channel.