j3d1/esp-open-rtos
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
esp-open-rtos/extras/sht3x/sht3x.h
Gunar Schorcht b8c22d2d21 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
2017-10-20 17:18:33 +02:00

250 lines
8.6 KiB
C
Raw Blame History

/*
* 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 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 {
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
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 Start single shot or periodic measurements
*
* The function starts the measurement either in *single shot mode*
* (exactly one measurement) or *periodic mode* (periodic measurements).
*
* 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). 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*
* @return measurement duration given in RTOS ticks or -1 on error
*/
bool sht3x_start_measurement (sht3x_sensor_t* dev, sht3x_mode_t mode);
/**
* @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 with configured 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.
*
* @param dev pointer to sensor device data structure
* @return measurement duration given in RTOS ticks
*/
uint8_t sht3x_get_measurement_duration (sht3x_sensor_t* dev);
/**
* @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 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 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 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_ */
Reference in a new issue View git blame Copy permalink