als_driver.h

00001 /*******************************************************************************
00002 ################################################################################
00003 #                             (C) STMicroelectronics 2014
00004 #
00005 # This program is free software; you can redistribute it and/or modify it under
00006 # the terms of the GNU General Public License version 2 and only version 2 as
00007 # published by the Free Software Foundation.
00008 #
00009 # This program is distributed in the hope that it will be useful, but WITHOUT
00010 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00011 # FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00012 # details.
00013 #
00014 # You should have received a copy of the GNU General Public License along with
00015 # this program; if not, write to the Free Software Foundation, Inc.,
00016 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00017 #
00018 #------------------------------------------------------------------------------
00019 #                             Imaging Division
00020 ################################################################################
00021 ********************************************************************************/
00022 
00023 /*!
00024  *\file als_driver.h
00025  *\brief Application-level methods used by VL6180X for ALS operations.
00026  */
00027 
00028 #ifndef _ALS_DRIVER
00029 #define _ALS_DRIVER
00030 
00031 #include "definitions.h"
00032 #include "common_driver.h"
00033 
00034 //-----------------------------------------------------------------------------
00035 // constant definitions
00036 //----------------------------------------------------------------------------
00037 
00038 // registers addresses
00039 #define IDENTIFICATION_MODEL_ID             0x00
00040 #define IDENTIFICATION_FIRMWARE_REVISION_ID 0x0B
00041 #define IDENTIFICATION_MODULE_REV_MAJOR     0x03
00042 #define IDENTIFICATION_MODULE_REV_MINOR     0x04
00043 
00044 #define SYSALS_START                        0x38
00045 #define SYSALS_THRESH_HIGH                  0x3A
00046 #define SYSALS_THRESH_LOW                   0x3C
00047 #define SYSALS_INTERMEASUREMENT_PERIOD      0x3E
00048 #define SYSALS_ANALOGUE_GAIN                0x3F
00049 #define SYSALS_INTEGRATION_PERIOD           0x40
00050 
00051 #define RESULT_ALS_STATUS                   0x4E
00052 #define RESULT_ALS_VAL                      0x50
00053 
00054 #define INTERLEAVED_MODE_ENABLE             0x2A3
00055 
00056 
00057 // SYSALS_START
00058 #define ALS_START_SINGLESHOT                0x01 // bit 0 set / bit 1 clear
00059 #define ALS_START_CONTINUOUS                0x03 // bit 0 set / bit 1 set
00060 #define ALS_STOP                            0x00 // bit 0 set / bit 1 don't care
00061 
00062 // RESULT_ALS_STATUS
00063 #define ALS_DEVICE_READY                    0x01
00064 #define ALS_ERROR_CODE                      0xF0 // covers bits [7:4]
00065 #define FW_ALS_RESULT_SCALER                   0x120
00066 
00067 
00068 #define DEFAULT_INTEGRATION_PERIOD          0x64
00069 #define DEFAULT_LUX_RESOLUTION              0.56f
00070 #define DEFAULT_ALS_SCALER                  1
00071 #define DEFAULT_ALS_GAIN                    20
00072 /**
00073  * @brief This data type defines range measurment data.
00074  */
00075 typedef struct
00076 {
00077     float_t lux;
00078     /**< Light measurement (Lux) */
00079 
00080     uint32_t errorStatus;
00081     /**< Error status of the current measurement. \n
00082      * No Error := 0. \n
00083      * Refer to product sheets for other error codes. */
00084 }sensor_AlsData;
00085 
00086 
00087 /*!
00088  *
00089  *\brief Device setup for ALS parameters. These settings can be applied at any time. The status of operation bit (bit 0) of the SYSALS_START is not important.
00090  *\param[in] device_base_address
00091  *\retval sensor_error
00092  */
00093 sensor_error als_set_dynamic_config(uint8_t device_base_address);
00094 
00095 /*!
00096  *\brief Set Mode and Operation commands in the SYSALS_START register.
00097  *
00098  * Possible combinations are : \n
00099  *   ALS_START_SINGLESHOT 0x01 (bit 0 set / bit 1 clear) \n
00100  *   ALS_START_CONTINUOUS 0x03 (bit 0 set / bit 1 set) \n
00101  *   ALS_STOP             0x01 (bit 0 set / bit 1 don't care) \n
00102  *\param[in] device_base_address
00103  *\param[in] mode Mode select/operation command to be written to the SYSALS_START register.
00104  *\retval sensor_error
00105  */
00106 sensor_error als_set_systemMode(uint8_t device_base_address, uint8_t mode);
00107 
00108 /*!
00109  *\brief Report status of ALS mode-select and Stop/Start.
00110  *
00111  * Returns a reading of the SYSALS_START register. \n
00112  * Possible results are : \n
00113  *   ALS_START_SINGLESHOT 0x01 (bit 0 set / bit 1 clear) \n
00114  *   ALS_START_CONTINUOUS 0x03 (bit 0 set / bit 1 set) \n
00115  *   ALS_STOP             0x01 (bit 0 set / bit 1 don't care) \n
00116  *\param[in] device_base_address
00117  *\retval uint8_t (unsigned, byte-wide integer)
00118  */
00119 uint8_t als_get_systemMode(uint8_t device_base_address);
00120 
00121 /*!
00122  *\brief Report 16-bit result from last ALS operation.
00123  *
00124  * Accesses the RESULT_ALS_VAL register, to report the latest ALS raw measurement.
00125  *\param[in] device_base_address
00126  *\retval uint16_t (unsigned, word-wide integer)
00127  */
00128 uint16_t als_get_result(uint8_t device_base_address);
00129 
00130 /*!
00131  *\brief Report 16-bit result from last ALS operation.
00132  *
00133  * Reads the latest ALS measurement and reports to the calling operation in LUX.
00134  *\param[in] device_base_address
00135  *\retval uint16_t (unsigned, word-wide integer)
00136  */
00137 uint16_t als_get_lux(uint8_t device_base_address);
00138 
00139 /*!
00140  *\brief Set min/max ALS thresholds (units?) in SYSALS_THRESH_LOW & SYSALS_THRESH_HIGH registers.
00141  *\param[in] device_base_address
00142  *\param[in] low_threshold Byte-wide, integer, ALS low threshold to be written to the SYSALS_THRESH_LOW register.
00143  *\param[in] high_threshold Byte-wide, integer, ALS high threshold to be written to the SYSALS_THRESH_HIGH register.
00144  *\retval sensor_error
00145  */
00146 sensor_error als_set_thresholds(uint8_t device_base_address, uint16_t low_threshold, uint16_t high_threshold);
00147 
00148 /*!
00149  *\brief Set ALS high threshold the SYSALS_THRESH_HIGH register.
00150  *\param[in] device_base_address
00151  *\param[in] threshold Word-wide, integer, ALS high threshold to be written to the SYSALS_THRESH_HIGH register.
00152  *\retval sensor_error
00153  */
00154 sensor_error als_set_high_threshold(uint8_t device_base_address, uint16_t threshold);
00155 
00156 /*!
00157  *\brief Report ALS high threshold from the SYSALS_THRESH_HIGH register.
00158  *\param[in] device_base_address
00159  *\retval uint16_t (unsigned, word-wide integer)
00160  */
00161 uint16_t als_get_high_threshold(uint8_t device_base_address);
00162 
00163 /*!
00164  *\brief Set ALS low threshold the SYSALS_THRESH_LOW register.
00165  *\param[in] device_base_address
00166  *\param[in] threshold ALS low threshold to be written to the SYSALS_THRESH_LOW register.
00167  *\retval sensor_error
00168  */
00169 sensor_error als_set_low_threshold(uint8_t device_base_address, uint16_t threshold);
00170 
00171 /*!
00172  *\brief Report ALS low threshold from the SYSALS_THRESH_LOW register.
00173  *\param[in] device_base_address
00174  *\retval uint16_t (unsigned, word-wide integer)
00175  */
00176 uint16_t als_get_low_threshold(uint8_t device_base_address);
00177 
00178 /*!
00179  *\brief Set ALS intermeasurement period in the SYSALS_INTERMEASUREMENT_PERIOD register.
00180  *
00181  * Range 10ms-2.55s, 1 code = 10 ms, code 0 = 10ms
00182  *\param[in] device_base_address
00183  *\param[in] intermeasurement_period: Time delay in ms between measurements in continuous-ALS mode.
00184  *\retval sensor_error
00185  */
00186 sensor_error als_set_interMeasurement_period(uint8_t device_base_address, uint16_t intermeasurement_period);
00187 
00188 /*!
00189  *\brief Report ALS intermeasurement period from the SYSALS_INTERMEASUREMENT_PERIOD register.
00190  *
00191  * Range 0-2.55s, 1 code = 10 ms
00192  *\param[in] device_base_address
00193  *\retval an 16-bit integer as time in ms.
00194  */
00195 uint16_t als_get_interMeasurement_period(uint8_t device_base_address);
00196 
00197 /*!
00198  *\brief Set dark/light ALS analogue gains in the SYSALS_ANALOGUE_GAIN register.
00199  *
00200  * Light gain will be clipped to a maximum value of 7. \n
00201  * Dark Gain is frozen at 4. \n
00202  *
00203  * [2:0] sysals_analogue_gain_light: ALS analogue gain (light channel) \n
00204  * 0: ALS Gain = 20 \n
00205  * 1: ALS Gain = 10 \n
00206  * 2: ALS Gain = 5.0 \n
00207  * 3: ALS Gain = 2.5 \n
00208  * 4: ALS Gain = 1.67 \n
00209  * 5: ALS Gain = 1.25 \n
00210  * 6: ALS Gain = 1.0 \n
00211  * 7: ALS Gain = 40 (testmode) \n
00212  *\param[in] device_base_address
00213  *\param[in] light_analogue_gain light gain
00214  *\retval sensor_error
00215  */
00216 sensor_error als_set_analogue_gain(uint8_t device_base_address, uint8_t light_analogue_gain);
00217 
00218 /*!
00219  *\brief Report ALS analogue gain from the SYSALS_ANALOGUE_GAIN register.
00220  *\param[in] device_base_address
00221  *\retval an 8-bit integer.
00222  */
00223 uint8_t als_get_analogue_gain(uint8_t device_base_address);
00224 
00225 /*!
00226  *\brief Set ALS Integration Period in the SYSALS_INTEGRATION_PERIOD register.
00227  *\param[in] device_base_address
00228  *\param[in] integration_period Integration period for ALS mode, in ms. 1 code = 1ms [codes (0:464) == (1ms:465ms)]
00229  *\retval sensor_error
00230  */
00231 sensor_error als_set_integration_period(uint8_t device_base_address, uint16_t integration_period);
00232 
00233 /*!
00234  *\brief Report ALS Integration Period from the SYSALS_INTEGRATION_PERIOD register.
00235  *\param[in] device_base_address
00236  *\retval a 16-bit integer.
00237  */
00238 uint16_t als_get_integration_period(uint8_t device_base_address);
00239 
00240 /*!
00241  *\brief Report ALS Result Status from RESULT_ALS_STATUS register.
00242  *\param[in] device_base_address
00243  *\retval an 8-bit integer.
00244  */
00245 uint8_t als_get_result_status(uint8_t device_base_address);
00246 
00247 /*!
00248  *\brief Report result_ALS_device_ready status in the ALS_RANGE_STATUS register.
00249  *\param[in] device_base_address
00250  *\retval True if the result_ALS_device_ready bit in the RESULT_ALS_STATUS register is set, otherwise False.
00251  */
00252 bool_t als_get_device_ready(uint8_t device_base_address);
00253 
00254 /*!
00255  *\brief Report ALS Result Error Codes from RESULT_ALS_STATUS register.
00256  *\param[in] device_base_address
00257  *\retval an 8-bit integer.
00258  */
00259 uint8_t als_get_result_error_codes(uint8_t device_base_address);
00260 
00261 /*!
00262  *\brief Enable Interleaved Mode.
00263  *\param[in] device_base_address
00264  *\retval sensor_error
00265  */
00266 sensor_error als_set_interleaved_mode(uint8_t device_base_address);
00267 
00268 /*!
00269  *\brief Disable Interleaved Mode.
00270  *\param[in] device_base_address
00271  *\retval sensor_error
00272  */
00273 sensor_error als_clear_interleaved_mode(uint8_t device_base_address);
00274 
00275 /*!
00276  *\brief Report Interleaved Mode.
00277  *\param[in] device_base_address
00278  *\retval an 8-bit integer.
00279  */
00280 uint8_t als_get_interleaved_mode(uint8_t device_base_address);
00281 
00282 /*!
00283  *\brief Set System Interrupt Config GPIO for ALS operations.
00284 
00285     Returns True a valid command was completed successfully, otherwise False.\n
00286     Possible settings are :\n
00287       CONFIG_GPIO_INTERRUPT_DISABLED = 0x00 \n
00288       CONFIG_GPIO_INTERRUPT_LEVEL_LOW = 0x01 \n
00289       CONFIG_GPIO_INTERRUPT_LEVEL_HIGH = 0x02 \n
00290       CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW = 0x03 \n
00291       CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY = 0x04 \n
00292  *\param[in] device_base_address
00293  *\param[in] ALS_GPIO_interrupt_config:
00294  *\retval sensor_error
00295 */
00296 sensor_error als_set_system_interrupt_config_gpio(uint8_t device_base_address, uint8_t ALS_GPIO_interrupt_config);
00297 
00298 /*!
00299  *\brief Report System Interrupt Config GPIO ALS.
00300 
00301     Returns the ALS-only portion of the SYSTEM_INTERRUPT_CONFIG_GPIO register.\n
00302     Possible returns are : \n
00303       CONFIG_GPIO_INTERRUPT_DISABLED = 0x00 \n
00304       CONFIG_GPIO_INTERRUPT_LEVEL_LOW = 0x01 \n
00305       CONFIG_GPIO_INTERRUPT_LEVEL_HIGH = 0x02 \n
00306       CONFIG_GPIO_INTERRUPT_OUT_OF_WINDOW = 0x03 \n
00307       CONFIG_GPIO_INTERRUPT_NEW_SAMPLE_READY = 0x04 \n
00308  *\param[in] device_base_address
00309  *\retval Integer
00310 */
00311 uint8_t als_get_system_interrupt_config_gpio(uint8_t device_base_address);
00312 
00313 /*!
00314  *\brief Report GPIO Interrupt Result Status for an ALS operation.
00315 
00316     Returns the ALS-only portion of the RESULT_INTERRUPT_STATUS_GPIO register.\n
00317     Possible returns are : \n
00318     0: No threshold events reported \n
00319     1: Level Low threshold event \n
00320     2: Level High threshold event \n
00321     3: Out Of Window threshold event \n
00322     4: New Sample Ready threshold event \n
00323  *\param[in] device_base_address
00324  *\retval Integer
00325 */
00326 uint8_t als_get_result_interrupt_status_gpio(uint8_t device_base_address);
00327 
00328 
00329 /*!
00330  *\brief Clear ALS System Interrupt.
00331  *\param[in] device_base_address
00332  *\retval sensor_error
00333 */
00334 sensor_error als_set_system_interrupt_clear(uint8_t device_base_address);
00335 
00336 /*!
00337  *\brief Set history buffer to ALS mode and enable.
00338  *\param[in] device_base_address
00339  *\retval sensor_error
00340 */
00341 sensor_error als_set_history_buffer_mode_enable(uint8_t device_base_address);
00342 
00343 sensor_error Get_ALS_History_Buffer(uint8_t device_base_address);
00344 
00345 sensor_error als_set_scaler(uint8_t device_base_address, uint8_t scaler);
00346 
00347 uint32_t als_get_scaler(uint8_t device_base_address);
00348 
00349 #endif
00350 
00351