adafruit_sht31d.py

# The MIT License (MIT)
#
# Copyright (c) 2017 Jerry Needell
# Copyright (c) 2019 Llewelyn Trahaearn
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
"""
`adafruit_sht31d`
====================================================

This is a CircuitPython driver for the SHT31-D temperature and humidity sensor.

* Author(s): Jerry Needell, Llewelyn Trahaearn

Implementation Notes
--------------------

**Hardware:**

* Adafruit `Sensiron SHT31-D Temperature & Humidity Sensor Breakout
  <https://www.adafruit.com/product/2857>`_ (Product ID: 2857)

**Software and Dependencies:**

* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
  https://github.com/adafruit/circuitpython/releases
* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
"""

# imports
try:
    import struct
except ImportError:
    import ustruct as struct

import time

from micropython import const
from adafruit_bus_device.i2c_device import I2CDevice

__version__ = "0.0.0-auto.0"
__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_SHT31D.git"


_SHT31_DEFAULT_ADDRESS = const(0x44)
_SHT31_SECONDARY_ADDRESS = const(0x45)

_SHT31_ADDRESSES = (_SHT31_DEFAULT_ADDRESS, _SHT31_SECONDARY_ADDRESS)

_SHT31_READSERIALNBR = const(0x3780)
_SHT31_READSTATUS = const(0xF32D)
_SHT31_CLEARSTATUS = const(0x3041)
_SHT31_HEATER_ENABLE = const(0x306D)
_SHT31_HEATER_DISABLE = const(0x3066)
_SHT31_SOFTRESET = const(0x30A2)
_SHT31_NOSLEEP = const(0x303E)
_SHT31_PERIODIC_FETCH = const(0xE000)
_SHT31_PERIODIC_BREAK = const(0x3093)

MODE_SINGLE = 'Single'
MODE_PERIODIC = 'Periodic'

_SHT31_MODES = (MODE_SINGLE, MODE_PERIODIC)

REP_HIGH = 'High'
REP_MED = 'Medium'
REP_LOW = 'Low'

_SHT31_REP = (REP_HIGH, REP_MED, REP_LOW)

FREQUENCY_0_5 = 0.5
FREQUENCY_1 = 1
FREQUENCY_2 = 2
FREQUENCY_4 = 4
FREQUENCY_10 = 10

_SHT31_FREQUENCIES = (FREQUENCY_0_5, FREQUENCY_1, FREQUENCY_2, FREQUENCY_4, FREQUENCY_10)

_SINGLE_COMMANDS = ((REP_LOW, const(False), const(0x2416)),
                    (REP_MED, const(False), const(0x240B)),
                    (REP_HIGH, const(False), const(0x2400)),
                    (REP_LOW, const(True), const(0x2C10)),
                    (REP_MED, const(True), const(0x2C0D)),
                    (REP_HIGH, const(True), const(0x2C06)))

_PERIODIC_COMMANDS = ((True, None, const(0x2B32)),
                      (REP_LOW, FREQUENCY_0_5, const(0x202F)),
                      (REP_MED, FREQUENCY_0_5, const(0x2024)),
                      (REP_HIGH, FREQUENCY_0_5, const(0x2032)),
                      (REP_LOW, FREQUENCY_1, const(0x212D)),
                      (REP_MED, FREQUENCY_1, const(0x2126)),
                      (REP_HIGH, FREQUENCY_1, const(0x2130)),
                      (REP_LOW, FREQUENCY_2, const(0x222B)),
                      (REP_MED, FREQUENCY_2, const(0x2220)),
                      (REP_HIGH, FREQUENCY_2, const(0x2236)),
                      (REP_LOW, FREQUENCY_4, const(0x2329)),
                      (REP_MED, FREQUENCY_4, const(0x2322)),
                      (REP_HIGH, FREQUENCY_4, const(0x2334)),
                      (REP_LOW, FREQUENCY_10, const(0x272A)),
                      (REP_MED, FREQUENCY_10, const(0x2721)),
                      (REP_HIGH, FREQUENCY_10, const(0x2737)))

