HS400X Temperature/Humidity Sensor (rm_hs400x)

Functions
fsp_err_t	RM_HS400X_Open (rm_hs400x_ctrl_t *const p_api_ctrl, rm_hs400x_cfg_t const *const p_cfg)
	Opens and configures the HS400X middleware module. Implements rm_hs400x_api_t::open. More...
fsp_err_t	RM_HS400X_Close (rm_hs400x_ctrl_t *const p_api_ctrl)
	Disables specified HS400X control block. Implements rm_hs400x_api_t::close. More...
fsp_err_t	RM_HS400X_MeasurementStart (rm_hs400x_ctrl_t *const p_api_ctrl)
	This function should be called when start one shot measurement. Sends the command of measurement to HS400X and start a measurement. This function supports No-Hold measurement and Periodic measurement only. If Hold measurement is enabled, please call RM_HS400X_Read() without calling this function. In Periodic measurement, if the periodic measurement has already run, RM_HS400X_EVENT_ERROR is received in callback because HS400x device replies with NACK. Implements rm_hs400x_api_t::measurementStart. More...
fsp_err_t	RM_HS400X_MeasurementStop (rm_hs400x_ctrl_t *const p_api_ctrl)
	Stop a periodic measurement. Sends the command of stopping periodic measurement to HS400X. This function supports periodic measurement only. If a periodic measurement is not running, RM_HS400X_EVENT_ERROR is received in callback because HS400x device replies with NACK. Implements rm_hs400x_api_t::measurementStop. More...
fsp_err_t	RM_HS400X_Read (rm_hs400x_ctrl_t *const p_api_ctrl, rm_hs400x_raw_data_t *const p_raw_data)
	Reads ADC data from HS400X. If Hold measurement is enabled, HS400X holds the SCL line low during the measurement and releases the SCL line when the measurement is complete. If No-Hold measurement is enabled and the measurement result is not ready, RM_HS400X_EVENT_MEASUREMENT_NOT_COMPLETE is received in callback. Implements rm_hs400x_api_t::read. More...
fsp_err_t	RM_HS400X_DataCalculate (rm_hs400x_ctrl_t *const p_api_ctrl, rm_hs400x_raw_data_t *const p_raw_data, rm_hs400x_data_t *const p_hs400x_data)
	Calculates temperature [Celsius] and humidity [RH] from ADC data. Implements rm_hs400x_api_t::dataCalculate. More...

Detailed Description

Middleware to implement the HS400X sensor interface. This module implements the HS400X Middleware Interface.

Overview

Features

The HS400X sensor interface implementation has the following key features:

• Starting a measurement at any time
• Selecting one shot or a periodic measurement
• Getting ADC data from the sensor
• Calculating humidity and temperature value from getting ADC data

Limitations

• Alert feature is not supported. It will be supported in the future.
• I2C Master (r_sau_i2c) is not supported. Please refer to Limitations of I2C Master (r_sau_i2c)

Notifications

The minimum frequency for the SCL clock in Hold measurement is 200kHz. Please configure I2C_MASTER_RATE_FAST or I2C_MASTER_RATE_FASTPLUS to "Rate" in I2C Master (r_iic_master) or I2C Master (r_sci_i2c).

Configuration

Build Time Configurations for rm_hs400x

The following build time configurations are defined in fsp_cfg/rm_hs400x_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.
Measurement Type	Hold Measurement No-Hold Measurement Periodic Measurement	No-Hold Measurement	Select measurement type.
Data type	Both humidity and temperature Temperature only	Both humidity and temperature	Select getting temperature only or both humidity and temperature.

Configurations for Sensor > HS400X Temperature/Humidity Sensor (rm_hs400x)

This module can be added to the Stacks tab via New Stack > Sensor > HS400X Temperature/Humidity Sensor (rm_hs400x).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_hs400x_sensor0	Module name.
Temperature Resolution	8-bit 10-bit 12-bit 14-bit	14-bit	Set resolution of temperature.
Humidity Resolution	8-bit 10-bit 12-bit 14-bit	14-bit	Set resolution of humidity.
Frequency for Periodic Measurement	0.4Hz 1Hz 2Hz	1Hz	Set frequency for periodic measurement.
Comms I2C Callback	Name must be a valid C symbol	hs400x_comms_i2c_callback	A user COMMS I2C callback function can be provided.

