Driver for Panasonic AMG88xx infrared array sensors. More...

Detailed Description

Driver for Panasonic AMG88xx infrared array sensors.

The AMG88xx (Grid-EYE) is a family of 8x8 infrared (thermal) array sensors connected via I2C. It measures temperatures in the range of 0 to 80 or -20 to 100 degrees Celsius (depends on the variant) with a resolution of 0.25 degrees Celsius per pixel. The on-chip thermistor provides the ambient temperature with a resolution of 0.0625 degrees Celsius.

The sensor outputs a frame of 8x8 pixels, where each pixel represents the temperature of the corresponding area in the field of view. The sensors support configurable frame rates (1 or 10 FPS), multiple power modes, a moving average filter, and per-pixel interrupt thresholds.

This driver provides [S]ensor [A]ctuator [U]ber [L]ayer capabilities.

Usage

Add one of the following variants to the application Makefile:

USEMODULE += amg8831
USEMODULE += amg8832
USEMODULE += amg8833
USEMODULE += amg8834
USEMODULE += amg8851
USEMODULE += amg8852
USEMODULE += amg8853
USEMODULE += amg8854

Support for interrupts is available and included if GPIO interrupts are supported. Interrupts can be used to trigger processing when a pixel exceeds a certain temperature threshold. Note that the AMG88xx requires a pull-up resistor on the interrupt line, which may not be present on all off-the-shelve (evaluation) boards.

Files
file	amg88xx_constants.h
	Internal addresses, registers and constants.

file	amg88xx_params.h
	Default configuration.

file	amg88xx.h
	Interface definition for the AMG88xx infrared array sensor driver.

Data Structures
struct	amg88xx_params_t
	Device initialization parameters. More...

struct	amg88xx_t
	Device descriptor for the driver. More...

Macros
#define	AMG88XX_PIXELS_HORIZONTAL (8)
	Dimensions of a frame.

#define	AMG88XX_PIXELS_VERTICAL (8)
	Number of vertical pixels.

#define	AMG88XX_PIXELS_COUNT (64)
	Number of pixels per frame.

#define	AMG88XX_BYTES_PER_PIXEL (2)
	Size of pixel data.

#define	AMG88XX_BYTES_PER_FRAME (128)
	Bytes per frame.

Typedefs
typedef void(*	amg88xx_int_cb_t) (void *)
	Interrupt callback type.

Enumerations
enum	amg88xx_fps_t { AMG88XX_FPS_10 = 0x00 , AMG88XX_FPS_1 = 0x01 }
	Frame rate options. More...

enum	amg88xx_mode_t { AMG88XX_MODE_NORMAL = 0x00 , AMG88XX_MODE_SLEEP = 0x10 , AMG88XX_MODE_STANDBY_60S = 0x20 , AMG88XX_MODE_STANDBY_10S = 0x21 }
	Operating mode options. More...

enum	amg88xx_interrupt_mode_t { AMG88XX_INT_DIFFERENCE = 0x00 , AMG88XX_INT_ABSOLUTE = 0x01 }
	Interrupt mode options. More...

Functions
int	amg88xx_set_fps (const amg88xx_t *dev, amg88xx_fps_t fps)
	Set the frame rate.

int	amg88xx_get_fps (const amg88xx_t dev, amg88xx_fps_t fps)
	Get the current frame rate.

int	amg88xx_set_mode (amg88xx_t *dev, amg88xx_mode_t mode)
	Set the operating mode.

int	amg88xx_get_mode (const amg88xx_t dev, amg88xx_mode_t mode)
	Get the current operating mode.

int	amg88xx_set_averaging (const amg88xx_t *dev, bool enabled)
	Enable or disable twice moving average mode.

int	amg88xx_get_averaging (const amg88xx_t dev, bool enabled)
	Get the current averaging mode.

int	amg88xx_get_temperature (const amg88xx_t dev, int16_t temperature)
	Read the thermistor (chip) temperature.

int	amg88xx_get_frame (const amg88xx_t *dev, int16_t pixels[AMG88XX_PIXELS_COUNT])
	Read a 8x8 frame of thermal pixel data.

int	amg88xx_init_int (amg88xx_t dev, amg88xx_int_cb_t cb, void arg)
	Initialize the interrupt pin.

int	amg88xx_set_interrupt (const amg88xx_t *dev, amg88xx_interrupt_mode_t mode, bool enabled)
	Enable or disable the interrupt with the given mode.

