Osram SFH7770 light & proximity sensor driver.

This file contains functions for initializing and reading data from a Osram SFH7770 light & proximity sensor.

#include <string.h>
#include "sfh7770.h"

Data Structures
struct	current_level_t
	Proximity sensor LED current table (mA, register field value) More...

struct	sample_rate_t
	Sample rate table entry. More...

Macros
#define	NUM_CURRENT_LEVELS (sizeof(current_table) / sizeof(current_level_t))

#define	NUM_LIGHT_RATES (sizeof(light_rate_table) / sizeof(sample_rate_t))

#define	NUM_PROX_RATES (sizeof(prox_rate_table) / sizeof(sample_rate_t))

#define	SFH7770_NVRAM_OFFSET (0x18)

Functions
static bool	sfh7770_calibrate (sensor_t sensor, sensor_calibration_t calib_type, int step, void info)
	Calibrate proximity sensor detection thresholds. More...

static bool	sfh7770_device_id (sensor_hal_t hal, sensor_data_t data)
	Read SFH7770 device ID and revision numbers. More...

static bool	sfh7770_event (sensor_t sensor, sensor_event_t sensor_event, sensor_event_callback_t callback, bool enable)
	Enable or disable SFH7770 sensor events. More...

static bool	sfh7770_get_light (sensor_hal_t hal, sensor_data_t data)
	Read SFH7770 light level data. More...

static bool	sfh7770_get_proximity (sensor_hal_t hal, sensor_data_t data)
	Read SFH7770 proximity data. More...

static bool	sfh7770_get_threshold (sensor_hal_t hal, int16_t channel, sensor_threshold_desc_t threshold)
	Get event threshold value. More...

bool	sfh7770_init (sensor_t *sensor, int resvd)
	Osram SFH7770 light & proximity sensor driver initialization. More...

static bool	sfh7770_ioctl (sensor_t sensor, sensor_command_t cmd, void arg)
	SFH7770 ioctl control entry point. More...

static void	sfh7770_isr (volatile void *arg)
	Osram SFH7770 driver interrupt service routine. More...

static bool	sfh7770_read (sensor_t sensor, sensor_read_t type, sensor_data_t data)
	Read sensor data. More...

static bool	sfh7770_set_current (sensor_hal_t hal, int16_t channel, uint16_t level_mA)
	Set proximity LED current level. More...

static bool	sfh7770_set_rate (sensor_hal_t *hal, sensor_type_t type, uint16_t rate_hz)
	Set sensor sample rate. More...

static bool	sfh7770_set_state (sensor_hal_t *hal, sensor_type_t type, sensor_state_t state)
	Set the SFH7770 execution mode. More...

static bool	sfh7770_set_threshold (sensor_hal_t hal, int16_t channel, sensor_threshold_desc_t threshold)
	Set event threshold value. More...

Variables
static const current_level_t	current_table []

static sensor_event_callback_t	event_cb [3]
	Sensor Event Callback table (proximity=0, low light=1, high light=2) More...

static uint16_t	high_light_threshold
	Event threshold value for hight light. More...

static const sample_rate_t	light_rate_table []
	Light sensor sample rate table (Hz, reg field value) More...

static uint16_t	low_light_threshold
	Event threshold value for low light. More...

static const sample_rate_t	prox_rate_table []
	Proximity sensor sample rate table (Hz, reg field value) More...

static bool	sfh7770_initialized = false
	Driver initialization flag. More...

#define NUM_CURRENT_LEVELS (sizeof(current_table) / sizeof(current_level_t))

Referenced by sfh7770_set_current().

#define NUM_LIGHT_RATES (sizeof(light_rate_table) / sizeof(sample_rate_t))

Referenced by sfh7770_set_rate().

#define NUM_PROX_RATES (sizeof(prox_rate_table) / sizeof(sample_rate_t))

Referenced by sfh7770_set_rate().

#define SFH7770_NVRAM_OFFSET (0x18)

Referenced by sfh7770_calibrate(), sfh7770_init(), and sfh7770_set_threshold().

