sensor.temp_rh.sht3x.spin

{
----------------------------------------------------------------------------------------------------
    Filename:       sensor.temp_rh.sht3x.spin
    Description:    Driver for Sensirion SHT3x series Temperature/Relative Humidity sensors
    Author:         Jesse Burt
    Started:        Nov 19, 2017
    Updated:        Nov 13, 2024
    Copyright (c) 2024 - See end of file for terms of use.
----------------------------------------------------------------------------------------------------
}

#include "sensor.temp_rh.common.spinh"

CON

    { default I/O settings; these can be overridden in the parent object }
    SCL         = 28
    SDA         = 29
    RST         = 24
    I2C_FREQ    = 100_000
    I2C_ADDR    = %0

    SLAVE_WR    = core.SLAVE_ADDR
    SLAVE_RD    = core.SLAVE_ADDR | 1

    MSB         = 1
    LSB         = 0

' Measurement repeatability
    LOW         = 0
    MED         = 1
    HIGH        = 2

' Measurement modes
    SINGLE      = 0
    CONT        = 1


VAR

    long _reset_pin
    byte _repeatability
    byte _addr_bit
    byte _measure_mode
    byte _drate_hz


OBJ

#ifdef SHT3X_I2C_BC
    i2c:    "com.i2c.nocog"                     ' BC I2C engine
#else
    i2c:    "com.i2c"                           ' PASM I2C engine
#endif
    core:   "core.con.sht3x"                    ' hw-specific constants
    time:   "time"                              ' timekeeping methods
    crc:    "math.crc"                          ' crc algorithms


PUB null()
' This is not a top-level object

PUB start(): status
' Start using default I/O settings
    return startx(SCL, SDA, I2C_FREQ, I2C_ADDR, RST)


PUB startx(SCL_PIN, SDA_PIN, I2C_HZ, ADDR_BIT, RESET_PIN): status
' Start using custom I/O settings and I2C bus speed
'   NOTE: RESET_PIN is optional; choose an invalid value to ignore (e.g., -1)
    if ( lookdown(SCL_PIN: 0..31) and lookdown(SDA_PIN: 0..31) )
        if (status := i2c.init(SCL_PIN, SDA_PIN, I2C_HZ))
            time.usleep(core.T_POR)             ' wait for device startup
            _addr_bit := ((ADDR_BIT <> 0) & 1) << 1
            if ( i2c.present(SLAVE_WR | _addr_bit) )
                _reset_pin := RESET_PIN
                reset()
                clr_status()
                return status
    ' if this point is reached, something above failed
    ' Double check I/O pin assignments, connections, power
    ' Lastly - make sure you have at least one free core/cog
    return FALSE


PUB stop()
' Stop the driver
    i2c.deinit()
    bytefill(@_reset_pin, 0, 8)


PUB clr_status()
' Clears the status register
    writereg(core.CLRSTATUS, 0, 0)
    time.usleep(core.T_POR)


PUB data_rate(rate=-2): curr_rate | tmp
' Output data rate, in Hz
'   Valid values: 0_5 (0.5Hz), 1, 2, 4, 10
'   Any other value returns the current setting
'   NOTE: Applies when opmode() == CONT (continuous), only
'   NOTE: Sensirion notes that at the highest measurement rate (10Hz),
'       self-heating of the sensor might occur
    case rate
        0, 5:
            ' Measurement rate and repeatability configured in the same reg
            tmp := core.MEAS_PER_0_5 | lookupz( _repeatability: core.RPT_LO_0_5, ...
                                                                core.RPT_MED_0_5, ...
                                                                core.RPT_HI_0_5 )
            _drate_hz := rate
        1:
            tmp := core.MEAS_PER_1 | lookupz( _repeatability:   core.RPT_LO_1, ...
                                                                core.RPT_MED_1, ...
                                                                core.RPT_HI_1 )
            _drate_hz := rate
        2:
            tmp := core.MEAS_PER_2 | lookupz( _repeatability:   core.RPT_LO_2, ...
                                                                core.RPT_MED_2, ...
                                                                core.RPT_HI_2 )
            _drate_hz := rate
        4:
            tmp := core.MEAS_PER_4 | lookupz( _repeatability:   core.RPT_LO_4, ...
                                                                core.RPT_MED_4, ...
                                                                core.RPT_HI_4 )
            _drate_hz := rate
        10:
            tmp := core.MEAS_PER_10 | lookupz( _repeatability:  core.RPT_LO_10, ...
                                                                core.RPT_MED_10, ...
                                                                core.RPT_HI_10 )
            _drate_hz := rate
        other:
            return _drate_hz
    stop_cont_meas()                            ' Stop ongoing measurements
    writereg(tmp, 0, 0)
    _measure_mode := CONT


