stm32/adc: Add read_timed_multi() static method, with docs and tests.

1 files changed, 52 insertions, 1 deletions

diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst
index 58aae6129..c2d09ad40 100644
--- a/docs/library/pyb.ADC.rst
+++ b/docs/library/pyb.ADC.rst
@@ -76,7 +76,58 @@ Methods
            for val in buf:                     # loop over all values
                print(val)                      # print the value out
 
-       This function does not allocate any memory.
+       This function does not allocate any heap memory. It has blocking behaviour:
+       it does not return to the calling program until the buffer is full.
+
+    .. method:: ADC.read_timed_multi((adcx, adcy, ...), (bufx, bufy, ...), timer)
+
+       This is a static method. It can be used to extract relative timing or
+       phase data from multiple ADC's.
+
+       It reads analog values from multiple ADC's into buffers at a rate set by
+       the *timer* object. Each time the timer triggers a sample is rapidly
+       read from each ADC in turn.
+
+       ADC and buffer instances are passed in tuples with each ADC having an
+       associated buffer. All buffers must be of the same type and length and
+       the number of buffers must equal the number of ADC's.
+
+       Buffers can be ``bytearray`` or ``array.array`` for example. The ADC values
+       have 12-bit resolution and are stored directly into the buffer if its element
+       size is 16 bits or greater.  If buffers have only 8-bit elements (eg a
+       ``bytearray``) then the sample resolution will be reduced to 8 bits.
+
+       *timer* must be a Timer object. The timer must already be initialised
+       and running at the desired sampling frequency.
+
+       Example reading 3 ADC's::
+
+           adc0 = pyb.ADC(pyb.Pin.board.X1)    # Create ADC's
+           adc1 = pyb.ADC(pyb.Pin.board.X2)
+           adc2 = pyb.ADC(pyb.Pin.board.X3)
+           tim = pyb.Timer(8, freq=100)        # Create timer
+           rx0 = array.array('H', (0 for i in range(100))) # ADC buffers of
+           rx1 = array.array('H', (0 for i in range(100))) # 100 16-bit words
+           rx2 = array.array('H', (0 for i in range(100)))
+           # read analog values into buffers at 100Hz (takes one second)
+           pyb.ADC.read_timed_multi((adc0, adc1, adc2), (rx0, rx1, rx2), tim)
+           for n in range(len(rx0)):
+               print(rx0[n], rx1[n], rx2[n])
+
+       This function does not allocate any heap memory. It has blocking behaviour:
+       it does not return to the calling program until the buffers are full.
+
+       The function returns ``True`` if all samples were acquired with correct
+       timing. At high sample rates the time taken to acquire a set of samples
+       can exceed the timer period. In this case the function returns ``False``,
+       indicating a loss of precision in the sample interval. In extreme cases
+       samples may be missed.
+
+       The maximum rate depends on factors including the data width and the
+       number of ADC's being read. In testing two ADC's were sampled at a timer
+       rate of 140KHz without overrun. Samples were missed at 180KHz. At high
+       sample rates disabling interrupts for the duration can reduce the risk
+       of sporadic data loss.
 
 The ADCAll Object
 -----------------