static bool sfh7770_calibrate	(	sensor_t *	sensor,
		sensor_calibration_t	calib_type,
		int	step,
		void *	info
	)

static

Calibrate proximity sensor detection thresholds.

This function measures the proximity sensor output in 3 different steps, one for each channel in the device. This function should be called when a sample object has been placed at the desired distance from the device to define the threshold for near-proximity detection. The measured proximity sensor value for each channel is stored in non-volatile memory. These thresholds will later be used to set the threshold during the device initialization sequence.

This routine must be called 3 times total, with the "step" parameter indicating what stage of the calibration is being performed (i.e. which channel of the proximity sensor). This multi-step mechanism allows the application to prompt for physical placement of the object to be detected before this routine is called.

Parameters

sensor	Address of an initialized sensor device descriptor.
calib_type	The address of a vector storing sensor axis data.
step	The calibration stage number [1,3].
info	Unimplemented (ignored) parameter.

Returns: bool true if the call succeeds, else false is returned.

References sensor_desc::err, sensor_desc::hal, MANUAL_CALIBRATE, nvram_read(), nvram_write(), prox_data, sensor_bus_get, sensor_bus_write, SENSOR_ERR_IO, SENSOR_ERR_PARAMS, SFH7770_NVRAM_OFFSET, SFH7770_PS_DATA_LED1, SFH7770_PS_DATA_LED2, SFH7770_PS_DATA_LED3, and SFH7770_PS_THR_LED1.

Referenced by sfh7770_init().

static bool sfh7770_device_id	(	sensor_hal_t *	hal,
		sensor_data_t *	data
	)

static

Read SFH7770 device ID and revision numbers.

This function reads the sensor hardware identification registers and returns these values in the specified data structure.

Parameters

hal	Address of an initialized sensor hardware descriptor.
data	Address of sensor_data_t structure to return values.

Returns: bool true if the call succeeds, else false is returned.

References sensor_data_t::device, PART_ID_MASK, PART_ID_SHIFT, PART_REV_MASK, sensor_bus_get, and SFH7770_PART_ID.

Referenced by sfh7770_read().

static bool sfh7770_event	(	sensor_t *	sensor,
		sensor_event_t	sensor_event,
		sensor_event_callback_t *	callback,
		bool	enable
	)

static

Enable or disable SFH7770 sensor events.

Parameters

sensor	Address of an initialized sensor device descriptor
callback	Application-defined event callback handler descriptor
enable	Enable flag: true = enable event, false = disable event

Returns: bool true if the call succeeds, else false is returned

References sensor_desc::hal, INT_MODE_ALS, INT_MODE_PS, sensor_bus_get, sensor_bus_put, SENSOR_EVENT_HIGH_LIGHT, SENSOR_EVENT_LOW_LIGHT, SENSOR_EVENT_NEAR_PROXIMITY, SFH7770_INT_SET, and status.

Referenced by sfh7770_init(), and sfh7770_ioctl().

static bool sfh7770_get_light	(	sensor_hal_t *	hal,
		sensor_data_t *	data
	)

static

Read SFH7770 light level data.

This function reads the ambient light level data from the sensor and places it in the user-provided sensor_data_t structure.

Parameters

sensor	Address of an initialized sensor device descriptor.
data	The address of a vector storing sensor measurement data.

Returns: bool true if the call succeeds, else false is returned.

References sensor_data_t::light, light_data, sensor_bus_read, and SFH7770_ALS_DATA_LSB.

Referenced by sfh7770_read().

static bool sfh7770_get_proximity	(	sensor_hal_t *	hal,
		sensor_data_t *	data
	)

static

Read SFH7770 proximity data.

This function reads the proximity data from the three channels of the sensor and places it in the user-provided sensor_data_t structure. The proximity value is not in standard units, so for "scaled" output the values are encoded based on whether or not the proximity reading exceeds the programmed threshold level for each channel (LED).

The sensor has only a single threshold level, so only two possible values are reported: PROXIMITY_NEAR (if threshold is exceeded) or PROXIMITY_NONE.

Parameters

sensor	Address of an initialized sensor device descriptor.
data	The address of a vector storing sensor measurement data.