_DELAY = ((REP_LOW, .0045),
          (REP_MED, .0065),
          (REP_HIGH, .0155))


def _crc(data):
    crc = 0xff
    for byte in data:
        crc ^= byte
        for _ in range(8):
            if crc & 0x80:
                crc <<= 1
                crc ^= 0x131
            else:
                crc <<= 1
    return crc

def _unpack(data):
    length = len(data)
    crc = [None] * (length//3)
    word = [None] * (length//3)
    for i in range(length//6):
        word[i*2], crc[i*2], word[(i*2)+1], crc[(i*2)+1] = struct.unpack('>HBHB', data[i*6:(i*6)+6])
        if crc[i*2] == _crc(data[i*6:(i*6)+2]):
            length = (i+1)*6
    for i in range(length//3):
        if crc[i] != _crc(data[i*3:(i*3)+2]):
            raise RuntimeError("CRC mismatch")
    return word[:length//3]


class SHT31D:
    """
    A driver for the SHT31-D temperature and humidity sensor.

    :param i2c_bus: The `busio.I2C` object to use. This is the only required parameter.
    :param int address: (optional) The I2C address of the device.
    """
    def __init__(self, i2c_bus, address=_SHT31_DEFAULT_ADDRESS):
        if address not in _SHT31_ADDRESSES:
            raise ValueError('Invalid address: 0x%x' % (address))
        self.i2c_device = I2CDevice(i2c_bus, address)
        self._mode = MODE_SINGLE
        self._repeatability = REP_HIGH
        self._frequency = FREQUENCY_4
        self._clock_stretching = False
        self._art = False
        self._last_read = 0
        self._cached_temperature = None
        self._cached_humidity = None
        self._reset()

    def _command(self, command):
        with self.i2c_device as i2c:
            i2c.write(struct.pack('>H', command))

    def _reset(self):
        """
        Soft reset the device
        The reset command is preceded by a break command as the
        device will not respond to a soft reset when in 'Periodic' mode.
        """
        self._command(_SHT31_PERIODIC_BREAK)
        time.sleep(.001)
        self._command(_SHT31_SOFTRESET)
        time.sleep(.0015)

    def _periodic(self):
        for command in _PERIODIC_COMMANDS:
            if self.art == command[0] or \
            (self.repeatability == command[0] and self.frequency == command[1]):
                self._command(command[2])
                time.sleep(.001)
                self._last_read = 0

    def _data(self):
        if self.mode == MODE_PERIODIC:
            data = bytearray(48)
            data[0] = 0xff
            self._command(_SHT31_PERIODIC_FETCH)
            time.sleep(.001)
        elif self.mode == MODE_SINGLE:
            data = bytearray(6)
            data[0] = 0xff
            for command in _SINGLE_COMMANDS:
                if self.repeatability == command[0] and self.clock_stretching == command[1]:
                    self._command(command[2])
            if not self.clock_stretching:
                for delay in _DELAY:
                    if self.repeatability == delay[0]:
                        time.sleep(delay[1])
            else:
                time.sleep(.001)
        with self.i2c_device as i2c:
            i2c.readinto(data)
        word = _unpack(data)
        length = len(word)
        temperature = [None] * (length//2)
        humidity = [None] * (length//2)
        for i in range(length//2):
            temperature[i] = -45 + (175 * (word[i*2] / 65535))
            humidity[i] = 100 * (word[(i*2)+1] / 65523)
        if (len(temperature) == 1) and (len(humidity) == 1):
            return temperature[0], humidity[0]
        return temperature, humidity

    def _read(self):
        if self.mode == MODE_PERIODIC and time.time() > self._last_read+1/self.frequency:
            self._cached_temperature, self._cached_humidity = self._data()
            self._last_read = time.time()
        elif self.mode == MODE_SINGLE:
            self._cached_temperature, self._cached_humidity = self._data()
        return self._cached_temperature, self._cached_humidity

    @property
    def mode(self):
        """
        Operation mode
        Allowed values are the constants MODE_*
        Return the device to 'Single' mode to stop periodic data acquisition and allow it to sleep.
        """
        return self._mode

    @mode.setter
    def mode(self, value):
        if not value in _SHT31_MODES:
            raise ValueError("Mode '%s' not supported" % (value))
        if self._mode == MODE_PERIODIC and value != MODE_PERIODIC:
            self._command(_SHT31_PERIODIC_BREAK)
            time.sleep(.001)
        if value == MODE_PERIODIC and self._mode != MODE_PERIODIC:
            self._periodic()
        self._mode = value

    @property
    def repeatability(self):
        """
        Repeatability
        Allowed values are the constants REP_*
        """
        return self._repeatability

    @repeatability.setter
    def repeatability(self, value):
        if not value in _SHT31_REP:
            raise ValueError("Repeatability '%s' not supported" % (value))
        if self.mode == MODE_PERIODIC and not self._repeatability == value:
            self._repeatability = value
            self._periodic()
        else:
            self._repeatability = value

    @property
    def clock_stretching(self):
        """
        Control clock stretching.
        This feature only affects 'Single' mode.
        """
        return self._clock_stretching

    @clock_stretching.setter
    def clock_stretching(self, value):
        self._clock_stretching = bool(value)

    @property
    def art(self):
        """
        Control accelerated response time
        This feature only affects 'Periodic' mode.
        """
        return self._art

    @art.setter
    def art(self, value):
        if value:
            self.frequency = FREQUENCY_4
        if self.mode == MODE_PERIODIC and not self._art == value:
            self._art = bool(value)
            self._periodic()
        else:
            self._art = bool(value)

    @property
    def frequency(self):
        """
        Periodic data acquisition frequency
        Allowed values are the constants FREQUENCY_*
        Frequency can not be modified when ART is enabled
        """
        return self._frequency

    @frequency.setter
    def frequency(self, value):
        if self.art:
            raise RuntimeError("Frequency locked to '4 Hz' when ART enabled")
        if not value in _SHT31_FREQUENCIES:
            raise ValueError("Data acquisition frequency '%s Hz' not supported" % (value))
        if self.mode == MODE_PERIODIC and not self._frequency == value:
            self._frequency = value
            self._periodic()
        else:
            self._frequency = value

    @property
    def temperature(self):
        """
        The measured temperature in degrees celsius.
        'Single' mode reads and returns the current temperature as a float.
        'Periodic' mode returns the most recent readings available from the sensor's cache
        in a FILO list of eight floats. This list is backfilled with with the
        sensor's maximum output of 130.0 when the sensor is read before the
        cache is full.
        """
        temperature, _ = self._read()
        return temperature

    @property
    def relative_humidity(self):
        """
        The measured relative humidity in percent.
        'Single' mode reads and returns the current humidity as a float.
        'Periodic' mode returns the most recent readings available from the sensor's cache
        in a FILO list of eight floats. This list is backfilled with with the
        sensor's maximum output of 100.01831417975366 when the sensor is read
        before the cache is full.
        """
        _, humidity = self._read()
        return humidity

    @property
    def heater(self):
        """Control device's internal heater."""
        return (self.status & 0x2000) != 0

    @heater.setter
    def heater(self, value=False):
        if value:
            self._command(_SHT31_HEATER_ENABLE)
            time.sleep(.001)
        else:
            self._command(_SHT31_HEATER_DISABLE)
            time.sleep(.001)

    @property
    def status(self):
        """Device status."""
        data = bytearray(2)
        self._command(_SHT31_READSTATUS)
        time.sleep(.001)
        with self.i2c_device as i2c:
            i2c.readinto(data)
        status = data[0] << 8 | data[1]
        return status

    @property
    def serial_number(self):
        """Device serial number."""
        data = bytearray(6)
        data[0] = 0xff
        self._command(_SHT31_READSERIALNBR)
        time.sleep(.001)
        with self.i2c_device as i2c:
            i2c.readinto(data)
        word = _unpack(data)
        return (word[0] << 16) | word[1]