261 lines
9 KiB
C
261 lines
9 KiB
C
/*
|
|
* Driver for Sensirion SHT3x digital temperature and humidity sensor
|
|
* connected to I2C
|
|
*
|
|
* Part of esp-open-rtos
|
|
*
|
|
* ----------------------------------------------------------------
|
|
*
|
|
* The BSD License (3-clause license)
|
|
*
|
|
* Copyright (c) 2017 Gunar Schorcht (https://github.com/gschorcht
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright notice,
|
|
* this list of conditions and the following disclaimer.
|
|
*
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* 3. Neither the name of the copyright holder nor the names of its
|
|
* contributors may be used to endorse or promote products derived from this
|
|
* software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
#ifndef DRIVER_SHT3x_H_
|
|
#define DRIVER_SHT3x_H_
|
|
|
|
#include "stdint.h"
|
|
#include "stdbool.h"
|
|
|
|
#include "FreeRTOS.h"
|
|
|
|
#include "i2c/i2c.h"
|
|
|
|
// Uncomment to enable debug output
|
|
// #define SHT3x_DEBUG
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
// definition of possible I2C slave addresses
|
|
#define SHT3x_ADDR_1 0x44 // ADDR pin connected to GND/VSS (default)
|
|
#define SHT3x_ADDR_2 0x45 // ADDR pin connected to VDD
|
|
|
|
// definition of error codes
|
|
#define SHT3x_OK 0
|
|
|
|
#define SHT3x_I2C_ERROR_MASK 0x000f
|
|
#define SHT3x_DRV_ERROR_MASK 0xfff0
|
|
|
|
// error codes for I2C interface ORed with SHT3x error codes
|
|
#define SHT3x_I2C_READ_FAILED 1
|
|
#define SHT3x_I2C_SEND_CMD_FAILED 2
|
|
#define SHT3x_I2C_BUSY 3
|
|
|
|
// SHT3x driver error codes OR ed with error codes for I2C interface
|
|
#define SHT3x_MEAS_NOT_STARTED (1 << 8)
|
|
#define SHT3x_MEAS_ALREADY_RUNNING (2 << 8)
|
|
#define SHT3x_MEAS_STILL_RUNNING (3 << 8)
|
|
#define SHT3x_READ_RAW_DATA_FAILED (4 << 8)
|
|
|
|
#define SHT3x_SEND_MEAS_CMD_FAILED (5 << 8)
|
|
#define SHT3x_SEND_RESET_CMD_FAILED (6 << 8)
|
|
#define SHT3x_STATUS_CMD_FAILED (7 << 8)
|
|
|
|
#define SHT3x_WRONG_CRC_TEMPERATURE (8 << 8)
|
|
#define SHT3x_WRONG_CRC_HUMIDITY (9 << 8)
|
|
|
|
#define SHT3x_RAW_DATA_SIZE 6
|
|
|
|
/**
|
|
* @brief raw data type
|
|
*/
|
|
typedef uint8_t sht3x_raw_data_t [SHT3x_RAW_DATA_SIZE];
|
|
|
|
/**
|
|
* @brief sensor values type
|
|
*/
|
|
typedef struct {
|
|
float temperature; // temperature in degree Celcius
|
|
float humidity; // humidity in percent
|
|
} sht3x_values_t;
|
|
|
|
|
|
/**
|
|
* @brief possible measurement modes
|
|
*/
|
|
typedef enum {
|
|
single_shot = 0, // one single measurement
|
|
periodic_05mps, // periodic with 0.5 measurements per second (mps)
|
|
periodic_1mps, // periodic with 1 measurements per second (mps)
|
|
periodic_2mps, // periodic with 2 measurements per second (mps)
|
|
periodic_4mps, // periodic with 4 measurements per second (mps)
|
|
periodic_10mps // periodic with 10 measurements per second (mps)
|
|
} sht3x_mode_t;
|
|
|
|
|
|
/**
|
|
* @brief possible repeatability modes
|
|
*/
|
|
typedef enum {
|
|
high = 0,
|
|
medium,
|
|
low
|
|
} sht3x_repeat_t;
|
|
|
|
/**
|
|
* @brief SHT3x sensor device data structure type
|
|
*/
|
|
typedef struct {
|
|
|
|
bool active; // indicates whether sensor is active
|
|
|
|
uint32_t error_code; //
|
|
|
|
uint8_t bus; // I2C bus at which sensor is connected
|
|
uint8_t addr; // I2C slave address of the sensor
|
|
|
|
sht3x_mode_t mode; // used measurement mode
|
|
sht3x_repeat_t repeatability; // used repeatability
|
|
|
|
bool meas_started; // indicates whether measurement started
|
|
TickType_t meas_start_tick; // measurement start time in RTOS ticks
|
|
bool meas_first; // first measurement in periodic mode
|
|
|
|
} sht3x_sensor_t;
|
|
|
|
|
|
/**
|
|
* @brief Initialize a SHT3x sensor
|
|
*
|
|
* The function creates a data structure describing the sensor device,
|
|
* initializes, probes for the device, and configures the device that is
|
|
* connected at the specified I2C bus with the given slave address.
|
|
*
|
|
* @param bus I2C bus at which sensor is connected
|
|
* @param addr I2C slave address of the sensor
|
|
* @return pointer to sensor data structure, or NULL on error
|
|
*/
|
|
sht3x_sensor_t* sht3x_init_sensor (uint8_t bus, uint8_t addr);
|
|
|
|
|
|
/**
|
|
* @brief Start single shot or periodic measurements
|
|
*
|
|
* The function starts the measurement either in *single shot mode*
|
|
* (exactly one measurement) or *periodic mode* (periodic measurements) and
|
|
* returns an estimated measurement duration given in RTOS ticks.
|
|
*
|
|
* In the *single shot mode*, this function has to be called for each
|
|
* measurement. The measurement duration returned by the function has to be
|
|
* waited every time before the results can be fetched.
|
|
*
|
|
* In the *periodic mode*, this function has to be called only once. Also
|
|
* the measurement duration must be waited only once until the first
|
|
* results are available. After this first measurement, the sensor then
|
|
* automatically performs all subsequent measurements. The rate of periodic
|
|
* measurements can be 10, 4, 2, 1 or 0.5 measurements per second (mps). Due
|
|
* to inaccuracies in timing of the sensor, the user task should fetch the
|
|
* results at a lower rate. The rate of the periodic measurements is defined
|
|
* by the parameter *mode*.
|
|
*
|
|
* On success, the function returns an estimated measurement duration given
|
|
* in RTOS ticks. This defines the duration needed by the sensor before
|
|
* first results become available. The user task has to wait this time
|
|
* before it can fetch the results using function *sht3x_get_results* or
|
|
* *sht3x_get_raw_data*.
|
|
*
|
|
* @param dev pointer to sensor device data structure
|
|
* @param mode measurement mode, see type *sht3x_mode_t*
|
|
* @return measurement duration given in RTOS ticks or -1 on error
|
|
*/
|
|
int32_t sht3x_start_measurement (sht3x_sensor_t* dev, sht3x_mode_t mode);
|
|
|
|
|
|
/**
|
|
* @brief Check whether measurement is still running
|
|
*
|
|
* The function can be used to test whether a measurement has been
|
|
* started and how long it still takes before measurement results
|
|
* become available. The return value is given in RTOS ticks and can be
|
|
*
|
|
* >0 in case the measurement is is still running,
|
|
* 0 in case the measurement has been already finished, or
|
|
* <0 in case of error.
|
|
*
|
|
* That is, a return value greater than 0 indicates that the measurement
|
|
* results are still not available and the user task has to wait that time.
|
|
*
|
|
* @param dev pointer to sensor device data structure
|
|
* @return remaining measurement duration in RTOS ticks or -1 on error
|
|
*/
|
|
int32_t sht3x_is_measuring (sht3x_sensor_t* dev);
|
|
|
|
/**
|
|
* @brief Read the results from sensor as raw data
|
|
*
|
|
* The function read measurement results from the sensor, checks the CRC
|
|
* checksum and stores them in the byte array as following.
|
|
*
|
|
* data[0] = Temperature MSB
|
|
* data[1] = Temperature LSB
|
|
* data[2] = Temperature CRC
|
|
* data[3] = Pressure MSB
|
|
* data[4] = Pressure LSB
|
|
* data[2] = Pressure CRC
|
|
*
|
|
* In case that there are no new data that can be read, the function returns
|
|
* false.
|
|
*
|
|
* @param dev pointer to sensor device data structure
|
|
* @param raw_data byte array in which raw data are stored
|
|
* @return true on success, false on error
|
|
*/
|
|
bool sht3x_get_raw_data(sht3x_sensor_t* dev, sht3x_raw_data_t raw_data);
|
|
|
|
/**
|
|
* @brief Computes sensor values from raw data
|
|
*
|
|
* @param raw_data byte array that contains raw data
|
|
* @param values pointer to data structure in which results are stored
|
|
* @return true on success, false on error
|
|
*/
|
|
bool sht3x_compute_values (sht3x_raw_data_t raw_data,
|
|
sht3x_values_t* values);
|
|
|
|
/**
|
|
* @brief Get the results of latest measurement
|
|
*
|
|
* The function combines function *sht3x_read_raw_data* and function
|
|
* *sht3x_compute_values* to get the latest measurement results.
|
|
*
|
|
* @param dev pointer to sensor device data structure
|
|
* @param values pointer to data structure in which results are stored
|
|
* @return true on success, false on error
|
|
*/
|
|
bool sht3x_get_results (sht3x_sensor_t* dev, sht3x_values_t* values);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* DRIVER_SHT3x_H_ */
|