PUB heater_ena(state=-2): curr_state
' Enable/Disable built-in heater
'   Valid values: TRUE (-1 or 1), FALSE (0)
'   Any other value polls the chip and returns the current setting
'   NOTE: Per SHT3x datasheet, this is for plausability checking only
    case ||(state)
        0, 1:
            state := lookupz(||(state): core.HEATERDIS, core.HEATEREN)
            writereg(state, 0, 0)
        other:
            curr_state := 0
            readreg(core.STATUS, 3, @curr_state)
            curr_state >>= 8                    ' Chop off CRC
            return ((curr_state >> core.HEATER) & 1) == 1


PUB last_cmd_ok(): flag
' Flag indicating last command executed without error
'   Returns: TRUE (-1) if no error, FALSE (0) otherwise
    flag := 0
    readreg(core.STATUS, 2, @flag)
    return (((flag >> 1) & 1) == 0)


PUB last_crc_ok(): flag
' Flag indicating CRC of last command was good
'   Returns: TRUE (-1) if CRC was good, FALSE (0) otherwise
    flag := 0
    readreg(core.STATUS, 2, @flag)
    return ((flag & 1) == 0)


PUB measure()
' dummy method


PUB opmode(mode=-2): curr_mode
' Set device operating mode
'   Valid values
'      *SINGLE (0): single-shot measurements
'       CONT (1): continuously measure
'   Any other value returns the current setting
    case mode
        SINGLE:
            stop_cont_meas()
        CONT:
            stop_cont_meas()
            data_rate(_drate_hz)
        other:
            return _measure_mode

    _measure_mode := mode


PUB repeatability(level=-2): curr_lvl
' Set measurement repeatability/stability
'   Valid values: LOW (0), MED (1), HIGH (2)
'   Any other value returns the current setting
    case level
        LOW, MED, HIGH:
            _repeatability := level
        other:
            return _repeatability


PUB reset()
' Perform Soft Reset
    case _reset_pin
        0..31:
            outa[_reset_pin] := 1
            dira[_reset_pin] := 1
            outa[_reset_pin] := 0
#ifdef __OUTPUT_ASM__
            time.usleep(1)                      ' only needed if building with PASM backend
#endif
            outa[_reset_pin] := 1
        other:
            writereg(core.SOFTRESET, 0, 0)
    time.usleep(core.T_POR)


PUB rh_data(): rh_adc | tmp[2]
' Read relative humidity ADC data
'   Returns: u16
    tmp := 0
    case _measure_mode
        SINGLE:
            one_shot_meas(@tmp)
            _last_temp := tmp.word[1]
            _last_rh := tmp.word[0]
        CONT:
            poll_measure(@tmp)
            ' update last temp and RH measurement vars
            _last_temp := (tmp.byte[5] << 8) | tmp.byte[4]
            _last_rh := (tmp.byte[2] << 8) | tmp.byte[1]
    return _last_rh


PUB rh_int_hi_hyst(l=-2): cl
' High RH interrupt: clear level, in hundredths of a percent
'   Valid values: 0..100_00
'   Any other value polls the chip and returns the current setting, in hundredths of a percent
    cl := 0
    readreg(core.ALERTLIM_RD_HI_CLR, 2, @cl)
    case l
        0..100_00:
            l := rhpct_7bit(l)
            l := (cl & core.ALERTLIM_RH_MASK) | l
            writereg(core.ALERTLIM_WR_HI_CLR, 2, @l)
        other:
            return rh7bit_pct(cl)


