adafruit/adafruit_circuitpython_ds18x20

CircuitPython drivers for the DS18x20 one wire temperature sensors

Introduction

CircuitPython driver for Dallas 1-Wire temperature sensor.

Dependencies

This driver depends on:

• Adafruit CircuitPython
• Adafruit OneWire

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Usage Example

import board
from adafruit_onewire.bus import OneWireBus
from adafruit_ds18x20 import DS18X20

ow_bus = OneWireBus(board.D2)
ds18 = DS18X20(ow_bus, ow_bus.scan()[0])
ds18.temperature

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

adafruit_circuitpython_ds18x20's Issues

DisplayIO Example Wanted

Add a Basic DisplayIO Based Example

We would like to have a basic displayio example for this library. The example should be written for microcontrollers with a built-in display. At a minimum it should show a Label on the display and update it with live readings from the sensor.

The example should not be overly complex, it's intended to be a good starting point for displayio based projects that utilize this sensor library. Try to keep all visual content as near to the top left corner as possible in order to best fascilitate devices with small built-in display resolutions.

The new example should follow the naming convention examples/libraryname_displayio_simpletest.py with "libraryname" being replaced by the actual name of this library.

You can find an example of a Pull Request that adds this kind of example here: adafruit/Adafruit_CircuitPython_BME680#72

We have a guide that covers the process of contributing with git and github: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

If you're interested in contributing but need additional help, or just want to say hi, feel free to join the Discord server to ask questions: https://adafru.it/discord

ValueError: Incorrect family code in device address.

Attempting to use the DS18X20 with Metro M4 Airlift Lite with circuitpython 5.0.0-beta.0 with the ds18x20_simpletest.py example. I hit this error, so am now setting a large _maximum_devices. However I now hit a different error - ValueError: Incorrect family code in device address.

>>> import time
>>> import board
>>> from adafruit_onewire.bus import OneWireBus
>>> from adafruit_ds18x20 import DS18X20
>>> ow_bus = OneWireBus(board.D5)
>>> ow_bus.maximum_devices(200)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'int' object is not callable
>>> ow_bus._maximum_devices = 200
>>> ds18 = DS18X20(ow_bus, ow_bus.scan()[0])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "adafruit_onewire/bus.py", line 156, in scan
RuntimeError: Maximum device count of 200 exceeded.
>>> ow_bus._maximum_devices = 2000
>>> ds18 = DS18X20(ow_bus, ow_bus.scan()[0])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "adafruit_ds18x20.py", line 56, in __init__
ValueError: Incorrect family code in device address.

I Keep getting this error even when the family code is right

I've been following this tutorial so far. and when I run the code, in this module I get this error Traceback (most recent call last): File "<stdin>", line 38, in <module> File "adafruit_ds18x20.py", line 84, in __init__ ValueError: Incorrect family code in device address. This is the thermostat that i'm using. Any help is greatly appreciated. I also have the resistor connected to it.

OneWireIO is not implemeted yet, state this in the Readme

When following the example from the Readme file, I get this error:

