TSL4531x Illuminance sensor

Device driver for the AMS TSL4531 sensor.

Power modes

This driver has two power modes: high and low. Its startup mode is configured in the initialization parameters, and it can also be changed during runtime.

In high power mode, the user application can read from the device using the tsl4531x_simple_read function, and it will return immediately.

In low power mode, the user application can interact with the driver in a synchronous or asynchronous manner. For synchronous operation, the application can call tsl4531x_simple_read, and the driver will block for the integration time defined in the initialization parameters (plus a small margin, to encompass the max times indicated in the datasheet). For asyncronous operation, the application needs to use the functions tsl4531x_start_sample, tsl4531x_time_until_sample_ready and tsl4531x_get_sample, as described in those functions’ descriptions.

Both modes will work through SAUL, with the low-power mode being synchronous.

TSL45311_PARTNO
1
(0x8)
TSL45313_PARTNO
1
(0x9)
TSL45315_PARTNO
1
(0xA)
TSL45317_PARTNO
1
(0xB)
TSL45311_ADDR

TSL4531x I2C addresses. 

1
(0x39)
TSL45313_ADDR
1
(0x39)
TSL45315_ADDR
1
(0x29)
TSL45317_ADDR
1
(0x29)
enum tsl4531x_intgn_time_t
TSL4531X_INTEGRATE_400MS = 0
TSL4531X_INTEGRATE_200MS = 1
TSL4531X_INTEGRATE_100MS = 2
int tsl4531x_init(tsl4531x_t * dev, const tsl4531x_params_t * params)

Initialize the TSL4531x device.

Parameters

dev:Initialized device descriptor
params:Device initialization parameters

Return values

  • Zero on success
  • -ENODEV if I2C bus can’t be acquired
  • -ENXIO if device can’t be read or configured
  • -ENOTSUP if ID, once read, is wrong
int tsl4531x_set_low_power_mode(tsl4531x_t * dev, uint8_t low_power_on)

Set the low power mode of the driver on or off.

Parameters

dev:Initialized device descriptor
low_power_on:Bool indicating whether low power mode is on or off

Return values

  • Zero
int tsl4531x_start_sample(tsl4531x_t * dev)

Start collecting sample in low power mode.

This provides asynchronous operation along with tsl4531x_time_until_sample_ready and tsl4531x_get_sample. It does nothing in high power mode.

Parameters

dev:Initialized device descriptor

Return values

  • Zero
uint32_t tsl4531x_time_until_sample_ready(tsl4531x_t * dev)

Deliver time in microseconds until sample is ready, or zero if it is ready.

In low power mode, this counts down from the point at which tsl4531x_start_sample is called, and along with that function and tsl4531x_get_sample, provides asynchronous operation. In high power mode, this counts down from the point at which the driver is switched into high power mode or started up, and indicates whether enough time has passed for a full sample to be collected.

Note that for low power mode this rolls over and repeats its behaviour every 1.2 hours. The sample should have been collected well before this, however.

The countdown time equals the integration time, which can be set in the device initialisation parameters, plus 5% margin to encompass the max times indicated in the datasheet.

Parameters

dev:Initialized device descriptor

Return values

  • Time in microseconds until sample is ready
int tsl4531x_get_sample(const tsl4531x_t * dev)

Reads the sample from the device immediately.

In high power mode, this does the same as tsl4531x_simple_read once the device has performed one integration cycle. In low power mode, this provides asynchronous operation along with tsl4531x_start_sample and tsl4531x_time_until_sample_ready which determine whether the device has performed an integration cycle.

Note that this function will always return the value stored in the device’s internal register, and this value will be sensible physically, representing the last time an integration cycle has been performed. However, in order for it to be accurate, the start_sample and time_until_sample_ready functions need to also be used, or alternatively the simple_read function can be used.

Parameters

dev:Initialized device descriptor

Return values

  • The sample value in Lux
int tsl4531x_simple_read(tsl4531x_t * dev)

Reads the sample from the device.

In low power mode, or in high power mode just after startup, this starts collecting the sample, blocks until the sample is ready (400/200/100ms depending on the integration time set in the initialization parameters), and then reads and returns the sample.

Parameters

dev:Initialized device descriptor

Return values

  • The sample value in Lux
struct tsl4531x_params_t

Device initialization parameters.

i2c.h::i2c_t i2c_dev

I2C device which is used.

i2c.h::i2c_t i2c_addr

I2C address of sensor.

tsl4531x.h::tsl4531x_intgn_time_t integration_time

integration time

uint8_t low_power_mode

low power mode

uint8_t part_number

part number, according to variant

struct tsl4531x_t

Device descriptor.

i2c.h::i2c_t i2c_dev

I2C device which is used.

i2c.h::i2c_t i2c_addr

I2C address of sensor.

tsl4531x.h::tsl4531x_intgn_time_t integration_time

integration time

uint8_t low_power_mode

low power mode

uint8_t high_power_mode_started_up

high power mode started up flag

uint32_t sample_start_time

sample start time