pah_driver.h

00001 /**
00002  * @file sns_dd_pah_driver.h
00003  *
00004  * Copyright (c) 2016-2017 PixArt Imaging Inc.
00005  * All Rights Reserved.
00006  * Confidential and Proprietary - PixArt Imaging Inc.
00007  **/
00008 
00009 /*==============================================================================
00010 * Edit History
00011 * 
00012 * This section contains comments describing changes made to the module. Notice
00013 * that changes are listed in reverse chronological order. Please use ISO format
00014 * for dates.
00015 * 
00016 * when       who       what, where, why
00017 * ---------- ---       -----------------------------------------------------------
00018 * 2016-10-14 bell      - Add functions: pah_init_with_flags().
00019 *                      - Add pah_ppg_led_on_e flag.
00020 * 2016-06-07 bell      - Add functions: pah_set_mode(), pah_run_device().
00021 *                      - Add enum: pah_device.
00022 *                      - Add comments.
00023 * 2016-04-29 bell      - Add PPG 200Hz modes.
00024 *                      - Add helper functions: pah_is_ppg_mode(), pah_is_ppg_20hz_mode(), pah_fifo_data_num_per_ch().
00025 *                      - Add pah_stop_mode
00026 *                      - Remove pah_suspend_mode.
00027 *                      - Fix setting pah_set_report_sample_num_per_ch() after enter_mode() causes bad behavior.
00028 * 2016-04-20 bell      Add pah_stop_mode. pah_none can be regarded as pah_stop_mode.
00029 * 2016-04-12 bell      Add license information and revision information.
00030 * 2016-04-07 bell      Initial revision.
00031 ==============================================================================*/
00032 
00033 #ifndef __sns_dd_pah_driver_h__
00034 #define __sns_dd_pah_driver_h__
00035 
00036 #include "pah_platform_types.h"
00037 #include "pah_driver_types.h"
00038 #include "pah_ret.h"
00039 
00040 
00041 typedef struct {
00042 
00043     pah_stream_e                    stream;
00044     pah_intshape_pulse_type_e       intshape_pulse_type;
00045     pah_powerdown_int_status_e      powerdown_int_status;
00046     pah_ppg_led_on_e                ppg_led_on;
00047 
00048 } pah_flags_s;
00049 
00050 
00051 
00052 /**
00053  * @brief Initialize the driver.
00054  * 
00055  * It should been called once before any other function calls.
00056  *
00057  * @return True if successful.
00058  */
00059 bool        pah_init(void);
00060 
00061 /**
00062 * @brief Initialize the driver.
00063 *
00064 * It should been called once before any other function calls.
00065 *
00066 * @param[in]  flags        Refer to struct pah_flags_s.
00067 *
00068 * @return True if successful.
00069 */
00070 bool        pah_init_with_flags(const pah_flags_s *flags);
00071 
00072 /**
00073  * @brief De-initialize the driver.
00074  *
00075  * @return None.
00076  */
00077 void        pah_deinit(void);
00078 
00079 
00080 /**
00081  * @brief Set device into a given pah mode and run device.
00082  * 
00083  * It change device into a specific mode(refer to enum pah_mode) and then enable device to run if the mode depends on device.
00084  * Equal to the combination of pah_set_mode() and pah_run(), i.e
00085  *     pah_set_mode(pah_ppg_mode);
00086  *     pah_run(pah_device_ppg, true);
00087  *
00088  * @param[in]  mode         Refer to enum pah_mode.
00089  *
00090  * @return True if setting successfully.
00091  */
00092 bool        pah_enter_mode(pah_mode mode);
00093 
00094 
00095 /**
00096  * @brief Set device into a given pah mode.
00097  * 
00098  * It change device into a specific mode(refer to enum pah_mode).
00099  *
00100  * @param[in]  mode         Refer to enum pah_mode.
00101  *
00102  * @return True if setting successfully.
00103  */
00104 bool        pah_set_mode(pah_mode mode);
00105 
00106 /**
00107  * @brief Enable/Disable device to run.
00108  * 
00109  * It returns false if the current mode isn't activable, such as pah_stop_mode.
00110  *
00111  * @param[in]  device       Refer to enum pah_device.
00112  * @param[in]  enable       Enable/Disable the device.
00113  *
00114  * @return True if setting successfully.
00115  */
00116 bool        pah_run_device(pah_device device, bool enable);
00117 
00118 
00119 /**
00120  * @brief Query current mode.
00121  *
00122  * @return Refer to enum pah_mode.
00123  */
00124 pah_mode    pah_query_mode(void);
00125 
00126 /**
00127  * @brief Check if the device is in PPG mode.
00128  *
00129  * @return True if the device is in PPG mode.
00130  */
00131 bool        pah_is_ppg_mode(void);
00132 
00133 /**
00134  * @brief Check if the device is in PPG(20Hz) mode.
00135  *
00136  * @return True if the device is in PPG(20Hz) mode.
00137  */
00138 bool        pah_is_ppg_20hz_mode(void);
00139 
00140 
00141 /**
00142  * @brief Process tasks after INT1 interrupt.
00143  *
00144  * Whenever the device raises INT1 interrupt, this function must be called once to process tasks.
00145  * This return pah_ret stands for a erorr code, normally it should been pah_success.
00146  *
00147  * If it returns pah_success, you can handle with some tasks according to current mode.
00148  *
00149  * Else if it returns pah_no_interrupt, it means that the device didn't raise INT1 interrupt yet.
00150  * Generally there is an extrinsic factor raising the interrupt which has nothing to do with the device.
00151  *
00152  * @return pah_success if the open operation was done successfully.
00153  *         pah_no_interrupt if the device didn't raise interrupt yet.
00154  *         pah_err_fifo_overflow if pah_task() was too late to be called.
00155  *         Otherwise to indicate an error has occurred.
00156  */
00157 pah_ret     pah_task(void);
00158 
00159 
00160 /**
00161  * @brief Access current fifo data.
00162  * 
00163  * This information is updated after a successful pah_task().
00164  *
00165  * @return Location where fifo data is stored.
00166  */
00167 uint8_t*    pah_get_fifo_data(void);
00168 
00169 /**
00170  * @brief Read current length of fifo data.
00171  * 
00172  * This information is updated after a successful pah_task().
00173  *
00174  * @return The length(in bytes) of fifo data.
00175  */
00176 uint32_t    pah_fifo_data_num_per_ch(void);
00177 
00178 /**
00179  * @brief Check if there are fifo data.
00180  * 
00181  * This information is updated after a successful pah_task().
00182  *
00183  * @return True if there are fifo data.
00184  */
00185 bool        pah_has_fifo_data(void);
00186 
00187 /**
00188  * @brief Check fifo channel number.
00189  * 
00190  * This information is updated after a successful pah_task().
00191  *
00192  * @return Channel number.
00193  */
00194 uint32_t    pah_get_fifo_ch_num(void);
00195 
00196 /**
00197  * @brief Check if the device is on touch.
00198  * 
00199  * This information is updated after a successful pah_task().
00200  *
00201  * @return True if the device is on touch.
00202  */
00203 bool        pah_is_touched(void);
00204 
00205 
00206 /**
00207  * @brief Set all values of fifo data to 0.
00208  *
00209  * @return None.
00210  */
00211 void        pah_clear_fifo_data(void);
00212 
00213 
00214 /**
00215  * @brief Set report fifo callback.
00216  *
00217  * @param[in]  fp_handler   The callback function to be called when pah_task() receives new fifo data.
00218  * @param[in]  user_data    The user data to be passed as parameter of callback function.
00219  * 
00220  * @return None.
00221  */
00222 void        pah_set_report_fifo_callback(pah_report_fifo_handle fp_handler, void* user_data);
00223 
00224 
00225 /**
00226  * @brief Get the specific I2C slave address of the device.
00227  * 
00228  * @return I2C slave address of the device.
00229  */
00230 uint16_t    pah_get_i2c_slave_addr(void);
00231 
00232 
00233 /**
00234  * @brief Enable or disable INT2 as touch flag.
00235  * 
00236  * Default is disabled.
00237  *
00238  * By default, touch/no-touch detection raises a pulse interrupt to INT1 which shared with FIFO interrupt.
00239  * If INT2 as touch flag is enabled, the device on touch causes INT2 pull-up, otherwise pull-down.
00240  *
00241  * @param[in]  enable   True to enable, otherwise to disable.
00242  * 
00243  * @return True if setting successfully.
00244  */
00245 bool        pah_set_int2_as_touch_flag(bool enable);
00246 
00247 
00248 /**
00249  * @brief Set report number per channel.
00250  *
00251  * The report number determines how many fifo data number the device collects, the device will raise a fifo interrupt.
00252  * 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.
00253  *
00254  * @param[in]  report_sample_num_per_ch   The report number per channel.
00255  * 
00256  * @return None.
00257  */
00258 void        pah_set_report_sample_num_per_ch(uint32_t report_sample_num_per_ch);
00259 
00260 /**
00261  * @brief Get report number per channel.
00262  *
00263  * @return The report number per channel.
00264  */
00265 uint32_t    pah_get_report_sample_num_per_ch(void);
00266 
00267 /**
00268  * @brief Get the maximum report number per channel.
00269  * 
00270  * 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.
00271  *
00272  * @return The maximum report number per channel.
00273  */
00274 uint32_t    pah_get_max_report_sample_num_per_ch(void);
00275 
00276 /**
00277  * @brief Get how many bytes per fifo sample.
00278  *
00279  * @return Bytes per fifo sample.
00280  */
00281 uint32_t    pah_get_bytes_per_sample(void);
00282 
00283 
00284 /**
00285  * @brief Check if the driver is valid to the device.
00286  * 
00287  * This function reads device registers directly.
00288  *
00289  * @return True if the driver is valid to the device.
00290  */
00291 bool        pah_verify_product_id(void);
00292 
00293 /**
00294  * @brief Check if the device is on touch.
00295  * 
00296  * This function reads device registers directly.
00297  *
00298  * @param[out]  is_touched   True if the device is on touch.
00299  *
00300  * @return pah_success if the open operation was done successfully.
00301  *         Otherwise to indicate an error has occurred.
00302  */
00303 pah_ret     pah_read_touch_flag(bool *is_touched);
00304 
00305 
00306 #endif  // header guard
00307