DS18B20 library/driver for Raspberry Pi using the w1_therm kernel driver
Project description
DS18B20 library/driver for Raspberry Pi using the w1_therm kernel driver
Skip to API documentation
This module provides a clean and mostly complete (*) API for DS18B20 temperature sensors using the w1_therm kernel driver. It also provides a command line interface for interactive dev/debug.
Supports:
- Reading temperatures
- Bulk parallel conversion of temperatures for all sensors on the bus
- Resolution setting and Alarm thresholds setting in scratchpad
- Setting and measuring actual conversion (temperature measurement) time
- Scratchpad save/restore to/from EEPROM
- Multiple w1 busses
(*) Not supported:
- Alarm search - I've not found any useful documentation for triggering an alarm search nor reading back the in-alarm sensor list. I'm happy to add the feature if I only knew how.
- 'features' register (conversion error check and poll for completion)
- async_io (just needs development)
- Other sensor models
Tested on Python 3.9.2 and kernel version 6.1.21-v7+ #1642 SMP Mon Apr 3 17:20:52 BST 2023, and should work on similar kernel versions since about 2020.
Do read the fine datasheet.
Command Line Interface and Demo
Once installed (pip install DS18B20), a cli tool is available. The cli tool provides some useful debug and configuration features (such as setting and permanently saving the resolution setting), and also a few demonstration cases (such as triggering a bulk/parallel conversion on multiple sensors and reading back their values).
$ DS18B20cli -h
usage: DS18B20cli [-h] [-m MODE] [-n NAME] [-r RESOLUTION] [-L TL] [-H TH] [-c CONV_TIME] [-v] [-V] [DeviceID]
DS18B20 driver and CLI/demo for Raspberry Pi
Modes:
0: Dump info for all sensors (-m 0) (DeviceID is optional, ignored)
1: Get current temp (-m 1)
2: Read scratchpad (-m 2)
3: Get current resolution (-m 3)
4: Set resolution (-m 4 -r 9)
5: Get current alarm temps (-m 5)
6: Set alarm temps (-m 6 -L 20 -H 30)
7: Send bulk_convert_trigger (-m 7)
8: Save scratchpad to EEPROM (-m 8)
9: Restore EEPROM to scratchpad (-m 9)
10: Get current conversion time (-m 10)
11: Set conversion time or start measurement (-m 11 -c 1)
12: Get parasitic/external power status (-m 12)
20: Minimal example for README (-m 20)
21: Demonstrate saving alarm/resolution to EEPROM and restoring (-m 21)
22: Demonstrate bulk/parallel temperature conversions and sensor reads (-m 22)
1.1
positional arguments:
DeviceID ID of target device, eg 28-0b2280337113
optional arguments:
-h, --help show this help message and exit
-m MODE, --mode MODE Test mode select (default 0)
-n NAME, --name NAME Name of the sensor to be displayed (default DS18B20)
-r RESOLUTION, --resolution RESOLUTION
Resolution value (9, 10, 11, or 12) to be set with --mode 4 (default 12)
-L TL, --TL TL TL alarm value (degrees C) to be set with --mode 6 (default -25)
-H TH, --TH TH TH alarm value (degrees C) to be set with --mode 6 (default 50)
-c CONV_TIME, --conv-time CONV_TIME
Conversion time setting or trigger measurement operation (default 0 - set to spec value)
-v, --verbose Print debug-level status and activity messages
-V, --version Print version number and exit
A Minimal Example
In its simplest form, to use this library simply declare (instantiate) a sensor using its ID then issue a read_temperature() call. The cli tool mode 20 demonstrates this:
if args.mode == 20: # Minimal example for README
sensor = DS18B20(args.DeviceID, args.name)
logging.info (f"Current temperature for sensor {sensor.device_name} / {sensor.device_id}: {sensor.read_temperature(tempunits='F'):7.3f} F")
... And resultant output:
$ DS18B20cli 28-0b228004203c --name "My_Sensor" --mode 20
INFO:root:Current temperature for sensor My_Sensor / 28-0b228004203c: 76.212 F
Useful for debug
Mode 2 calls read_scratchpad()
which invokes a dump and parse of a sensor's return results register, w1_slave
:
$ DS18B20cli 28-0b228004203c --name "My_Sensor" --mode 2 --verbose
DEBUG:root:28-0b228004203c / My_Sensor - w1_slave file content:
8b 01 3c 0f 7f ff 7f 10 6c : crc=6c YES
8b 01 3c 0f 7f ff 7f 10 6c t=24687
DEBUG:root:28-0b228004203c / My_Sensor - temperature code: 01 8b 24.688 C, 76.438 F, 297.837 K
DEBUG:root:28-0b228004203c / My_Sensor - High alarm limit: 3c 60 C, 140.000 F, 333.150 K
DEBUG:root:28-0b228004203c / My_Sensor - Low alarm limit: 0f 15 C, 59.000 F, 288.150 K
DEBUG:root:28-0b228004203c / My_Sensor - Resolution: 7f 12
DEBUG:root:28-0b228004203c / My_Sensor - Sensor root directory: /sys/bus/w1/devices/28-0b228004203c
DEBUG:root:28-0b228004203c / My_Sensor - Bus master root directory: /sys/bus/w1/devices/w1_bus_master1
INFO:root:['8b', '01', '3c', '0f', '7f', 'ff', '7f', '10', '6c', ':', 'crc=6c', 'YES']
Mode 0 (the default mode) invokes a similar dump for every sensor found on the host, across all w1 busses, and includes conversion time and external power status:
$ DS18B20cli
DEBUG:root:
Sensor </sys/bus/w1/devices/28-0b228004203c> on bus master </sys/bus/w1/devices/w1_bus_master1>:
DEBUG:root:28-0b228004203c / DS18B20 - w1_slave file content:
8c 01 3c 0f 7f ff 7f 10 bc : crc=bc YES
8c 01 3c 0f 7f ff 7f 10 bc t=24750
DEBUG:root:28-0b228004203c / DS18B20 - temperature code: 01 8c 24.750 C, 76.550 F, 297.900 K
DEBUG:root:28-0b228004203c / DS18B20 - High alarm limit: 3c 60 C, 140.000 F, 333.150 K
DEBUG:root:28-0b228004203c / DS18B20 - Low alarm limit: 0f 15 C, 59.000 F, 288.150 K
DEBUG:root:28-0b228004203c / DS18B20 - Resolution: 7f 12
DEBUG:root:28-0b228004203c / DS18B20 - Sensor root directory: /sys/bus/w1/devices/28-0b228004203c
DEBUG:root:28-0b228004203c / DS18B20 - Bus master root directory: /sys/bus/w1/devices/w1_bus_master1
DEBUG:root:28-0b228004203c / DS18B20 - Current conversion time: 750
DEBUG:root:28-0b228004203c / DS18B20 - External power status: 1
DEBUG:root:
Sensor </sys/bus/w1/devices/28-0b2280337113> on bus master </sys/bus/w1/devices/w1_bus_master1>:
DEBUG:root:28-0b2280337113 / DS18B20 - w1_slave file content:
7a 01 3c 0f 7f ff 7f 10 08 : crc=08 YES
7a 01 3c 0f 7f ff 7f 10 08 t=23625
DEBUG:root:28-0b2280337113 / DS18B20 - temperature code: 01 7a 23.625 C, 74.525 F, 296.775 K
DEBUG:root:28-0b2280337113 / DS18B20 - High alarm limit: 3c 60 C, 140.000 F, 333.150 K
DEBUG:root:28-0b2280337113 / DS18B20 - Low alarm limit: 0f 15 C, 59.000 F, 288.150 K
DEBUG:root:28-0b2280337113 / DS18B20 - Resolution: 7f 12
DEBUG:root:28-0b2280337113 / DS18B20 - Sensor root directory: /sys/bus/w1/devices/28-0b2280337113
DEBUG:root:28-0b2280337113 / DS18B20 - Bus master root directory: /sys/bus/w1/devices/w1_bus_master1
DEBUG:root:28-0b2280337113 / DS18B20 - Current conversion time: 750
DEBUG:root:28-0b2280337113 / DS18B20 - External power status: 1
References
- https://www.analog.com/media/en/technical-documentation/data-sheets/DS18B20.pdf
- https://docs.kernel.org/w1/slaves/w1_therm.html
- https://docs.kernel.org/w1/w1-generic.html
- https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-driver-w1_therm
Links to classes, methods, and functions
- ds18b20
- read_temperature
- read_temperature2
- read_scratchpad
- get_resolution
- set_resolution
- get_alarm_temps
- set_alarm_temps
- copy_scratchpad
- recall_e2
- bulk_convert_trigger
- bulk_convert_status
- get_conv_time
- set_conv_time
- get_ext_power
Class DS18B20 (device_id, device_name='DS18B20') - DS18B20 library/driver for Raspberry Pi using the w1_therm kernel driver
Parameters
device_id
(str)
- As listed in /sys/bus/w1/devices/, eg '28-0b228004203c'
device_name
(str, default 'DS18B20')
- User friendly name for the sensor
Class variables
device_id
(str)
- device_id from sensor instantiation
device_name
(str, default 'DS18B20')
- device_name from sensor instantiation
sensor_path
(Path)
- full pathlib path to the sensor directory
bus_master_path
(Path)
- full pathlib path the w1 bus master for the sensor
read_temperature (tempunits='C') - Return the temperature from w1_slave file, with CRC check
DS18B20() class member function
Parameter
tempunits
(str, default 'C')
- Must be 'C', 'F' or 'K', else ValueError is raised.
Returns
- (float) Read temperature in tempunits
- (int) -255: CRC_ERROR
- (int) -256: READ_ERROR
- Raises
ValueError
if tempunits is not valid
read_temperature2 (tempunits='C') - Return the temperature from temperature file. Used with bulk_convert_trigger().
DS18B20() class member function
If a bulk_convert_trigger() was previously executed, return the previously captured temperature, else take and return a new measurement.
Parameter
tempunits
(str, default 'C')
- Must be 'C', 'F' or 'K', else ValueError is raised.
Returns
- (float) Read temperature in tempunits
- (int) -256: READ_ERROR
- Raises
ValueError
if tempunits is not valid
read_scratchpad () - Return the w1_slave file line 1. Forces a new temperature conversion.
DS18B20() class member function
With debug logging, logs full w1_slave file, temperature (bytes 0 & 1), TH and TL (bytes 2 & 3), and resolution in the config register (byte 4).
Returns
- (str) Just line 1 (9 bytes and CRC calc/confirmation) from the w1_slave file (not the second line which include 't=xxxxx')
- (int) -256: READ_ERROR
get_resolution () - Return the current resolution setting in the config register
DS18B20() class member function
Returns
- (int) Current resolution setting in the config register, eg 12
set_resolution (resolution) - Set the configuration register resolution field. Requires root privilege (sudo).
DS18B20() class member function
Parameter
resolution
(int or str)
- 9, 10, 11, or 12
Returns
- (int) New resolution setting, eg 12
get_alarm_temps () - Return the current alarm settings
DS18B20() class member function
Returns
- (str) Current alarm settings pair, eg '-15 20'
- Values are degrees C
set_alarm_temps (TL, TH) - Set the alarm TL and TH registers. Requires root privilege (sudo).
DS18B20() class member function
Values must be between -55C and +125C. w1_therm sets TL to the lower of the two temps, TH to the higher.
Parameters
TL
(int or str)
- Low temp alarm threshold in degrees C
TH
(int or str)
- High temp alarm threshold in degrees C
Returns
- (str) The newly set alarm settings pair, eg '-15 20'
- Raises
ValueError
if TL or TH value is not valid or out of range
copy_scratchpad () - write scratchpad TH, TL, and resolution to EEPROM. Requires root privilege (sudo).
DS18B20() class member function
Returns
- None
recall_E2 () - Restore EEPROM TH, TL, and resolution to scratchpad. Requires root privilege (sudo).
DS18B20() class member function
Returns
- None
bulk_convert_trigger () - Trigger parallel temp conversions for all sensors on this sensor's bus.
DS18B20() class member function
Requires root privilege (sudo), or <chmod 666 /sys/bus/w1/devices/w1_bus_masterX/therm_bulk_read>. Note that the chmod must be redone after each boot.
Follow with calls to .read_temperature2() for each sensor on the bus.
Returns
- (int) 1 on successful trigger. Returns after the parallel conversion time of all sensors on the bus.
- (int) 0 if trigger was not successful
- (int) -1 if at least one sensor is still in conversion
bulk_convert_status () - Return the status of bulk/parallel sensor conversions and reading on this sensor's bus.
DS18B20() class member function
Returns
- (int) 1 if any sensor on this sensor's bus has not yet be read with read_temperature2()
- (int) 0 if all sensors on this sensor's bus have been read
- (int) -1 if at least one sensor is still in conversion
get_conv_time () - Return the current conversion time setting
DS18B20() class member function
Returns
- (int) Currently set conversion time in milliseconds, eg 750
set_conv_time (conv_setting) - Set the conversion time for temperature measurements. Requires root privilege (sudo).
DS18B20() class member function
Parameter
conv_setting
(int or str)
- 0: Set the default conversion time from the datasheet based on the current resolution (eg 750ms for 12-bit resolution)
- 1: Trigger measurement of the actual required conversion time, and set future conversions to the measured time. Note that this value is guardbanded 20% higher than the actual measured time, and thus may be higher than the specification time.
- >1: Set conversion time to
conv_setting
, resolution milliseconds
Returns
- (int) Currently set conversion time in milliseconds as a result of the
conv_setting
operation
get_ext_power () - Return the external power status
DS18B20() class member function
Returns
- (int) 0: Parasitic powered
- (int) 1: Externally powered
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for DS18B20_driver-1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6624e6d435f9b6574e5216e34e0aa1225885fc53dc3779460a85dcb6df1ebdbd |
|
MD5 | d5a9f1fe7146380b7d4782aaed913a6a |
|
BLAKE2b-256 | c45a7f96f67a046fd0577b678096031dbc6057a5fa2cfc2d85a5ff5d797a49d0 |