{

----------------------------------------------------------------------------------------------------

Filename: sensor.light.si114x.spin2

Description: Driver for the Silicon Labs Si114[5|6|7] Proximity/UV/Amblient light sensor

Author: Jesse Burt

Started: Oct 24, 2021

Updated: Jun 4, 2024

Copyright (c) 2024 - See end of file for terms of use.

----------------------------------------------------------------------------------------------------

}

CON

{ default I/O configuration - these can be overridden by the parent object }

SCL = 0

SDA = 1

I2C_FREQ = 100_000

{ Chip status }

SLEEP = core.CHIP_STAT_SLEEP

SUSP = core.CHIP_STAT_SUSPEND

RUN = core.CHIP_STAT_RUNNING

{ Operation modes }

ONE_PS = core.CMD_PS_FORCE

ONE_ALS = core.CMD_ALS_FORCE

ONE_PSALS = core.CMD_PSALS_FORCE

CONT_PS = core.CMD_PS_AUTO

CONT_ALS = core.CMD_ALS_AUTO

CONT_PSALS = core.CMD_PSALS_AUTO

PAUSE_PS = core.CMD_PS_PAUSE

PAUSE_ALS = core.CMD_ALS_PAUSE

PAUSE_PSALS = core.CMD_PSALS_PAUSE

{ Visible/IR sensor measurement range }

NORMAL = $00

HIGH = $20

{ Read/write for uv_coeffs() }

R = 0

W = 1

{ Default dark sensor values }

IR_DARK_DEF = 250

VIS_DARK_DEF = 260

{ Lux calculation coefficients }

VIS_COEFF = 5_4100

IR_COEFF = 0_0800

VIS_CPL = 0_3190

IR_CPL = 8_4600

CORR_FACT = 0_0800

SLAVE_WR = core.SLAVE_ADDR

SLAVE_RD = core.SLAVE_ADDR|1

DEF_SCL = 0

DEF_SDA = 1

DEF_HZ = 100_000

I2C_MAX_FREQ = core.I2C_MAX_FREQ

VAR

word _cal_data[6]

word _ir_dark, _vis_dark

byte _opmode

OBJ

i2c: "com.i2c" ' I2C engine

core: "core.con.si114x" ' HW-specific constants

u64: "math.unsigned64" ' unsigned 64-bit math

PUB null()

' This is not a top-level object

PUB start(): status

' Start using default I/O settings

return startx(SCL, SDA, I2C_FREQ)

PUB startx(SCL_PIN, SDA_PIN, I2C_HZ): status

' Start using custom I2C pins and bus frequency

if ( lookdown(SCL_PIN: 0..63) and lookdown(SDA_PIN: 0..63) )

if ( status := i2c.init(SCL_PIN, SDA_PIN, I2C_HZ) )

waitus(core.T_POR)

if ( lookdown(dev_id(): core.PART_ID_RESP_1145, ...

core.PART_ID_RESP_1146, ...

core.PART_ID_RESP_1147) )

reset()

return

' if this point is reached, something above failed

' Double check I/O pin assignments, connections, power

' Lastly - make sure you have at least one free core/cog

return FALSE

PUB stop()

' Stop I2C engine and clear cached data

i2c.deinit()

wordfill(@_cal_data, 0, 8)

_opmode := 0

PUB defaults()

' Factory default settings

reset()

PUB preset_als()

' Preset settings for ambient light sensing mode

reset() ' start with POR defaults

opmode(CONT_ALS)

als_data_rate(32_000_000)

aux_chan_ena(FALSE)

uv_chan_ena(FALSE)

ir_chan_ena(TRUE)

white_chan_ena(TRUE)

int_mask(core.INTSRC_ALS)

PUB preset_prox()

' Preset settings for proximity sensor mode

reset()

opmode(CONT_PS)

' XXX fill in

PUB preset_uvi()

' Preset settings for measuring UV Index

reset()

opmode(CONT_ALS)

als_data_rate(32_000_000)

' These are the factory default part-to-part variance coefficients.

' They are restored by calling Reset(), but show them here so the user

' doesn't have to look far for them.

uv_set_coeffs($00_01_6B_7B)

aux_chan_ena(TRUE)

uv_chan_ena(TRUE)

ir_chan_ena(FALSE)

white_chan_ena(FALSE)

