RRH62000 All-in-one Air Quality Module (rm_rrh62000)

Functions
fsp_err_t	RM_RRH62000_Open (rm_air_sensor_ctrl_t *const p_api_ctrl, rm_air_sensor_cfg_t const *const p_cfg)
	Opens and configures the RRH62000 sensor module. If ZMOD cleaning is not complete, this function will take at least 1 minute. Implements rm_air_sensor_api_t::open. More...
fsp_err_t	RM_RRH62000_Close (rm_air_sensor_ctrl_t *const p_api_ctrl)
	This function should be called when close the sensor module. Implements rm_air_sensor_api_t::close. More...
fsp_err_t	RM_RRH62000_StatusCheck (rm_air_sensor_ctrl_t *const p_api_ctrl)
	This function should be called when polling is used. It reads the status of sensor. Implements rm_air_sensor_api_t::statusCheck. More...
fsp_err_t	RM_RRH62000_Read (rm_air_sensor_ctrl_t *const p_api_ctrl, rm_air_sensor_raw_data_t *const p_raw_data)
	This function should be called to get measurement results after measurement finishes. To check measurement status either polling or busy/interrupt pin can be used. Implements rm_air_sensor_api_t::read. More...
fsp_err_t	RM_RRH62000_DataCalculate (rm_air_sensor_ctrl_t *const p_api_ctrl, const rm_air_sensor_raw_data_t *const p_raw_data, rm_air_sensor_data_t *const p_rrh62000_data)
	This function should be called when calculating gas data from measurement results. Implements rm_air_sensor_api_t::dataCalculate. More...
fsp_err_t	RM_RRH62000_FirmwareVersionGet (rm_air_sensor_ctrl_t *const p_api_ctrl, rm_air_sensor_version_t *const p_version)
	This function should be called to get firmware version. Firmware version does not use "patch" of p_version. Implements rm_air_sensor_api_t::firmwareVersionGet. More...
fsp_err_t	RM_RRH62000_AlgorithmVersionGet (rm_air_sensor_ctrl_t *const p_api_ctrl, rm_air_sensor_version_t *const p_version)
	This function should be called to get algorithm version. Implements rm_air_sensor_api_t::algorithmVersionGet. More...

Detailed Description

Middleware to implement the RRH62000 sensor module interface. This module implements the SENSOR Middleware Interface.

Overview

This module provides an API for configuring and controlling the RRH62000 sensor module.

I2C communication with the RRH62000 sensor module is realized by connecting with the rm_comms_i2c module.

Features

The RRH62000 sensor interface implementation has the following key features:

• Initialize the sensor for measurement
• Receive status for wait until the measurement is done.
• Get the measruement results from the sensor module

Configuration

Build Time Configurations for rm_rrh62000

The following build time configurations are defined in fsp_cfg/rm_rrh62000_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Sensor > RRH62000 All-in-one Air Quality Module (rm_rrh62000)

This module can be added to the Stacks tab via New Stack > Sensor > RRH62000 All-in-one Air Quality Module (rm_rrh62000).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rrh62000_sensor0	Module name.
Number of moving average [times]	Value must be 1 or more	10	Set number of moving average. Min = 1 and Max = 60.
Fan speed control [%]	Value must be 60 or more	86	Set fan speed control. Min = 60 and Max = 100.
Comms I2C Callback	Name must be a valid C symbol	rrh62000_comms_i2c_callback	A user COMMS I2C callback function can be provided.

Pin Configuration

This module use SDA and SCL pins of I2C Master, SCI I2C and IICA Master.

Usage Notes

RRH62000 datasheet is here.
When using the sensor for the first time, allow up to 48 hours for re-hydration of the humidity sensor in ambient air and for TVOC sensor conditioning. This will allow the module to take optimal readings. The RRH62000 is an integrated sensor module for the measurement of critical air quality parameters. Sensors for particulate matter (PM), total volatile organic compounds (TVOC), estimation of carbon dioxide (eCO2) optional nitrogen dioxide (NO2), optional ozone (O3), humidity (RH), and temperature (T), are combined in a single package.
If an RTOS is used, blocking and bus lock is available.

• If blocking of an I2C bus is required, it is necessary to create a semaphore for blocking.
• If bus lock is required, it is necessary to create a mutex for bus lock. Bus lock is only available when a semaphore for blocking is used.

Notifications

• After turning on the module for the first time, the sensor will automatically start in ZMOD sensor cleaning mode for 1 minute. Do not cut power to the sensor during this period.
• Interval time needs to be at least 1s after power-on or reset.
• I2C-master access interval for RRH62000 must be longer than 1s.
• This module supports I2C only (not support UART).

Limitations

• I2C Master (r_sau_i2c) is not supported. RRH62000 needs clock stretching, but is not supported by SAU I2C.
• The following commands are currently not supported.
  • SLEEP
  • CLEAN
  • TINTC_H
  • TINTC_L
  • TCLEAN
  • RMOX
  • UID

Bus Initialization

The RRH62000 interface expects a bus instance to be opened before opening any RRH62000 device. The interface will handle switching between devices on the bus but will not open or close the bus instance. The user should open the bus with the appropriate I2C Master Interface open call.

