Sensor Box has general interface to collect sensor data and it will benefit the user easy to use.

Currently, these sensors are ported into sensor box as default. Note that the user needs to prepare the H/W for the sensor by yourself.

• HDC1080 - Digital Temperature/Humidity Sensor

Item	Description
Vendor	Texas Instruments
Interface	I2C
Pin-defined	"hdc1050.cpp"

• DS18B20 - 1-Wire Digital Thermometer

Item	Description
Vendor	Maxim
Interface	GPIO
Pin-defined	DS1820_api.cpp

• VL53L0X - Time-of-Flight ranging sensor

Item	Description
Vendor	STMicroelectronics
Interface	I2C
Pin-defined	VL53L0X_api.cpp shutdown_pin

• HPMA215S0-XXX - Particle Sensor

Item	Description
Vendor	Honeywell
Interface	I2C
Pin-defined	HPMA215S0_api.cpp

These are commonly APIs of sensor box.

int SBox_iInit(void);

• Brief

Initialize sensor box

• Parameters

None

• Return

On success, eSErr_None is returned.

On error, other is returned.

int SBox_iUnInit(void);

• Brief

Uninitialize sensor box

• Parameters

None

• Return

On success, eSErr_None is returned.

On error, other is returned.

int SBox_iGetAllData(TSBDataFmt *_ptDataSet);

• Brief

Update all sensors and get all data of sensors

• Parameters

_ptDataSet: the pointer to data buffer that is used to get sensor data back.

• Return

On success, eSErr_None is returned.

On error, other is returned.

Note that each sensor has different data type of sensor data, the user can review sensor_cfg.h to know which sensor has what data type of sensor data.

int SBox_iGetData(int _iModelName, TSBDataFmt *_ptData);

• Brief

Update only one sensor and get data

• Parameters

_iModelName: the index of model name to specify which sensor will be updated.

_ptData: the pointer to data that is used to get sensor data back.

• Return

On success, eSErr_None is returned.

On error, other is returned.

Note that each sensor has different data type of sensor data, the user can review sensor_cfg.h to know which sensor has what data type of sensor data.

These macros are used to get index depended on model name and data name of sensors.

SB_GET_INDEX(model_name);

• Brief

Get the index with the model name of sensor.

• Parameters

model_name: the model name that is defined in the sensor_cfg.h.

• Return

The number is returned.

SB_GET_DATA_INDEX(model_name, data_name);

• Brief

Get the index with the data of sensor.

• Parameters

model_name: the model name that is defined in the sensor_cfg.h.

data_name: the name of sensor data that is defined in the sensor_cfg.h.

• Return

The number is returned.

Please click "Link to source" to get source code of Sensor Box and review the file "README.md" to know how use it.

• Single sensor

#include "mbed.h"
#include <stdio.h>
#include "sbox_api.h"
#include "sbox_dbg.h"
#include "sbox_error.h"

static TSBDataFmt g_atData[eSD_Data_Total];

