ZMOD4510 Ultra-Low Power Ozone Firmware Documentation |

Files | Functions | Data Structures | Macros | Typedefs | Enumerations
ZMOD4xxx Sensor API

## 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