Initialization

Initialize with RM_RRH62000_Open().

From measurement start to data acquisition

An endless loop continuously checks the status of the RRH62000 sensor module and reads its data. The measurement results are subsequently processed, and the air quality values are calculated.

1. Call RM_RRH62000_StatusCheck(). This function will execute a status check over I2C.
2. If RM_AIR_SENSOR_EVENT_MEASUREMENT_NOT_COMPLETE is received in callback, user should wait some time (min=1s) and then call RM_RRH62000_StatusCheck() again.
3. Wait until RM_AIR_SENSOR_EVENT_MEASUREMENT_COMPLETE is received.
4. Call RM_RRH62000_Read() and read the measurement data.
5. Wait until RM_AIR_SENSOR_EVENT_SUCCESS is received.
6. Call RM_RRH62000_DataCalculate().

Examples

Basic Example

These are basic examples of minimal use of RRH62000 sensor implementation in an application.

void rm_rrh62000_basic_example (void)
{
    fsp_err_t                err = FSP_SUCCESS;
    rm_air_sensor_raw_data_t raw_data;
    rm_air_sensor_data_t     rrh62000_data;

    /* Open the I2C bus if it is not already open. */
    rm_comms_i2c_bus_extended_cfg_t * p_extend =
        (rm_comms_i2c_bus_extended_cfg_t *) g_rrh62000_cfg.p_comms_instance->p_cfg->p_extend;
    i2c_master_instance_t * p_driver_instance = (i2c_master_instance_t *) p_extend->p_driver_instance;
    p_driver_instance->p_api->open(p_driver_instance->p_ctrl, p_driver_instance->p_cfg);

#if BSP_CFG_RTOS

    /* Create a semaphore for blocking if a semaphore is not NULL */
    if (NULL != p_extend->p_blocking_semaphore)
    {
 #if BSP_CFG_RTOS == 1                 // AzureOS
        tx_semaphore_create(p_extend->p_blocking_semaphore->p_semaphore_handle,
                            p_extend->p_blocking_semaphore->p_semaphore_name,
                            (ULONG) 0);
 #elif BSP_CFG_RTOS == 2               // FreeRTOS
        *(p_extend->p_blocking_semaphore->p_semaphore_handle) =
            xSemaphoreCreateCountingStatic((UBaseType_t) 1,
                                           (UBaseType_t) 0,
                                           p_extend->p_blocking_semaphore->p_semaphore_memory);
 #endif
    }

    /* Create a recursive mutex for bus lock if a recursive mutex is not NULL */
    if (NULL != p_extend->p_bus_recursive_mutex)
    {
 #if BSP_CFG_RTOS == 1                 // AzureOS
        tx_mutex_create(p_extend->p_bus_recursive_mutex->p_mutex_handle,
                        p_extend->p_bus_recursive_mutex->p_mutex_name,
                        TX_INHERIT);
 #elif BSP_CFG_RTOS == 2               // FreeRTOS
        *(p_extend->p_bus_recursive_mutex->p_mutex_handle) =
            xSemaphoreCreateRecursiveMutexStatic(p_extend->p_bus_recursive_mutex->p_mutex_memory);
 #endif
    }
#endif

    /* Delay 1s after power-on */
    R_BSP_SoftwareDelay(RRH62000_WAIT_1000_MS, BSP_DELAY_UNITS_MILLISECONDS);

    err = RM_RRH62000_Open(&g_rrh62000_ctrl, &g_rrh62000_cfg);

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);

    g_rrh62000_i2c_callback_flag = 0;

    while (1)
    {
        do
        {
            err = RM_RRH62000_StatusCheck(&g_rrh62000_ctrl);
            handle_error(err);
            while (0U == g_rrh62000_i2c_callback_flag)
            {
            }

            g_rrh62000_i2c_callback_flag = 0;

            err = RM_RRH62000_Read(&g_rrh62000_ctrl, &raw_data);
            if (err == FSP_ERR_SENSOR_MEASUREMENT_NOT_FINISHED)
            {
                R_BSP_SoftwareDelay(RRH62000_WAIT_1000_MS, BSP_DELAY_UNITS_MILLISECONDS);
            }
        } while (err == FSP_ERR_SENSOR_MEASUREMENT_NOT_FINISHED);

        handle_error(err);

        while (0U == g_rrh62000_i2c_callback_flag)
        {
        }

        g_rrh62000_i2c_callback_flag = 0;

        err = RM_RRH62000_DataCalculate(&g_rrh62000_ctrl, &raw_data, &rrh62000_data);
        handle_error(err);
    }
}

Data Structures
struct	rm_rrh62000_init_process_params_t
struct	rm_rrh62000_status_params_t
struct	rm_rrh62000_instance_ctrl_t

---

Data Structure Documentation

rm_rrh62000_init_process_params_t

struct rm_rrh62000_init_process_params_t

RRH62000 initialization process block

Data Fields
volatile bool	communication_finished	Communication flag for blocking.
volatile rm_air_sensor_event_t	event	Callback event.

rm_rrh62000_status_params_t

struct rm_rrh62000_status_params_t