PUB rh_int_hi_thresh(l=-2): cl
' High RH interrupt: trigger level, in hundredths of a percent
'   Valid values: 0..100_00
'   Any other value polls the chip and returns the current setting, in hundredths of a percent
    cl := 0
    readreg(core.ALERTLIM_RD_HI_SET, 2, @cl)
    case l
        0..100_00:
            l := rhpct_7bit(l)
            l := (cl & core.ALERTLIM_RH_MASK) | l
            writereg(core.ALERTLIM_WR_HI_SET, 2, @l)
        other:
            return rh7bit_pct(cl)


PUB rh_int_lo_hyst(l=-2): cl
' Low RH interrupt: clear level, in hundredths of a percent
'   Valid values: 0..100_00
'   Any other value polls the chip and returns the current setting, in hundredths of a percent
    cl := 0
    readreg(core.ALERTLIM_RD_LO_CLR, 2, @cl)
    case l
        0..100_00:
            l := rhpct_7bit(l)
            l := (cl & core.ALERTLIM_RH_MASK) | l
            writereg(core.ALERTLIM_WR_LO_CLR, 2, @l)
        other:
            return rh7bit_pct(cl)


PUB rh_int_lo_thresh(l=-2): cl
' Low RH interrupt: trigger level, in hundredths of a percent
'   Valid values: 0..100_00
'   Any other value polls the chip and returns the current setting, in hundredths of a percent
    cl := 0
    readreg(core.ALERTLIM_RD_LO_SET, 2, @cl)
    case l
        0..100:
            l := rhpct_7bit(l)
            l := (cl & core.ALERTLIM_RH_MASK) | l
            writereg(core.ALERTLIM_WR_LO_SET, 2, @l)
        other:
            return rh7bit_pct(cl)


PUB rh_word2pct(rh_word): rh
' Convert RH ADC word to percent
'   Returns: relative humidity, in hundredths of a percent
    return (100 * (rh_word * 100)) / core.ADC_MAX


PUB serial_num(ptr_sn)
' Get serial number
'   ptr_sn: pointer to copy serial number to (4 bytes)
    readreg(core.READ_SN, 4, ptr_sn)


PUB temp_data(): temp_adc | tmp[2]
' Read temperature ADC data
'   Returns: s16
    tmp := 0
    case _measure_mode
        SINGLE:
            one_shot_meas(@tmp)
            _last_temp := tmp.word[1]
            _last_rh := tmp.word[0]
        CONT:
            poll_measure(@tmp)
            ' update last temp and RH measurement vars
            _last_temp := (tmp.byte[5] << 8) | tmp.byte[4]
            _last_rh := (tmp.byte[2] << 8) | tmp.byte[1]

    return _last_temp


PUB temp_int_hi_hyst(l=negx): cl
' High temperature interrupt: clear level, in degrees C
'   Valid values: -45..130
'   Any other value polls the chip and returns the current setting, in hundredths of a degree C
    cl := 0
    readreg(core.ALERTLIM_RD_HI_CLR, 2, @cl)
    case temp_scale()
        C:
            case l
                -45_00..130_00:
                    l := tempc_9bit(l)
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_HI_CLR, 2, @l)
                other:
                    return temp9bit_c(cl & $1ff)
        F:
            case l
                -49_00..266_00:
                    l := tempc_9bit( f_to_c(l) )
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_HI_CLR, 2, @l)
                other:
                    return c_to_f( temp9bit_c(cl & $1ff) )


PUB temp_int_hi_thresh(l=negx): cl
' High temperature interrupt: trigger level, in degrees C
'   Valid values: -45..130
'   Any other value polls the chip and returns the current setting, in hundredths of a degree C
    cl := 0
    readreg(core.ALERTLIM_RD_HI_SET, 2, @cl)
    case temp_scale()
        C:
            case l
                -45_00..130_00:
                    l := tempc_9bit(l)
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_HI_SET, 2, @l)
                other:
                    return temp9bit_c(cl & $1ff)
        F:
            case l
                -49_00..266_00:
                    l := tempc_9bit( f_to_c(l) )
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_HI_SET, 2, @l)
                other:
                    return c_to_f( temp9bit_c(cl & $1ff) )