ir_range(HIGH)

white_range(HIGH)

ir_gain(1)

white_gain(1)

int_mask(core.INTSRC_ALS)

PUB als_data_rate(rate=-2): curr_rate

' Set measurement data rate, in milli-Hz

' Valid values: 489..32_000_000 (= 0.489Hz .. 32kHz)

' Any other value polls the chip and returns the current setting

case rate

489..32_000_000:

rate := (32_000_000 / rate)

writereg(core.MEAS_RATE0, 2, @rate)

other:

curr_rate := 0

readreg(core.MEAS_RATE0, 2, @curr_rate)

return (32_000_000 / curr_rate)

PUB als_data_rdy(): flag

' Flag indicating ALS data is ready

' Returns: TRUE (-1) or FALSE (0)

flag := ((interrupt() & core.ALS_INT_BITS) <> 0)

if (flag)

int_clear(core.INTSRC_ALS)

PUB aux_chan_ena(state=-2): curr_state

' Enable the auxiliary source data channel

' Valid values: TRUE (-1 or 1), FALSE (0)

' Any other value polls the chip and returns the current setting

curr_state := command(core.CMD_PARAM_QUERY, core.CHLIST, 0)

case abs(state)

0, 1:

state := abs(state) << core.EN_AUX

other:

return (((curr_state >> core.EN_AUX) & 1) == 1)

state := ((curr_state & core.EN_AUX_MASK) | state)

command(core.CMD_PARAM_SET, core.CHLIST, state)

PUB cal_data(idx): cal_word

' Return a word of calibration data

' Valid values: 0..5

' Any other value is ignored

case idx

0..5:

return _cal_data[idx]

other:

return

PUB dev_id(): id

' Part ID of sensor

' Returns:

' $45: Si1145

' $46: Si1146

' $47: Si1147

id := 0

readreg(core.PART_ID, 1, @id)

PUB int_clear(mask)

' Clear interrupts

' Bits: 5..0 (set a bit to clear the interrupt)

' 5: command interrupt

' 4: proximity sensor ch3 interrupt

' 3: proximity sensor ch2 interrupt

' 2: proximity sensor ch1 interrupt

' 0: ALS or UV measurement is ready

mask &= core.IRQ_STATUS_MASK

writereg(core.IRQ_STATUS, 1, @mask)

PUB interrupt(): src

' Interrupt source(s)

' Returns: interrupt mask

' Bits: 5..0 (set a bit to clear the interrupt)

' 5: command interrupt

' 4: proximity sensor ch3 interrupt

' 3: proximity sensor ch2 interrupt

' 2: proximity sensor ch1 interrupt

' 0: ALS or UV measurement is ready

src := 0

readreg(core.IRQ_STATUS, 1, @src)

PUB int_mask(mask=-2): curr_mask

' Set interrupt mask

' Bits: 4..0 (set a bit to assert INT pin when interrupt occurs)

' 4: proximity sensor ch3 interrupt

' 3: proximity sensor ch2 interrupt

' 2: proximity sensor ch1 interrupt

' 0: ALS or UV measurement is ready

' Any other value polls the chip and returns the current setting

case mask

%00000000..%11111111:

mask &= core.IRQ_ENABLE_MASK

writereg(core.IRQ_ENABLE, 1, @mask)

other:

curr_mask := 0

readreg(core.IRQ_ENABLE, 1, @curr_mask)

PUB ir_chan_ena(state=-2): curr_state

' Enable the IR ambient light source data channel

' Valid values: TRUE (-1 or 1), FALSE (0)

' Any other value polls the chip and returns the current setting

curr_state := command(core.CMD_PARAM_QUERY, core.CHLIST, 0)

case abs(state)

0, 1:

state := abs(state) << core.EN_ALS_IR

other:

return (((curr_state >> core.EN_ALS_IR) & 1) == 1)

state := ((curr_state & core.EN_ALS_IR_MASK) | state)

command (core.CMD_PARAM_SET, core.CHLIST, state)

PUB ir_bias(val=-2): curr_val

' Set IR sensor dark value (ADC word)

' Valid values: 0..65535

' Any other value returns the current setting

if (lookdown(val: 0..65535))

_ir_dark := val

else

return _ir_dark

PUB ir_data(): ir_adc

' Return data from infra-red light channel

