Bell Huang / pixart_pah8011

class pah8011 for mbed

pah8011/pah_driver.h@0:242cf8f28bf2, 2017-10-26 (annotated)

Committer:
bell_huang
Date:
Thu Oct 26 02:49:44 2017 +0000
Revision:
0:242cf8f28bf2
Child:
6:d196b612b14a
Init version

Who changed what in which revision?

UserRevisionLine numberNew contents of line
bell_huang 0:242cf8f28bf2 1 /*==============================================================================
bell_huang 0:242cf8f28bf2 2 * Edit History
bell_huang 0:242cf8f28bf2 3 *
bell_huang 0:242cf8f28bf2 4 * This section contains comments describing changes made to the module. Notice
bell_huang 0:242cf8f28bf2 5 * that changes are listed in reverse chronological order. Please use ISO format
bell_huang 0:242cf8f28bf2 6 * for dates.
bell_huang 0:242cf8f28bf2 7 *
bell_huang 0:242cf8f28bf2 8 * when who what, where, why
bell_huang 0:242cf8f28bf2 9 * ---------- --- -----------------------------------------------------------
bell_huang 0:242cf8f28bf2 10 * 2016-10-20 bh - Move some public types to new file pah_driver_types.h for reuse.
bell_huang 0:242cf8f28bf2 11 * - Add function: pah_fifo_data_num_per_ch().
bell_huang 0:242cf8f28bf2 12 * 2016-09-08 bh - Add functions: pah_init_with_flags().
bell_huang 0:242cf8f28bf2 13 * - Add pah_ppg_led_on_e flag.
bell_huang 0:242cf8f28bf2 14 * 2016-06-07 bh - Add functions: pah_set_mode(), pah_run_device().
bell_huang 0:242cf8f28bf2 15 * - Add enum: pah_device.
bell_huang 0:242cf8f28bf2 16 * - Add comments.
bell_huang 0:242cf8f28bf2 17 * 2016-04-29 bh - Add PPG 200Hz modes.
bell_huang 0:242cf8f28bf2 18 * - Add helper functions: pah_is_ppg_mode(), pah_is_ppg_20hz_mode(), pah_fifo_data_num_per_ch().
bell_huang 0:242cf8f28bf2 19 * - Add pah_stop_mode
bell_huang 0:242cf8f28bf2 20 * - Remove pah_suspend_mode.
bell_huang 0:242cf8f28bf2 21 * - Fix setting pah_set_report_sample_num_per_ch() after enter_mode() causes bad behavior.
bell_huang 0:242cf8f28bf2 22 * 2016-04-20 bh Add pah_stop_mode. pah_none can be regarded as pah_stop_mode.
bell_huang 0:242cf8f28bf2 23 * 2016-04-12 bh Add license information and revision information.
bell_huang 0:242cf8f28bf2 24 * 2016-04-07 bh Initial revision.
bell_huang 0:242cf8f28bf2 25 ==============================================================================*/
bell_huang 0:242cf8f28bf2 26
bell_huang 0:242cf8f28bf2 27 #ifndef __pah_driver_h__
bell_huang 0:242cf8f28bf2 28 #define __pah_driver_h__
bell_huang 0:242cf8f28bf2 29
bell_huang 0:242cf8f28bf2 30
bell_huang 0:242cf8f28bf2 31 #include "pah_driver_types.h"
bell_huang 0:242cf8f28bf2 32 #include "pah_platform_types.h"
bell_huang 0:242cf8f28bf2 33
bell_huang 0:242cf8f28bf2 34
bell_huang 0:242cf8f28bf2 35 typedef struct {
bell_huang 0:242cf8f28bf2 36
bell_huang 0:242cf8f28bf2 37 pah_stream_e stream;
bell_huang 0:242cf8f28bf2 38 pah_intshape_pulse_type_e intshape_pulse_type;
bell_huang 0:242cf8f28bf2 39 pah_powerdown_int_status_e powerdown_int_status;
bell_huang 0:242cf8f28bf2 40 pah_ppg_led_on_e ppg_led_on;
bell_huang 0:242cf8f28bf2 41
bell_huang 0:242cf8f28bf2 42 } pah_flags_s;
bell_huang 0:242cf8f28bf2 43
bell_huang 0:242cf8f28bf2 44
bell_huang 0:242cf8f28bf2 45 /**
bell_huang 0:242cf8f28bf2 46 * @brief Get default pah_flags_s.
bell_huang 0:242cf8f28bf2 47 *
bell_huang 0:242cf8f28bf2 48 * @param[out] flags Refer to struct pah_flags_s.
bell_huang 0:242cf8f28bf2 49 */
bell_huang 0:242cf8f28bf2 50 void pah_flags_default(pah_flags_s *flags);
bell_huang 0:242cf8f28bf2 51
bell_huang 0:242cf8f28bf2 52 /**
bell_huang 0:242cf8f28bf2 53 * @brief Initialize the driver.
bell_huang 0:242cf8f28bf2 54 *
bell_huang 0:242cf8f28bf2 55 * It should been called once before any other function calls.
bell_huang 0:242cf8f28bf2 56 *
bell_huang 0:242cf8f28bf2 57 * @return True if successful.
bell_huang 0:242cf8f28bf2 58 */
bell_huang 0:242cf8f28bf2 59 bool pah_init(void);
bell_huang 0:242cf8f28bf2 60
bell_huang 0:242cf8f28bf2 61 /**
bell_huang 0:242cf8f28bf2 62 * @brief Initialize the driver.
bell_huang 0:242cf8f28bf2 63 *
bell_huang 0:242cf8f28bf2 64 * It should been called once before any other function calls.
bell_huang 0:242cf8f28bf2 65 *
bell_huang 0:242cf8f28bf2 66 * @param[in] flags Refer to struct pah_flags_s.
bell_huang 0:242cf8f28bf2 67 *
bell_huang 0:242cf8f28bf2 68 * @return True if successful.
bell_huang 0:242cf8f28bf2 69 */
bell_huang 0:242cf8f28bf2 70 bool pah_init_with_flags(const pah_flags_s *flags);
bell_huang 0:242cf8f28bf2 71
bell_huang 0:242cf8f28bf2 72 /**
bell_huang 0:242cf8f28bf2 73 * @brief De-initialize the driver.
bell_huang 0:242cf8f28bf2 74 *
bell_huang 0:242cf8f28bf2 75 * @return None.
bell_huang 0:242cf8f28bf2 76 */
bell_huang 0:242cf8f28bf2 77 void pah_deinit(void);
bell_huang 0:242cf8f28bf2 78
bell_huang 0:242cf8f28bf2 79
bell_huang 0:242cf8f28bf2 80 /**
bell_huang 0:242cf8f28bf2 81 * @brief Set device into a given pah mode and run device.
bell_huang 0:242cf8f28bf2 82 *
bell_huang 0:242cf8f28bf2 83 * It change device into a specific mode(refer to enum pah_mode) and then enable device to run if the mode depends on device.
bell_huang 0:242cf8f28bf2 84 * Equal to the combination of pah_set_mode() and pah_run(), i.e
bell_huang 0:242cf8f28bf2 85 * pah_set_mode(pah_ppg_mode);
bell_huang 0:242cf8f28bf2 86 * pah_run(pah_device_ppg, true);
bell_huang 0:242cf8f28bf2 87 *
bell_huang 0:242cf8f28bf2 88 * @param[in] mode Refer to enum pah_mode.
bell_huang 0:242cf8f28bf2 89 *
bell_huang 0:242cf8f28bf2 90 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 91 */
bell_huang 0:242cf8f28bf2 92 bool pah_enter_mode(pah_mode mode);
bell_huang 0:242cf8f28bf2 93
bell_huang 0:242cf8f28bf2 94
bell_huang 0:242cf8f28bf2 95 /**
bell_huang 0:242cf8f28bf2 96 * @brief Set device into a given pah mode.
bell_huang 0:242cf8f28bf2 97 *
bell_huang 0:242cf8f28bf2 98 * It change device into a specific mode(refer to enum pah_mode).
bell_huang 0:242cf8f28bf2 99 *
bell_huang 0:242cf8f28bf2 100 * @param[in] mode Refer to enum pah_mode.
bell_huang 0:242cf8f28bf2 101 *
bell_huang 0:242cf8f28bf2 102 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 103 */
bell_huang 0:242cf8f28bf2 104 bool pah_set_mode(pah_mode mode);
bell_huang 0:242cf8f28bf2 105
bell_huang 0:242cf8f28bf2 106 /**
bell_huang 0:242cf8f28bf2 107 * @brief Enable/Disable device to run.
bell_huang 0:242cf8f28bf2 108 *
bell_huang 0:242cf8f28bf2 109 * It returns false if the current mode isn't activable, such as pah_stop_mode.
bell_huang 0:242cf8f28bf2 110 *
bell_huang 0:242cf8f28bf2 111 * @param[in] device Refer to enum pah_device.
bell_huang 0:242cf8f28bf2 112 * @param[in] enable Enable/Disable the device.
bell_huang 0:242cf8f28bf2 113 *
bell_huang 0:242cf8f28bf2 114 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 115 */
bell_huang 0:242cf8f28bf2 116 bool pah_run_device(pah_device device, bool enable);
bell_huang 0:242cf8f28bf2 117
bell_huang 0:242cf8f28bf2 118
bell_huang 0:242cf8f28bf2 119 /**
bell_huang 0:242cf8f28bf2 120 * @brief Query current mode.
bell_huang 0:242cf8f28bf2 121 *
bell_huang 0:242cf8f28bf2 122 * @return Refer to enum pah_mode.
bell_huang 0:242cf8f28bf2 123 */
bell_huang 0:242cf8f28bf2 124 pah_mode pah_query_mode(void);
bell_huang 0:242cf8f28bf2 125
bell_huang 0:242cf8f28bf2 126 /**
bell_huang 0:242cf8f28bf2 127 * @brief Check if the device is in PPG mode.
bell_huang 0:242cf8f28bf2 128 *
bell_huang 0:242cf8f28bf2 129 * @return True if the device is in PPG mode.
bell_huang 0:242cf8f28bf2 130 */
bell_huang 0:242cf8f28bf2 131 bool pah_is_ppg_mode(void);
bell_huang 0:242cf8f28bf2 132
bell_huang 0:242cf8f28bf2 133 /**
bell_huang 0:242cf8f28bf2 134 * @brief Check if the device is in PPG(20Hz) mode.
bell_huang 0:242cf8f28bf2 135 *
bell_huang 0:242cf8f28bf2 136 * @return True if the device is in PPG(20Hz) mode.
bell_huang 0:242cf8f28bf2 137 */
bell_huang 0:242cf8f28bf2 138 bool pah_is_ppg_20hz_mode(void);
bell_huang 0:242cf8f28bf2 139
bell_huang 0:242cf8f28bf2 140
bell_huang 0:242cf8f28bf2 141 /**
bell_huang 0:242cf8f28bf2 142 * @brief Process tasks after INT1 interrupt.
bell_huang 0:242cf8f28bf2 143 *
bell_huang 0:242cf8f28bf2 144 * Whenever the device raises INT1 interrupt, this function must be called once to process tasks.
bell_huang 0:242cf8f28bf2 145 * This return pah_ret stands for a erorr code, normally it should been pah_success.
bell_huang 0:242cf8f28bf2 146 *
bell_huang 0:242cf8f28bf2 147 * If it returns pah_success, you can handle with some tasks according to current mode.
bell_huang 0:242cf8f28bf2 148 *
bell_huang 0:242cf8f28bf2 149 * Else if it returns pah_no_interrupt, it means that the device didn't raise INT1 interrupt yet.
bell_huang 0:242cf8f28bf2 150 * Generally there is an extrinsic factor raising the interrupt which has nothing to do with the device.
bell_huang 0:242cf8f28bf2 151 *
bell_huang 0:242cf8f28bf2 152 * @return pah_success if the open operation was done successfully.
bell_huang 0:242cf8f28bf2 153 * pah_no_interrupt if the device didn't raise interrupt yet.
bell_huang 0:242cf8f28bf2 154 * pah_err_fifo_overflow if pah_task() was too late to be called.
bell_huang 0:242cf8f28bf2 155 * Otherwise to indicate an error has occurred.
bell_huang 0:242cf8f28bf2 156 */
bell_huang 0:242cf8f28bf2 157 pah_ret pah_task(void);
bell_huang 0:242cf8f28bf2 158
bell_huang 0:242cf8f28bf2 159
bell_huang 0:242cf8f28bf2 160 /**
bell_huang 0:242cf8f28bf2 161 * @brief Access current fifo data.
bell_huang 0:242cf8f28bf2 162 *
bell_huang 0:242cf8f28bf2 163 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 164 *
bell_huang 0:242cf8f28bf2 165 * @return Location where fifo data is stored.
bell_huang 0:242cf8f28bf2 166 */
bell_huang 0:242cf8f28bf2 167 uint8_t* pah_get_fifo_data(void);
bell_huang 0:242cf8f28bf2 168
bell_huang 0:242cf8f28bf2 169 /**
bell_huang 0:242cf8f28bf2 170 * @brief Read current length of fifo data.
bell_huang 0:242cf8f28bf2 171 *
bell_huang 0:242cf8f28bf2 172 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 173 *
bell_huang 0:242cf8f28bf2 174 * @return The length(in bytes) of fifo data.
bell_huang 0:242cf8f28bf2 175 */
bell_huang 0:242cf8f28bf2 176 uint32_t pah_fifo_data_num_per_ch(void);
bell_huang 0:242cf8f28bf2 177
bell_huang 0:242cf8f28bf2 178 /**
bell_huang 0:242cf8f28bf2 179 * @brief Check if there are fifo data.
bell_huang 0:242cf8f28bf2 180 *
bell_huang 0:242cf8f28bf2 181 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 182 *
bell_huang 0:242cf8f28bf2 183 * @return True if there are fifo data.
bell_huang 0:242cf8f28bf2 184 */
bell_huang 0:242cf8f28bf2 185 bool pah_has_fifo_data(void);
bell_huang 0:242cf8f28bf2 186
bell_huang 0:242cf8f28bf2 187 /**
bell_huang 0:242cf8f28bf2 188 * @brief Check fifo channel number.
bell_huang 0:242cf8f28bf2 189 *
bell_huang 0:242cf8f28bf2 190 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 191 *
bell_huang 0:242cf8f28bf2 192 * @return Channel number.
bell_huang 0:242cf8f28bf2 193 */
bell_huang 0:242cf8f28bf2 194 uint32_t pah_get_fifo_ch_num(void);
bell_huang 0:242cf8f28bf2 195
bell_huang 0:242cf8f28bf2 196 /**
bell_huang 0:242cf8f28bf2 197 * @brief Check if the device is on touch.
bell_huang 0:242cf8f28bf2 198 *
bell_huang 0:242cf8f28bf2 199 * This information is updated after a successful pah_task().
bell_huang 0:242cf8f28bf2 200 *
bell_huang 0:242cf8f28bf2 201 * @return True if the device is on touch.
bell_huang 0:242cf8f28bf2 202 */
bell_huang 0:242cf8f28bf2 203 bool pah_is_touched(void);
bell_huang 0:242cf8f28bf2 204
bell_huang 0:242cf8f28bf2 205
bell_huang 0:242cf8f28bf2 206 /**
bell_huang 0:242cf8f28bf2 207 * @brief Set all values of fifo data to 0.
bell_huang 0:242cf8f28bf2 208 *
bell_huang 0:242cf8f28bf2 209 * @return None.
bell_huang 0:242cf8f28bf2 210 */
bell_huang 0:242cf8f28bf2 211 void pah_clear_fifo_data(void);
bell_huang 0:242cf8f28bf2 212
bell_huang 0:242cf8f28bf2 213
bell_huang 0:242cf8f28bf2 214 /**
bell_huang 0:242cf8f28bf2 215 * @brief Set report fifo callback.
bell_huang 0:242cf8f28bf2 216 *
bell_huang 0:242cf8f28bf2 217 * @param[in] fp_handler The callback function to be called when pah_task() receives new fifo data.
bell_huang 0:242cf8f28bf2 218 * @param[in] user_data The user data to be passed as parameter of callback function.
bell_huang 0:242cf8f28bf2 219 *
bell_huang 0:242cf8f28bf2 220 * @return None.
bell_huang 0:242cf8f28bf2 221 */
bell_huang 0:242cf8f28bf2 222 void pah_set_report_fifo_callback(pah_report_fifo_handle fp_handler, void* user_data);
bell_huang 0:242cf8f28bf2 223
bell_huang 0:242cf8f28bf2 224
bell_huang 0:242cf8f28bf2 225 /**
bell_huang 0:242cf8f28bf2 226 * @brief Get the specific I2C slave address of the device.
bell_huang 0:242cf8f28bf2 227 *
bell_huang 0:242cf8f28bf2 228 * @return I2C slave address of the device.
bell_huang 0:242cf8f28bf2 229 */
bell_huang 0:242cf8f28bf2 230 uint16_t pah_get_i2c_slave_addr(void);
bell_huang 0:242cf8f28bf2 231
bell_huang 0:242cf8f28bf2 232
bell_huang 0:242cf8f28bf2 233 /**
bell_huang 0:242cf8f28bf2 234 * @brief Enable or disable INT2 as touch flag.
bell_huang 0:242cf8f28bf2 235 *
bell_huang 0:242cf8f28bf2 236 * Default is disabled.
bell_huang 0:242cf8f28bf2 237 *
bell_huang 0:242cf8f28bf2 238 * By default, touch/no-touch detection raises a pulse interrupt to INT1 which shared with FIFO interrupt.
bell_huang 0:242cf8f28bf2 239 * If INT2 as touch flag is enabled, the device on touch causes INT2 pull-up, otherwise pull-down.
bell_huang 0:242cf8f28bf2 240 *
bell_huang 0:242cf8f28bf2 241 * @param[in] enable True to enable, otherwise to disable.
bell_huang 0:242cf8f28bf2 242 *
bell_huang 0:242cf8f28bf2 243 * @return True if setting successfully.
bell_huang 0:242cf8f28bf2 244 */
bell_huang 0:242cf8f28bf2 245 bool pah_set_int2_as_touch_flag(bool enable);
bell_huang 0:242cf8f28bf2 246
bell_huang 0:242cf8f28bf2 247
bell_huang 0:242cf8f28bf2 248 /**
bell_huang 0:242cf8f28bf2 249 * @brief Set report number per channel.
bell_huang 0:242cf8f28bf2 250 *
bell_huang 0:242cf8f28bf2 251 * The report number determines how many fifo data number the device collects, the device will raise a fifo interrupt.
bell_huang 0:242cf8f28bf2 252 * For example, in PPG(20Hz) the device generates one data per 50ms, thus setting report number 20 makes the device raise fifo interrupts each 50ms*20 = 1000ms.
bell_huang 0:242cf8f28bf2 253 *
bell_huang 0:242cf8f28bf2 254 * @param[in] report_sample_num_per_ch The report number per channel.
bell_huang 0:242cf8f28bf2 255 *
bell_huang 0:242cf8f28bf2 256 * @return None.
bell_huang 0:242cf8f28bf2 257 */
bell_huang 0:242cf8f28bf2 258 void pah_set_report_sample_num_per_ch(uint32_t report_sample_num_per_ch);
bell_huang 0:242cf8f28bf2 259
bell_huang 0:242cf8f28bf2 260 /**
bell_huang 0:242cf8f28bf2 261 * @brief Get report number per channel.
bell_huang 0:242cf8f28bf2 262 *
bell_huang 0:242cf8f28bf2 263 * @return The report number per channel.
bell_huang 0:242cf8f28bf2 264 */
bell_huang 0:242cf8f28bf2 265 uint32_t pah_get_report_sample_num_per_ch(void);
bell_huang 0:242cf8f28bf2 266
bell_huang 0:242cf8f28bf2 267 /**
bell_huang 0:242cf8f28bf2 268 * @brief Get the maximum report number per channel.
bell_huang 0:242cf8f28bf2 269 *
bell_huang 0:242cf8f28bf2 270 * Due to the limit of buffer length, the number passing to pah_set_report_sample_num_per_ch() must be less than a maximum value.
bell_huang 0:242cf8f28bf2 271 *
bell_huang 0:242cf8f28bf2 272 * @return The maximum report number per channel.
bell_huang 0:242cf8f28bf2 273 */
bell_huang 0:242cf8f28bf2 274 uint32_t pah_get_max_report_sample_num_per_ch(void);
bell_huang 0:242cf8f28bf2 275
bell_huang 0:242cf8f28bf2 276 /**
bell_huang 0:242cf8f28bf2 277 * @brief Get how many bytes per fifo sample.
bell_huang 0:242cf8f28bf2 278 *
bell_huang 0:242cf8f28bf2 279 * @return Bytes per fifo sample.
bell_huang 0:242cf8f28bf2 280 */
bell_huang 0:242cf8f28bf2 281 uint32_t pah_get_bytes_per_sample(void);
bell_huang 0:242cf8f28bf2 282
bell_huang 0:242cf8f28bf2 283 /**
bell_huang 0:242cf8f28bf2 284 * @brief Check if the driver is valid to the device.
bell_huang 0:242cf8f28bf2 285 *
bell_huang 0:242cf8f28bf2 286 * This function reads device registers directly.
bell_huang 0:242cf8f28bf2 287 *
bell_huang 0:242cf8f28bf2 288 * @return True if the driver is valid to the device.
bell_huang 0:242cf8f28bf2 289 */
bell_huang 0:242cf8f28bf2 290 bool pah_verify_product_id(void);
bell_huang 0:242cf8f28bf2 291
bell_huang 0:242cf8f28bf2 292 /**
bell_huang 0:242cf8f28bf2 293 * @brief Check if the device is on touch.
bell_huang 0:242cf8f28bf2 294 *
bell_huang 0:242cf8f28bf2 295 * This function reads device registers directly.
bell_huang 0:242cf8f28bf2 296 *
bell_huang 0:242cf8f28bf2 297 * @param[out] is_touched True if the device is on touch.
bell_huang 0:242cf8f28bf2 298 *
bell_huang 0:242cf8f28bf2 299 * @return pah_success if the open operation was done successfully.
bell_huang 0:242cf8f28bf2 300 * Otherwise to indicate an error has occurred.
bell_huang 0:242cf8f28bf2 301 */
bell_huang 0:242cf8f28bf2 302 pah_ret pah_read_touch_flag(bool *is_touched);
bell_huang 0:242cf8f28bf2 303
bell_huang 0:242cf8f28bf2 304
bell_huang 0:242cf8f28bf2 305 #endif // header guard