How to interface a DS18B20 temperature sensor with MicroPython's Onewire driver

The 1-Wire protocol is a proprietary standard for serial data communication from Maxim Integrated. This protocol is a low-speed, half-duplex, bidirectional, low-power master-slave data communication standard used by several devices, including temperature sensors, real-time clocks, EEPROMs, identification (intellectual property protection) devices, timers, and iButtons.

There can be only one master device on a 1-wire standard bus, with up to 100 slave devices. Serial communication is fully controlled and managed by the master device. The protocol uses no clock signal and data is communicated in fixed timeslots. This means the slave devices must sync with the master for the read and write operations.

The standard 1-wire bus has a minimum of two wires: a data line and the ground return. Most 1-wire devices have three terminals. The third line is added for a positive supply.

For a bus with two lines, the 1-wire slave’s VDD and GND terminals are connected to the ground return. The signal and data are provided by the data line. This is called a parasitic powering mode.

For a bus with three lines, the VDD is also traced to the positive supply. This is called conventional powering. The mode is considered more reliable than parasitic powering because the latter is dependent on the timing of the pull-up over the data line.

Some 1-wire devices have five terminals for greater access to lines for sequence detection.

As the 1-Wire is a proprietary protocol, it has no hardware implementation in microcontrollers. However, it is implemented in the software of most microcontrollers and single-board computers because of the popularity of 1-wire devices — such as iButtons.

MicroPython implements the 1-Wire protocol in its software, using bit-banging. The standard can be applied to any output-capable pin. In this article, we’ll cover MicroPython’s Onewire driver, discussing how it can be used to interface a DS18B20 temperature sensor.

The protocol
For the 1-Wire protocol, data communication with the slave devices is controlled by the master. As there’s no clock signal, the slaves must synchronize their internal clock with the signals from the master device. The master can be a microcontroller, microcomputer, or desktop computer.

The master uses five types of signals for communicating with the slave devices: Reset, Presence, Write 0, Write 1, and Read.

The master begins communication with the slaves with a reset signal. In response, the slaves will pull down the data line, which is sampled by the master as a presence signal. Once the presence of at least one slave on the bus is confirmed, the master starts sending the ROM commands.

The first command is the search ROM command, which looks for the ROM addresses of the connected slaves. Each 1-wire slave is identified by a 64-bit ROM address. When the master receives the ROM addresses of the connected slaves, it looks for any address conflicts. The addresses are further used by the master device to identify a 1-wire device and communicate the function commands associated with it.

The ROM commands are 8-bits long. All data, whether written to or read from the slave devices, is also in groups of 8 bits.

By default, the data line is pulled high with the help of an external pull-up resistor. Without this pull-up, data communication would not be possible.

The reset is the first signal sent by the master. It does so by pulling down the data line for 480 us. It then releases the data line, allowing the pull-up resistor to pull the data line high.

The slave devices have a basic monostable multivibrator to detect the state of the data line and the duration of the pulses. When connected to the bus, the slaves can detect a reset signal and respond by pulling the data line low for 60~240 us.

If, after a reset signal, the data line is still pulled high, the master assumes no slaves are connected to the bus.
If, after a reset signal, the data line is pulled low, the master recognizes that at least one slave is connected to the bus.

After confirming the presence of a 1-wire slave, the master starts writing ROM and function commands. In response to these commands, the master will read from the slave devices. As mentioned, the commands and data are in groups of 8 bits. They’re communicated as packets where the errors in each 8-bit block are reviewed with a cyclic redundancy check (CRC).

At the signal level, each bit is communicated in a fixed 60 us time slot or shorter if the bus is overdriven. There’s an interval of 1 us between each time slot, so the pull-up resistor can pull the data line high between the communication of each bit.

To write ‘0,’ the master pulls the data line down for the full 60 us time slot, then releases it for the 1 us interval between time slots.
To write ‘1,’ the master pulls the data line down for 15 us, then releases it for a 1us interval between time slots.
The slaves sample bits from the master after 30 us of each time slot.

At this point, the master reads from the slave again, bit by bit. The data from the slave continues to be communicated in groups of 8 bits. The master pulls down the data line for 1 us and releases it, and then samples the data from the bus after 15 us.

If the slave writes ‘0’ over the bus, it keeps the line pulled down for the full 60 us time slot. It then releases the data line for a 1 us interval between time slots.
If the slave writes ‘1’ over the bus, it keeps the line pulled down for 15 us. It then releases the data line for the pull-up resistor to pull the data line high.
The master samples the data after 15 us of each time slot.