Returns: bool true if the call succeeds, else false is returned.

References sensor_data_t::proximity, PROXIMITY_NEAR, PROXIMITY_NONE, PS_LED1_THRESH, PS_LED2_THRESH, PS_LED3_THRESH, sensor_data_t::scaled, sensor_bus_read, and SFH7770_ALS_PS_STATUS.

Referenced by sfh7770_read().

static bool sfh7770_get_threshold	(	sensor_hal_t *	hal,
		int16_t	channel,
		sensor_threshold_desc_t *	threshold
	)

static

Get event threshold value.

Parameters

hal	Address of an initialized sensor hardware descriptor.
channel	Channel (LED) number to set threshold
threshold	Address of threshold descriptor.

Returns: bool true if the call succeeds, else false is returned.

References high_light_threshold, low_light_threshold, sensor_bus_get, SENSOR_CHANNEL_ALL, SENSOR_THRESHOLD_HIGH_LIGHT, SENSOR_THRESHOLD_LOW_LIGHT, SENSOR_THRESHOLD_NEAR_PROXIMITY, SFH7770_PS_THR_LED1, sensor_threshold_desc_t::type, and sensor_threshold_desc_t::value.

Referenced by sfh7770_ioctl().

bool sfh7770_init	(	sensor_t *	sensor,
		int	resvd
	)

Osram SFH7770 light & proximity sensor driver initialization.

This is the main initialization function for the SFH7770 device.

Parameters

sensor	Address of a sensor device descriptor.
resvd	Reserved value.

Returns: bool true if the call succeeds, else false is returned.

References ALS_CONTROL_SW_RESET, ALS_INTERVAL_500MS, ALS_MODE_FREE_RUNNING, sensor_hal::burst_addr, sensor_hal::bus, sensor_desc::drv, sensor_device_t::func, sensor_desc::hal, I_LED2_SHIFT, I_LED_50MA, LED_ACTIVE_ALL, sensor_hal::mcu_sigint, nvram_read(), PS_INTERVAL_100MS, PS_MODE_FREE_RUNNING, sensor_funcs_t::read, sensor_hal::resolution, sensor_bus_get, sensor_bus_put, sensor_bus_write, sensor_irq_connect(), SENSOR_SCALE_one, SENSOR_TYPE_LIGHT, SENSOR_TYPE_PROXIMITY, SENSOR_UNITS_lux, SENSOR_VENDOR_OSRAM, SFH7770_ALS_CONTROL, SFH7770_ALS_DATA_LSB, SFH7770_ALS_INTERVAL, sfh7770_calibrate(), SFH7770_DATA_RESOLUTION, sfh7770_event(), SFH7770_I_LED_1_2, SFH7770_I_LED_3, sfh7770_initialized, SFH7770_INT_SET, sfh7770_ioctl(), sfh7770_isr(), SFH7770_NVRAM_OFFSET, SFH7770_PART_ID, SFH7770_PART_ID_VAL, SFH7770_PART_REV_VAL, SFH7770_PS_CONTROL, SFH7770_PS_INTERVAL, SFH7770_PS_THR_LED1, sfh7770_read(), status, bus_desc_t::status, STATUS_OK, and sensor_desc::type.

static bool sfh7770_ioctl	(	sensor_t *	sensor,
		sensor_command_t	cmd,
		void *	arg
	)

static

SFH7770 ioctl control entry point.

Parameters

hal	Address of an initialized sensor hardware descriptor.
cmd	Command to execute
arg	Argument for command (varies)

Returns: bool true if the call succeeds, else false is returned.

References sensor_desc::channel, sensor_desc::err, sensor_desc::hal, SENSOR_DISABLE_EVENT, SENSOR_ENABLE_EVENT, SENSOR_ERR_UNSUPPORTED, SENSOR_GET_THRESHOLD, SENSOR_SET_CURRENT, SENSOR_SET_SAMPLE_RATE, SENSOR_SET_STATE, SENSOR_SET_THRESHOLD, sfh7770_event(), sfh7770_get_threshold(), sfh7770_set_current(), sfh7770_set_rate(), sfh7770_set_state(), sfh7770_set_threshold(), status, and sensor_desc::type.

