:mod:`ds18x20` --- DS18x20 temperature sensor driver
====================================================

.. module:: ds18x20
   :synopsis: DS18x20 temperature sensor driver

The :mod:`ds18x20` module provides a driver for the Maxim/Dallas DS18B20,
DS18S20 and DS1822 1-Wire digital temperature sensors. It is built on top of
the :mod:`onewire` module and supports multiple sensors sharing a single bus.

Example::

    import time
    from machine import Pin
    from onewire import OneWire
    from ds18x20 import DS18X20

    ds = DS18X20(OneWire(Pin(15)))
    roms = ds.scan()

    ds.convert_temp()
    time.sleep_ms(750)
    for rom in roms:
        print(rom, ds.read_temp(rom))

Classes
-------

.. class:: DS18X20(onewire: OneWire)

   Construct a DS18x20 driver bound to the given `onewire.OneWire` bus.
   Multiple DS18x20 sensors may share the same bus.

   .. method:: scan() -> list[bytearray]

      Search the underlying 1-Wire bus and return a list of ROM codes that
      correspond to DS18x20-family devices. Only ROMs whose family code is
      ``0x10`` (DS18S20), ``0x22`` (DS1822) or ``0x28`` (DS18B20) are
      returned; other 1-Wire devices on the same bus are filtered out.

   .. method:: convert_temp() -> None

      Issue a temperature conversion command to **all** DS18x20 sensors on
      the bus simultaneously (using SKIP ROM). After calling this method
      you must wait for the conversion to complete (up to 750 ms at the
      default 12-bit resolution) before calling :meth:`read_temp`.

   .. method:: read_scratch(rom: bytes | bytearray) -> bytearray

      Read the 9-byte scratchpad from the device addressed by *rom* and
      return it as a ``bytearray``. The scratchpad CRC is verified;
      raises :exc:`Exception` with the message ``"CRC error"`` on a CRC
      mismatch.

      .. note::

         The returned buffer is the driver's internal buffer and is
         overwritten by subsequent calls.

   .. method:: write_scratch(rom: bytes | bytearray, buf: bytes | bytearray) -> None

      Write 3 bytes to the scratchpad of the device addressed by *rom*.
      *buf* must contain the high alarm trigger (TH), low alarm trigger
      (TL) and configuration register values.

   .. method:: read_temp(rom: bytes | bytearray) -> float

      Read the most recently converted temperature from the device
      addressed by *rom* and return it in degrees Celsius as a
      ``float``. Handles both DS18S20 (family code ``0x10``) and DS18B20
      / DS1822 (family codes ``0x28`` / ``0x22``) encodings, including
      negative temperatures.

      Call :meth:`convert_temp` and wait for the conversion to finish
      before calling this method.