Files
file	zmod4xxx.h
	zmod4xxx-API functions

file	zmod4xxx_types.h
	zmod4xxx types

Functions
zmod4xxx_err	zmod4xxx_calc_factor (zmod4xxx_conf conf, uint8_t hsp, uint8_t *config)
	Calculate measurement settings. More...

float	zmod4xxx_calc_single_rmox (zmod4xxx_dev_t dev, uint8_t adc_result)
	Calculate mox resistance from ADC raw data. More...

zmod4xxx_err	zmod4xxx_calc_rmox (zmod4xxx_dev_t dev, uint8_t adc_result, float *rmox)
	Calculate mox resistance on array of results. More...

zmod4xxx_err	zmod4xxx_check_error_event (zmod4xxx_dev_t *dev)
	Check the error event of the device. More...

zmod4xxx_err	zmod4xxx_init_measurement (zmod4xxx_dev_t *dev)
	Initialize the sensor for corresponding measurement. More...

zmod4xxx_err	zmod4xxx_init_sensor (zmod4xxx_dev_t *dev)
	Initialize the sensor after power on. More...

zmod4xxx_err	zmod4xxx_null_ptr_check (zmod4xxx_dev_t *dev)
	Check if all function pointers are assigned. More...

zmod4xxx_err	zmod4xxx_prepare_sensor (zmod4xxx_dev_t *dev)
	High-level function to prepare sensor. More...

zmod4xxx_err	zmod4xxx_read_adc_result (zmod4xxx_dev_t dev, uint8_t adc_result)
	Read adc values from the sensor. More...

zmod4xxx_err	zmod4xxx_read_rmox (zmod4xxx_dev_t dev, uint8_t adc_result, float *rmox)
	High-level function to read rmox. More...

zmod4xxx_err	zmod4xxx_read_sensor_info (zmod4xxx_dev_t *dev)
	Read sensor parameter. More...

zmod4xxx_err	zmod4xxx_read_status (zmod4xxx_dev_t dev, uint8_t status)
	Read the status of the device. More...

zmod4xxx_err	zmod4xxx_read_tracking_number (zmod4xxx_dev_t dev, uint8_t track_num)
	Read tracking number of sensor. More...

zmod4xxx_err	zmod4xxx_start_measurement (zmod4xxx_dev_t *dev)
	Start the measurement. More...

zmod4xxx_err	zmod4xxx_start_measurement_at (zmod4xxx_dev_t *dev, uint8_t step)
	Start the measurement at an user-defined sequencer step. More...

Data Structures
struct	zmod4xxx_conf_str
	A single data set for the configuration. More...

struct	zmod4xxx_conf
	Structure to hold the gas sensor module configuration. More...

struct	zmod4xxx_dev_t
	Device structure ZMOD4xxx. More...

Macros
#define	ZMOD4XXX_ADDR_PID (0x00)

#define	ZMOD4XXX_ADDR_CONF (0x20)

#define	ZMOD4XXX_ADDR_PROD_DATA (0x26)

#define	ZMOD4XXX_ADDR_CMD (0x93)

#define	ZMOD4XXX_ADDR_STATUS (0x94)

#define	ZMOD4XXX_ADDR_TRACKING (0x3A)

#define	ZMOD4XXX_LEN_PID (2)

#define	ZMOD4XXX_LEN_CONF (6)

#define	ZMOD4XXX_LEN_TRACKING (6)

#define	HSP_MAX (8)

#define	RSLT_MAX (32)

#define	STATUS_SEQUENCER_RUNNING_MASK (0x80)

#define	STATUS_SLEEP_TIMER_ENABLED_MASK (0x40)

#define	STATUS_ALARM_MASK (0x20)

#define	STATUS_LAST_SEQ_STEP_MASK (0x1F)

#define	STATUS_POR_EVENT_MASK (0x80)

#define	STATUS_ACCESS_CONFLICT_MASK (0x40)

Typedefs
typedef int8_t(*	zmod4xxx_i2c_ptr_t) (uint8_t addr, uint8_t reg_addr, uint8_t *data_buf, uint8_t len)
	function pointer type for i2c access More...

typedef void(*	zmod4xxx_delay_ptr_p) (uint32_t ms)
	function pointer to hardware dependent delay function More...

