diff options
Diffstat (limited to 'stmhal/dac.c')
| -rw-r--r-- | stmhal/dac.c | 50 |
1 files changed, 45 insertions, 5 deletions
diff --git a/stmhal/dac.c b/stmhal/dac.c index cd62f017fb..b440bcbf50 100644 --- a/stmhal/dac.c +++ b/stmhal/dac.c @@ -16,6 +16,31 @@ /// \moduleref pyb /// \class DAC - digital to analog conversion /// +/// The DAC is used to output analog values (a specific voltage) on pin X5 or pin X6. +/// The voltage will be between 0 and 3.3V. +/// +/// *This module will undergo changes to the API.* +/// +/// Example usage: +/// +/// from pyb import DAC +/// +/// dac = DAC(1) # create DAC 1 on pin X5 +/// dac.write(128) # write a value to the DAC (makes X5 1.65V) +/// +/// To output a continuous sine-wave: +/// +/// import math +/// from pyb import DAC +/// +/// # create a buffer containing a sine-wave +/// buf = bytearray(100) +/// for i in range(len(buf)): +/// buf[i] = 128 + 127 * math.sin(2 * math.pi * i / len(buf)) +/// +/// # output the sine-wave at 400Hz +/// dac = DAC(1) +/// dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR) STATIC DAC_HandleTypeDef DAC_Handle; @@ -52,6 +77,10 @@ typedef struct _pyb_dac_obj_t { // create the dac object // currently support either DAC1 on X5 (id = 1) or DAC2 on X6 (id = 2) +/// \classmethod \constructor(id) +/// Construct a new DAC object. +/// +/// `id` can be 1 or 2: DAC 1 is on pin X5 and DAC 2 is on pin X6. STATIC mp_obj_t pyb_dac_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const mp_obj_t *args) { // check arguments mp_arg_check_num(n_args, n_kw, 1, 1, false); @@ -93,6 +122,9 @@ STATIC mp_obj_t pyb_dac_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const return dac; } +/// \method noise(freq) +/// Generate a pseudo-random noise signal. A new random sample is written +/// to the DAC output at the given frequency. STATIC mp_obj_t pyb_dac_noise(mp_obj_t self_in, mp_obj_t freq) { pyb_dac_obj_t *self = self_in; @@ -117,6 +149,10 @@ STATIC mp_obj_t pyb_dac_noise(mp_obj_t self_in, mp_obj_t freq) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(pyb_dac_noise_obj, pyb_dac_noise); +/// \method triangle(freq) +/// Generate a triangle wave. The value on the DAC output changes at +/// the given frequency, and the frequence of the repeating triangle wave +/// itself is 256 (or 1024, need to check) times smaller. STATIC mp_obj_t pyb_dac_triangle(mp_obj_t self_in, mp_obj_t freq) { pyb_dac_obj_t *self = self_in; @@ -141,7 +177,8 @@ STATIC mp_obj_t pyb_dac_triangle(mp_obj_t self_in, mp_obj_t freq) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(pyb_dac_triangle_obj, pyb_dac_triangle); -// direct access to DAC (8 bit only at the moment) +/// \method write(value) +/// Direct access to the DAC output (8 bit only at the moment). STATIC mp_obj_t pyb_dac_write(mp_obj_t self_in, mp_obj_t val) { pyb_dac_obj_t *self = self_in; @@ -160,12 +197,15 @@ STATIC mp_obj_t pyb_dac_write(mp_obj_t self_in, mp_obj_t val) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(pyb_dac_write_obj, pyb_dac_write); -// initiates a burst of RAM->DAC using DMA -// input data is treated as an array of bytes (8 bit data) -// TIM6 is used to set the frequency of the transfer +/// \method 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). +/// +/// `mode` can be `DAC.NORMAL` or `DAC.CIRCULAR`. +/// +/// TIM6 is used to control the frequency of the transfer. // TODO add callback argument, to call when transfer is finished // TODO add double buffer argument - STATIC const mp_arg_t pyb_dac_write_timed_args[] = { { MP_QSTR_data, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, { MP_QSTR_freq, MP_ARG_REQUIRED | MP_ARG_INT, {.u_int = 0} }, |