rpp/include/rpp/din.h

   1 /**
   2  * Digital Input RPP API header file.
   3  *
   4  * @file din.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_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 is given pin can wake module from sleep state and
  60  *                      trigger an interrupt on MCU. FALSE otherwise.
  61  *
  62  * @return SUCCESS if successful.\n
  63  *         -1 if pin number is out of range.\n
  64  *         -2 if pull_type is requested for pins without this feature.
  65  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  66  */
  67 int8_t rpp_din_setup(uint8_t pin, boolean_t pull_up,
  68                                          boolean_t active, boolean_t can_wake);
  69
  70
  71 /**
  72  * Get the current cached value of the switch state on the given pin.
  73  *
  74  * Call rpp_din_update() to update cached values.
  75  *
  76  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  77  *
  78  * @param[in] pin       The pin number to read [0-15].
  79  *
  80  * @return RPP_CLOSED or RPP_OPEN if successful.\n
  81  *         -1 if pin number is out of range.\n
  82  *         -2 if var_thr is requested for inputs without this feature.
  83  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  84  */
  85 int8_t rpp_din_get(uint8_t pin);
  86
  87
  88 /**
  89  * Get uncached logical value of the given pin read via comparator with programmable threshold.
  90  *
  91  * Inputs [8-11] use programmable threshold B and [12-15] use
  92  * programmable threshold A.\n
  93  *
  94  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  95  *
  96  * @see rpp_din_ref().
  97  *
  98  * @param[in] pin       The pin number to read [8-15].
  99  *
 100  * @return HIGH or LOW if successful.\n
 101  *         -1 if pin number is out of range.\n
 102  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
 103  */
 104 int8_t rpp_din_get_tr(uint8_t pin);
 105
 106
 107 /**
 108  * Get the diagnostic cached value for given pin.
 109  *
 110  * Call rpp_din_update() to update cached values.
 111  *
 112  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
 113  *
 114  * @param[in] pin       The pin number to read [0-15].
 115  *
 116  * @return HIGH or LOW if successful.\n
 117  *         -1 if pin number is out of range.
 118  *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
 119  */
 120 int8_t rpp_din_diag(uint8_t pin);
 121
 122
 123 /**
 124  * Read and update cached values and diagnostic values of all pins. Also commit
 125  * configuration changes.
 126  *
 127  * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
 128  *
 129  * @return SUCCESS when transaction was successful.\n
 130  *         FAILURE if transaction could not be confirmed.
 131  */
 132 int8_t rpp_din_update();
 133
 134
 135 #endif /* __RPP_DIN_H */