API Reference

adafruit_tmp117

CircuitPython library for the TI TMP117 Temperature sensor

  • Author(s): Bryan Siepert, Ian Grant

parts based on SparkFun_TMP117_Arduino_Library by Madison Chodikov @ SparkFun Electronics: https://github.com/sparkfunX/Qwiic_TMP117 https://github.com/sparkfun/SparkFun_TMP117_Arduino_Library

Serial number register information: https://e2e.ti.com/support/sensors/f/1023/t/815716?TMP117-Reading-Serial-Number-from-EEPROM

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_tmp117.AlertMode

Options for alert_mode. See alert_mode for more information.

class adafruit_tmp117.AlertStatus(high_alert, low_alert)

Create new instance of AlertStatus(high_alert, low_alert)

high_alert

Alias for field number 0

low_alert

Alias for field number 1

class adafruit_tmp117.AverageCount

Options for averaged_measurements

class adafruit_tmp117.MeasurementDelay

Options for measurement_delay

class adafruit_tmp117.MeasurementMode

Options for measurement_mode. See measurement_mode for more information.

class adafruit_tmp117.TMP117(i2c_bus: busio.I2C, address: int = 72)

Library for the TI TMP117 high-accuracy temperature sensor

Create a driver for a TMP117 or TMP119 on the given I2C bus.

Parameters:

  • i2c_bus (I2C) – the I2C bus the sensor is connected to.

  • address (int) – the 7-bit I2C address (0x48-0x4B, default 0x48).

Raises:

AttributeError – if no TMP117/TMP119-family device answers at address.

Note

The device-ID register reports a 16-bit value whose upper nibble is a silicon-revision field, not a part number: TMP117 = 0x0117, TMP119 = 0x2117, both sharing DID[11:0] = 0x117. The check below matches that shared field so future silicon revisions are still accepted.

property alert_mode: int

Sets the behavior of the low_limit, high_limit, and alert_status properties.

When set to AlertMode.WINDOW, the high_limit property will unset when the measured temperature goes below high_limit. Similarly low_limit will be True or False depending on if the measured temperature is below (False) or above(True) low_limit.

When set to AlertMode.HYSTERESIS, the high_limit property will be set to False when the measured temperature goes below low_limit. In this mode, the low_limit property of alert_status will not be set.

The default is AlertMode.WINDOW

Returns:

the current AlertMode register code.

Return type:

int

property alert_status: AlertStatus

The current triggered status of the high and low temperature alerts as a AlertStatus named tuple with attributes for the triggered status of each alert.

Returns:

an AlertStatus namedtuple (high_alert, low_alert) of booleans.

Return type:

AlertStatus

Warning

Reading this property reads the configuration register, which clears the latched HIGH/LOW alert flags in window mode (AlertMode.WINDOW). Read it once per loop and reuse the result; reading it twice can miss an alert that the first read cleared. In hysteresis mode (AlertMode.HYSTERESIS) the flag is not cleared by a register read.

Note

In hysteresis mode low_alert is always False (the low flag is disabled); only high_alert is meaningful.

import board
import adafruit_tmp117
i2c = board.I2C()  # uses board.SCL and board.SDA

tmp117 = adafruit_tmp117.TMP117(i2c)

tmp117.high_limit = 25
tmp117.low_limit = 10

print("High limit", tmp117.high_limit)
print("Low limit", tmp117.low_limit)

# Try changing `alert_mode`  to see how it modifies the behavior of the alerts.
# tmp117.alert_mode = AlertMode.WINDOW #default
# tmp117.alert_mode = AlertMode.HYSTERESIS

print("Alert mode:", AlertMode.string[tmp117.alert_mode])
print("")
print("")
while True:
    print("Temperature: %.2f degrees C" % tmp117.temperature)
    alert_status = tmp117.alert_status
    print("High alert:", alert_status.high_alert)
    print("Low alert:", alert_status.low_alert)
    print("")
    time.sleep(1)
property averaged_measurements

The number of measurements that are taken and averaged before updating the temperature measurement register. A larger number will reduce measurement noise but may also affect the rate at which measurements are updated, depending on the value of measurement_delay

Note that each averaged measurement takes 15.5ms which means that larger numbers of averaged measurements may make the delay between new reported measurements to exceed the delay set by measurement_delay

Returns:

the current AverageCount register code (number of averaged samples).

Return type:

int

property high_limit: float

The high temperature limit in degrees Celsius. When the measured temperature exceeds this value, the high_alert attribute of the alert_status property will be True. See the documentation for alert_status for more information.

Returns:

the high limit in degrees Celsius.

Return type:

float

initialize() → None

Configure the sensor with sensible defaults. initialize is primarily provided to be called after reset, however it can also be used to easily set the sensor to a known configuration

Returns:

None

Return type:

None

property low_limit: float

The low temperature limit in degrees Celsius. When the measured temperature goes below this value, the low_alert attribute of the alert_status property will be True. See the documentation for alert_status for more information.

Returns:

the low limit in degrees Celsius.

Return type:

float

property measurement_delay

The minimum amount of time between measurements in seconds. Must be a MeasurementDelay. The specified amount may be exceeded depending on the current setting off averaged_measurements which determines the minimum time needed between reported measurements.

Returns:

the current MeasurementDelay register code.

Return type:

int

property measurement_mode
Sets the measurement mode, specifying the behavior of how often measurements are taken.

measurement_mode must be one of:

Mode

Behavior

MeasurementMode.CONTINUOUS

Measurements are made at the interval determined by

averaged_measurements and measurement_delay.

temperature returns the most recent measurement

MeasurementMode.ONE_SHOT

Take a single measurement with the current number of

averaged_measurements and switch to SHUTDOWN when

finished.

temperature will return the new measurement until

measurement_mode is set to CONTINUOUS or ONE_SHOT is

set again.

MeasurementMode.SHUTDOWN

The sensor is put into a low power state and no new

measurements are taken.

temperature will return the last measurement until

a new measurement_mode is selected.
Returns:

the current MeasurementMode register code.

Return type:

int

reset() → None

Reset the sensor to its unconfigured power-on state.

Returns:

None

Return type:

None

property serial_number: int

A 48-bit, factory-set unique identifier for the device.

Returns:

the 48-bit unique ID from EEPROM as an integer.

Return type:

int

Note

This reads the factory NIST-traceability ID stored in EEPROM1-3. It is only meaningful if those EEPROM locations have not been reprogrammed for general-purpose use.

take_single_measurement() → float

Perform a single measurement cycle respecting the value of averaged_measurements, returning the measurement once complete. Once finished the sensor is placed into a low power state until take_single_measurement() or temperature are read.

Returns:

the freshly measured temperature in degrees Celsius.

Return type:

float

Note: if averaged_measurements is set to a high value there will be a notable delay before the temperature measurement is returned while the sensor takes the required number of measurements

property temperature: float

The current measured temperature in degrees Celsius.

Returns:

the most recent temperature in degrees Celsius.

Return type:

float

Note

In continuous-conversion mode this returns the most recent sample and does not block. After a reset and before the first conversion completes, the sensor reports -256 degrees C.

property temperature_offset: float

User defined temperature offset to be added to measurements from temperature.

The offset is applied inside the sensor (added after linearization) and is in the same -256 to +255.9921 degrees C range as the temperature result.

Returns:

the configured offset in degrees Celsius.

Return type:

float