Referenced by sfh7770_init().

static void sfh7770_isr ( volatile void * arg )

static

Osram SFH7770 driver interrupt service routine.

This is the common interrupt service routine for all enabled SFH7770 interrupt events. Three different types of interrupts can be programmed: high light level, low light level, and near proximity. All share the same interrupt pin and therefore the same ISR entry.

Parameters

arg	The address of the driver sensor_hal_t descriptor.

Returns: Nothing.

References sensor_hal::burst_addr, sensor_hal::bus, sensor_event_data_t::channel, sensor_event_data_t::data, sensor_event_data_t::event, sensor_event_callback_t::handler, high_light_threshold, INT_SOURCE_ALS, INT_SOURCE_LED1, INT_SOURCE_LED2, INT_SOURCE_LED3, INT_SOURCE_MASK, sensor_data_t::light, low_light_threshold, bus_desc_t::no_wait, sensor_data_t::proximity, PROXIMITY_NEAR, PROXIMITY_NONE, PS_LED1_THRESH, PS_LED2_THRESH, PS_LED3_THRESH, sensor_data_t::scaled, sensor_bus_read, SENSOR_EVENT_HIGH_LIGHT, SENSOR_EVENT_LOW_LIGHT, SENSOR_EVENT_NEAR_PROXIMITY, SENSOR_EVENT_UNKNOWN, sensor_timestamp(), bus_desc_t::status, STATUS_OK, and sensor_data_t::timestamp.

Referenced by sfh7770_init().

static bool sfh7770_read	(	sensor_t *	sensor,
		sensor_read_t	type,
		sensor_data_t *	data
	)

static

Read sensor data.

This routine calls the appropriate internal data function to obtain the specified type of data from the sensor device.

Parameters

sensor	Address of an initialized sensor device descriptor.
type	Type of sensor data to read.
data	The address where data values are returned.

Returns: bool true if the call succeeds, else false is returned.

References sensor_desc::err, sensor_desc::hal, SENSOR_ERR_FUNCTION, SENSOR_READ_ID, SENSOR_READ_LIGHT, SENSOR_READ_PROXIMITY, sfh7770_device_id(), sfh7770_get_light(), and sfh7770_get_proximity().

Referenced by sfh7770_init().

static bool sfh7770_set_current	(	sensor_hal_t *	hal,
		int16_t	channel,
		uint16_t *	level_mA
	)

static

Set proximity LED current level.

Parameters

hal	Address of an initialized sensor hardware descriptor.
channel	Channel (LED) number to set current
curr_levels	Address of an array of current levels (1 per LED)

Returns: bool true if the call succeeds, else false is returned.

References current_level_t::field_val, I_LED1_MASK, I_LED2_MASK, I_LED2_SHIFT, NUM_CURRENT_LEVELS, sensor_bus_get, sensor_bus_put, SENSOR_CHANNEL_ALL, SFH7770_I_LED_1_2, SFH7770_I_LED_3, and status.

Referenced by sfh7770_ioctl().

static bool sfh7770_set_rate	(	sensor_hal_t *	hal,
		sensor_type_t	type,
		uint16_t	rate_hz
	)

static

Set sensor sample rate.

Parameters

hal	Address of an initialized sensor hardware descriptor.
type	Active mode of the sensor (i.e. light or proximity)
rate_hz	Sample rate in Hz

Returns: bool true if the call succeeds, else false is returned.

References NUM_LIGHT_RATES, NUM_PROX_RATES, sensor_bus_put, SENSOR_TYPE_LIGHT, SENSOR_TYPE_PROXIMITY, SFH7770_ALS_INTERVAL, SFH7770_PS_INTERVAL, and status.

Referenced by sfh7770_ioctl().

static bool sfh7770_set_state	(	sensor_hal_t *	hal,
		sensor_type_t	type,
		sensor_state_t	state
	)

static

Set the SFH7770 execution mode.

This routine sets a specified SFH7770 execution state to one of the following:

