si114x_functions.h

00001 //-----------------------------------------------------------------------------
00002 // Si114x_functions.h
00003 //-----------------------------------------------------------------------------
00004 // Copyright 2013 Silicon Laboratories, Inc.
00005 // http://www.silabs.com
00006 //
00007 // File Description:
00008 //
00009 // Function Prototypes, register and bit definitions for reusable low-level
00010 // Si114x functions.
00011 //
00012 // Target:         Si114x
00013 // Command Line:   None
00014 //
00015 //-----------------------------------------------------------------------------
00016 
00017 #ifndef SI114X_FUNCTIONS_H
00018 #define SI114X_FUNCTIONS_H
00019 
00020 
00021 #ifndef PGM_TOOLKIT_TYPES
00022 #define PGM_TOOLKIT_TYPES
00023 #include "em_device.h"
00024 typedef signed char       s8;
00025 typedef signed short      s16;
00026 typedef signed int        s32;
00027 typedef unsigned char     u8;
00028 typedef unsigned short    u16;
00029 typedef unsigned int      u32;
00030 
00031 typedef void *            HANDLE;
00032 typedef char *            STRING;
00033 typedef s16               PT_RESULT;
00034 typedef s8                PT_BOOL;
00035 
00038 typedef struct {
00039     I2C_TypeDef *i2c;
00040     uint8_t addr;
00041   } si114x_i2c_t;
00042 
00045 #endif
00046 
00047 
00048 //
00049 // Function Prototypes
00050 //
00051 
00052 // Byte Read/Write Access to Si114x I2C Registers
00053 s16 Si114xWriteToRegister (HANDLE si114x_handle, u8 address, u8 data);
00054 s16 Si114xReadFromRegister(HANDLE si114x_handle, u8 address);
00055 
00056 // Block Read/Write Access to Si114x I2C Registers
00057 s16 Si114xBlockWrite(HANDLE si114x_handle, u8 address, u8 length, u8 const *values);
00058 s16 Si114xBlockRead(HANDLE si114x_handle, u8 address, u8 length, u8 *values);
00059 
00060 // Commands to the Si114x
00061 s16 Si114xReset      (HANDLE si114x_handle);
00062 s16 Si114xPauseAll   (HANDLE si114x_handle);
00063 s16 Si114xNop        (HANDLE si114x_handle);
00064 s16 Si114xPsForce    (HANDLE si114x_handle);
00065 s16 Si114xAlsForce   (HANDLE si114x_handle);
00066 s16 Si114xPsAlsForce (HANDLE si114x_handle);
00067 s16 Si114xPsAlsAuto  (HANDLE si114x_handle);
00068 
00069 // Read/Write Access to Parameter RAM is implemented as a 'Command' to the
00070 // Si114x
00071 s16 Si114xParamSet (HANDLE si114x_handle, u8 address, u8 data);
00072 s16 Si114xParamRead(HANDLE si114x_handle, u8 address);
00073 
00074 
00075 
00076 //
00077 // I2C Registers
00078 //
00079 #define REG_PART_ID               0x00
00080 #define REG_REV_ID                0x01
00081 #define REG_SEQ_ID                0x02
00082 #define REG_INT_CFG               0x03
00083 #define REG_IRQ_ENABLE            0x04
00084 #define REG_IRQ_MODE1             0x05
00085 #define REG_IRQ_MODE2             0x06
00086 #define REG_HW_KEY                0x07
00087 #define REG_MEAS_RATE             0x08
00088 #define REG_ALS_RATE              0x09
00089 #define REG_PS_RATE               0x0A
00090 #define REG_ALS_LO_TH_LSB         0x0B
00091 #define REG_ALS_LO_TH_MSB         0x0C
00092 #define REG_ALS_HI_TH_LSB         0x0D
00093 #define REG_ALS_HI_TH_MSB         0x0E
00094 #define REG_PS_LED21              0x0F
00095 #define REG_PS_LED3               0x10
00096 #define REG_PS1_TH_LSB            0x11
00097 #define REG_PS1_TH_MSB            0x12
00098 #define REG_PS2_TH_LSB            0x13
00099 #define REG_PS2_TH_MSB            0x14
00100 #define REG_PS3_TH_LSB            0x15
00101 #define REG_PS3_TH_MSB            0x16
00102 #define REG_PARAM_WR              0x17
00103 #define REG_COMMAND               0x18
00104 #define REG_RESPONSE              0x20
00105 #define REG_IRQ_STATUS            0x21
00106 #define REG_ALS_VIS_DATA0         0x22
00107 #define REG_ALS_VIS_DATA1         0x23
00108 #define REG_ALS_IR_DATA0          0x24
00109 #define REG_ALS_IR_DATA1          0x25
00110 #define REG_PS1_DATA0             0x26
00111 #define REG_PS1_DATA1             0x27
00112 #define REG_PS2_DATA0             0x28
00113 #define REG_PS2_DATA1             0x29
00114 #define REG_PS3_DATA0             0x2A
00115 #define REG_PS3_DATA1             0x2B
00116 #define REG_AUX_DATA0             0x2C
00117 #define REG_AUX_DATA1             0x2D
00118 #define REG_PARAM_OUT             0x2E
00119 #define REG_PARAM_RD              0x2E
00120 #define REG_CHIP_STAT             0x30
00121 
00122 #define REG_UCOEF0                0x13
00123 #define REG_UCOEF1                0x14
00124 #define REG_UCOEF2                0x15
00125 #define REG_UCOEF3                0x16
00126 
00127 #define REG_MEAS_RATE_LSB         0x08
00128 #define REG_MEAS_RATE_MSB         0x09
00129 
00130 // Parameter Offsets
00131 #define PARAM_I2C_ADDR            0x00
00132 #define PARAM_CH_LIST             0x01
00133 #define PARAM_PSLED12_SELECT      0x02
00134 #define PARAM_PSLED3_SELECT       0x03
00135 #define PARAM_FILTER_EN           0x04
00136 #define PARAM_PS_ENCODING         0x05
00137 #define PARAM_ALS_ENCODING        0x06
00138 #define PARAM_PS1_ADC_MUX         0x07
00139 #define PARAM_PS2_ADC_MUX         0x08
00140 #define PARAM_PS3_ADC_MUX         0x09
00141 #define PARAM_PS_ADC_COUNTER      0x0A
00142 #define PARAM_PS_ADC_CLKDIV       0x0B
00143 #define PARAM_PS_ADC_GAIN         0x0B
00144 #define PARAM_PS_ADC_MISC         0x0C
00145 #define PARAM_VIS_ADC_MUX         0x0D
00146 #define PARAM_IR_ADC_MUX          0x0E
00147 #define PARAM_AUX_ADC_MUX         0x0F
00148 #define PARAM_ALSVIS_ADC_COUNTER  0x10
00149 #define PARAM_ALSVIS_ADC_CLKDIV   0x11
00150 #define PARAM_ALSVIS_ADC_GAIN     0x11
00151 #define PARAM_ALSVIS_ADC_MISC     0x12
00152 #define PARAM_ALS_HYST            0x16
00153 #define PARAM_PS_HYST             0x17
00154 #define PARAM_PS_HISTORY          0x18
00155 #define PARAM_ALS_HISTORY         0x19
00156 #define PARAM_ADC_OFFSET          0x1A
00157 #define PARAM_SLEEP_CTRL          0x1B
00158 #define PARAM_LED_RECOVERY        0x1C
00159 #define PARAM_ALSIR_ADC_COUNTER   0x1D
00160 #define PARAM_ALSIR_ADC_CLKDIV    0x1E
00161 #define PARAM_ALSIR_ADC_GAIN      0x1E
00162 #define PARAM_ALSIR_ADC_MISC      0x1F
00163 
00164 
00165 
00166 // REG_IRQ_CFG
00167 #define  ICG_INTOE                0x01
00168 #define  ICG_INTMODE              0x02
00169 
00170 
00171 // REG_IRQ_ENABLE
00172 // REG_IRQ_STATUS
00173 #define IE_NONE                   0x00
00174 
00175 #define IE_ALS_NONE               0x00
00176 #define IE_ALS_EVRYSAMPLE         0x01
00177 #define IE_ALS_EXIT_WIN           0x01
00178 #define IE_ALS_ENTER_WIN          0x02
00179 
00180 #define IE_PS1_NONE               0x00
00181 #define IE_PS1_EVRYSAMPLE         0x04
00182 #define IE_PS1_CROSS_TH           0x04
00183 #define IE_PS1_EXCEED_TH          0x04
00184 #define IE_PS1                    0x04
00185 
00186 #define IE_PS2_NONE               0x00
00187 #define IE_PS2_EVRYSAMPLE         0x08
00188 #define IE_PS2_CROSS_TH           0x08
00189 #define IE_PS2_EXCEEED_TH         0x08
00190 #define IE_PS2                    0x08
00191 
00192 #define IE_PS3_NONE               0x00
00193 #define IE_PS3_EVRYSAMPLE         0x10
00194 #define IE_PS3_CROSS_TH           0x10
00195 #define IE_PS3_EXCEED_TH          0x10
00196 #define IE_PS3                    0x10
00197 
00198 #define IE_CMD                    0x20
00199 
00200 #define IE_ALL                    0x3F
00201 
00202 // REG_IRQ_MODE1
00203 #define IM1_NONE                  0x00
00204 #define IM1_ALS_NONE              0x00
00205 #define IM1_ALS_EVRYSAMPLE        0x00
00206 #define IM1_ALS_VIS_EXIT          0x01
00207 #define IM1_ALS_VIS_ENTER         0x05
00208 #define IM1_ALS_IR_EXIT           0x03
00209 #define IM1_ALS_IR_ENTER          0x06
00210 
00211 #define IM1_PS1_NONE              0x00
00212 #define IM1_PS1_EVRYSAMPLE        (0x0<<4)
00213 #define IM1_PS1_CROSS_TH          (0x1<<4)
00214 #define IM1_PS1_EXCEED_TH         (0x3<<4)
00215 
00216 #define IM1_PS2_NONE              0x00
00217 #define IM1_PS2_EVRYSAMPLE        (0x0<<6)
00218 #define IM1_PS2_CROSS_TH          (0x1<<6)
00219 #define IM1_PS2_EXCEED_TH         (0x3<<6)
00220 
00221 
00222 // REG_IRQ_MODE1
00223 #define IM2_PS3_NONE              0x00
00224 #define IM2_PS3_EVRYSAMPLE        (0x0)
00225 #define IM2_PS3_CROSS_TH          (0x1)
00226 #define IM2_PS3_EXCEED_TH         (0x3)
00227 
00228 
00229 //
00230 // REG_PS_LED21   LED2 Current is upper nibble
00231 //                LED1 Current is lower nibble
00232 //
00233 // REG_PS_LED3    LED3 Current is lower nibble
00234 #define LEDI_000                  0x00
00235 #define LEDI_006                  0x01
00236 #define LEDI_011                  0x02
00237 #define LEDI_022                  0x03
00238 #define LEDI_045                  0x04
00239 #define LEDI_067                  0x05
00240 #define LEDI_090                  0x06
00241 #define LEDI_112                  0x07
00242 #define LEDI_135                  0x08
00243 #define LEDI_157                  0x09
00244 #define LEDI_180                  0x0A
00245 #define LEDI_202                  0x0B
00246 #define LEDI_224                  0x0C
00247 #define LEDI_269                  0x0D
00248 #define LEDI_314                  0x0E
00249 #define LEDI_359                  0x0F
00250 
00251 
00252 // PARAM_CH_LIST
00253 #define PS1_TASK                  0x01
00254 #define PS2_TASK                  0x02
00255 #define PS3_TASK                  0x04
00256 #define ALS_VIS_TASK              0x10
00257 #define ALS_IR_TASK               0x20
00258 #define AUX_TASK                  0x40
00259 
00260 //
00261 // ADC Counters
00262 // PARAM_PS_ADC_COUNTER
00263 // PARAM_ALSVIS_ADC_COUNTER
00264 // PARAM_ALSIR_ADC_COUNTER
00265 //
00266 #define RECCNT_001                0x00
00267 #define RECCNT_007                0x10
00268 #define RECCNT_015                0x20
00269 #define RECCNT_031                0x30
00270 #define RECCNT_063                0x40
00271 #define RECCNT_127                0x50
00272 #define RECCNT_255                0x60
00273 #define RECCNT_511                0x70
00274 
00275 //
00276 // Proximity LED Selection
00277 // PARAM_PSLED12_SELECT  PS2 LED Choice is Upper Nibble
00278 //                       PS1 LED Choice is Lower Nibble
00279 //
00280 // PARAM_PSLED3_SELECT   PS3 LED Choice is Lower Nibble
00281 //
00282 // Each of the three PS measurements can choose whichever
00283 // irLED to light up during the measurement, with whichever
00284 // combination desired.
00285 #define NO_LED                    0x00
00286 #define LED1_EN                   0x01
00287 #define LED2_EN                   0x02
00288 #define LED3_EN                   0x04
00289 #define SEL_LED1_PS1              (LED1_EN)
00290 #define SEL_LED2_PS1              (LED2_EN)
00291 #define SEL_LED3_PS1              (LED3_EN)
00292 #define SEL_LED1_PS2              (LED1_EN<<4)
00293 #define SEL_LED2_PS2              (LED2_EN<<4)
00294 #define SEL_LED3_PS2              (LED3_EN<<4)
00295 #define SEL_LED1_PS3              (LED1_EN)
00296 #define SEL_LED2_PS3              (LED2_EN)
00297 #define SEL_LED3_PS3              (LED3_EN)
00298 
00299 //
00300 // PARAM_PS_ENCODING
00301 // When these bits are set the corresponding measurement
00302 // will report the least significant bits of the
00303 // ADC is used instead of the most significant bits
00304 #define PS1_LSB                   0x10
00305 #define PS2_LSB                   0x20
00306 #define PS3_LSB                   0x40
00307 #define PS_ENCODING_MASK          0x70
00308 
00309 //
00310 // PARAM_ALS_ENCODING
00311 // When these bits are set the corresponding measurement
00312 // will report the least significant bits of the
00313 // ADC is used instead of the most significant bits
00314 #define ALS_VIS_LSB               0x10
00315 #define ALS_IR_LSB                0x20
00316 #define AUX_LSB                   0x40
00317 #define ALS_ENCODING_MASK         0xCF
00318 
00319 
00320 //
00321 // PARAM_PS_ADC_MISC
00322 // PARAM_ALS_VIS_ADC_MISC
00323 // PARAM_ALS_IR_ADC_MISC
00324 //
00325 // PS_MODE_MEAS_MODE and NOT_PS_MEAS_MODE are applicable only
00326 // for PARAM_PS_ADC_MISC.
00327 //
00328 //    PS_MEAS_MODE is used to perform normal Proximity measurements.
00329 //    While in this operatinal mode, it is possible to choose either
00330 //    the small IR photodiode or big IR photodiode. The big IR
00331 //    photodiode is the default for normal operation. The small IR
00332 //    photodiode is typically not used, but it is possible to use it
00333 //    for proximity measurements.
00334 //
00335 //    NOT_PS_MEAS_MODE can be applied to PARAM_PS_ADC_MISC.
00336 //
00337 //    This allows three PS channels to perform RAW ADC measurements
00338 //    on any source (no irLED driven). These measurements will have no
00339 //    reference, and will have an offset of 0x4000 if the most
00340 //    significant 16 bits of the 17-bit ADC is reported. Otherwise,
00341 //    if the PARAM_xxx_ENCODING _LSB settings are set, then the
00342 //    offset will be 0x8000 (due to bit shifting).
00343 //
00344 //    When performing voltage measurements (INT, LED1, LED2, TEMP),
00345 //    a separate VSS measurement should be subtracted from the reading.
00346 //
00347 //    When performing measurement with visible photodiode, first take
00348 //    a no-led measurement and subtract away the visible light measurement.
00349 //
00350 //    When performing an optical measurement using either two IR
00351 //    photodiodes, one should subtract away the no-led measurement from
00352 //    the IR measurement.
00353 //
00354 //    Note that the subtraction ordering is significant between
00355 //    taking visible light photodiode vs IR photodiode
00356 //    measurement. The raw ADC reading of visible light photodiode
00357 //    decreases with increasing light levels while the raw ADC reading
00358 //    of IR light photodiode increases with increasing light levels.
00359 //
00360 // HSIG_EN means 'high signal range enable'. The ADC would
00361 // be able to operate with higher light levels, but at the
00362 // expense of sensitivity. This setting can be used for
00363 // operation under direct sunlight.
00364 //
00365 // PARAM_PS_ADC_MISC, PARAM_ALSVIS_ADC_MISC and PARAM_ALSIR_ADC_MISC
00366 // can use HSIG_EN also.
00367 //
00368 //
00369 #define NOT_PS_MEAS_MODE          0x00
00370 #define PS_MEAS_MODE              0x04
00371 #define HSIG_EN                   0x20
00372 #define RANGE_EN                  0x20
00373 
00374 #define ALS_IR_ADC_MISC_MASK      0x20
00375 #define ALS_VIS_ADC_MISC_MASK     0x20
00376 
00377 //
00378 // ADC Mux Settings
00379 // PARAM_PS1_ADC_MUX    See PARAM_PS_ADC_MISC also
00380 // PARAM_PS2_ADC_MUX    See PARAM_PS_ADC_MISC also
00381 // PARAM_PS3_ADC_MUX    See PARAM_PS_ADC_MISC also
00382 //
00383 // PARAM_VIS_ADC_MUX    MUX_ALS_VIS or MUX_NONE only
00384 // PARAM_IR_ADC_MUX     MUX_ALS_IR, MUX_PS_IR or MUX_NONE only
00385 // PARAM_AUX_ADC_MUX    MUX_VTEMP, MUX_LED1, MUX_LED2, MUX_INT
00386 //                      to use anything other than MUX_VTEMP,
00387 //                      ANA_IN_KEY should be unlocked first.
00388 //
00389 #define MUX_SMALL_IR              0x00
00390 #define MUX_VIS                   0x02
00391 #define MUX_LARGE_IR              0x03
00392 #define MUX_NO_PHOTO_DIODE        0x06
00393 #define MUX_VTEMP                 0x65
00394 #define MUX_INT                   0x05
00395 #define MUX_LED1                  0x15
00396 #define MUX_VSS                   0x25
00397 #define MUX_LED2                  0x35
00398 #define MUX_VDD                   0x75
00399 
00400 //
00401 // ADC Dividers
00402 // PARAM_PS_ADC_GAIN
00403 // PARAM_ALSVIS_ADC_GAIN
00404 // PARAM_ALSIR_ADC_GAIN
00405 //
00406 #define ADC_NORM                  0x00
00407 #define ADC_DIV2                  0x01
00408 #define ADC_DIV4                  0x02
00409 #define ADC_DIV8                  0x03
00410 #define ADC_DIV16                 0x04
00411 #define ADC_DIV32                 0x05
00412 #define ADC_DIV64                 0x06
00413 #define ADC_DIV128                0x07
00414 #define ADC_DIV256                0x08
00415 #define ADC_DIV512                0x09
00416 #define ADC_DIV1024               0x0A
00417 #define ADC_DIV2048               0x0B
00418 
00419 
00420 // Hardware Key value
00421 // REG_HW_KEY
00422 #define HW_KEY_VAL0               0x17
00423 
00424 // Sleep Control
00425 // PARAM_SLEEP_CTRL
00426 #define SLEEP_DISABLED            0x01
00427 
00428 // ANA_IN_KEY value
00429 #define ANA_KEY_38                0x10
00430 #define ANA_KEY_39                0x40
00431 #define AMA_KEY_3A                0x62
00432 #define ANA_KEY_3B                0x3b
00433 
00434 //
00435 // si114x_calibration.h
00436 //
00437 //
00438 
00439 #ifdef SI114x_CAL_DEBUG
00440     void _debug(void);
00441 #endif
00442 
00443 //
00444 // This structure is used to store the result of the calibration retrieval
00445 //
00446 
00449 typedef struct
00450 {
00451     int cal;
00452 } SI114X_CAL_S;
00453 
00456 s16 si114x_get_calibration( HANDLE si114x_handle, SI114X_CAL_S *si114x_cal, char security);
00457 
00458 
00459 //
00460 // si114x_set_ucoef() takes in a reference ucoef, then modifies it based on
00461 // calibration.
00462 //
00463 // If there are any errors, si114x_cal   is populated with default values
00464 //
00465 // Input:
00466 //      si114x_handle   handle passed to low level routines to initiate
00467 //                      i2c communications
00468 //
00469 //      ref_ucoef       if NULL, a clear overlay is assumed
00470 //                      otherwise, 4 bytes representing the reference
00471 //                      coefficients are passed.
00472 //
00473 //      si114x_cal      pointer to an SI114X_CAL_S   structure that
00474 //                      will hold the calibration values from the Si114x
00475 // Return:
00476 //           0          No errors
00477 //          -1          Device is neither Si1132, Si1145, Si1146 nor Si1147
00478 //
00479 
00480 s16 si114x_set_ucoef( HANDLE si114x_handle, u8 ref_ucoef[], SI114X_CAL_S *si114x_cal );
00481 
00482 
00483 #endif // #define SI114X_FUNCTIONS_H