-
Notifications
You must be signed in to change notification settings - Fork 0
/
tmp117.py
527 lines (412 loc) · 21 KB
/
tmp117.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
# SPDX-FileCopyrightText: Copyright (c) 2020 Bryan Siepert for Adafruit Industries
# SPDX-FileCopyrightText: Copyright (c) 2023 Jose D. Montoya
#
# SPDX-License-Identifier: MIT
"""
`tmp117`
================================================================================
CircuitPython library for the TI TMP117 Temperature sensor
* Author(s): Bryan Siepert, Ian Grant, Jose D. Montoya
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:**
* `Adafruit TMP117 ±0.1°C High Accuracy I2C Temperature Sensor
<https://www.adafruit.com/product/4821>`_ (Product ID: 4821)
**Software and Dependencies:**
* Adafruit CircuitPython firmware for the supported boards:
https://circuitpython.org/downloads
* Adafruit's Bus Device library:
https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
* Adafruit's Register library:
https://github.com/adafruit/Adafruit_CircuitPython_Register
"""
import time
from collections import namedtuple
from micropython import const
from adafruit_bus_device import i2c_device
from adafruit_register.i2c_struct import ROUnaryStruct, UnaryStruct
from adafruit_register.i2c_bit import RWBit, ROBit
from adafruit_register.i2c_bits import RWBits, ROBits
try:
from typing import Tuple
from busio import I2C
from typing_extensions import Literal
except ImportError:
pass
__version__ = "0.0.0+auto.0"
__repo__ = "https://github.com/jposada202020/CircuitPython_TMP117.git"
_I2C_ADDR = 0x48 # default I2C Address
_TEMP_RESULT = const(0x00)
_CONFIGURATION = const(0x01)
_T_HIGH_LIMIT = const(0x02)
_T_LOW_LIMIT = const(0x03)
_EEPROM_UL = const(0x04)
_EEPROM1 = const(0x05)
_EEPROM2 = const(0x06)
_TEMP_OFFSET = const(0x07)
_EEPROM3 = const(0x08)
_DEVICE_ID = const(0x0F)
_DEVICE_ID_VALUE = 0x0117
_TMP117_RESOLUTION = (
0.0078125 # Resolution of the device, found on (page 1 of datasheet)
)
_CONTINUOUS_CONVERSION_MODE = const(0b00) # Continuous Conversion Mode
_ONE_SHOT_MODE = const(0b11) # One Shot Conversion Mode
_SHUTDOWN_MODE = const(0b01) # Shutdown Conversion Mode
ALERT_WINDOW = const(0)
ALERT_HYSTERESIS = const(1)
AVERAGE_1X = const(0b00)
AVERAGE_8X = const(0b01)
AVERAGE_32X = const(0b10)
AVERAGE_64X = const(0b11)
averaged_measurements_values = (AVERAGE_1X, AVERAGE_8X, AVERAGE_32X, AVERAGE_64X)
DELAY_0_0015_S = const(0b000) # 0.00155
DELAY_0_125_S = const(0b01) # 0.125
DELAY_0_250_S = const(0b010) # 0.250
DELAY_0_500_S = const(0b011) # 0.500
DELAY_1_S = const(0b100) # 1
DELAY_4_S = const(0b101) # 4
DELAY_8_S = const(0b110) # 8
DELAY_16_S = const(0b111) # 16
CONTINUOUS_CONVERSION_MODE = const(0b00) # Continuous Conversion Mode
ONE_SHOT_MODE = const(0b11) # One Shot Conversion Mode
SHUTDOWN_MODE = const(0b01) # Shutdown Conversion Mode
AlertStatus = namedtuple("AlertStatus", ["high_alert", "low_alert"])
class TMP117:
"""Library for the TI TMP117 high-accuracy temperature sensor"""
_part_id = ROUnaryStruct(_DEVICE_ID, ">H")
_raw_temperature = ROUnaryStruct(_TEMP_RESULT, ">h")
_raw_high_limit = UnaryStruct(_T_HIGH_LIMIT, ">h")
_raw_low_limit = UnaryStruct(_T_LOW_LIMIT, ">h")
_raw_temperature_offset = UnaryStruct(_TEMP_OFFSET, ">h")
# these three bits will clear on read in some configurations, so we read them together
_alert_status_data_ready = ROBits(3, _CONFIGURATION, 13, 2, False)
_eeprom_busy = ROBit(_CONFIGURATION, 12, 2, False)
_mode = RWBits(2, _CONFIGURATION, 10, 2, False)
_raw_measurement_delay = RWBits(3, _CONFIGURATION, 7, 2, False)
_raw_averaged_measurements = RWBits(2, _CONFIGURATION, 5, 2, False)
_data_ready = RWBit(_CONFIGURATION, 13, 2, False)
_raw_alert_mode = RWBit(_CONFIGURATION, 4, 2, False) # T/nA bits in the datasheet
_int_active_high = RWBit(_CONFIGURATION, 3, 2, False)
_data_ready_int_en = RWBit(_CONFIGURATION, 2, 2, False)
_soft_reset = RWBit(_CONFIGURATION, 1, 2, False)
_avg_3 = {0: 1, 1: 1, 2: 1, 3: 1, 4: 1, 5: 4, 6: 8, 7: 16}
_avg_2 = {0: 0.5, 1: 0.5, 2: 0.5, 3: 0.5, 4: 1, 5: 4, 6: 8, 7: 16}
_avg_1 = {0: 0.125, 1: 0.125, 2: 0.25, 3: 0.5, 4: 1, 5: 4, 6: 8, 7: 16}
_avg_0 = {0: 0.0155, 1: 0.125, 2: 0.25, 3: 0.5, 4: 1, 5: 4, 6: 8, 7: 16}
_averaging_modes = {0: _avg_0, 1: _avg_1, 2: _avg_2, 3: _avg_3}
def __init__(self, i2c_bus: I2C, address: int = _I2C_ADDR) -> None:
self.i2c_device = i2c_device.I2CDevice(i2c_bus, address)
if self._part_id != _DEVICE_ID_VALUE:
raise AttributeError("Cannot find a TMP117")
self._soft_reset = True
# Following a reset, the temperature register reads –256 °C until the first
# conversion, including averaging, is complete. So we sleep for that amount of time
time.sleep(
self._averaging_modes[self._raw_averaged_measurements][
self._raw_measurement_delay
]
)
self._mode = CONTINUOUS_CONVERSION_MODE
while not self._data_ready:
time.sleep(0.001)
_ = self._raw_temperature * _TMP117_RESOLUTION
@property
def temperature(self) -> float:
"""The current measured temperature in Celsius"""
return self._raw_temperature * _TMP117_RESOLUTION
@property
def temperature_offset(self) -> float:
"""User defined temperature offset to be added to measurements from `temperature`
In order the see the new change in the temperature we need for the data to be ready.
There is a time delay calculated according to current configuration.
.. code-block::python
import time
import board
import tmp117
i2c = board.I2C() # uses board.SCL and board.SDA
tmp117 = tmp117.TMP117(i2c)
print("Temperature without offset: %.2f degrees C" % tmp117.temperature)
tmp117.temperature_offset = 10.0
while True:
print("Temperature w/ offset: %.2f degrees C" % tmp117.temperature)
time.sleep(1)
"""
return self._raw_temperature_offset * _TMP117_RESOLUTION
@temperature_offset.setter
def temperature_offset(self, value: float) -> None:
self._raw_temperature_offset = self._scaled_limit(value)
@property
def high_limit(self) -> float:
"""The high temperature limit in Celsius. When the measured temperature exceeds this
value, the `high_alert` attribute of the `alert_status` property will be True.
"""
return self._raw_high_limit * _TMP117_RESOLUTION
@high_limit.setter
def high_limit(self, value: float) -> None:
self._raw_high_limit = self._scaled_limit(value)
@property
def low_limit(self) -> float:
"""The low temperature limit in Celsius. When the measured temperature goes below
this value, the `low_alert` attribute of the `alert_status` property will be True.
"""
return self._raw_low_limit * _TMP117_RESOLUTION
@low_limit.setter
def low_limit(self, value: float) -> None:
self._raw_low_limit = self._scaled_limit(value)
@property
def alert_status(self):
"""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.
.. code-block :: python
import board
import tmp117
i2c = board.I2C() # uses board.SCL and board.SDA
tmp117 = 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 = tmp117.ALERT_WINDOW #default
# tmp117.alert_mode = tmp117.HYSTERESIS
print("Alert mode:", 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)
"""
high_alert, low_alert, *_ = self._read_status()
return AlertStatus(high_alert=high_alert, low_alert=low_alert)
@property
def averaged_measurements(self):
"""
Users can configure the device to report the average of multiple temperature
conversions with the AVG[1:0] bits to reduce noise in the conversion results.
When the TMP117 is configured to perform averaging with AVG set to 01, the device executes
the configured number of conversions to eight. The device accumulates those conversion
results and reports the average of all the collected results at the end of the process.
+----------------------------------------+-------------------------+
| Mode | Value |
+========================================+=========================+
| :py:const:`tmp117.AVERAGE_1X` | :py:const:`0b00` |
+----------------------------------------+-------------------------+
| :py:const:`tmp117.AVERAGE_8X` | :py:const:`0b01` |
+----------------------------------------+-------------------------+
| :py:const:`tmp117.AVERAGE_32X` | :py:const:`0b10` |
+----------------------------------------+-------------------------+
| :py:const:`tmp117.AVERAGE_64X` | :py:const:`0b11` |
+----------------------------------------+-------------------------+
.. code-block::python3
import time
import board
import tmp117
i2c = board.I2C() # uses board.SCL and board.SDA
tmp117 = tmp117.TMP117(i2c)
print("Number of averaged samples per measurement:",
tmp117.averaged_measurements
)
"""
average_measure = ("AVERAGE_1X", "AVERAGE_8X", "AVERAGE_32X", "AVERAGE_64X")
return average_measure[self._raw_averaged_measurements]
@averaged_measurements.setter
def averaged_measurements(self, value: int):
if value not in (0, 1, 2, 3):
raise ValueError("averaged_measurements must be set to 0, 1, 2 or 3")
self._raw_averaged_measurements = value
@property
def measurement_mode(self):
# pylint: disable=line-too-long
"""Sets the measurement mode, specifying the behavior of how often measurements are taken.
`measurement_mode` must be one of:
When we use the sensor in One shot mode, the sensor will take the average_measurement value
into account. However, this measure is done with the formula (15.5 ms × average_time), so in
normal operation average_time will be 8, therefore time for measure is 124 ms.
(See datasheet. 7.3.2 Averaging for more information). If we use 64, time will be 15.5 x 65 = 992 ms,
the standby time will decrease, but the measure is still under 1 Hz cycle.
(See Fig 7.2 on the datasheet)
+-----------------------------------------------+------------------------------------------------------+
| Mode | Behavior |
+===============================================+======================================================+
| :py:const:`tmp117.CONTINUOUS_CONVERSION_MODE` | Measurements are made at the interval determined by |
| | averaging_measurements. |
| | `temperature` returns the most recent measurement |
+-----------------------------------------------+------------------------------------------------------+
| :py:const:`tmp117.ONE_SHOT` | Take a single measurement with the current number of |
| | averaging_measurements and switch to |
| | :py:const:`SHUTDOWN` when finished. |
| | `temperature` will return the new measurement until |
| | `measurement_mode` is set to :py:const:`CONTINUOUS` |
| | or :py:const:`ONE_SHOT` is set again. |
+-----------------------------------------------+------------------------------------------------------+
| :py:const:`tmp117.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. |
+-----------------------------------------------+------------------------------------------------------+
"""
# pylint: enable=line-too-long
sensor_modes = {
0: "CONTINUOUS_CONVERSION_MODE",
1: "SHUTDOWN_MODE",
3: "ONE_SHOT_MODE",
}
return sensor_modes[self._mode]
@measurement_mode.setter
def measurement_mode(self, value: int) -> None:
self._mode = value
@property
def measurement_delay(self):
"""The minimum amount of time between measurements in seconds.
The specified amount may be exceeded depending on the
current setting off `averaged_measurements` which determines the minimum
time needed between reported measurements.
+-----------------------------------+-------------------+
| Mode | Value |
+===================================+===================+
| :py:const:`tmp117.DELAY_0_0015_S` | :py:const:`0b000` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_0_125_S` | :py:const:`0b01` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_0_250_S` | :py:const:`0b010` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_0_500_S` | :py:const:`0b011` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_1_S` | :py:const:`0b100` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_4_S` | :py:const:`0b101` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_8_S` | :py:const:`0b110` |
+-----------------------------------+-------------------+
| :py:const:`tmp117.DELAY_16_S` | :py:const:`0b111` |
+-----------------------------------+-------------------+
.. code-block::python
import time
import board
import tmp117
ii2c = board.I2C() # uses board.SCL and board.SDA
tmp117 = mp117.TMP117(i2c)
In order to print information in a nicer way, we create a dictionary with the
sensor information for the measurement delay.
.. code-block::python3
Delay_times = {
0: "DELAY_0_0015_S",
1: "DELAY_0_125_S",
2: "DELAY_0_250_S",
3: "DELAY_0_500_S",
4: "DELAY_1_S",
5: "DELAY_4_S",
6: "DELAY_8_S",
7: "DELAY_16_S",
}
We print the information for the Temperature sensor
.. code-block::python3
# uncomment different options below to see how it affects the reported temperature
print("Minimum time between measurements:",
Delay_times[tmp117.measurement_delay])
"""
return self._raw_measurement_delay
@measurement_delay.setter
def measurement_delay(self, value: int) -> None:
if value not in (0, 1, 2, 3, 4, 5, 6, 7):
raise ValueError(
"averaged_measurements must be set to 0, 1, 2, 3, 4, 5, 6, 7"
)
self._raw_measurement_delay = value
def take_single_measurement(self) -> 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 :py:meth:`take_single_measurement` or `temperature` are read.
**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
"""
return self._set_mode_and_wait_for_measurement(_ONE_SHOT_MODE) # one shot
@property
def alert_mode(self) -> Literal[ALERT_WINDOW, ALERT_HYSTERESIS]:
"""Sets the behavior of the `low_limit`, `high_limit`, and `alert_status` properties.
When set to :py:const:`ALERT_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 :py:const:`ALERT_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 :py:const:`ALERT_WINDOW`
+----------------------------------------+-------------------------+
| Mode | Value |
+========================================+=========================+
| :py:const:`tmp117.ALERT_WINDOW` | :py:const:`0b0` |
+----------------------------------------+-------------------------+
| :py:const:`tmp117.ALERT_HYSTERESIS` | :py:const:`0b1` |
+----------------------------------------+-------------------------+
"""
alert_modes = ("ALERT_WINDOW", "ALERT_HYSTERESIS")
return alert_modes[self._raw_alert_mode]
@alert_mode.setter
def alert_mode(self, value: Literal[ALERT_WINDOW, ALERT_HYSTERESIS]):
"""The alert_mode of the sensor
Could have the following values:
* ALERT_WINDOW
* ALERT_HYSTERESIS
"""
if value not in [0, 1]:
raise ValueError("alert_mode must be set to 0 or 1")
self._raw_alert_mode = value
@property
def serial_number(self):
"""A 48-bit, factory-set unique identifier for the device."""
eeprom1_data = bytearray(2)
eeprom2_data = bytearray(2)
eeprom3_data = bytearray(2)
# Fetch EEPROM registers
with self.i2c_device as i2c:
i2c.write_then_readinto(bytearray([_EEPROM1]), eeprom1_data)
i2c.write_then_readinto(bytearray([_EEPROM2]), eeprom2_data)
i2c.write_then_readinto(bytearray([_EEPROM3]), eeprom3_data)
# Combine the 2-byte portions
combined_id = bytearray(
[
eeprom1_data[0],
eeprom1_data[1],
eeprom2_data[0],
eeprom2_data[1],
eeprom3_data[0],
eeprom3_data[1],
]
)
# Convert to an integer
return combined_id
def _set_mode_and_wait_for_measurement(self, mode: int) -> float:
self._mode = mode
# poll for data ready
while not self._read_status()[2]:
time.sleep(0.001)
return self._raw_temperature * _TMP117_RESOLUTION
# eeprom write enable to set defaults for limits and config
# requires context manager or something to perform a general call reset
def _read_status(self) -> Tuple[int, int, int]:
# 3 bits: high_alert, low_alert, data_ready
status_flags = self._alert_status_data_ready
high_alert = 0b100 & status_flags > 0
low_alert = 0b010 & status_flags > 0
data_ready = 0b001 & status_flags > 0
return (high_alert, low_alert, data_ready)
# pylint: disable=no-self-use
@staticmethod
def _scaled_limit(value: float) -> int:
"""Validates for values to be in the range of :const:`-256` and :const:`255`,
then return the value divided by the :const:`_TMP117_RESOLUTION`
"""
if value not in range(-256, 255):
raise ValueError("value must be from 255 to -256")
return int(value / _TMP117_RESOLUTION)