Enumerations
enum	zmod4xxx_err { ZMOD4XXX_OK = 0, ERROR_INIT_OUT_OF_RANGE, ERROR_GAS_TIMEOUT, ERROR_I2C = -3, ERROR_SENSOR_UNSUPPORTED, ERROR_CONFIG_MISSING, ERROR_ACCESS_CONFLICT, ERROR_POR_EVENT, ERROR_CLEANING, ERROR_NULL_PTR }
	error_codes Error codes More...

Detailed Description

All ZMOD4xxx based gas sensing applications generate their results using algorithm libraries which are computing the desired result from raw data input that is delivered by the gas sensor. An overview of different algorithm implementations is given in ZMOD4xxx Programming Manual - Read Me. The raw sensor data is obtained through the ZMOD4xxx API. This API defines data structures and functions required to configure and operate the sensor. All of these functions work by accessing the sensor through its I2C interface.

As the sensor may be used in arbitrary hardware environments, the ZMOD4xxx API requires a hardware abstraction layer (HAL), providing access to hardware specific functions in a generic way. The HAL minimizes the effort to port a ZMOD4xxx application to a new platform (e.g. MCU). Only the HAL related files need to be provided.

An overview on the relation of the different sensor system components is given in the figure on the Overview section.

HAL API ports to a customer specific hardware require the following function pointers of the Interface_t HAL data structure to be initialized and working as documented:

Function Pointer	Required
i2cRead	Mandatory
i2cWrite	Mandatory
msSleep	Mandatory
reset	Not required

Data Structure Documentation

◆ zmod4xxx_conf_str

struct zmod4xxx_conf_str

A single data set for the configuration.

Data Fields
uint8_t	addr

uint8_t	len

uint8_t *	data_buf

◆ zmod4xxx_conf

struct zmod4xxx_conf

Structure to hold the gas sensor module configuration.

Data Fields
uint8_t	start

zmod4xxx_conf_str	h

zmod4xxx_conf_str	d

zmod4xxx_conf_str	m

zmod4xxx_conf_str	s

zmod4xxx_conf_str	r

uint8_t	prod_data_len

◆ zmod4xxx_dev_t

struct zmod4xxx_dev_t

Device structure ZMOD4xxx.

Data Fields
uint8_t	i2c_addr

uint8_t	config [6]

uint16_t	mox_er

uint16_t	mox_lr

uint16_t	pid

uint8_t *	prod_data

zmod4xxx_i2c_ptr_t	read

zmod4xxx_i2c_ptr_t	write

zmod4xxx_delay_ptr_p	delay_ms

zmod4xxx_conf *	init_conf

zmod4xxx_conf *	meas_conf

Field Documentation

◆ config

uint8_t config[6]

configuration parameter set

◆ delay_ms

zmod4xxx_delay_ptr_p delay_ms

function pointer to delay function

◆ i2c_addr

uint8_t i2c_addr

i2c address of the sensor

◆ init_conf

zmod4xxx_conf* init_conf

pointer to the init configuration

◆ meas_conf

zmod4xxx_conf* meas_conf

pointer to the measurement configuration

◆ mox_er

uint16_t mox_er

sensor specific parameter

◆ mox_lr

uint16_t mox_lr

sensor specific parameter

◆ pid

uint16_t pid

product id of the sensor

◆ prod_data

uint8_t* prod_data

production data

◆ read

zmod4xxx_i2c_ptr_t read

function pointer to i2c read

◆ write

zmod4xxx_i2c_ptr_t write

function pointer to i2c write

Macro Definition Documentation

◆ STATUS_ACCESS_CONFLICT_MASK

#define STATUS_ACCESS_CONFLICT_MASK (0x40)

AccessConflict

◆ STATUS_ALARM_MASK

#define STATUS_ALARM_MASK (0x20)

Alarm

◆ STATUS_LAST_SEQ_STEP_MASK

#define STATUS_LAST_SEQ_STEP_MASK (0x1F)

Last executed sequencer step

◆ STATUS_POR_EVENT_MASK

#define STATUS_POR_EVENT_MASK (0x80)

POR_event

◆ STATUS_SEQUENCER_RUNNING_MASK

#define STATUS_SEQUENCER_RUNNING_MASK (0x80)