This is how the master communicates the reset and presence, write 1, write 0, and read signals with the 1-wire slaves. The protocol is implemented by microcontrollers and computers using bit-banging or the universal asynchronous receiver-transmitter (UART).

Learn more about the 1-Wire protocol from here.

MicroPython’s Onewire driver
MicroPython implements the Onewire driver as a library package, which is now part of the standard MicroPython firmware. The library is called onewire. It can be imported in a MicroPython script using this statement:

import onewire

The onewire driver includes two libraries: onewire and ds18x20. The Onewire class is a generic implementation of the 1-Wire protocol. The ds18x20 is a specific implementation of the protocol for reading the temperature from 1-wire digital thermometers, like the DS18B20 and DS18S20.

These libraries can be accessed using these statements:

import onewire
import ds18x20
import onewire, ds18x20

The Onewire driver is dependent on MicroPython firmware’s time and machine modules. Three constants are used for the ROM commands, listed below.

The driver’s Onewire class is instantiated with a constructor function. The constructor has this prototype:

OneWire(pin)

The constructor method takes only a single argument (i.e. the pin where the 1-Wire protocol’s implemented). A pin passed as an argument must be the output-capable.

The other methods provided by the Onewire class are as follows:

reset(): sends the reset signal. If any 1-wire slave is detected, it returns True. Otherwise, it returns False. This method does not take any arguments.
readbit(): reads a bit from the data line. It does not take any arguments. It returns a boolean value, which is True if the read bit is ‘1’ or False if the read bit is ‘0.’
readbyte(): reads a byte from the data line. It calls the read_bit() method eight times and stores each bit in a byte object. The byte is returned by the method.
readinto(count): reads the specified number of bytes from the data line. It iterates the read_byte() method for the number of times specified as an argument. The bytes are stored in a buffer object, which is returned by the method.
writebit(value): writes a bit, ‘0’ or ‘1,’ to the data line. It takes a boolean argument.
writebyte(value): writes a byte to the data line. It takes a byte object as an argument.
write(buf): writes a group of bytes to the data line. It takes a buffer object as an argument. All the bytes stored in the buffer object are written to the data line.
select_rom(rom): selects a specific 1-wire slave to talk to. The slave is identified by its 64-bit address. This method takes an 8-byte long bytearray as an argument. The bytearray is called a rom object.
crc8(data): used to perform a cyclic redundancy check on the data. It takes a buffer object as an argument.
scan(): used to scan the 1-wire slaves connected to the bus. It returns a list of ROM addresses for all of the attached slaves. Each ROM address is an 8-byte long bytearray.
_search_rom(l_rom, diff): used to detect ROM addresses, checking if each one is a valid 64-bit ROM address or not. It’s called the within scan() method, used for searching attached 1-wire devices.

The ds18x20 library is specially written to attain temperature readings from the DS18B20 and DS18S20 digital thermometers. The library makes use of MicroPython library’s const class.

The following three constants for the DS18X20 function commands are used by the library.

The DS18X20 class is instantiated using a constructor function. The constructor has this prototype:

DS18X20(onewire)

The constructor takes a one-wire object as an argument. The other methods provided by the DS18X20 class include:

scan(): used to scan the 1-wire temperature sensor connected to the bus. It reads the ROM addresses of the attached 1-wire devices, checking if any address starts with 0x10, 0x22, or 0x28. The first 8 bits of the ROM address are a family code: 0x10 is the family code for the DS18S20, 0x22 is the family code for the DS1922, and 0x28 is the family code for the DS18B20.
read_scratch(): reads the contents of the DS18x20 scratchpad. The least significant bit is read first until the ninth byte. The ninth byte is the CRC byte.
write_scratch(): writes three bytes of data to the DS18x20 scratchpad. The least significant bit is sent first. The first byte is written to the TH register, the second bit to the TL register, and the third bit to the configuration register.
convert_temp(rom=None): sends the function command to start the temperature conversion to an attached DS18X20 device. This method returns nothing. Instead, it initiates the DS18X20 device to start the temperature conversion. This method does not allow for selecting a specific 1-wire temperature sensor. The DS18x20 sensors attached to the 1-wire bus are commanded to start temperature conversion.
read_temp (rom=None): reads the temperature from the specified DS18X20 device once the conversion is complete. Otherwise, it returns nothing. The specific DS18x20 sensor is selected by passing the ROM address as an argument. If the ROM address is not passed, any DS18x20 sensor attached to a 1-wire bus is automatically selected.

The libraries and classes discussed here are a part of the official MicroPython framework. There are also some board-specific drivers for 1-wire and DS18x20 thermometers. These drivers must be uploaded to the respective board.

