rpp/include/rpp/dac.h

   1 /**
   2  * Analog Output RPP API header file.
   3  *
   4  * @file dac.h
   5  *
   6  * @copyright Copyright (C) 2013 Czech Technical University in Prague
   7  *
   8  * @author Carlos Jenkins <carlos@jenkins.co.cr>
   9  */
  10
  11
  12 #ifndef __RPP_DAC_H
  13 #define __RPP_DAC_H
  14
  15 /**
  16  * DAC output operational amplifier multiplication constant.
  17  */
  18 #define RPP_DAC_OA          5.6
  19 /**
  20  * DAC hardware reference voltage.
  21  */
  22 #define RPP_DAC_VREF        2.5
  23
  24 /**
  25  * DAC module initialization.
  26  *
  27  * Call this method before using this module.
  28  *
  29  * This function is not thread safe. Do not call it from multiple threads.
  30  *
  31  * @return SUCCESS if initialization successful.\n
  32  *         FAILURE if module already initialized.
  33  */
  34 int8_t rpp_dac_init();
  35
  36
  37 /**
  38  * Configure enabled/disabled state for given pin.
  39  *
  40  * Call rpp_dac_update() to commit setup changes to real hardware.
  41  *
  42  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  43  *
  44  * @param[in] pin       The pin number to setup [1-4].
  45  * @param[in] enabled   TRUE to enable pin or FALSE to disable it.
  46  *
  47  * @return SUCCESS if successful.\n
  48  *         -1 if pin number is out of range.
  49  */
  50 int8_t rpp_dac_setup(uint8_t pin, boolean_t enabled);
  51
  52
  53 /**
  54  * Set the output cache of given pin to given value.
  55  *
  56  * Call rpp_dac_update() to flush cached values to real hardware.
  57  *
  58  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  59  *
  60  * @param[in] pin       The pin number to set [1-4].
  61  * @param[in] val       The value to be set [0-4095] (DAC is 12bit resolution).
  62  *
  63  * @return SUCCESS when success.\n
  64  *         -1 if pin number is out of range.\n
  65  *         -2 if value is out of range.
  66  *
  67  * @note Due to hardware characteristics (operational amplifiers and voltage
  68  *       reference) the DAC outputs top 12V at arround 3510. To avoid confusion
  69  *       to the user and to support future changes the value given is mapped
  70  *       from [0-4095] to [0-3510] with the expected resolution loss.
  71  */
  72 int8_t rpp_dac_set(uint8_t pin, uint16_t val);
  73
  74
  75 /**
  76  * Set output to given voltage.
  77  *
  78  * Helper function that calculates DAC value given a voltage in millivolts.
  79  *
  80  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  81  *
  82  * @param[in] pin       The pin number to set [1-4].
  83  * @param[in] mv        Voltage level in mV to be set on specified pin [0-12000].
  84  *
  85  * @return SUCCESS when success.\n
  86  *         -1 if pin number is out of range.\n
  87  *         -2 if voltage is out of range.
  88  */
  89 int8_t rpp_dac_set_voltage(uint8_t pin, uint16_t mv);
  90
  91
  92 /**
  93  * Flush cached output values and configuration changes.
  94  *
  95  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  96  *
  97  * @bug This function should be called only after the FreeRTOS Scheduler has
  98  * started (which implies from a FreeRTOS Task). If called before starting the
  99  * scheduler, like for library initialization, or application DAC
 100  * initialization, the application will freeze. The cause of this is unknown at
 101  * the moment.
 102  *
 103  * @return SUCCESS when transaction was successful.\n
 104  *         FAILURE if transaction could not be confirmed.
 105  */
 106 int8_t rpp_dac_update();
 107
 108
 109 #endif /* __RPP_DAC_H */