stmhal: Allow to set bits resolution for DAC; 8 is default, can have 12.

This patch allows to configure the DAC resolution in the constructor and
in the init function, eg:

dac = DAC(1, bits=12).

The default resolution is 8 bits for backwards compatibility.  The bits
sets the maximum value accepted by write and write_timed methods, being
2**bits - 1.

When using write_timed with 12-bit resolution, the input buffer is
treated as an unsigned half-word array, typecode 'H'.

See PR #1130 for discussion.

1 files changed, 30 insertions, 5 deletions

diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst
index 578a4d126..f70436958 100644
--- a/docs/library/pyb.DAC.rst
+++ b/docs/library/pyb.DAC.rst
@@ -15,6 +15,9 @@ Example usage::
     dac = DAC(1)            # create DAC 1 on pin X5
     dac.write(128)          # write a value to the DAC (makes X5 1.65V)
 
+    dac = DAC(1, bits=12)   # use 12 bit resolution
+    dac.write(4095)         # output maximum value, 3.3V
+
 To output a continuous sine-wave::
 
     import math
@@ -29,21 +32,40 @@ To output a continuous sine-wave::
     dac = DAC(1)
     dac.write_timed(buf, 400 \* len(buf), mode=DAC.CIRCULAR)
 
+To output a continuous sine-wave at 12-bit resolution::
+
+    import math
+    from array import array
+    from pyb import DAC
+
+    # create a buffer containing a sine-wave, using half-word samples
+    buf = array('H', 2048 + int(2047 * math.sin(2 * math.pi * i / 128)) for i in range(128))
+
+    # output the sine-wave at 400Hz
+    dac = DAC(1, bits=12)
+    dac.write_timed(buf, 400 \* len(buf), mode=DAC.CIRCULAR)
 
 Constructors
 ------------
 
-.. class:: pyb.DAC(port)
+.. class:: pyb.DAC(port, bits=8)
 
    Construct a new DAC object.
-   
+
    ``port`` can be a pin object, or an integer (1 or 2).
    DAC(1) is on pin X5 and DAC(2) is on pin X6.
 
+   ``bits`` is an integer specifying the resolution, and can be 8 or 12.
+   The maximum value for the write and write_timed methods will be
+   2\*\*``bits``-1.
 
 Methods
 -------
 
+.. method:: dac.init(bits=8)
+
+   Reinitialise the DAC.  ``bits`` can be 8 or 12.
+
 .. method:: dac.noise(freq)
 
    Generate a pseudo-random noise signal.  A new random sample is written
@@ -57,13 +79,16 @@ Methods
 
 .. method:: dac.write(value)
 
-   Direct access to the DAC output (8 bit only at the moment).
+   Direct access to the DAC output.  The minimum value is 0.  The maximum
+   value is 2\*\*``bits``-1, where ``bits`` is set when creating the DAC
+   object or by using the ``init`` method.
 
 .. method:: dac.write_timed(data, freq, \*, mode=DAC.NORMAL)
 
    Initiates a burst of RAM to DAC using a DMA transfer.
-   The input data is treated as an array of bytes (8 bit data).
-   
+   The input data is treated as an array of bytes in 8-bit mode, and
+   an array of unsigned half-words (array typecode 'H') in 12-bit mode.
+
    ``freq`` can be an integer specifying the frequency to write the DAC
    samples at, using Timer(6).  Or it can be an already-initialised
    Timer object which is used to trigger the DAC sample.  Valid timers