You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
280 lines
10 KiB
280 lines
10 KiB
/*
|
|
* Driver for Sensirion SHT3x digital temperature and humidity sensor
|
|
* connected to I2C
|
|
*
|
|
* This driver is for the usage with the ESP8266 and FreeRTOS (esp-open-rtos)
|
|
* [https://github.com/SuperHouse/esp-open-rtos]. It is also working with ESP32
|
|
* and ESP-IDF [https://github.com/espressif/esp-idf.git] as well as Linux
|
|
* based systems using a wrapper library for ESP8266 functions.
|
|
*
|
|
* ----------------------------------------------------------------
|
|
*
|
|
* 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 __SHT3x_H__
|
|
#define __SHT3x_H__
|
|
|
|
// Uncomment to enable debug output
|
|
// #define SHT3x_DEBUG_LEVEL_1 // only error messages
|
|
// #define SHT3x_DEBUG_LEVEL_2 // error and debug messages
|
|
|
|
#include "stdint.h"
|
|
#include "stdbool.h"
|
|
|
|
#include "sht3x_platform.h"
|
|
|
|
#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 /* __SHT3x_H__ */
|
|
|