Sequencer is running

◆ STATUS_SLEEP_TIMER_ENABLED_MASK

#define STATUS_SLEEP_TIMER_ENABLED_MASK (0x40)

SleepTimer_enabled

Typedef Documentation

◆ zmod4xxx_delay_ptr_p

typedef void(* zmod4xxx_delay_ptr_p) (uint32_t ms)

function pointer to hardware dependent delay function

Parameters

[in] delay in milliseconds

Returns: none

◆ zmod4xxx_i2c_ptr_t

typedef int8_t(* zmod4xxx_i2c_ptr_t) (uint8_t addr, uint8_t reg_addr, uint8_t *data_buf, uint8_t len)

function pointer type for i2c access

Parameters

[in]	addr	7-bit I2C slave address of the ZMOD4xxx
[in]	reg_addr	address of internal register to read/write
[in,out]	data	pointer to the read/write data value
[in]	len	number of bytes to read/write

Returns: error code

Return values

0	success
!= 0	error

Enumeration Type Documentation

◆ zmod4xxx_err

enum zmod4xxx_err

error_codes Error codes

Enumerator
ERROR_INIT_OUT_OF_RANGE	The initialization value is out of range.
ERROR_GAS_TIMEOUT	A previous measurement is running that could not be stopped or sensor does not respond.
ERROR_I2C	I2C communication was not successful.
ERROR_SENSOR_UNSUPPORTED	The Firmware configuration used does not match the sensor module.
ERROR_CONFIG_MISSING	There is no pointer to a valid configuration.
ERROR_ACCESS_CONFLICT	Invalid ADC results due to a still running measurement while results readout.
ERROR_POR_EVENT	Power-on reset event. Check power supply and reset pin.
ERROR_CLEANING	The maximum numbers of cleaning cycles ran on this sensor. Cleaning function has no effect anymore.
ERROR_NULL_PTR	The dev structure did not receive the pointers for I2C read, write and/or delay.

Function Documentation

◆ zmod4xxx_calc_factor()

zmod4xxx_err zmod4xxx_calc_factor	(	zmod4xxx_conf *	conf,
		uint8_t *	hsp,
		uint8_t *	config
	)

Calculate measurement settings.

Parameters

[in]	conf	measurement configuration data
[in]	hsp	heater set point pointer
[in]	config	sensor configuration data pointer

Returns: error code

Return values

0 success

◆ zmod4xxx_calc_rmox()

zmod4xxx_err zmod4xxx_calc_rmox	(	zmod4xxx_dev_t *	dev,
		uint8_t *	adc_result,
		float *	rmox
	)

Calculate mox resistance on array of results.

Note: This is not a generic function. Only use it if indicated in your example program flow.; This function uses zmod4xxx_calc_single_rmox

Parameters

[in]	dev	pointer to the device
[in,out]	adc_result	pointer to the adc results
[in,out]	rmox	pointer to the rmox values

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_calc_single_rmox()

float zmod4xxx_calc_single_rmox	(	zmod4xxx_dev_t *	dev,
		uint8_t *	adc_result
	)

Calculate mox resistance from ADC raw data.

Note: This is not a generic function. Only use it if indicated in your example program flow.

Parameters

[in]	dev	pointer to the device
[in,out]	adc_result	pointer to the adc results

Returns: computed MOX resistance

◆ zmod4xxx_check_error_event()

zmod4xxx_err zmod4xxx_check_error_event ( zmod4xxx_dev_t * dev )

Check the error event of the device.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_init_measurement()

zmod4xxx_err zmod4xxx_init_measurement ( zmod4xxx_dev_t * dev )

Initialize the sensor for corresponding measurement.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!= 0	error

Note: Before calling function, measurement data set has to be passed the dev->meas_conf

◆ zmod4xxx_init_sensor()

zmod4xxx_err zmod4xxx_init_sensor ( zmod4xxx_dev_t * dev )

Initialize the sensor after power on.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!= 0	error

Note: Before calling function, initialization data set has to be passed the dev->init_conf

◆ zmod4xxx_null_ptr_check()

zmod4xxx_err zmod4xxx_null_ptr_check ( zmod4xxx_dev_t * dev )

Check if all function pointers are assigned.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_prepare_sensor()

