RZG Flexible Software Package Documentation  Release v2.1.0

 
HS300X Temperature/Humidity Sensor (rm_hs300x)

Functions

fsp_err_t RM_HS300X_Open (rm_hs300x_ctrl_t *const p_api_ctrl, rm_hs300x_cfg_t const *const p_cfg)
 Opens and configures the HS300X Middle module. Implements rm_hs300x_api_t::open. More...
 
fsp_err_t RM_HS300X_Close (rm_hs300x_ctrl_t *const p_api_ctrl)
 Disables specified HS300X control block. Implements rm_hs300x_api_t::close. More...
 
fsp_err_t RM_HS300X_MeasurementStart (rm_hs300x_ctrl_t *const p_api_ctrl)
 This function should be called when start a measurement and when measurement data is stale data. Sends the slave address to the hs300x and start a measurement. Implements rm_hs300x_api_t::measurementStart. More...
 
fsp_err_t RM_HS300X_Read (rm_hs300x_ctrl_t *const p_api_ctrl, rm_hs300x_raw_data_t *const p_raw_data)
 Reads ADC data from HS300X. Implements rm_hs300x_api_t::read. More...
 
fsp_err_t RM_HS300X_DataCalculate (rm_hs300x_ctrl_t *const p_api_ctrl, rm_hs300x_raw_data_t *const p_raw_data, rm_hs300x_data_t *const p_hs300x_data)
 Calculates humidity [RH] and temperature [Celsius] from ADC data. Implements rm_hs300x_api_t::dataCalculate. More...
 
fsp_err_t RM_HS300X_ProgrammingModeEnter (rm_hs300x_ctrl_t *const p_api_ctrl)
 This function must be called within 10ms after applying power to the sensor. Sends the commands to enter the programming mode. After calling this function, please wait 120us. Implements rm_hs300x_api_t::programmingModeEnter. More...
 
fsp_err_t RM_HS300X_ResolutionChange (rm_hs300x_ctrl_t *const p_api_ctrl, rm_hs300x_data_type_t const data_type, rm_hs300x_resolution_t const resolution)
 This function must be called after calling the RM_HS300X_ProgrammingModeEnter function. Changes the sensor resolution. This function blocks for 120 us software delay plus 9 bytes on the I2C bus. After calling this function, 14ms must be waited. Failure to comply with these times may result in data corruption and introduce errors in sensor measurements. Implements rm_hs300x_api_t::resolutionChange. More...
 
fsp_err_t RM_HS300X_SensorIdGet (rm_hs300x_ctrl_t *const p_api_ctrl, uint32_t *const p_sensor_id)
 This function must be called after calling the RM_HS300X_ProgrammingModeEnter function. Gets the sensor ID. This function blocks for 240 us software delay plus 12 bytes on the I2C bus. Implements rm_hs300x_api_t::sensorIdGet. More...
 
fsp_err_t RM_HS300X_ProgrammingModeExit (rm_hs300x_ctrl_t *const p_api_ctrl)
 This function must be called after calling the RM_HS300X_ProgrammingModeEnter function. This function must be called to return to normal sensor operation and perform measurements. Sends the commands to exit the programming mode. Implements rm_hs300x_api_t::programmingModeExit. More...
 

Detailed Description

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

Overview

Features

The HS300X sensor interface implementation has the following key features:

Configuration

Build Time Configurations for rm_hs300x

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

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.
Data type
  • Both humidity and temperature
  • Humidity only
Both humidity and temperature Select Getting humidity only and both humidity and temperature.
Programming Mode
  • ON
  • OFF
OFF If selected the programming mode can be entered.

Configurations for Sensor > HS300X Temperature/Humidity Sensor (rm_hs300x)

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

ConfigurationOptionsDefaultDescription
NameManual Entryg_hs300x_sensor0 Module name.
CallbackName must be a valid C symbolhs300x_callback A user callback function can be provided.

Pin Configuration

This module use SDA and SCL pins of I2C function.

Usage Notes

HS300x datasheet is here.
If ADC data is valid and calculating humidity and temperature is finished, it is needed to start a measurement again. If ADC data is invalid, it is needed to read ADC data from HS300x again.

If changing the sensor resolution and getting the sensor ID, RM_HS300X_ProgrammingModeEnter function must be called within 10ms after applying power to the sensor. Entering the programming mode takes 120us. Thresore, after calling RM_HS300X_ProgrammingModeEnter function, please wait 120us. After calling RM_HS300X_ResolutionChange function, 14ms must be waited because failure to comply with these times may result in data corruption and introduce errors in sensor measurements.