PUB temp_int_lo_hyst(l=negx): cl
' Low temperature interrupt: clear level, in degrees C
'   Valid values: -45..130
'   Any other value polls the chip and returns the current setting, in hundredths of a degree C
    cl := 0
    readreg(core.ALERTLIM_RD_LO_CLR, 2, @cl)
    case temp_scale()
        C:
            case l
                -45_00..130_00:
                    l := tempc_9bit(l)
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_LO_CLR, 2, @l)
                other:
                    return temp9bit_c(cl & $1ff)
        F:
            case l
                -49_00..266_00:
                    l := tempc_9bit( f_to_c(l) )
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_LO_CLR, 2, @l)
                other:
                    return c_to_f( temp9bit_c(cl & $1ff) )


PUB temp_int_lo_thresh(l=negx): cl
' Low temperature interrupt: trigger level, in degrees C
'   Valid values: -45..130
'   Any other value polls the chip and returns the current setting, in hundredths of a degree C
    cl := 0
    readreg(core.ALERTLIM_RD_LO_SET, 2, @cl)
    case temp_scale()
        C:
            case l
                -45_00..130_00:
                    l := tempc_9bit(l)
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_LO_SET, 2, @l)
                other:
                    return temp9bit_c(cl & $1ff)
        F:
            case l
                -49_00..266_00:
                    l := tempc_9bit( f_to_c(l) )
                    l := (cl & core.ALERTLIM_TEMP_MASK) | l
                    writereg(core.ALERTLIM_WR_LO_SET, 2, @l)
                other:
                    return c_to_f( temp9bit_c(cl & $1ff) )

PUB temp_word2deg(temp_word): temp
' Convert temperature ADC word to temperature
'   Returns: temperature, in hundredths of a degree, in chosen scale
    case _temp_scale
        C:
            return ((175 * (temp_word * 100)) / core.ADC_MAX)-(45 * 100)
        F:
            return ((315 * (temp_word * 100)) / core.ADC_MAX)-(49 * 100)
        other:
            return FALSE


PRI one_shot_meas(ptr_buff)
' Perform single-shot measurement
    case _repeatability
        LOW, MED, HIGH:
            readreg(lookupz(_repeatability: core.MEAS_LOWREP_CS, core.MEAS_MEDREP_CS, ...
                                            core.MEAS_HIGHREP_CS), ...
                    6, ...
                    ptr_buff)
        other:
            return


PRI poll_measure(ptr_buff)
' Poll for measurement when sensor is in continuous measurement mode
    readreg(core.FETCHDATA, 6, ptr_buff)


PRI rhpct_7bit(rh_pct): rh7bit
' Converts hundrdths of a percent RH to 7-bit value, for use with alert threshold setting
'   Valid values: 0..100_00
'   Any other value is ignored
'   NOTE: Value is left-justified in MSB of word
    case rh_pct
        0..100_00:
            rh_pct /= 100
            return (((rh_pct * 100) / 100 * core.ADC_MAX) / 100) & $FE00
        other:
            return


PRI rh7bit_pct(rh_7b): rhpct
' Converts 7-bit value to Percent RH, for use with alert threshold settings
'   Valid values: $02xx..$FExx (xx = 00)
'   NOTE: Value must be left-justified in MSB of word
    rh_7b &= $FE00                              ' Mask off temperature
    rh_7b *= 10000                              ' Scale up
    return (rh_7b / core.ADC_MAX)               ' Scale to %


PRI stop_cont_meas()
' Stop continuous measurement mode
    writereg(core.BREAK_STOP, 0, 0)


PRI tempc_9bit(temp_c): temp9b | scale
' Converts hundredths of a degree C to 9-bit value, for use with alert threshold settings
'   Valid values: -45_00..130_00
    case temp_c
        -45_00..130_00:
            temp_c /= 100                       ' scale down
            scale := 10_000                     ' Fixed-point scale
            temp9b := ((((temp_c * scale) + (45 * scale)) / 175 * core.ADC_MAX)) / scale
            return (temp9b >> 7) & $001FF
        other:
            return


PRI temp9bit_c(temp_9b): tempc | scale
' Converts raw 9-bit value to temperature in degrees C
'   Valid values: 0..511
'   Returns: hundredths of a degree C -45_00..129_66 (-45.00C..129.66C)
'   Any other value is ignored
    scale := 100
    case temp_9b
        0..511:
            tempc := (temp_9b << 7)
            return ((175 * (tempc * scale)) / core.ADC_MAX)-(45 * scale)
        other:
            return