zmod4xxx_err zmod4xxx_prepare_sensor ( zmod4xxx_dev_t * dev )

High-level function to prepare sensor.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!=0	error

◆ zmod4xxx_read_adc_result()

zmod4xxx_err zmod4xxx_read_adc_result	(	zmod4xxx_dev_t *	dev,
		uint8_t *	adc_result
	)

Read adc values from the sensor.

Parameters

[in]	dev	pointer to the device
[in,out]	adc_result	pointer to the adc results

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_read_rmox()

zmod4xxx_err zmod4xxx_read_rmox	(	zmod4xxx_dev_t *	dev,
		uint8_t *	adc_result,
		float *	rmox
	)

High-level function to read rmox.

Note: This is not a generic function. Only use it if indicated in your example program flow.

Parameters

[in]	dev	pointer to the device
[in,out]	adc_result	pointer to the adc results
[in,out]	rmox	pointer to the rmox values

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_read_sensor_info()

zmod4xxx_err zmod4xxx_read_sensor_info ( zmod4xxx_dev_t * dev )

Read sensor parameter.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!= 0	error

Note: This function must be called once before running other sensor functions.

◆ zmod4xxx_read_status()

zmod4xxx_err zmod4xxx_read_status	(	zmod4xxx_dev_t *	dev,
		uint8_t *	status
	)

Read the status of the device.

Parameters

[in]	dev	pointer to the device
[in,out]	status	pointer to the status variable

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_read_tracking_number()

zmod4xxx_err zmod4xxx_read_tracking_number	(	zmod4xxx_dev_t *	dev,
		uint8_t *	track_num
	)

Read tracking number of sensor.

Note: The buffer pointed to by track_num must be at least 6 bytes long

Parameters

[in]	dev	pointer to the device
[in,out]	track_num	pointer to buffer to store the tracking number

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_start_measurement()

zmod4xxx_err zmod4xxx_start_measurement ( zmod4xxx_dev_t * dev )

Start the measurement.

Parameters

[in] dev pointer to the device

Returns: error code

Return values

0	success
!= 0	error

◆ zmod4xxx_start_measurement_at()

zmod4xxx_err zmod4xxx_start_measurement_at	(	zmod4xxx_dev_t *	dev,
		uint8_t	step
	)

Start the measurement at an user-defined sequencer step.

Parameters

[in]	dev	pointer to the device
[in]	step	sequencer step to start at

Returns: error code

Return values

0	success
!= 0	error

Files

Functions

Data Structures

Macros

Typedefs

Enumerations

Detailed Description

Data Structure Documentation

◆ zmod4xxx_conf_str

Data Fields

◆ zmod4xxx_conf

Data Fields

◆ zmod4xxx_dev_t

Data Fields

Field Documentation

◆ config

◆ delay_ms

◆ i2c_addr

◆ init_conf

◆ meas_conf

◆ mox_er

◆ mox_lr

◆ pid

◆ prod_data

◆ read

◆ write

Macro Definition Documentation

◆ STATUS_ACCESS_CONFLICT_MASK

◆ STATUS_ALARM_MASK

◆ STATUS_LAST_SEQ_STEP_MASK

◆ STATUS_POR_EVENT_MASK

◆ STATUS_SEQUENCER_RUNNING_MASK

◆ STATUS_SLEEP_TIMER_ENABLED_MASK

Typedef Documentation

◆ zmod4xxx_delay_ptr_p

◆ zmod4xxx_i2c_ptr_t

Enumeration Type Documentation

◆ zmod4xxx_err

Function Documentation

◆ zmod4xxx_calc_factor()

◆ zmod4xxx_calc_rmox()

◆ zmod4xxx_calc_single_rmox()

◆ zmod4xxx_check_error_event()

◆ zmod4xxx_init_measurement()

◆ zmod4xxx_init_sensor()

◆ zmod4xxx_null_ptr_check()

◆ zmod4xxx_prepare_sensor()

◆ zmod4xxx_read_adc_result()

◆ zmod4xxx_read_rmox()

◆ zmod4xxx_read_sensor_info()

◆ zmod4xxx_read_status()

◆ zmod4xxx_read_tracking_number()

◆ zmod4xxx_start_measurement()

◆ zmod4xxx_start_measurement_at()