Pin Configuration

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

Usage Notes

HS400x datasheet is here.
This module supports three measurement type :

• Hold measurement
• No-Hold measurement
• Periodic measurement

Hold and no-hold measurements also support measuring temperature data only. However, a periodic measurement only supports measuring both humidity and temperature data.

Hold Measurement

A hold measurement sequence consists of the following steps.

1. Wake up the HS400x series sensor from sleep mode by sending its I2C address with a write bit, and initiate a measurement by sending the desired hold measurement command.
2. Change the direction of communication by sending a start bit, the HS400x I2C address, and a read bit. The SCL line is held low by the sensor during the measurement process, which prevents the master from initiating any communications with other slaves on the bus.
3. Once the requested measurement is completed by the HS400x series sensor, the SCL line is released and the chip waits for the SCL clock signal to send the results. The sensor will then transmit the requested measurement data on the bus for the master to capture.

No-Hold Measurement

A no-hold measurement sequence consists of the following steps.

1. Wake up the HS400x series sensor from sleep mode by sending its I2C address with a write bit, and initiate a measurement by sending the desired no-hold measurement command.
2. To read the result from the HS400x series sensor, the master has to send the chip its I2C address and a read bit. If the measurement is completed and the result is ready, the chip will send an ACK bit and starts to send the result over the bus. If the measurement is still in progress, the chip will send a NACK bit and the master will need to try to read the result again.

Periodic Measurement

The HS400x sensors can also be configured to measure at regular intervals without user intervention. In this mode, the user can read the latest relative humidity / temperature data by issuing a data fetch sequence, which consists of sending the HS400x I2C address with a read bit. The sensor will then send the latest measurement result over the I2C bus.
When the periodic measurement mode is active, the only commands the chip will respond to are the data fetch command, and a command to stop the periodic measurements. The command to stop periodic measurements is issued by sending the I2C address with a write bit, followed by the command 0x30. Sequence to Stop Periodic Measurements. Once the periodic measurements have been stopped, the chip returns to sleep and is ready to accept all valid I2C commands.

Bus Initialization

The HS400X interface expects a I2C bus instance to be opened before opening any I2C 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.

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.

Initialization

Initialize with RM_HS400X_Open().

From measurement start to data acquisition

After normal completion, start the each measurement.

Hold Measurement

In hold measurement, the HS400x series sensor holds the SCL line low during the measurement and releases the SCL line when the measurement is complete.

1. Call RM_HS400X_Read(). This function will start a measurement and read the ADC data.
2. Wait until RM_HS400X_EVENT_SUCCESS is received.
3. Call RM_HS400X_DataCalculate(). This function will calculate temperature and humidity data from the ADC data.

No-Hold Measurement

In no-hold measurement, the HS400x series sensor does not hold the SCL line low, and the master is free to initiate communication with other slaves while the chip is performing the measurement.

1. Call RM_HS400X_MeasurementStart(). This function will start a measurement.
2. Wait until RM_HS400X_EVENT_SUCCESS is received.
3. Call RM_HS400X_Read(). This function will read the ADC data.
4. If the measurement result is not ready, RM_HS400X_EVENT_MEASUREMENT_NOT_COMPLETE is received in callback. User should call RM_HS400X_Read() again. If the measurement is completed, RM_HS400X_EVENT_SUCCESS is received in callback.
5. Wait until RM_HS400X_EVENT_SUCCESS is received.
6. Call RM_HS400X_DataCalculate(). This function will calculate temperature and humidity data from the ADC data.

Periodic Measurement

In periodic measurement, the HS400x sensors measure at regular intervals without user intervention. If a periodic measurement is running, the resolution and the frequency cannot be changed. please stop the periodic measurement with RM_HS400X_MeasurementStop().

1. Call RM_HS400X_MeasurementStart(). This function will start a measurement. If the function is called once, a second call is not required.
2. Wait until RM_HS400X_EVENT_SUCCESS is received.
3. Wait for frequency for periodic measurement.
4. Call RM_HS400X_Read(). This function will read the ADC data.
5. Wait until RM_HS400X_EVENT_SUCCESS is received.
6. Call RM_HS400X_DataCalculate(). This function will calculate temperature and humidity data from the ADC data.