int	amg88xx_get_interrupt (const amg88xx_t dev, amg88xx_interrupt_mode_t mode, bool *enabled)
	Get the current interrupt configuration.

int	amg88xx_set_interrupt_levels (const amg88xx_t *dev, int16_t upper, int16_t lower, int16_t hysteresis)
	Set the interrupt threshold levels.

int	amg88xx_get_interrupt_levels (const amg88xx_t dev, int16_t upper, int16_t lower, int16_t hysteresis)
	Get the current interrupt threshold levels.

int	amg88xx_get_interrupt_table (const amg88xx_t *dev, uint8_t table[8])
	Read the interrupt table.

int	amg88xx_get_status (const amg88xx_t dev, uint8_t status)
	Read the status register.

int	amg88xx_clear_status (const amg88xx_t *dev)
	Clear all status and interrupt flags.

int	amg88xx_init (amg88xx_t dev, const amg88xx_params_t params)
	Initialize the given sensor.

static int16_t	amg88xx_raw_to_temperature (int16_t raw)
	Convert a raw pixel value to temperature in centi-degrees Celsius.

static int16_t	amg88xx_temperature_to_raw (int16_t temperature)
	Convert a temperature in centi-degrees Celsius to a raw pixel value.

Variables
const saul_driver_t	amg88xx_temperature_saul_driver
	Export of SAUL interface for temperature sensor.

Macro Definition Documentation

◆ AMG88XX_BYTES_PER_FRAME

#define AMG88XX_BYTES_PER_FRAME (128)

Bytes per frame.

Definition at line 82 of file amg88xx.h.

◆ AMG88XX_BYTES_PER_PIXEL

#define AMG88XX_BYTES_PER_PIXEL (2)

Size of pixel data.

Bytes per pixel

Definition at line 81 of file amg88xx.h.

◆ AMG88XX_PIXELS_COUNT

#define AMG88XX_PIXELS_COUNT (64)

Number of pixels per frame.

Definition at line 76 of file amg88xx.h.

◆ AMG88XX_PIXELS_HORIZONTAL

#define AMG88XX_PIXELS_HORIZONTAL (8)

Dimensions of a frame.

Number of horizontal pixels

Definition at line 74 of file amg88xx.h.

◆ AMG88XX_PIXELS_VERTICAL

#define AMG88XX_PIXELS_VERTICAL (8)

Number of vertical pixels.

Definition at line 75 of file amg88xx.h.

Typedef Documentation

◆ amg88xx_int_cb_t

typedef void(* amg88xx_int_cb_t) (void *)

Interrupt callback type.

Definition at line 114 of file amg88xx.h.

Enumeration Type Documentation

◆ amg88xx_fps_t

enum amg88xx_fps_t

Frame rate options.

Enumerator
AMG88XX_FPS_10	10 frames per second
AMG88XX_FPS_1	1 frame per second

Definition at line 87 of file amg88xx.h.

◆ amg88xx_interrupt_mode_t

enum amg88xx_interrupt_mode_t

Interrupt mode options.

Enumerator
AMG88XX_INT_DIFFERENCE	Difference interrupt mode.
AMG88XX_INT_ABSOLUTE	Absolute value interrupt mode.

Definition at line 105 of file amg88xx.h.

◆ amg88xx_mode_t

enum amg88xx_mode_t

Operating mode options.

Enumerator
AMG88XX_MODE_NORMAL	Normal mode.
AMG88XX_MODE_SLEEP	Sleep mode.
AMG88XX_MODE_STANDBY_60S	Standby with 60s intermittence.
AMG88XX_MODE_STANDBY_10S	Standby with 10s intermittence.

Definition at line 95 of file amg88xx.h.

Function Documentation

◆ amg88xx_clear_status()

int amg88xx_clear_status ( const amg88xx_t * dev )

Clear all status and interrupt flags.

Parameters

[in] dev Device descriptor

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_averaging()

int amg88xx_get_averaging	(	const amg88xx_t *	dev,
		bool *	enabled )

Get the current averaging mode.

Parameters

[in]	dev	Device descriptor
[out]	enabled	Current averaging state

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_fps()

int amg88xx_get_fps	(	const amg88xx_t *	dev,
		amg88xx_fps_t *	fps )

Get the current frame rate.

Parameters

[in]	dev	Device descriptor
[out]	fps	Current frame rate setting

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_frame()

int amg88xx_get_frame	(	const amg88xx_t *	dev,
		int16_t	pixels[AMG88XX_PIXELS_COUNT] )