SENSOR_STATE_SLEEP: Setting the sleep mode puts the specific sensor unit (light or proximity) in standby mode, in which no measurements are made.

SENSOR_STATE_NORMAL: Setting the sleep mode puts the specific sensor unit (light or proximity) in continuous measurement mode.

Parameters

hal	Address of an initialized sensor hardware descriptor.
type	The operational type of the sensor (light or proximity)
state	A specified sensor operational state.

Returns: bool true if the call succeeds, else false is returned.

References ALS_MODE_FREE_RUNNING, ALS_MODE_STANDBY, PS_MODE_FREE_RUNNING, PS_MODE_STANDBY, sensor_bus_put, SENSOR_STATE_NORMAL, SENSOR_STATE_SLEEP, SENSOR_TYPE_LIGHT, SFH7770_ALS_CONTROL, and SFH7770_PS_CONTROL.

Referenced by sfh7770_ioctl().

static bool sfh7770_set_threshold	(	sensor_hal_t *	hal,
		int16_t	channel,
		sensor_threshold_desc_t *	threshold
	)

static

Set event threshold value.

Parameters

hal	Address of an initialized sensor hardware descriptor.
channel	Channel (LED) number to set threshold
threshold	Address of threshold descriptor.

Returns: bool true if the call succeeds, else false is returned.

References high_light_threshold, if(), low_light_threshold, nvram_write(), sensor_bus_put, sensor_bus_write, SENSOR_CHANNEL_ALL, SENSOR_THRESHOLD_HIGH_LIGHT, SENSOR_THRESHOLD_LOW_LIGHT, SENSOR_THRESHOLD_NEAR_PROXIMITY, SFH7770_ALS_LO_THR_LSB, SFH7770_ALS_UP_THR_LSB, SFH7770_NVRAM_OFFSET, SFH7770_PS_THR_LED1, sensor_threshold_desc_t::type, and sensor_threshold_desc_t::value.

Referenced by sfh7770_ioctl().

const current_level_t current_table[]

static

Initial value:

= {
    {  5, I_LED_5MA  }, { 10, I_LED_10MA },
    { 20, I_LED_20MA }, { 50, I_LED_50MA },
    {100, I_LED_100MA}, {150, I_LED_150MA},
    {200, I_LED_200MA}
}

sensor_event_callback_t event_cb[3]

static

Initial value:

= {
    {.handler = default_event_handler},
    {.handler = default_event_handler},
    {.handler = default_event_handler}
}

Sensor Event Callback table (proximity=0, low light=1, high light=2)

uint16_t high_light_threshold

static

Event threshold value for hight light.

Referenced by sfh7770_get_threshold(), sfh7770_isr(), and sfh7770_set_threshold().

const sample_rate_t light_rate_table[]

static

Initial value:

= {
    { 0, ALS_INTERVAL_2000MS},  
    { 1, ALS_INTERVAL_1000MS},  
    { 2, ALS_INTERVAL_500MS },  
    { 5, ALS_INTERVAL_200MS },  
    {10, ALS_INTERVAL_100MS }   
}

Light sensor sample rate table (Hz, reg field value)

uint16_t low_light_threshold

static

Event threshold value for low light.

Referenced by sfh7770_get_threshold(), sfh7770_isr(), and sfh7770_set_threshold().

const sample_rate_t prox_rate_table[]

static

Initial value:

= {
    {  0, PS_INTERVAL_2000MS},  
    {  1, PS_INTERVAL_1000MS},  
    {  2, PS_INTERVAL_500MS },  
    {  5, PS_INTERVAL_200MS },  
    { 10, PS_INTERVAL_100MS },  
    { 14, PS_INTERVAL_70MS  },  
    { 20, PS_INTERVAL_50MS  },  
    { 33, PS_INTERVAL_30MS  },  
    { 50, PS_INTERVAL_20MS  },  
    {100, PS_INTERVAL_10MS  }   
}

Proximity sensor sample rate table (Hz, reg field value)

bool sfh7770_initialized = false

static

Driver initialization flag.

Referenced by sfh7770_init().

Microchip® Advanced Software Framework

Data Structures

Macros

Functions

Variables