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

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

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)

Macro Definition Documentation

TSL45311_ADDR

#define TSL45311_ADDR   (0x39)

TSL4531x I2C addresses.

Definition at line 75 of file tsl4531x.h.

TSL45311_PARTNO

#define TSL45311_PARTNO   (0x8)

Definition at line 67 of file tsl4531x.h.

TSL45313_ADDR

#define TSL45313_ADDR   (0x39)

Definition at line 76 of file tsl4531x.h.

TSL45313_PARTNO

#define TSL45313_PARTNO   (0x9)

Definition at line 68 of file tsl4531x.h.

TSL45315_ADDR

#define TSL45315_ADDR   (0x29)

Definition at line 77 of file tsl4531x.h.

TSL45315_PARTNO

#define TSL45315_PARTNO   (0xA)

Definition at line 69 of file tsl4531x.h.

TSL45317_ADDR

#define TSL45317_ADDR   (0x29)

Definition at line 78 of file tsl4531x.h.

TSL45317_PARTNO

#define TSL45317_PARTNO   (0xB)

Definition at line 70 of file tsl4531x.h.

Enumeration Type Documentation

tsl4531x_intgn_time_t

enum tsl4531x_intgn_time_t

Integration times.

Definition at line 55 of file tsl4531x.h.

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

dev	Initialized 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]	dev	Initialized device descriptor
[in]	params	Device 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

dev	Initialized device descriptor
low_power_on	Bool 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

dev	Initialized 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

dev	Initialized 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

dev	Initialized device descriptor

Returns

Time in microseconds until sample is ready