If an RTOS is used, blocking and bus lock is available.

Bus Initialization

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

Examples

Basic Example

This is a basic example of minimal use of HS300X sensor implementation in an application.

void rm_hs300x_basic_example (void)
{
fsp_err_t err = FSP_SUCCESS;
rm_hs300x_raw_data_t hs300x_raw_data;
rm_hs300x_data_t hs300x_data;
uint8_t calculated_flag = 0;
/* 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_hs300x_cfg.p_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_HS300X_Open(&g_hs300x_ctrl, &g_hs300x_cfg);
/* Handle any errors. This function should be defined by the user. */
handle_error(err);
#if RM_HS300X_CFG_PROGRAMMING_MODE
uint32_t sensor_id;
g_flag = 0;
/* Enter the programming mode. This must be called within 10ms after applying power. */
while (0 == g_flag)
{
/* Wait callback */
}
/* Delay 120us. Entering the programming mode takes 120us. */
/* Get the sensor ID */
RM_HS300X_SensorIdGet(&g_hs300x_ctrl, &sensor_id);
g_flag = 0;
/* Change the humidity resolution */
RM_HS300X_ResolutionChange(&g_hs300x_ctrl, RM_HS300X_HUMIDITY_DATA, RM_HS300X_RESOLUTION_8BIT);
while (0 == g_flag)
{
/* Wait callback */
}
/* Delay 14ms. Failure to comply with these times may result in data corruption and introduce errors in sensor measurements. */
g_flag = 0;
/* Change the temperature resolution */
RM_HS300X_ResolutionChange(&g_hs300x_ctrl, RM_HS300X_TEMPERATURE_DATA, RM_HS300X_RESOLUTION_8BIT);
while (0 == g_flag)
{
/* Wait callback */
}
/* Delay 14ms. Failure to comply with these times may result in data corruption and introduce errors in sensor measurements. */
g_flag = 0;
/* Exit the programming mode */
while (0 == g_flag)
{
/* Wait callback */
}
#endif
while (true)
{
g_flag = 0;
/* Start Measurement */
RM_HS300X_MeasurementStart(&g_hs300x_ctrl);
while (0 == g_flag)
{
/* Wait callback */
}
do
{
g_flag = 0;
/* Read ADC Data from HS300X */
RM_HS300X_Read(&g_hs300x_ctrl, &hs300x_raw_data);
while (0 == g_flag)
{
/* Wait callback */
}
/* Calculate Humidity and Temperatuere values from ADC data */
err = RM_HS300X_DataCalculate(&g_hs300x_ctrl, &hs300x_raw_data, &hs300x_data);
if (FSP_SUCCESS == err)
{
calculated_flag = 1;
}
else if (FSP_ERR_SENSOR_INVALID_DATA == err)
{
/* Stale data */
calculated_flag = 0;
}
else
{
handle_error(err);
}
} while (0 == calculated_flag);
/* Wait 4 seconds. See table 4 on the page 6 of the datasheet. */
}
}

Data Structures

struct  rm_hs300x_programmnig_mode_params_t
 
struct  rm_hs300x_instance_ctrl_t
 

Data Structure Documentation

◆ rm_hs300x_programmnig_mode_params_t

struct rm_hs300x_programmnig_mode_params_t

HS300X programming mode process block

Data Fields
volatile bool enter Enter flag.
volatile bool blocking Blocking flag.
volatile bool communication_finished Communication flag for blocking.
volatile rm_hs300x_event_t event Callback event.

◆ rm_hs300x_instance_ctrl_t

struct rm_hs300x_instance_ctrl_t

HS300x Control Block

Data Fields

uint32_t open
 Open flag.
 
rm_hs300x_cfg_t const * p_cfg
 Pointer to HS300X 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_hs300x_programmnig_mode_params_t programming_mode
 Programming mode flag.
 
uint8_t buf [3]
 Buffer for I2C communications.
 

Function Documentation

◆ RM_HS300X_Open()

fsp_err_t RM_HS300X_Open ( rm_hs300x_ctrl_t *const  p_api_ctrl,
rm_hs300x_cfg_t const *const  p_cfg 
)

Opens and configures the HS300X Middle module. Implements rm_hs300x_api_t::open.

Example:

err = RM_HS300X_Open(&g_hs300x_ctrl, &g_hs300x_cfg);
Return values
FSP_SUCCESSHS300X successfully configured.
FSP_ERR_ASSERTIONNull pointer, or one or more configuration options is invalid.
FSP_ERR_ALREADY_OPENModule is already open. This module can only be opened once.