These board-specific drivers might have different or additional class methods, such as for the conversion of raw temperature reading to degree centigrade. The Onewire driver in the official MicroPython framework can be browsed from the micropython-x.x.x\drivers\onewire folder.

MicroPython’s Onewire driver in ESP8266 and ESP32
MicroPython’s Onewire driver works on all of the pins of ESP8266 and ESP32. Here’s an example:

from machine import Pin
import onewire
ow = onewire.OneWire(Pin(12))
ow.scan()
ow.reset()
ow.readbyte()
ow.writebyte(0x12)
ow.write(‘123’)
ow.select_rom(b’12345678′)

A valid example using the ds18x20 library:

import time, ds18x20
ds = ds18x20.DS18X20(ow)
roms = ds.scan()
ds.convert_temp()
time.sleep_ms(750)
for rom in roms:
print(ds.read_temp(rom))

DS18B20 temperature sensor
DS18B20 is a 1-wire digital thermometer from Maxim Integrated. The sensor has multi-drop capability, enabling interfacing of several DS18B20 sensors on a single data line as a distributed network. It outputs a temperature measurement with scales from 9 to 12-bit resolution. The operating temperature range of DS18B20 is -55˚ to 125˚ C with an accuracy of +/-0.5˚ C. The default resolution of the sensor is 12 bits, which measures temperature with a precision of 0.0625˚ C.

The sensor takes less than 750 ms to convert a reading. Therefore, it’s possible to attain temperature measurements at a one-second interval from the sensor network.

The operating voltage of DS18B20 is 3.3~5V, and the current consumption is about 1mA. This temperature sensor can easily interface with any microcontroller or microcomputer, provided a software library for the 1-Wire protocol is available.

The sensor comes in two types of packages, and one is waterproof.

The DS18B20 has this pin diagram:

In the waterproof version of the sensor,

The pins are identified by color-coding for the waterproof sensor. The GND, CDD, and data D lines are black, red, and yellow wires.

Getting ESP8266 and ESP32 ready
MicroPython IDE must be ready to write, edit, and upload codes. It’s also possible to use uPyCraft IDE or Thonny IDE for the software. With the help of the respective IDE, upload the MicroPython firmware to ESP8266 or ESP32. Learn how to get uPyCraft IDE ready and upload MicroPython firmware to ESP8266/ESP32.

Interfacing DS18B20 with ESP8266
DS18B20 can be interfaced with ESP8266 in parasitic or conventional powering mode. For the parasitic powering mode, connect DS18B20’s out pin with any of the ESP8266’s GPIOs.

Below, the out pin is connected to GPIO4. Pull the data out pin high by connecting it to ESP8266’s 3V pin via the 4.7K resistor. Connect DS18B20’s GND and VDD pins to ESP8266’s ground.

For the conventional powering mode, connect DS18B20’s VDD pin to the 3V instead of the GND.

Interfacing DS18B20 with ESP32
DS18B20 can be interfaced with ESP32 in parasitic or conventional powering mode. For the parasitic powering mode, DS18B20’s VDD and GND are connected to the ground. DS18B20’s data out pin connects to any of ESP32’s GPIOs pulled high via the 4.7K resistor.

For conventional powering, connect the DS18B20’s VDD to ESP32’s instead of the ground.

MicroPython script

import machine, onewire, ds18x20, time
ds = ds18x20.DS18X20(onewire.OneWire(machine.Pin(4)))
roms = ds.scan()
print(‘Found DS devices: ‘, roms)
while True:
ds.convert_temp()
time.sleep_ms(750)
for rom in roms:
print(rom)
print(ds.read_temp(rom))

Results

Interfacing multiple DS18B20 with ESP8266
Many DS18B20 sensors can be connected to the same 1-wire. The MicroPython library can read temperatures from all of the attached sensors simultaneously.

For the parasitic powering mode, make the same circuit connections as shown below.

The conventional powering mode is recommended when multiple DS18B20s are connected to the 1-wire bus. For the conventional powering mode, make the circuit connections as shown below.

Interfacing multiple DS18B20 with ESP32
Several DS18B20 sensors can be connected to ESP32. For the parasitic powering mode, make the circuit connections shown below.

For the conventional powering mode, make the circuit connections shown below.

MicroPython script

Results

Conclusion
MicroPython has a well-written driver for 1-wire devices and a separate driver for DS18BX20 devices — which works with DS18B20, DS1922, and DS18S20.

It’s easy to interface DS18X20 digital thermometers with ESP8266 and ESP32. Multiple DS18X20 devices can be interfaced to the same 1-wire bus without any issues. The same MicroPython code works for single and multiple DS18X20 thermometers.