1.. currentmodule:: pyb 2.. _pyb.ADC: 3 4class ADC -- analog to digital conversion 5========================================= 6 7Usage:: 8 9 import pyb 10 11 adc = pyb.ADC(pin) # create an analog object from a pin 12 val = adc.read() # read an analog value 13 14 adc = pyb.ADCAll(resolution) # create an ADCAll object 15 adc = pyb.ADCAll(resolution, mask) # create an ADCAll object for selected analog channels 16 val = adc.read_channel(channel) # read the given channel 17 val = adc.read_core_temp() # read MCU temperature 18 val = adc.read_core_vbat() # read MCU VBAT 19 val = adc.read_core_vref() # read MCU VREF 20 val = adc.read_vref() # read MCU supply voltage 21 22 23Constructors 24------------ 25 26.. class:: pyb.ADC(pin) 27 28 Create an ADC object associated with the given pin. 29 This allows you to then read analog values on that pin. 30 31Methods 32------- 33 34.. method:: ADC.read() 35 36 Read the value on the analog pin and return it. The returned value 37 will be between 0 and 4095. 38 39.. method:: ADC.read_timed(buf, timer) 40 41 Read analog values into ``buf`` at a rate set by the ``timer`` object. 42 43 ``buf`` can be bytearray or array.array for example. The ADC values have 44 12-bit resolution and are stored directly into ``buf`` if its element size is 45 16 bits or greater. If ``buf`` has only 8-bit elements (eg a bytearray) then 46 the sample resolution will be reduced to 8 bits. 47 48 ``timer`` should be a Timer object, and a sample is read each time the timer 49 triggers. The timer must already be initialised and running at the desired 50 sampling frequency. 51 52 To support previous behaviour of this function, ``timer`` can also be an 53 integer which specifies the frequency (in Hz) to sample at. In this case 54 Timer(6) will be automatically configured to run at the given frequency. 55 56 Example using a Timer object (preferred way):: 57 58 adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19 59 tim = pyb.Timer(6, freq=10) # create a timer running at 10Hz 60 buf = bytearray(100) # creat a buffer to store the samples 61 adc.read_timed(buf, tim) # sample 100 values, taking 10s 62 63 Example using an integer for the frequency:: 64 65 adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19 66 buf = bytearray(100) # create a buffer of 100 bytes 67 adc.read_timed(buf, 10) # read analog values into buf at 10Hz 68 # this will take 10 seconds to finish 69 for val in buf: # loop over all values 70 print(val) # print the value out 71 72 This function does not allocate any heap memory. It has blocking behaviour: 73 it does not return to the calling program until the buffer is full. 74 75.. method:: ADC.read_timed_multi((adcx, adcy, ...), (bufx, bufy, ...), timer) 76 77 This is a static method. It can be used to extract relative timing or 78 phase data from multiple ADC's. 79 80 It reads analog values from multiple ADC's into buffers at a rate set by 81 the *timer* object. Each time the timer triggers a sample is rapidly 82 read from each ADC in turn. 83 84 ADC and buffer instances are passed in tuples with each ADC having an 85 associated buffer. All buffers must be of the same type and length and 86 the number of buffers must equal the number of ADC's. 87 88 Buffers can be ``bytearray`` or ``array.array`` for example. The ADC values 89 have 12-bit resolution and are stored directly into the buffer if its element 90 size is 16 bits or greater. If buffers have only 8-bit elements (eg a 91 ``bytearray``) then the sample resolution will be reduced to 8 bits. 92 93 *timer* must be a Timer object. The timer must already be initialised 94 and running at the desired sampling frequency. 95 96 Example reading 3 ADC's:: 97 98 adc0 = pyb.ADC(pyb.Pin.board.X1) # Create ADC's 99 adc1 = pyb.ADC(pyb.Pin.board.X2) 100 adc2 = pyb.ADC(pyb.Pin.board.X3) 101 tim = pyb.Timer(8, freq=100) # Create timer 102 rx0 = array.array('H', (0 for i in range(100))) # ADC buffers of 103 rx1 = array.array('H', (0 for i in range(100))) # 100 16-bit words 104 rx2 = array.array('H', (0 for i in range(100))) 105 # read analog values into buffers at 100Hz (takes one second) 106 pyb.ADC.read_timed_multi((adc0, adc1, adc2), (rx0, rx1, rx2), tim) 107 for n in range(len(rx0)): 108 print(rx0[n], rx1[n], rx2[n]) 109 110 This function does not allocate any heap memory. It has blocking behaviour: 111 it does not return to the calling program until the buffers are full. 112 113 The function returns ``True`` if all samples were acquired with correct 114 timing. At high sample rates the time taken to acquire a set of samples 115 can exceed the timer period. In this case the function returns ``False``, 116 indicating a loss of precision in the sample interval. In extreme cases 117 samples may be missed. 118 119 The maximum rate depends on factors including the data width and the 120 number of ADC's being read. In testing two ADC's were sampled at a timer 121 rate of 210kHz without overrun. Samples were missed at 215kHz. For three 122 ADC's the limit is around 140kHz, and for four it is around 110kHz. 123 At high sample rates disabling interrupts for the duration can reduce the 124 risk of sporadic data loss. 125 126The ADCAll Object 127----------------- 128 129Instantiating this changes all masked ADC pins to analog inputs. The preprocessed MCU temperature, 130VREF and VBAT data can be accessed on ADC channels 16, 17 and 18 respectively. 131Appropriate scaling is handled according to reference voltage used (usually 3.3V). 132The temperature sensor on the chip is factory calibrated and allows to read the die temperature 133to +/- 1 degree centigrade. Although this sounds pretty accurate, don't forget that the MCU's internal 134temperature is measured. Depending on processing loads and I/O subsystems active the die temperature 135may easily be tens of degrees above ambient temperature. On the other hand a pyboard woken up after a 136long standby period will show correct ambient temperature within limits mentioned above. 137 138The ``ADCAll`` ``read_core_vbat()``, ``read_vref()`` and ``read_core_vref()`` methods read 139the backup battery voltage, reference voltage and the (1.21V nominal) reference voltage using the 140actual supply as a reference. All results are floating point numbers giving direct voltage values. 141 142``read_core_vbat()`` returns the voltage of the backup battery. This voltage is also adjusted according 143to the actual supply voltage. To avoid analog input overload the battery voltage is measured 144via a voltage divider and scaled according to the divider value. To prevent excessive loads 145to the backup battery, the voltage divider is only active during ADC conversion. 146 147``read_vref()`` is evaluated by measuring the internal voltage reference and backscale it using 148factory calibration value of the internal voltage reference. In most cases the reading would be close 149to 3.3V. If the pyboard is operated from a battery, the supply voltage may drop to values below 3.3V. 150The pyboard will still operate fine as long as the operating conditions are met. With proper settings 151of MCU clock, flash access speed and programming mode it is possible to run the pyboard down to 1522 V and still get useful ADC conversion. 153 154It is very important to make sure analog input voltages never exceed actual supply voltage. 155 156Other analog input channels (0..15) will return unscaled integer values according to the selected 157precision. 158 159To avoid unwanted activation of analog inputs (channel 0..15) a second parameter can be specified. 160This parameter is a binary pattern where each requested analog input has the corresponding bit set. 161The default value is 0xffffffff which means all analog inputs are active. If just the internal 162channels (16..18) are required, the mask value should be 0x70000. 163 164Example:: 165 166 adcall = pyb.ADCAll(12, 0x70000) # 12 bit resolution, internal channels 167 temp = adcall.read_core_temp() 168