RRH62000 status parameters block

Data Fields
uint8_t	value	Value to check measurement complete.
volatile bool	flag	Flag to identify StatusCheck API and other APIs in callback.

rm_rrh62000_instance_ctrl_t

struct rm_rrh62000_instance_ctrl_t

RRH62000 control block

Data Fields
uint32_t	open
	Open flag.
uint8_t	write_buf [2]
	Write buffer for I2C communications.
uint8_t	read_buf [2]
	Read buffer for I2C communications.
uint8_t *	p_read_data
	Pointer to read data. This is used for checking error code and checksum in callback.
uint8_t	read_bytes
	Read bytes. This is used for checking error code and checksum in callback.
volatile rm_air_sensor_event_t	event
	Callback event.
rm_rrh62000_status_params_t	status
	Status parameter for arriving new measurement results.
rm_rrh62000_status_params_t	cleaning_status
	Status parameter for ZMOD cleaning.
rm_rrh62000_init_process_params_t	init_process_params
	For the initialization process.
rm_air_sensor_cfg_t const *	p_cfg
	Pointer of configuration block.
rm_comms_instance_t const *	p_comms_i2c_instance
	Pointer of I2C Communications Middleware instance structure.
void const *	p_context
	Pointer to the user-provided context.
void(*	p_comms_callback )(rm_air_sensor_callback_args_t *p_args)
	I2C Communications callback.

Function Documentation

RM_RRH62000_Open()

fsp_err_t RM_RRH62000_Open	(	rm_air_sensor_ctrl_t *const	p_api_ctrl,
		rm_air_sensor_cfg_t const *const	p_cfg
	)

Opens and configures the RRH62000 sensor module. If ZMOD cleaning is not complete, this function will take at least 1 minute. Implements rm_air_sensor_api_t::open.

Return values

FSP_SUCCESS	RRH62000 successfully configured.
FSP_ERR_ASSERTION	Null pointer, or one or more configuration options is invalid.
FSP_ERR_ALREADY_OPEN	Module is already open. This module can only be opened once.
FSP_ERR_NOT_INITIALIZED	ZMOD cleaning is not complete.

RM_RRH62000_Close()

fsp_err_t RM_RRH62000_Close

(

rm_air_sensor_ctrl_t *const

p_api_ctrl

)

This function should be called when close the sensor module. Implements rm_air_sensor_api_t::close.

Return values

FSP_SUCCESS	Successfully closed.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

RM_RRH62000_StatusCheck()

fsp_err_t RM_RRH62000_StatusCheck

(

rm_air_sensor_ctrl_t *const

p_api_ctrl

)

This function should be called when polling is used. It reads the status of sensor. Implements rm_air_sensor_api_t::statusCheck.

Return values

FSP_SUCCESS	Successfully started.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not opened configured.
FSP_ERR_TIMEOUT	communication is timeout.
FSP_ERR_ABORTED	communication is aborted.

RM_RRH62000_Read()

fsp_err_t RM_RRH62000_Read	(	rm_air_sensor_ctrl_t *const	p_api_ctrl,
		rm_air_sensor_raw_data_t *const	p_raw_data
	)

This function should be called to get measurement results after measurement finishes. To check measurement status either polling or busy/interrupt pin can be used. Implements rm_air_sensor_api_t::read.

Return values

FSP_SUCCESS	Successfully results are read.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not opened configured.
FSP_ERR_TIMEOUT	Communication is timeout.
FSP_ERR_ABORTED	Communication is aborted.

RM_RRH62000_DataCalculate()

fsp_err_t RM_RRH62000_DataCalculate	(	rm_air_sensor_ctrl_t *const	p_api_ctrl,
		const rm_air_sensor_raw_data_t *const	p_raw_data,
		rm_air_sensor_data_t *const	p_rrh62000_data
	)

This function should be called when calculating gas data from measurement results. Implements rm_air_sensor_api_t::dataCalculate.

Return values

FSP_SUCCESS	Successfully gas data is calculated.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not opened configured.

RM_RRH62000_FirmwareVersionGet()

fsp_err_t RM_RRH62000_FirmwareVersionGet	(	rm_air_sensor_ctrl_t *const	p_api_ctrl,
		rm_air_sensor_version_t *const	p_version
	)

This function should be called to get firmware version. Firmware version does not use "patch" of p_version. Implements rm_air_sensor_api_t::firmwareVersionGet.

Return values

FSP_SUCCESS	Successfully results are read.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not opened configured.
FSP_ERR_TIMEOUT	Communication is timeout.
FSP_ERR_ABORTED	Communication is aborted.

RM_RRH62000_AlgorithmVersionGet()

fsp_err_t RM_RRH62000_AlgorithmVersionGet	(	rm_air_sensor_ctrl_t *const	p_api_ctrl,
		rm_air_sensor_version_t *const	p_version
	)

This function should be called to get algorithm version. Implements rm_air_sensor_api_t::algorithmVersionGet.

Return values

FSP_SUCCESS	Successfully results are read.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not opened configured.
FSP_ERR_TIMEOUT	Communication is timeout.
FSP_ERR_ABORTED	Communication is aborted.