MojoScale Studio Docs
API Reference

ds18b20

DS18B20 temperature sensor module.

All modules Open Studio
Studio Docs Sensors & I/O

import ds18b20

The ds18b20 module reads Dallas/Maxim DS18B20 digital temperature sensors over a OneWire data pin. It provides a sensor-friendly API on top of the raw OneWire bus: scan attached DS18B20 ROM IDs, read Celsius/Fahrenheit values, and adjust sensor resolution.

Quick example

import ds18b20

ds18b20.begin(5)
reading = ds18b20.read()
print(reading["c"])

sensors = ds18b20.scan()
for rom in sensors:
    print(rom, ds18b20.temperature(rom))

importds18b20

DS18B20 temperature sensor module.

The ds18b20 module reads Dallas/Maxim DS18B20 digital temperature sensors over a OneWire data pin. It provides a sensor-friendly API on top of the raw OneWire bus: scan attached DS18B20 ROM IDs, read Celsius/Fahrenheit values, and adjust sensor resolution.

API 10 available

ds18b20.begin(pin: int, parasite_power: bool = None) -> None

Attach DS18B20 support to a GPIO pin.

Parameters
Name Type Pass as Required Description
pin int positional or keyword Yes GPIO number connected to the DS18B20 DQ data line.
parasite_power bool positional or keyword No Optional bool. Set True only when the sensor is powered from the data line instead of VDD. Defaults to False.
Returns

None None.

ds18b20.scan() -> list

Find DS18B20 sensors on the OneWire bus.

Only ROM IDs with the DS18B20 family code and valid Dallas CRC are returned. Each ROM is a 16-character lowercase hex string.

Returns

list List of DS18B20 ROM hex strings.

ds18b20.count() -> int

Count DS18B20 sensors on the OneWire bus.

Returns

int Integer number of discovered DS18B20 sensors.

ds18b20.convert(rom: str = None, wait: bool = None) -> bool

Start a temperature conversion.

Use this when you want to start conversion manually, do other work, and read the scratchpad later. Most scripts should use ``read()`` or ``temperature()`` instead because they start conversion and wait automatically.

Parameters
Name Type Pass as Required Description
rom str positional or keyword No Optional DS18B20 ROM ID. Omit when exactly one sensor is on the bus.
wait bool positional or keyword No Optional bool. Wait for conversion to finish before returning. Defaults to True. Keep True when parasite_power is enabled.
Returns

bool True when the conversion command was accepted and, if waiting, completed before timeout.

ds18b20.read_scratchpad(rom: str = None) -> bytes

Read and validate the DS18B20 scratchpad.

Parameters
Name Type Pass as Required Description
rom str positional or keyword No Optional DS18B20 ROM ID. Omit when exactly one sensor is on the bus.
Returns

bytes Bytes-like native value containing the 9-byte scratchpad.

ds18b20.read(rom: str = None) -> dict

Read temperature and sensor metadata.

This starts a temperature conversion, waits for it to complete, reads the scratchpad, checks its CRC, and returns a dict.

Parameters
Name Type Pass as Required Description
rom str positional or keyword No Optional DS18B20 ROM ID. Omit when exactly one sensor is on the bus.
Returns

dict Dict with ``ok``, ``rom``, ``c``, ``f``, ``raw``, ``resolution``, ``pin``, and ``parasite_power`` fields.

ds18b20.temperature(rom: str = None) -> float

Read temperature in Celsius.

Parameters
Name Type Pass as Required Description
rom str positional or keyword No Optional DS18B20 ROM ID. Omit when exactly one sensor is on the bus.
Returns

float Float temperature in degrees Celsius.

ds18b20.set_resolution(resolution: int, rom: str = None, persist: bool = None) -> bool

Set DS18B20 conversion resolution.

Parameters
Name Type Pass as Required Description
resolution int positional or keyword Yes Resolution in bits. Must be 9, 10, 11, or 12.
rom str positional or keyword No Optional DS18B20 ROM ID. Omit when exactly one sensor is on the bus.
persist bool positional or keyword No Optional bool. When True, copy the setting to the sensor's EEPROM. Defaults to False.
Returns

bool True when the setting was written.

ds18b20.crc8(data: list) -> int

Calculate the Dallas/Maxim OneWire CRC-8.

Parameters
Name Type Pass as Required Description
data list positional or keyword Yes Bytes, string, or list of integer byte values.
Returns

int Integer CRC-8 value from 0 to 255.

ds18b20.info() -> dict

Return DS18B20 module state.

Returns

dict Dict with ``initialized``, ``pin``, ``parasite_power``, and ``default_resolution`` fields.