Examples

Basic Example

This is a basic examples of minimal use of HS400X sensor implementation in an application.

void rm_hs400x_basic_example (void)
{
    fsp_err_t            err = FSP_SUCCESS;
    rm_hs400x_raw_data_t hs400x_raw_data;
    rm_hs400x_data_t     hs400x_data;
    bool                 measurement_complete = false;
    bool                 calculated           = false;

    /* 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_hs400x_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


    err = RM_HS400X_Open(&g_hs400x_ctrl, &g_hs400x_cfg);


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

#if 3 == RM_HS400X_CFG_MEASUREMENT_TYPE // Periodic Measurement
    g_flag = 0;

    /* Start a periodic measurement */
    RM_HS400X_MeasurementStart(&g_hs400x_ctrl);
    while (0 == g_flag)
    {
        /* Wait callback */
    }
#endif

    while (true)
    {
#if 2 == RM_HS400X_CFG_MEASUREMENT_TYPE // No-Hold Measurement
        g_flag = 0;

        /* Start one shot measurement */
        RM_HS400X_MeasurementStart(&g_hs400x_ctrl);
        while (0 == g_flag)
        {
            /* Wait callback */
        }

#elif 3 == RM_HS400X_CFG_MEASUREMENT_TYPE // Periodic Measurement

        /* Wait Periodic measurement period. See table 12 on the page 20 of the datasheet. */
        switch (g_hs400x_cfg.frequency)
        {
            case RM_HS400X_PERIODIC_MEASUREMENT_FREQUENCY_2HZ:
                R_BSP_SoftwareDelay(500, BSP_DELAY_UNITS_MILLISECONDS);
                break;

            case RM_HS400X_PERIODIC_MEASUREMENT_FREQUENCY_1HZ:
                R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_SECONDS);
                break;

            case RM_HS400X_PERIODIC_MEASUREMENT_FREQUENCY_0P4HZ:
                R_BSP_SoftwareDelay(2500, BSP_DELAY_UNITS_MILLISECONDS);
                break;

            default:
                assert(false);
                break;
        }
#else
#endif

        do
        {
            do
            {
                g_flag = 0;

                /* Read ADC Data from HS400X */
                RM_HS400X_Read(&g_hs400x_ctrl, &hs400x_raw_data);
                while (0 == g_flag)
                {
                    /* Wait callback */
                }

#if 2 == RM_HS400X_CFG_MEASUREMENT_TYPE // No-Hold Measurement
                if (RM_HS400X_EVENT_MEASUREMENT_NOT_COMPLETE == g_hs400x_event)
                {
                    /* RM_HS400X_EVENT_MEASUREMENT_NOT_COMPLETE is received */
                    measurement_complete = false;
                }
                else
                {
                    /* RM_HS400X_EVENT_SUCCESS is received. */
                    measurement_complete = true;
                }

#else
                measurement_complete = true;
#endif
            } while (false == measurement_complete);

            /* Calculate Humidity and Temperature values from ADC data */
            err = RM_HS400X_DataCalculate(&g_hs400x_ctrl, &hs400x_raw_data, &hs400x_data);
            if (FSP_SUCCESS == err)
            {
                calculated = true;
            }
            else if (FSP_ERR_SENSOR_INVALID_DATA == err)
            {
                /* CRC error */
                calculated = false;
            }
            else
            {
                handle_error(err);
            }
        } while (false == calculated);
    }
}

Data Structures
struct	rm_hs400x_init_process_params_t
struct	rm_hs400x_instance_ctrl_t

---

Data Structure Documentation

rm_hs400x_init_process_params_t

struct rm_hs400x_init_process_params_t

HS400X initialization process block

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

rm_hs400x_instance_ctrl_t

struct rm_hs400x_instance_ctrl_t

HS400x Control Block

Data Fields
uint32_t	open
	Open flag.
rm_hs400x_cfg_t const *	p_cfg
	Pointer to HS400X Configuration.
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.
rm_hs400x_init_process_params_t	init_process_params
	For the initialization process.
uint8_t	resolution_register
	Register for temperature and humidity measurement resolution settings.
uint8_t	periodic_measurement_register [2]
	Register for periodic measurement settings.
