esp-open-rtos/extras/sht3x/sht3x.h

/*
 * 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__ */