readreg (core.ALS_IR_DATA0, 2, @ir_adc)

PUB ir_gain(gain=-2): curr_gain

' Gain factor of infra-red light sensor

' Valid values: 1, 16, 64, 128

' Any other value polls the chip and returns the current setting

curr_gain := 0

curr_gain := command(core.CMD_PARAM_QUERY, core.ALS_IR_ADC_GAIN, 0)

case gain

1: gain := %000

16: gain := %100

64: gain := %110

128: gain := %111

other:

return lookupz(curr_gain & core.ALS_IR_ADCGAIN_BITS: 1, 0, 0, 0, 16, 0, 64, 128)

command(core.CMD_PARAM_SET, core.ALS_IR_ADCGAIN, gain)

gain <<= core.IR_ADC_REC

' Set the one's complement of the gain val

' to ADC recovery period, per datasheet

command(core.CMD_PARAM_SET, core.ALS_IR_ADC_COUNTER, !gain)

PUB ir_overflow(): flag

' Flag indicating infra-red light data conversion has overflowed

' Returns: TRUE (-1) if overflowed, FALSE (0) otherwise

flag := 0

readreg (core.RESPONSE, 1, @flag)

return (flag == core.ALS_IR_ADC_OVERFLOW)

PUB ir_range(range=-2): curr_rng

' Set measurement range of infra-red light sensor

' Valid values:

' NORMAL ($00): Normal signal range/high sensitivity

' HIGH ($20): High signal range (gain divided by 14.5)

curr_rng := command(core.CMD_PARAM_QUERY, core.ALS_IR_ADC_MISC, 0)

case range

NORMAL, HIGH:

other:

return curr_rng

range &= core.ALS_IR_ADC_MISC_MASK

command(core.CMD_PARAM_SET, core.ALS_IR_ADC_MISC, range)

PUB lux(): lx | vis, ir, lux1, lux2

' Calculate illuminance, in tenths of a lux (1000 = 100.0 lx)

vis := ir := 0

{ average 50 samples }

repeat 50

opmode(ONE_ALS)

vis += white_data()

ir += ir_data()

vis /= 50

ir /= 50

lux1 := u64.multdiv( (vis - _vis_dark), VIS_COEFF, 1000)

lux2 := u64.multdiv( (ir - _ir_dark), IR_COEFF, 1000)