volatile bool	periodic_measurement_stop
	Flag for stop of periodic measurement.
volatile bool	no_hold_measurement_read
	Flag for data read of No-Hold measurement.
uint8_t	write_buf [18]
	Buffer for data write.
void(*	p_comms_callback )(rm_hs400x_callback_args_t *p_args)
	I2C Communications callback.

Function Documentation

RM_HS400X_Open()

fsp_err_t RM_HS400X_Open	(	rm_hs400x_ctrl_t *const	p_api_ctrl,
		rm_hs400x_cfg_t const *const	p_cfg
	)

Opens and configures the HS400X middleware module. Implements rm_hs400x_api_t::open.

Example:

    err = RM_HS400X_Open(&g_hs400x_ctrl, &g_hs400x_cfg);

Return values

FSP_SUCCESS	HS400X 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_TIMEOUT	communication is timeout.
FSP_ERR_ABORTED	communication is aborted.

RM_HS400X_Close()

fsp_err_t RM_HS400X_Close

(

rm_hs400x_ctrl_t *const

p_api_ctrl

)

Disables specified HS400X control block. Implements rm_hs400x_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_HS400X_MeasurementStart()

fsp_err_t RM_HS400X_MeasurementStart

(

rm_hs400x_ctrl_t *const

p_api_ctrl

)

This function should be called when start one shot measurement. Sends the command of measurement to HS400X and start a measurement. This function supports No-Hold measurement and Periodic measurement only. If Hold measurement is enabled, please call RM_HS400X_Read() without calling this function. In Periodic measurement, if the periodic measurement has already run, RM_HS400X_EVENT_ERROR is received in callback because HS400x device replies with NACK. Implements rm_hs400x_api_t::measurementStart.

Return values

FSP_SUCCESS	Successfully started.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_TIMEOUT	communication is timeout.
FSP_ERR_ABORTED	communication is aborted.
FSP_ERR_UNSUPPORTED	Hold measurement is unsupported.

RM_HS400X_MeasurementStop()

fsp_err_t RM_HS400X_MeasurementStop

(

rm_hs400x_ctrl_t *const

p_api_ctrl

)

Stop a periodic measurement. Sends the command of stopping periodic measurement to HS400X. This function supports periodic measurement only. If a periodic measurement is not running, RM_HS400X_EVENT_ERROR is received in callback because HS400x device replies with NACK. Implements rm_hs400x_api_t::measurementStop.

Return values

FSP_SUCCESS	Successfully started.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_TIMEOUT	communication is timeout.
FSP_ERR_ABORTED	communication is aborted.
FSP_ERR_UNSUPPORTED	Hold and No-Hold measurement are unsupported.

RM_HS400X_Read()

fsp_err_t RM_HS400X_Read	(	rm_hs400x_ctrl_t *const	p_api_ctrl,
		rm_hs400x_raw_data_t *const	p_raw_data
	)

Reads ADC data from HS400X. If Hold measurement is enabled, HS400X holds the SCL line low during the measurement and releases the SCL line when the measurement is complete. If No-Hold measurement is enabled and the measurement result is not ready, RM_HS400X_EVENT_MEASUREMENT_NOT_COMPLETE is received in callback. Implements rm_hs400x_api_t::read.

Return values

FSP_SUCCESS	Successfully data decoded.
FSP_ERR_ASSERTION	Null pointer, or one or more configuration options is invalid.
FSP_ERR_TIMEOUT	communication is timeout.
FSP_ERR_ABORTED	communication is aborted.
FSP_ERR_NOT_OPEN	Module is not open.

RM_HS400X_DataCalculate()

fsp_err_t RM_HS400X_DataCalculate	(	rm_hs400x_ctrl_t *const	p_api_ctrl,
		rm_hs400x_raw_data_t *const	p_raw_data,
		rm_hs400x_data_t *const	p_hs400x_data
	)

Calculates temperature [Celsius] and humidity [RH] from ADC data. Implements rm_hs400x_api_t::dataCalculate.

Return values

FSP_SUCCESS	Successfully data decoded.
FSP_ERR_ASSERTION	Null pointer, or one or more configuration options is invalid.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_SENSOR_INVALID_DATA	Data is invalid.