TSL4531x Illuminance sensor

Device driver for the AMS TSL4531 sensor. More...

Detailed Description

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 asynchronous 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.

Files

file  tsl4531x.h
 Device driver for the AMS TSL4531 sensor.
 
file  tsl4531x_internals.h
 Internal addresses, registers, constants for the TSL4531x sensor.
 
file  tsl4531x_params.h
 Default configuration for tsl4531x light sensor.
 

Data Structures

struct  tsl4531x_params_t
 Device initialization parameters. More...
 
struct  tsl4531x_t
 Device descriptor. More...
 

Enumerations

enum  tsl4531x_intgn_time_t { TSL4531X_INTEGRATE_400MS = 0, TSL4531X_INTEGRATE_200MS = 1, TSL4531X_INTEGRATE_100MS = 2 }
 Integration times.
 

Functions

int tsl4531x_init (tsl4531x_t *dev, const tsl4531x_params_t *params)
 Initialize the TSL4531x device. More...
 
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. More...
 
int tsl4531x_start_sample (tsl4531x_t *dev)
 Start collecting sample in low power mode. More...
 
uint32_t tsl4531x_time_until_sample_ready (tsl4531x_t *dev)
 Deliver time in microseconds until sample is ready, or zero if it is ready. More...
 
int tsl4531x_get_sample (const tsl4531x_t *dev)
 Reads the sample from the device immediately. More...
 
int tsl4531x_simple_read (tsl4531x_t *dev)
 Reads the sample from the device. More...
 

Fixed values for different members of the TSL4531x series

Part numbers

#define TSL45311_PARTNO   (0x8)
 
#define TSL45313_PARTNO   (0x9)
 
#define TSL45315_PARTNO   (0xA)
 
#define TSL45317_PARTNO   (0xB)
 
#define TSL45311_ADDR   (0x39)
 TSL4531x I2C addresses.
 
#define TSL45313_ADDR   (0x39)
 
#define TSL45315_ADDR   (0x29)
 
#define TSL45317_ADDR   (0x29)
 

Function Documentation

◆ tsl4531x_get_sample()

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
devInitialized device descriptor
Returns
The sample value in Lux

◆ tsl4531x_init()

int tsl4531x_init ( tsl4531x_t dev,
const tsl4531x_params_t params 
)

Initialize the TSL4531x device.

Parameters
[out]devInitialized device descriptor
[in]paramsDevice initialization parameters
Returns
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

◆ tsl4531x_set_low_power_mode()

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
devInitialized device descriptor
low_power_onBool indicating whether low power mode is on or off
Returns
Zero

◆ tsl4531x_simple_read()

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
devInitialized device descriptor
Returns
The sample value in Lux

◆ tsl4531x_start_sample()

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
devInitialized device descriptor
Returns
Zero

◆ tsl4531x_time_until_sample_ready()

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
devInitialized device descriptor
Returns
Time in microseconds until sample is ready