return (0 #> (lux1 - lux2)) ' clamp to min of 0

PUB opmode(mode=-2): curr_mode

' Set operation mode

' Valid values:

' ONE_PS, ONE_ALS, ONE_PSALS: Force a single PS, ALS or PS+ALS measurement

' CONT_PS, CONT_ALS, CONT_PSALS: Start continuous PS, ALS, or PS+ALS measurement

' PAUSE_PS, PAUSE_ALS, PAUSE_PSALS: Pause a running continuous measurement

' Valid values return response status from chip

' Any other value returns the last setting (shadow register)

case mode

ONE_PS, ONE_ALS, ONE_PSALS, CONT_PS, CONT_ALS, CONT_PSALS, PAUSE_PS, PAUSE_ALS, PAUSE_PSALS:

_opmode := mode

other:

return _opmode ' not readable from sensor;

' keep a local copy

command(mode, 0, 0)

PUB power_state(): curr_state

' Chip status

' Returns:

' RUN (%100): Device is awake

' SUSP (%010): Device is in a low-power state, waiting for a measurement to complete

' SLEEP (%001): Device is in its lowest power state

curr_state := 0

readreg(core.CHIP_STAT, 1, @curr_state)

PUB rd_cal_data()

' Read calibration data into 6-word array

wordfill(@_cal_data, 0, 6)

command(core.CMD_GET_CAL, 0, 0)

readreg(core.CAL_DATA, 12, @_cal_data)

PUB reset()

' Perform soft-reset

command(core.CMD_RESET, 0, 0)

waitms(10)

hwkey()

waitms(10)

opmode(ONE_PSALS)

ir_bias(IR_DARK_DEF)

white_bias(VIS_DARK_DEF)

PUB rev_id(): id

' Revision

' Returns: $00

id := 0

readreg(core.REV_ID, 1, @id)

PUB running(): flag

' Flag indicating device is running/awake

' Returns: TRUE (-1) if device is awake, FALSE (0) otherwise

flag := 0

readreg(core.CHIP_STAT, 1, @flag)

return (flag == core.CHIP_STAT_RUNNING)

PUB seq_id(): seq_rev

' Sequencer revision

' Returns known values:

' $08: Si114x-A10 (MAJOR_SEQ=1, MINOR_SEQ=0)

seq_rev := 0

readreg(core.SEQ_ID, 1, @seq_rev)

PUB sleeping(): flag

' Flag indicating device is sleeping

' Returns: TRUE (-1) if device is in its lowest power state

' FALSE (0) otherwise

flag := 0

readreg(core.CHIP_STAT, 1, @flag)

return (flag == core.CHIP_STAT_SLEEP)

PUB suspended(): flag

' Suspended status

' Returns: TRUE (-1) if device is in a low-power state,

' FALSE (0) otherwise

flag := 0

readreg(core.CHIP_STAT, 1, @flag)

return (flag == core.CHIP_STAT_SUSPEND)

PUB uv_chan_ena(state=-2): curr_state

' Enable the UV index source data channel

' Valid values: TRUE (-1 or 1), FALSE (0)

' Any other value polls the chip and returns the current setting

curr_state := command(core.CMD_PARAM_QUERY, core.CHLIST, 0)

case abs(state)

0, 1:

state := abs(state) << core.EN_UV

other:

return (((curr_state >> core.EN_UV) & 1) == 1)

state := ((curr_state & core.EN_UV_MASK) | state)

command(core.CMD_PARAM_SET, core.CHLIST, state)

PUB uv_coeffs(): curr_coeffs

' Get coefficients used to calculate UV index readings

' NOTE: Four 8-bit coefficients are used, packed into long 'coeffs'

' UCOEF3_UCOEF2_UCOEF1_UCOEF0

curr_coeffs := 0

readreg(core.UCOEF0, 4, @curr_coeffs)

PUB uv_set_coeffs(coeffs)

' Set coefficients used to calculate UV index readings

' Valid values:

' rw: READ (0), WRITE (1)

' NOTE: Four 8-bit coefficients are used, packed into long 'coeffs'

' UCOEF3_UCOEF2_UCOEF1_UCOEF0

writereg(core.UCOEF0, 4, @coeffs)

PUB uv_data(): uv_adc

' Return data from UV index channel

uv_adc := 0

readreg(core.AUX_DATA0, 2, @uv_adc)

PUB white_bias(val=-2): curr_val

' Set white/visible sensor bias/dark value (ADC word)

' Valid values: 0..65535

' Any other value returns the current setting

if (lookdown(val: 0..65535))

_vis_dark := val

else

return _vis_dark

PUB white_chan_ena(state=-2): curr_state

' Enable the white/visible ambient light source data channel

' Valid values: TRUE (-1 or 1), FALSE (0)

' Any other value polls the chip and returns the current setting

curr_state := command(core.CMD_PARAM_QUERY, core.CHLIST, 0)

case abs(state)

0, 1:

state := abs(state) << core.EN_ALS_VIS

other:

return (((curr_state >> core.EN_ALS_VIS) & 1) == 1)

state := ((curr_state & core.EN_ALS_VIS_MASK) | state)

command(core.CMD_PARAM_SET, core.CHLIST, state)

PUB white_data(): vis_adc

' Return data from white/visible light channel

vis_adc := 0

readreg(core.ALS_VIS_DATA0, 2, @vis_adc)

PUB white_gain(gain=-2): curr_gain

' Gain factor of white/visible light sensor

' Valid values: 1, 16, 64, 128

' Any other value polls the chip and returns the current setting

curr_gain := 0

curr_gain := command(core.CMD_PARAM_QUERY, core.ALS_VIS_ADC_GAIN, 0)

case gain

1: gain := %000

16: gain := %100

64: gain := %110

128: gain := %111

other:

return lookupz(curr_gain & core.ALS_VIS_ADCGAIN_BITS: 1, 0, 0, 0, 16, 0, 64, 128)

command(core.CMD_PARAM_SET, core.ALS_VIS_ADCGAIN, gain)

gain <<= core.VIS_ADC_REC

' Set the one's complement of the gain val

' to ADC recovery period, per datasheet

command(core.CMD_PARAM_SET, core.ALS_VIS_ADC_COUNTER, !gain)

PUB white_overflow(): flag

' Flag indicating white/visible light data conversion has overflowed

' Returns: TRUE (-1) if overflowed, FALSE (0) otherwise

flag := 0

readreg(core.RESPONSE, 1, @flag)

return (flag == core.ALS_VIS_ADC_OVERFLOW)

PUB white_range(range=-2): curr_rng

' Set measurement range of white/visible light sensor

' Valid values:

' NORMAL ($00): Normal signal range/high sensitivity

' HIGH ($20): High signal range (gain divided by 14.5)

curr_rng := 0

curr_rng := command(core.CMD_PARAM_QUERY, core.ALS_VIS_ADC_MISC, 0)

case range

NORMAL, HIGH:

other:

return curr_rng

command(core.CMD_PARAM_SET, core.ALS_VIS_ADC_MISC, range)

PRI clr_resp(): resp | tmp

' Clear response register

' Returns: response, after clearing

resp := 0

tmp := core.CMD_NOP

writereg(core.COMMAND, 1, @tmp)

readreg(core.RESPONSE, 1, @resp)

PRI command(cmd, param, args): resp | tmp

' Send command with parameters to device

resp := 0

case cmd

core.CMD_PARAM_QUERY:

cmd |= param

repeat until (clr_resp() == core.NO_ERROR)

writereg(core.COMMAND, 1, @cmd)

repeat

readreg(core.RESPONSE, 1, @resp)

while (resp == 0)

readreg(core.PARAM_RD, 1, @resp)

return

core.CMD_PARAM_SET:

cmd |= param

writereg(core.PARAM_WR, 1, @args)

repeat until (clr_resp() == core.NO_ERROR)

writereg(core.COMMAND, 1, @cmd)

repeat

readreg(core.RESPONSE, 1, @resp)

while (resp == 0)

return

core.CMD_NOP, core.CMD_RESET, core.CMD_BUSADDR, core.CMD_PS_FORCE, core.CMD_GET_CAL, ...

core.CMD_ALS_FORCE, core.CMD_PSALS_FORCE, core.CMD_PS_PAUSE, core.CMD_ALS_PAUSE, ...

core.CMD_PSALS_PAUSE, core.CMD_PS_AUTO, core.CMD_ALS_AUTO, core.CMD_PSALS_AUTO:

repeat until (clr_resp() == core.NO_ERROR)

writereg(core.COMMAND, 1, @cmd)

if (cmd == core.CMD_RESET) ' no response when resetting

waitms(1) ' also must wait min. 1ms

return

readreg(core.RESPONSE, 1, @resp) ' XXX device NAK on bus if cmd was reset...must wait?

return

PRI hwkey() | tmp

' Writes $17 to HW_KEY reg (per the Si114x datasheet, this must be written for proper operation)

tmp := core.HW_KEY_EXPECTED

writereg(core.HW_KEY, 1, @tmp)

PRI readreg(reg_nr, nr_bytes, ptr_buff) | cmd_pkt

' Read nr_bytes from the device into ptr_buff

case reg_nr ' validate register

$00..$04, $07..$09, $10, $13..$18, $20..$2E, $30:

cmd_pkt.byte[0] := SLAVE_WR

cmd_pkt.byte[1] := reg_nr

i2c.start()

i2c.wrblock_lsbf(@cmd_pkt, 2)

i2c.start()

i2c.write(SLAVE_RD)

i2c.rdblock_lsbf(ptr_buff, nr_bytes, i2c.NAK)

i2c.stop()

other:

return

PRI writereg(reg_nr, nr_bytes, ptr_buff) | cmd_pkt

' Write nr_bytes from ptr_buff to the device

case reg_nr

$03, $04, $07, $08, $09, $0F, $10, $13..$18, $20..$2E:

cmd_pkt.byte[0] := SLAVE_WR

cmd_pkt.byte[1] := reg_nr

i2c.start()

i2c.wrblock_lsbf(@cmd_pkt, 2)

i2c.wrblock_lsbf(ptr_buff, nr_bytes)

i2c.stop()

other:

return

DAT

{

Copyright 2024 Jesse Burt

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and

associated documentation files (the "Software"), to deal in the Software without restriction,

including without limitation the rights to use, copy, modify, merge, publish, distribute,

sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or

substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT

NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,

DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT

OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

}