int main () 
{
    int ret;
    int cnt=0;

    SB_MSG_PRINT("Initialize sensor box...\n\r");

    ret = SBox_iInit();
    if(ret != eSErr_None) {
        SB_MSG_PRINT("API init failed!\n\r");
        SB_MSG_PRINT("[Error]->:%d, str:%s\n\r", ret, Sbox_strErr2str(ret));
        while(1);
    }
    
    while(1) 
    {
        ret = SBox_iGetData(SB_GET_INDEX(SB_MN_HDC1080), g_atData);
        if(ret == eSErr_None) {
            SB_MSG_PRINT("get temp: %.2f\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_HDC1080, SB_HDC1080_DATA1_NAME)].fData);
            SB_MSG_PRINT("get humi: %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_HDC1080, SB_HDC1080_DATA2_NAME)].u16Data);
        }
        else {
             SB_MSG_PRINT("[Error]->:%d, str:%s\n\r", ret, Sbox_strErr2str(ret));
        }

        SB_MSG_PRINT("cnt:%d\n\n\r", cnt++);
        Thread::wait(2000);
    }

    return 0;
}

• Multiple sensors

#include "mbed.h"
#include <stdio.h>
#include "sbox_api.h"
#include "sbox_dbg.h"
#include "sbox_error.h"

static TSBDataFmt g_atData[eSD_Data_Total];

int main () 
{
    int ret;
    int cnt=0;

    SB_MSG_PRINT("Initialize sensor box...\n\r");

    ret = SBox_iInit();
    if(ret != eSErr_None) {
        SB_MSG_PRINT("API init failed!\n\r");
        SB_MSG_PRINT("[Error]->:%d, str:%s\n\r", ret, Sbox_strErr2str(ret));
        while(1);
    }
    
    while(1) 
    {
        ret = SBox_iGetAllData(g_atData);
        if(ret == eSErr_None) {
// HDC 1080
#if defined(SB_MN_HDC1080)
            SB_MSG_PRINT("get temp: %.2f\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_HDC1080, SB_HDC1080_DATA1_NAME)].fData);
            SB_MSG_PRINT("get humi: %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_HDC1080, SB_HDC1080_DATA2_NAME)].u16Data);
#endif

// DS18B20
#if defined(SB_MN_DS18B20)
            SB_MSG_PRINT("get temp1: %.2f\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_DS18B20, SB_DS18B20_DATA1_NAME)].fData);
#if SB_DS18B20_MAX_SENSOR_NUM >= 2
            SB_MSG_PRINT("get temp2: %.2f\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_DS18B20, SB_DS18B20_DATA2_NAME)].fData);
#endif
#if SB_DS18B20_MAX_SENSOR_NUM >= 3
            SB_MSG_PRINT("get temp3: %.2f\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_DS18B20, SB_DS18B20_DATA3_NAME)].fData);
#endif
#endif

// VL53L0X
#if defined(SB_MN_VL53L0X)
            SB_MSG_PRINT("get Middle: %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_VL53L0X, SB_VL53L0X_DATA1_NAME)].u32Data);
            SB_MSG_PRINT("get Right : %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_VL53L0X, SB_VL53L0X_DATA2_NAME)].u32Data);
            SB_MSG_PRINT("get Left  : %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_VL53L0X, SB_VL53L0X_DATA3_NAME)].u32Data);
#endif

// HPMA215S0
#if defined(SB_MN_HPMA215S0)
            SB_MSG_PRINT("get pm2.5: %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_HPMA215S0, SB_HPMA215S0_DATA1_NAME)].u16Data);
            SB_MSG_PRINT("get pm1.0: %d\n\r", g_atData[SB_GET_DATA_INDEX(SB_MN_HPMA215S0, SB_HPMA215S0_DATA2_NAME)].u16Data);
#endif
        }
        else {
             SB_MSG_PRINT("[Error]->:%d, str:%s\n\r", ret, Sbox_strErr2str(ret));
        }

        SB_MSG_PRINT("cnt:%d\n\n\r", cnt++);
        Thread::wait(2000);
    }

    return 0;
}

This chapter is described for how to porting new sensor. The user needs to set configuration, implement HAL instance and sensor driver. Please follow the below in more detailed.

When the user intends to add new sensor into sensor box, the user needs to modify both files "sensor_cfg.h" and "sensor_index.h" located at the folder "sensor_api", then follows the below for how to do.

Step01: Define the model name:

Please define the model name by the macro that is based on naming rule of "SN_MN" + "DRIVER_FOLDER" in the file "sensor_cfg.h".

• "SB_MN_" is fixed string as prefix.
• "DRIVER_FOLDER" is the name of directory of specified sensor driver and it's located at the folder "sensor_driver".

For example as below:

#define SB_MN_HDC1080               Hdc1080

#define SB_MN_DS18B20               Ds18b20

Step02: Define the sensor data:

Please define the name of sensor data by the macro that is based on naming rule of "SB_" + "DRIVER_FOLDER" + "_DATA" + N + "_NAME" in the file "sensor_cfg.h".

• "SB_" is fixed string as prefix.
• "DRIVER_FOLDER" is the name of directory of specified sensor driver and it's located at the folder "sensor_driver".
• "_DATA" is fixed string.
• N is serial number of this sensor that follows the convention 1...N.
• "_NAME" is fixed string as postfix.

#define SB_HDC1080_DATA1_NAME       Temperature

#define SB_HDC1080_DATA2_NAME       Humidity

Step03: Create index with the sensor:

The user needs to modify the file "sensor_index.h" located at the folder "sensor_api" for below steps.

• Add index into "enum ESensorModelNameList"

The index of model name is defined using macro "SB_DEFINE_MN(model_name)". The model name is defined above by the user.

typedef enum ESensorModelNameList
{
// HDC 1080
#if defined(SB_MN_HDC1080)
    SB_DEFINE_MN(SB_MN_HDC1080),
#endif

    SB_DEFINE_MN(Total)
}TSBModelNameList;

• Add index into "enum ESensorDataList"

The index of sensor data is defined using macro "SB_DEFINE_DATA(model_name, sensor_data)". Both model name and sensor data are defined above by the user.

typedef enum ESensorDataList
{
// HDC 1080
#if defined(SB_MN_HDC1080)
    SB_DEFINE_DATA(SB_MN_HDC1080, SB_HDC1080_DATA1_NAME),
    SB_DEFINE_DATA(SB_MN_HDC1080, SB_HDC1080_DATA2_NAME),
#endif

    SB_DEFINE_DATA(Data, Total)
}TSBDataList;

To add new HAL instance, please create the new folder of your own sensor with uppercase in the folder "sensor_driver". The new folder it's called "DRIVER_FOLDER". there are three files include DRIVER_FOLDER_api.h, DRIVER_FOLDER_api.cpp and DRIVER_FOLDER_error.h the user needs to create and put it into the your "DRIVER_FOLDER". The HAL API of sensor box with your own sensor has been implemented by the user. After the instance of HAL API completely, it is added in the array of HAL for initiation. Please also remember to define the error code for your own sensor.

• Define the HAL instance

The user can refer to typedef struct TSensorBoxHal in the "sensor_hal.h" for creating the HAL instance. The HAL instance is defined in the DRIVER_FOLDER_api.cpp. For example, the below is the HAL instance with HDC1080 and the user will see it in the file HDC1080_api.cpp.

TSensorBoxHal gtHDC1080Hal = {
    .SBHal_pfiInit              = HDC1080_iInit,
    .SBHal_pfiUnInit            = HDC1080_iUnInit,
    .SBHal_pfiGetData           = HDC1080_iGetData
};

• Implement HAL API

Depended on your own sensor, please implement HAL APIs in the DRIVER_FOLDER_api.cpp. For example with HDC1080, we have implemented HDC1080_iInit, HDC1080_iUnInit and HDC1080_iGetData in the HDC1080_app.cpp.

• Define error code

Please define the set of error code with your own sensor in the DRIVER_FOLDER_error.h. For example, the below is the set of error code with HDC1080 and you will see it in HDC1080_error.h.

#if defined(SB_MN_HDC1080)
#define SB_ERR_HDC1080_LIST \
        X(eSErr_Hdc1080_Init) \
        X(eSErr_Hdc1080_GetData)
#endif

• Add the set of error code into sensor_error.h

For example, the below is with HDC1080.

#if defined(SB_MN_HDC1080)
#include "HDC1080_error.h"
#endif

Add the set of error into "enum ESensorBoxErrorList"

typedef enum ESensorBoxErrorList
{
    eSErr_None = 0,
    
    // HDC 1080
#if defined(SB_MN_HDC1080)
    SB_ERR_HDC1080_LIST
#endif

    eSErr_Total
}TSensorBoxErrorList;

Note: the user can get the string with specified error code to know what it means by the below API.

const char *Sbox_strErr2str(int _iErr);

_iErr: the number of error code.

• Add HAL instance for initialization

Please align the HAL instance to the array that has elements defined by pointer to typedef struct TSensorBoxHal in function "SBoxHal_iInit" in sbox_hal.cpp. For example, the below is with HDC1080.

// HDC1080
#if defined(SB_MN_HDC1080)
#include "HDC1080_api.h"
#endif

int SBoxHal_iInit(TSensorBoxHal* _atArray[])
{
// HDC1080
#if defined(SB_MN_HDC1080)
    _atArray[SB_GET_INDEX(SB_MN_HDC1080)] = &gtHDC1080Hal;
#endif
    
    return eSErr_None;
}

For various sensors, it needs different sensor driver. please put the sensor driver in your DRIVER_FOLDER. The sensor driver is used for implementation with HAL API. For example, in the directory "sensor_driver/HDC1080/", the user will see the directory "HDC1080.lib" that is sensor driver with HDC1080.