Driver for Sensirion SHT3x temperature and humidity sensor readded (#453)
* Driver for Sensirion SHT3x sensor added This is a driver for Sensirion SHT3x temperature and humidity sensors connected via I2C. This commit is a rebasing and contains some interface changes based on the review from @ourairquality. * SHT3x driver changes Additional include to satisfy the Travis CI test build * SHT3x driver - small changes README.md has been shortened * SHT3x driver - small changes * SHT3x driver - small changes - crc8 lookup table is now static to be held in flash memory - special handling for the timer overflow in sht3x_is_measuring removed - initialization reduced to availability check * SHT3x driver - some small changes - crc8 lookup table is now static to be held in flash memory - special handling for the timer overflow in sht3x_is_measuring removed - some whitespace removed - initialization reduced to availability check * SHT3x driver - some minor changes - lookup tables made const to be held in flash - crc8 computation changed to a non table lookup version - measurement duration is now given in ticks and can be used directly for vTaskDelay (documentation and examples changed accordingly) * SHT3x driver - documentation changed * SHT3x driver - minor correction - number of ticks for measurement duration takes now into account portTICK_PERIOD_MS * SHT3x driver - minor correction - number of ticks for measurement duration takes now into account portTICK_PERIOD_MS * SHT3x driver - minor correction - number of ticks for measurement duration takes now into account portTICK_PERIOD_MS * SHT3x driver - minor correction - number of ticks for measurement duration takes now into account portTICK_PERIOD_MS * SHT3x driver - minor corrections * SHT3x driver - minor corrections * Driver for Sensirion SHT3x sensor added This is a driver for Sensirion SHT3x temperature and humidity sensors connected via I2C. This commit is a rebasing and contains some interface changes based on the review from @ourairquality. SHT3x driver changes - additional include to satisfy the Travis CI test build - README.md has been shortened - special handling for the timer overflow in sht3x_is_measuring removed - some whitespaces removed - crc8 computation changed to a non table lookup version - measurement duration is now given in ticks and can be used directly for vTaskDelay (documentation and examples changed accordingly) - number of ticks for measurement duration takes now into account portTICK_PERIOD_MS - clock stretching disabled on sensor to avoid blocking when data are not ready to read - calculation of maesurement duration adds now one and a half ticks to be sure that measurement duration is not too short - function sht3x_is_measuring is now private and only for internal use, user task has always to use function vTaskDelay to wait for measurement results - function sht3x_is_measuring was simplified and returns now just a boolean value - private function sht3x_reset added which is used to reset the sensor during initialization - active flag in sensor data structure not needed anymore - function sht3_get_raw_data simplified - function sht3x_start_measurement returns now only a boolean - function sht3x_start_measurement does not check anymore whether there is already a measurment running - new function sht3x_get_measurement_duration which returns the measurement duration in ticks for configured repeatability * SHT3x driver minor changes - type sht3x_values_t replaced by separate float values - additional repeatability parameter defined for function sht3x_start_measurement - parameter of function sht3x_get_measurement_duration changed from sht3x_sensort_t to sht3_repeat_t - sensor modes and repeatability levels extended by prefix sht3x_ * SHT3x driver minor changes - new high level function sht3x_measure added, it comprises all three steps to perform one measurement in only one function - example with two sensors removed * SHT3x driver small correction
This commit is contained in:
Gunar Schorcht
Johan Kanflo
parent
5fa48d0298
commit
ac6797e916
7 changed files with 1236 additions and 0 deletions
279
extras/sht3x/sht3x.h
Normal file
279
extras/sht3x/sht3x.h
Normal file
|
|
@ -0,0 +1,279 @@
|
|||
/*
|
||||
* 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_LEVEL_1 // only error messages
|
||||
// #define SHT3x_DEBUG_LEVEL_2 // error and debug messages
|
||||
|
||||
#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_NOK -1
|
||||
|
||||
#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_SEND_STATUS_CMD_FAILED (7 << 8)
|
||||
#define SHT3x_SEND_FETCH_CMD_FAILED (8 << 8)
|
||||
|
||||
#define SHT3x_WRONG_CRC_TEMPERATURE (9 << 8)
|
||||
#define SHT3x_WRONG_CRC_HUMIDITY (10 << 8)
|
||||
|
||||
#define SHT3x_RAW_DATA_SIZE 6
|
||||
|
||||
/**
|
||||
* @brief raw data type
|
||||
*/
|
||||
typedef uint8_t sht3x_raw_data_t [SHT3x_RAW_DATA_SIZE];
|
||||
|
||||
|
||||
/**
|
||||
* @brief possible measurement modes
|
||||
*/
|
||||
typedef enum {
|
||||
sht3x_single_shot = 0, // one single measurement
|
||||
sht3x_periodic_05mps, // periodic with 0.5 measurements per second (mps)
|
||||
sht3x_periodic_1mps, // periodic with 1 measurements per second (mps)
|
||||
sht3x_periodic_2mps, // periodic with 2 measurements per second (mps)
|
||||
sht3x_periodic_4mps, // periodic with 4 measurements per second (mps)
|
||||
sht3x_periodic_10mps // periodic with 10 measurements per second (mps)
|
||||
} sht3x_mode_t;
|
||||
|
||||
|
||||
/**
|
||||
* @brief possible repeatability modes
|
||||
*/
|
||||
typedef enum {
|
||||
sht3x_high = 0,
|
||||
sht3x_medium,
|
||||
sht3x_low
|
||||
} sht3x_repeat_t;
|
||||
|
||||
/**
|
||||
* @brief SHT3x sensor device data structure type
|
||||
*/
|
||||
typedef struct {
|
||||
|
||||
uint32_t error_code; // combined error codes
|
||||
|
||||
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
|
||||
uint32_t meas_start_time; // measurement start time in us
|
||||
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 and
|
||||
* initializes the sensor device.
|
||||
*
|
||||
* @param bus I2C bus at which the 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 High level measurement function
|
||||
*
|
||||
* For convenience this function comprises all three steps to perform
|
||||
* one measurement in only one function:
|
||||
*
|
||||
* 1. Starts a measurement in single shot mode with high reliability
|
||||
* 2. Waits using *vTaskDelay* until measurement results are available
|
||||
* 3. Returns the results in kind of floating point sensor values
|
||||
*
|
||||
* This function is the easiest way to use the sensor. It is most suitable
|
||||
* for users that don't want to have the control on sensor details.
|
||||
*
|
||||
* Please note: The function delays the calling task up to 30 ms to wait for
|
||||
* the the measurement results. This might lead to problems when the function
|
||||
* is called from a software timer callback function.
|
||||
*
|
||||
* @param dev pointer to sensor device data structure
|
||||
* @param temperature returns temperature in degree Celsius
|
||||
* @param humidity returns humidity in percent
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
bool sht3x_measure (sht3x_sensor_t* dev, float* temperature, float* humidity);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Start the measurement in single shot or periodic mode
|
||||
*
|
||||
* The function starts the measurement either in *single shot mode*
|
||||
* (exactly one measurement) or *periodic mode* (periodic measurements)
|
||||
* with given repeatabilty.
|
||||
*
|
||||
* In the *single shot mode*, this function has to be called for each
|
||||
* measurement. The measurement duration 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 has to 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).
|
||||
*
|
||||
* Please note: 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*.
|
||||
*
|
||||
* @param dev pointer to sensor device data structure
|
||||
* @param mode measurement mode, see type *sht3x_mode_t*
|
||||
* @param repeat repeatability, see type *sht3x_repeat_t*
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
bool sht3x_start_measurement (sht3x_sensor_t* dev, sht3x_mode_t mode,
|
||||
sht3x_repeat_t repeat);
|
||||
|
||||
/**
|
||||
* @brief Get the duration of a measurement in RTOS ticks.
|
||||
*
|
||||
* The function returns the duration in RTOS ticks required by the sensor to
|
||||
* perform a measurement for the given repeatability. Once a measurement is
|
||||
* started with function *sht3x_start_measurement* the user task can use this
|
||||
* duration in RTOS ticks directly to wait with function *vTaskDelay* until
|
||||
* the measurement results can be fetched.
|
||||
*
|
||||
* Please note: The duration only depends on repeatability level. Therefore,
|
||||
* it can be considered as constant for a repeatibility.
|
||||
*
|
||||
* @param repeat repeatability, see type *sht3x_repeat_t*
|
||||
* @return measurement duration given in RTOS ticks
|
||||
*/
|
||||
uint8_t sht3x_get_measurement_duration (sht3x_repeat_t repeat);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Read measurement 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 fails.
|
||||
*
|
||||
* @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 temperature returns temperature in degree Celsius
|
||||
* @param humidity returns humidity in percent
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
bool sht3x_compute_values (sht3x_raw_data_t raw_data,
|
||||
float* temperature, float* humidity);
|
||||
|
||||
|
||||
/**
|
||||
* @brief Get measurement results in form of sensor values
|
||||
*
|
||||
* The function combines function *sht3x_read_raw_data* and function
|
||||
* *sht3x_compute_values* to get the measurement results.
|
||||
*
|
||||
* In case that there are no results that can be read, the function fails.
|
||||
*
|
||||
* @param dev pointer to sensor device data structure
|
||||
* @param temperature returns temperature in degree Celsius
|
||||
* @param humidity returns humidity in percent
|
||||
* @return true on success, false on error
|
||||
*/
|
||||
bool sht3x_get_results (sht3x_sensor_t* dev,
|
||||
float* temperature, float* humidity);
|
||||
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* DRIVER_SHT3x_H_ */
|
||||
Loading…
Add table
Add a link
Reference in a new issue