rpp/include/rpp/din.h

   1 /**
   2  * Digital Input RPP API header file.
   3  *
   4  * @file din.h
   5  *
   6  * @copyright Copyright (C) 2013, 2016 Czech Technical University in Prague
   7  *
   8  * @author Carlos Jenkins <carlos@jenkins.co.cr>
   9  */
  10
  11
  12 #ifndef __RPP_DIN_H
  13 #define __RPP_DIN_H
  14
  15 /**
  16  * DIN module initialization.
  17  *
  18  * Call this method before using this module.
  19  *
  20  * This function is not thread safe. Do not call it from multiple threads.
  21  *
  22  * @return SUCCESS if initialization successful.\n
  23  *         FAILURE if module already initialized.
  24  */
  25 int8_t rpp_din_init();
  26
  27
  28 /**
  29  * Configure voltage reference levels for digital inputs using variable
  30  * reference threshold.
  31  *
  32  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  33  *
  34  * @param[in] refA      [0-4095] value to set (DAC is 12bits) the reference
  35  *                      voltage A (pins 12-15).
  36  * @param[in] refB      [0-4095] value to set (DAC is 12bits) the reference
  37  *                      voltage B (pins 8-11).
  38  *
  39  * @return SUCCESS if successful.\n
  40  *         -1 if pin millivolts is out of range.
  41  */
  42 int8_t rpp_din_ref(uint16_t refA, uint16_t refB);
  43
  44
  45 /**
  46  * Configure given pin.
  47  *
  48  * Call rpp_din_update() to commit configuration changes to the hardware.
  49  *
  50  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  51  *
  52  * @param[in] pin       The pin number to setup [0-15].
  53  * @param[in] pull_up   TRUE to setup pin as pull-up (a switch-to-ground device
  54  *                      is connected) or FALSE to setup as pull-down
  55  *                      (switch-to-battery).
  56  *                      Note that pins [8-15] are pull-down only.
  57  * @param[in] active    TRUE to setup pin as active or FALSE to set it as
  58  *                      tri-stated.
  59  * @param[in] can_wake  TRUE if the given pin can wake the module from
  60  *                      sleep state and trigger an interrupt on MCU.
  61  *                      FALSE otherwise.
  62  *
  63  * @return SUCCESS if successful.\n
  64  *         -1 if pin number is out of range.\n
  65  *         -2 if pull_type is requested for pins without this feature.
  66  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  67  */
  68 int8_t rpp_din_setup(uint8_t pin, boolean_t pull_up,
  69                                          boolean_t active, boolean_t can_wake);
  70
  71
  72 /**
  73  * Get the current cached value of the switch state on the given pin.
  74  *
  75  * Call rpp_din_update() to update cached values.
  76  *
  77  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  78  *
  79  * @param[in] pin       The pin number to read [0-15].
  80  *
  81  * @return RPP_CLOSED or RPP_OPEN if successful.\n
  82  *         -1 if pin number is out of range.\n
  83  *         -2 if var_thr is requested for inputs without this feature.
  84  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  85  */
  86 int8_t rpp_din_get(uint8_t pin);
  87
  88
  89 /**
  90  * Get uncached logical value of the given pin read via comparator with programmable threshold.
  91  *
  92  * Inputs [8-11] use programmable threshold B and [12-15] use
  93  * programmable threshold A.\n
  94  *
  95  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  96  *
  97  * @see rpp_din_ref().
  98  *
  99  * @param[in] pin       The pin number to read [8-15].
 100  *
 101  * @return HIGH or LOW if successful.\n
 102  *         -1 if pin number is out of range.\n
 103  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
 104  */
 105 int8_t rpp_din_get_tr(uint8_t pin);
 106
 107
 108 /**
 109  * Get the diagnostic cached value for given pin.
 110  *
 111  * Call rpp_din_update() to update cached values.
 112  *
 113  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
 114  *
 115  * @param[in] pin       The pin number to read [0-15].
 116  *
 117  * @return HIGH or LOW if successful.\n
 118  *         -1 if pin number is out of range.
 119  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
 120  */
 121 int8_t rpp_din_diag(uint8_t pin);
 122
 123
 124 /**
 125  * Read and update cached values and diagnostic values of all pins. Also commit
 126  * configuration changes.
 127  *
 128  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
 129  *
 130  * @return SUCCESS when transaction was successful.\n
 131  *         FAILURE if transaction could not be confirmed.
 132  */
 133 int8_t rpp_din_update();
 134
 135
 136 #endif /* __RPP_DIN_H */