stmhal: Allow ADC.read_timed to take Timer object in place of freq.

This allows a user-specified Timer for the triggering of the ADC read,
mirroring the new behaviour of DAC.write_timed.

Addresses issue #1129.

1 files changed, 25 insertions, 7 deletions

diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst
index 64848d577..36c376d37 100644
--- a/docs/library/pyb.ADC.rst
+++ b/docs/library/pyb.ADC.rst
@@ -63,14 +63,32 @@ Methods
 
 .. only:: port_pyboard
 
-    .. method:: adc.read_timed(buf, freq)
+    .. method:: adc.read_timed(buf, timer)
     
-       Read analog values into the given buffer at the given frequency. Buffer
-       can be bytearray or array.array for example. If a buffer with 8-bit elements
-       is used, sample resolution will be reduced to 8 bits.
-       
-       Example::
-       
+       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::
+
            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