ow_bus = OneWireBus(pin.PB0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python3.9/dist-packages/adafruit_onewire/bus.py", line 69, in __init__
    self._ow = onewireio.OneWire(pin)
  File "/usr/local/lib/python3.9/dist-packages/onewireio.py", line 23, in __init__
    raise NotImplementedError("OneWire has not been implemented")
NotImplementedError: OneWire has not been implemented

This seems unavoidable, as OneWireBus calls OneWireIO here:

https://github.com/adafruit/Adafruit_CircuitPython_OneWire/blob/ecd884130f7a19def54cd2b720a7fd8b6f8c06c2/adafruit_onewire/bus.py#L69

And this happens since adafruit/Adafruit_CircuitPython_OneWire@692e01e

Then, OneWireIO will simply answer NotImplementedError:

https://github.com/adafruit/Adafruit_Blinka/blob/514f69e1d5d3ccdac2c414fad3344532671820d9/src/onewireio.py#L22-L23

So I consider that if this module cannot be used, this should be clearly stated in the Readme.

But I feel I am missing something... How did this work in the past? Seems that OneWire was not implemented neither in BusIO...

memory allocation failed, allocating 1024 bytes

Adafruit CircuitPython 3.0.3 on 2018-10-10; Adafruit Metro M0 Express with samd21g18
I get:

Traceback (most recent call last):
  File "code.py", line 7, in <module>
  File "adafruit_onewire/bus.py", line 134, in scan
MemoryError: memory allocation failed, allocating 1024 bytes

Update: same error on Adafruit CircuitPython 3.0.3 on 2018-10-10; Adafruit Trinket M0 with samd21e18

Missing Type Annotations

There are missing type annotations for some functions in this library.

The typing module does not exist on CircuitPython devices so the import needs to be wrapped in try/except to catch the error for missing import. There is an example of how that is done here:

try:
    from typing import List, Tuple
except ImportError:
    pass

Once imported the typing annotations for the argument type(s), and return type(s) can be added to the function signature. Here is an example of a function that has had this done already:

def wrap_text_to_pixels(
    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
) -> List[str]:

If you are new to Git or Github we have a guide about contributing to our projects here: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

There is also a guide that covers our CI utilities and how to run them locally to ensure they will pass in Github Actions here: https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/check-your-code In particular the pages: Sharing docs on ReadTheDocs and Check your code with pre-commit contain the tools to install and commands to run locally to run the checks.

If you are attempting to resolve this issue and need help, you can post a comment on this issue and tag both @FoamyGuy and @kattni or reach out to us on Discord: https://adafru.it/discord in the #circuitpython-dev channel.

The following locations are reported by mypy to be missing type annotations:

• adafruit_ds18x20.py:68
• adafruit_ds18x20.py:89
• adafruit_ds18x20.py:97
• adafruit_ds18x20.py:133

Asynchronous conversion?

The DS18x20 temperature conversion is quite slow, up to 750ms for 12 bit resolution and the application is unresponsive until the conversion is complete. My enhancement request is for an asynchronous conversion, much like the Arduino DallasTemperature library by Miles Burton et al.

It works something like this (I'm using the RBD::Timer library for timers to avoid delay() ):

void setup() {
    /* Start up the DallasTemperature library
     * IC Default 9 bit. If you have troubles consider upping it 12.
     * Ups the delay giving the IC more time to process the temperature measurement
     * (Miles Burton)
     * The conversion is very slow (approx. 750ms). As a workaround, the 
     * temperature conversion command is sent to all devices on the bus 
     * but the program thread is not blocked. Later, the temperatures are
     * read back one device at a time. 
     */
    sensors.begin(); 
    // Do not block during conversion (read later)
    sensors.setWaitForConversion(false);
}

void loop() {
    /* The temperature converstion takes approx. 750ms,
     * therefore the conversion is handled asynchronously.
     * The conversion is started but the program is not 
     * blocked. Later, the program gets each temperature.
     * This is a simple state machine but not implemented
     * with a formal structure.
     */
    if(thermo_timer.onRestart())
    {
        // Issue a global conversion command to all ICs on the bus
        sensors.requestTemperatures();
        thermo_conv_in_progress = true;
        thermo_conv_timer.restart();
    }

    if(thermo_conv_in_progress && thermo_conv_timer.onExpired())
    {
        thermo_conv_in_progress = false; // mark complete
        // Why "byIndex"? You can have more than one IC on the same bus.
        // 0 refers to the first IC on the wire (Miles Burton).
        temp_reading_heatsink = sensors.getTempCByIndex(HEATSINK_THERMOMETER);
        temp_reading_case = sensors.getTempCByIndex(CASE_THERMOMETER);
    }
}

I would like to help implement this but I'm quite new at CircuitPython, Git, GitHub and all that. Before starting, I would like to better define an API addition that doesn't break previous code while keeping with the learner friendly mandate of CircuitPython: keep the temperature property and add a method to kick off the conversion.

Perhaps something like this:

# keyword argument to wait, defaults to waiting
DS18X20(bus, address, wait_for_conversion=True)

    def request_temperature(self):
        # Similar to _convert_temp(self) but without the timeout check
        with self._device as dev:
            dev.write(_CONVERT)
            # EXPECTED_CONVERSION_DELAY need not be a constant,
            # it can be based on resolution as given in the datasheet.
            return time.monotonic() + EXPECTED_CONVERSION_DELAY

    @property
    def temperature(self):
        """The temperature in degrees Celsius."""
        # Caveat utilisator: if you cleared the flag and check too soon, 
        # the temperature is invalid.
        # Alternatively the bus or device can be polled to check for completion.
        # The method would still block if the routine didn't wait long enough,
        # but you would never get an invalid temperature.
        if self.wait_for_conversion:
            self._convert_temp()  
        return self._read_temp()

Thoughts? Where's the best place to discuss this? (I'm not on Discord but I can PM you my work email.)