Read a 8x8 frame of thermal pixel data.

Each pixel value is a signed 12-bit value in units of 0.25 deg C.

Use amg88xx_raw_to_temperature to convert a raw pixel value to centi-degrees Celsius.

Parameters

[in]	dev	Device descriptor
[out]	pixels	Buffer for AMG88XX_PIXELS_COUNT pixel values

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_interrupt()

int amg88xx_get_interrupt	(	const amg88xx_t *	dev,
		amg88xx_interrupt_mode_t *	mode,
		bool *	enabled )

Get the current interrupt configuration.

Parameters

[in]	dev	Device descriptor
[out]	mode	Current interrupt mode (absolute or difference)
[out]	enabled	Current interrupt enabled state

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_interrupt_levels()

int amg88xx_get_interrupt_levels	(	const amg88xx_t *	dev,
		int16_t *	upper,
		int16_t *	lower,
		int16_t *	hysteresis )

Get the current interrupt threshold levels.

All values are in raw sensor units (0.25 deg C per LSB), using 12-bit sign-magnitude format.

Use amg88xx_raw_to_temperature to convert the raw values read into upper, lower, and hysteresis to temperatures in centi-degrees Celsius.

Parameters

[in]	dev	Device descriptor
[out]	upper	Upper threshold level
[out]	lower	Lower threshold level
[out]	hysteresis	Hysteresis level

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_interrupt_table()

int amg88xx_get_interrupt_table	(	const amg88xx_t *	dev,
		uint8_t	table[8] )

Read the interrupt table.

The table contains 8 bytes (64 bits), one bit per pixel. A bit value of 1 indicates that the corresponding pixel has triggered an interrupt.

Parameters

[in]	dev	Device descriptor
[out]	table	Buffer for 8 bytes of interrupt flags

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_mode()

int amg88xx_get_mode	(	const amg88xx_t *	dev,
		amg88xx_mode_t *	mode )

Get the current operating mode.

Parameters

[in]	dev	Device descriptor
[out]	mode	Current operating mode

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_status()

int amg88xx_get_status	(	const amg88xx_t *	dev,
		uint8_t *	status )

Read the status register.

Returns the raw value of the status register (STAT). The following bits can be checked using the AMG88XX_STAT_* masks:

AMG88XX_STAT_INTF - interrupt triggered
AMG88XX_STAT_OVF_THS - thermistor temperature overflow
AMG88XX_STAT_OVF_IRS - pixel temperature overflow

Parameters

[in]	dev	Device descriptor
[out]	status	Raw status register value

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_get_temperature()

int amg88xx_get_temperature	(	const amg88xx_t *	dev,
		int16_t *	temperature )

Read the thermistor (chip) temperature.

Parameters

[in]	dev	Device descriptor
[out]	temperature	Current thermistor temperature in centi-degrees Celsius

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_init()

int amg88xx_init	(	amg88xx_t *	dev,
		const amg88xx_params_t *	params )

Initialize the given sensor.

The function resets the sensor by performing a wake-up routine.

Parameters

[in,out]	dev	Device descriptor of the driver
[in]	params	Initialization parameters

Return values

0	on success
-EIO	on I2C error
-ENODEV	on sensor not found

◆ amg88xx_init_int()

int amg88xx_init_int	(	amg88xx_t *	dev,
		amg88xx_int_cb_t	cb,
		void *	arg )

Initialize the interrupt pin.

The interrupt pin can be used to signal the CPU when the sensor detects a pixel temperature that exceeds the configured thresholds. The callback function is called when the interrupt is triggered, with the provided argument.

Use amg88xx_set_interrupt and amg88xx_set_interrupt_levels to enable and configure the interrupt behavior.

Precondition: The device must be initialized with amg88xx_init first.

Parameters

[in]	dev	Device descriptor
[in]	cb	Callback function when the interrupt is triggered
[in]	arg	Callback argument

Return values

0	on success
-ENODEV	if no valid interrupt pin is configured
-EIO	on error

◆ amg88xx_raw_to_temperature()

static int16_t amg88xx_raw_to_temperature ( int16_t raw )

inlinestatic

Convert a raw pixel value to temperature in centi-degrees Celsius.

Pixel values from amg88xx_get_frame are in units of 0.25 deg C per LSB. This function converts such a value to centi-degrees Celsius (1/100 deg C).

For example, a value of 100 corresponds to 25.0 deg C and a value of 40 corresponds to 10.0 deg C.

Parameters

[in] raw Raw pixel value (0.25 deg C per LSB)