PRI readreg(reg_nr, nr_bytes, ptr_buff) | cmd_pkt, r_tmp, t_tmp, crc_r
' Read nr_bytes from the slave device into ptr_buff
    case reg_nr                                 ' validate register num
        core.MEAS_HIGHREP_CS..core.MEAS_LOWREP_CS:
            cmd_pkt.byte[0] := (SLAVE_WR | _addr_bit)
            cmd_pkt.byte[1] := reg_nr.byte[MSB]
            cmd_pkt.byte[2] := reg_nr.byte[LSB]
            r_tmp := t_tmp := 0

            i2c.start()
            i2c.wrblock_lsbf(@cmd_pkt, 3)

            i2c.start()
            i2c.write(SLAVE_RD | _addr_bit)
            i2c.rdblock_msbf(@t_tmp, 3, i2c.ACK)
            i2c.rdblock_msbf(@r_tmp, 3, i2c.NAK)
            i2c.stop()

            crc_r := t_tmp.byte[0]              ' crc read with data
            t_tmp >>= 8                         ' chop it off the data
            if crc.sensirion_crc8(@t_tmp, 2) == crc_r
                word[ptr_buff][1] := t_tmp      ' copy temp
            else
                return

            crc_r := r_tmp.byte[0]
            r_tmp >>= 8
            if crc.sensirion_crc8(@r_tmp, 2) == crc_r
                word[ptr_buff][0] := r_tmp      ' copy RH
            else
                return

        core.READ_SN, core.STATUS, core.FETCHDATA, core.ALERTLIM_RD_LO_SET..core.ALERTLIM_RD_HI_SET:
            cmd_pkt.byte[0] := (SLAVE_WR | _addr_bit)
            cmd_pkt.byte[1] := reg_nr.byte[MSB]
            cmd_pkt.byte[2] := reg_nr.byte[LSB]

            i2c.start()
            i2c.wrblock_lsbf(@cmd_pkt, 3)

            i2c.start()
            i2c.write(SLAVE_RD | _addr_bit)
            i2c.rdblock_msbf(ptr_buff, nr_bytes, i2c.NAK)
            i2c.stop()

        other:
            return


PRI writereg(reg_nr, nr_bytes, ptr_buff) | cmd_pkt, chk
' Write nr_bytes to the slave device from ptr_buff
    chk := 0
    case reg_nr
        core.MEAS_HIGHREP..core.MEAS_LOWREP, core.CLRSTATUS, core.HEATEREN, core.HEATERDIS, ...
        core.SOFTRESET, core.BREAK_STOP, core.MEAS_P_HI_0_5, core.MEAS_P_MED_0_5, ...
        core.MEAS_P_LO_0_5, core.MEAS_P_HI_1, core.MEAS_P_MED_1, core.MEAS_P_LO_1, ...
        core.MEAS_P_HI_2, core.MEAS_P_MED_2, core.MEAS_P_LO_2, core.MEAS_P_HI_4, ...
        core.MEAS_P_MED_4, core.MEAS_P_LO_4, core.MEAS_P_HI_10, core.MEAS_P_MED_10, ...
        core.MEAS_P_LO_10:

        core.ALERTLIM_WR_LO_SET..core.ALERTLIM_WR_HI_SET:
            ' calc CRC for interrupt threshold set command (required)
            chk := crc.sensirion_crc8(ptr_buff, 2)
        other:
            return

    cmd_pkt.byte[0] := (SLAVE_WR | _addr_bit)
    cmd_pkt.byte[1] := reg_nr.byte[MSB]
    cmd_pkt.byte[2] := reg_nr.byte[LSB]

    i2c.start()
    i2c.wrblock_lsbf(@cmd_pkt, 3)

    if ( chk )                                  ' write params and CRC
        i2c.wrblock_msbf(ptr_buff, nr_bytes)
        i2c.write(chk)
    i2c.stop()
    time.usleep(500)


DAT
{
Copyright 2024 Jesse Burt

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.
}