◆ RM_HS300X_Close()

fsp_err_t RM_HS300X_Close ( rm_hs300x_ctrl_t *const  p_api_ctrl)

Disables specified HS300X control block. Implements rm_hs300x_api_t::close.

Return values
FSP_SUCCESSSuccessfully closed.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_HS300X_MeasurementStart()

fsp_err_t RM_HS300X_MeasurementStart ( rm_hs300x_ctrl_t *const  p_api_ctrl)

This function should be called when start a measurement and when measurement data is stale data. Sends the slave address to the hs300x and start a measurement. Implements rm_hs300x_api_t::measurementStart.

Return values
FSP_SUCCESSSuccessfully started.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_HS300X_Read()

fsp_err_t RM_HS300X_Read ( rm_hs300x_ctrl_t *const  p_api_ctrl,
rm_hs300x_raw_data_t *const  p_raw_data 
)

Reads ADC data from HS300X. Implements rm_hs300x_api_t::read.

Return values
FSP_SUCCESSSuccessfully data decoded.
FSP_ERR_ASSERTIONNull pointer, or one or more configuration options is invalid.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_HS300X_DataCalculate()

fsp_err_t RM_HS300X_DataCalculate ( rm_hs300x_ctrl_t *const  p_api_ctrl,
rm_hs300x_raw_data_t *const  p_raw_data,
rm_hs300x_data_t *const  p_hs300x_data 
)

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

Return values
FSP_SUCCESSSuccessfully data decoded.
FSP_ERR_ASSERTIONNull pointer, or one or more configuration options is invalid.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_SENSOR_INVALID_DATAData is invalid.

◆ RM_HS300X_ProgrammingModeEnter()

fsp_err_t RM_HS300X_ProgrammingModeEnter ( rm_hs300x_ctrl_t *const  p_api_ctrl)

This function must be called within 10ms after applying power to the sensor. Sends the commands to enter the programming mode. After calling this function, please wait 120us. Implements rm_hs300x_api_t::programmingModeEnter.

Return values
FSP_SUCCESSSuccessfully started.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_UNSUPPORTEDProgramming mode is not supported.

◆ RM_HS300X_ResolutionChange()

fsp_err_t RM_HS300X_ResolutionChange ( rm_hs300x_ctrl_t *const  p_api_ctrl,
rm_hs300x_data_type_t const  data_type,
rm_hs300x_resolution_t const  resolution 
)

This function must be called after calling the RM_HS300X_ProgrammingModeEnter function. Changes the sensor resolution. This function blocks for 120 us software delay plus 9 bytes on the I2C bus. After calling this function, 14ms must be waited. Failure to comply with these times may result in data corruption and introduce errors in sensor measurements. Implements rm_hs300x_api_t::resolutionChange.

Return values
FSP_SUCCESSSuccessfully started.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_MODEModule is not entering the programming mode.
FSP_ERR_ABORTEDCommunication is aborted.
FSP_ERR_TIMEOUTCommunication is timeout.
FSP_ERR_UNSUPPORTEDProgramming mode is not supported.

◆ RM_HS300X_SensorIdGet()

fsp_err_t RM_HS300X_SensorIdGet ( rm_hs300x_ctrl_t *const  p_api_ctrl,
uint32_t *const  p_sensor_id 
)

This function must be called after calling the RM_HS300X_ProgrammingModeEnter function. Gets the sensor ID. This function blocks for 240 us software delay plus 12 bytes on the I2C bus. Implements rm_hs300x_api_t::sensorIdGet.

Return values
FSP_SUCCESSSuccessfully started.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_MODEModule is not entering the programming mode.
FSP_ERR_ABORTEDCommunication is aborted.
FSP_ERR_TIMEOUTCommunication is timeout.
FSP_ERR_UNSUPPORTEDProgramming mode is not supported.

◆ RM_HS300X_ProgrammingModeExit()

fsp_err_t RM_HS300X_ProgrammingModeExit ( rm_hs300x_ctrl_t *const  p_api_ctrl)

This function must be called after calling the RM_HS300X_ProgrammingModeEnter function. This function must be called to return to normal sensor operation and perform measurements. Sends the commands to exit the programming mode. Implements rm_hs300x_api_t::programmingModeExit.

Return values
FSP_SUCCESSSuccessfully started.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_INVALID_MODEModule is not entering the programming mode.
FSP_ERR_UNSUPPORTEDProgramming mode is not supported.