Returns: Temperature in centi-degrees Celsius

Definition at line 416 of file amg88xx.h.

◆ amg88xx_set_averaging()

int amg88xx_set_averaging	(	const amg88xx_t *	dev,
		bool	enabled )

Enable or disable twice moving average mode.

When enabled, the sensor applies a twice moving average filter to the pixel output, reducing noise at the cost of slower response.

Note: The frame rate must be set to 10 FPS (AMG88XX_FPS_10) before enabling averaging. Behavior is undefined at 1 FPS.

Parameters

[in]	dev	Device descriptor
[in]	enabled	`true` to enable, `false` to disable

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_set_fps()

int amg88xx_set_fps	(	const amg88xx_t *	dev,
		amg88xx_fps_t	fps )

Set the frame rate.

Parameters

[in]	dev	Device descriptor
[in]	fps	Frame rate setting

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_set_interrupt()

int amg88xx_set_interrupt	(	const amg88xx_t *	dev,
		amg88xx_interrupt_mode_t	mode,
		bool	enabled )

Enable or disable the interrupt with the given mode.

Note: Use amg88xx_init_int to initialize the interrupt pin and callback.

Parameters

[in]	dev	Device descriptor
[in]	mode	Interrupt mode (absolute or difference)
[in]	enabled	`true` to enable, `false` to disable

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_set_interrupt_levels()

int amg88xx_set_interrupt_levels	(	const amg88xx_t *	dev,
		int16_t	upper,
		int16_t	lower,
		int16_t	hysteresis )

Set the interrupt threshold levels.

All values are in raw sensor units (0.25 deg C per LSB), using 12-bit sign-magnitude format.

Use amg88xx_temperature_to_raw to convert a temperature in centi-degrees Celsius to a raw value suitable for the upper, lower, and hysteresis parameters.

Note: The interrupt must be enabled with amg88xx_set_interrupt before the thresholds have any effect.

Parameters

[in]	dev	Device descriptor
[in]	upper	Upper threshold level
[in]	lower	Lower threshold level
[in]	hysteresis	Hysteresis level

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_set_mode()

int amg88xx_set_mode	(	amg88xx_t *	dev,
		amg88xx_mode_t	mode )

Set the operating mode.

When transitioning from sleep mode to any other mode, the driver automatically performs the required wake-up sequence (set normal mode, wait 50 ms, initial reset, wait 2 ms, flag reset) as specified by the datasheet.

Note: When the sensor is in sleep mode, all register values are volatile and unreliable.

Parameters

[in]	dev	Device descriptor
[in]	mode	Operating mode

Return values

0	on success
-EIO	on I2C error

◆ amg88xx_temperature_to_raw()

static int16_t amg88xx_temperature_to_raw ( int16_t temperature )

inlinestatic

Convert a temperature in centi-degrees Celsius to a raw pixel value.

This is the inverse of amg88xx_raw_to_temperature. The result can be used with amg88xx_set_interrupt_levels.

Parameters

[in] temperature Temperature in centi-degrees Celsius

Returns: Raw pixel value (0.25 deg C per LSB)

Definition at line 431 of file amg88xx.h.

Detailed Description

Usage

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ AMG88XX_BYTES_PER_FRAME

◆ AMG88XX_BYTES_PER_PIXEL

◆ AMG88XX_PIXELS_COUNT

◆ AMG88XX_PIXELS_HORIZONTAL

◆ AMG88XX_PIXELS_VERTICAL

Typedef Documentation

◆ amg88xx_int_cb_t

Enumeration Type Documentation

◆ amg88xx_fps_t

◆ amg88xx_interrupt_mode_t

◆ amg88xx_mode_t

Function Documentation

◆ amg88xx_clear_status()

◆ amg88xx_get_averaging()

◆ amg88xx_get_fps()

◆ amg88xx_get_frame()

◆ amg88xx_get_interrupt()

◆ amg88xx_get_interrupt_levels()

◆ amg88xx_get_interrupt_table()

◆ amg88xx_get_mode()

◆ amg88xx_get_status()

◆ amg88xx_get_temperature()

◆ amg88xx_init()

◆ amg88xx_init_int()

◆ amg88xx_raw_to_temperature()

◆ amg88xx_set_averaging()

◆ amg88xx_set_fps()

◆ amg88xx_set_interrupt()

◆ amg88xx_set_interrupt_levels()

◆ amg88xx_set_mode()

◆ amg88xx_temperature_to_raw()