The DS18B20 is the sensor people reach for when they want to know the temperature of something rather than the air in a room: the flow and return pipes of a heating system, a hot water tank, a freezer, an aquarium, the space under the floor. It comes in waterproof probes on a cable, it talks over a single data line, and you can hang several of them on that one line and connect it to one GPIO pin on an ESP32.

Getting one probe to show up in Home Assistant takes a few minutes. The part that trips people up comes later: with three or four probes on the same bus, which reading belongs to which pipe, and what happens when one of them is replaced. This guide covers the wiring, the ESPHome configuration, how to find and pin down each sensor's address, and the faults you are most likely to hit.

What the DS18B20 can and cannot do

From the Analog Devices product page and datasheet:

  • range from -55 °C to +125 °C;
  • ±0.5 °C accuracy from -10 °C to +85 °C (over the full range the datasheet gives a wider tolerance);
  • resolution set from 9 to 12 bits, which means steps of 0.5, 0.25, 0.125 or 0.0625 °C;
  • supply voltage from 3.0 V to 5.5 V, so it runs directly from the 3.3 V pin of an ESP board;
  • each chip has a unique 64-bit serial code, which is what lets many sensors share one bus;
  • a "parasite power" mode that takes power from the data line, so only two wires are needed.

At 12 bits, a conversion takes up to 750 ms. For heating, a freezer or a water tank that is irrelevant. For anything that needs a fast response, it is worth knowing.

A warning about cheap probes

A study by Chris Petrich bought more than 1,000 waterproof probes and bare chips from over 70 vendors in 2019. Every probe bought on eBay and AliExpress contained a counterfeit DS18B20, and almost all chips from those sites were counterfeit. Some clones do not work in parasite power mode, some are noisy, and some have offsets outside the ±0.5 °C band.

Many of them still work fine for home use. Just do not assume the datasheet accuracy applies to a probe from a marketplace. If the reading matters, check it against a reference thermometer and correct it in ESPHome (see the calibration section below).

Wiring

A DS18B20 has three connections: GND, DQ (data) and VDD. On the TO-92 package, pin 1 is GND, pin 2 is DQ and pin 3 is VDD. Waterproof probes come with three wires already attached, but colours vary between sellers, so check the pinout in the listing or with a multimeter before you power anything up.

Connect them like this:

  • VDD to 3.3 V on the ESP board;
  • GND to GND;
  • DQ to a free GPIO pin;
  • a pull-up resistor between DQ and 3.3 V.

The ESPHome docs recommend an external pull-up of about 4.7 kΩ and say values within ±1 kΩ of that generally work, unless your wires are unusually long. You need one resistor per bus, not one per sensor.

Use the three-wire connection with VDD powered. Parasite power saves one wire, but it needs a stronger pull-up during conversions, the datasheet advises against it above 100 °C, and some clones do not support it at all. On a breadboard or in a junction box, the extra wire costs nothing.

The pin you choose has to work as both input and output, because 1-Wire is bidirectional. It must also be a GPIO on the microcontroller itself, not on an I/O expander. On a classic ESP32, GPIO4 works well, for example. Avoid strapping pins.

Several probes on one bus

All sensors connect in parallel: every DQ to the same data line, every VDD to 3.3 V, every GND to GND. Run the cable as a single line from the ESP to the farthest sensor and connect the others along the way with short branches.

Do not build a star where several long cables start from the ESP and go off in different directions. Maxim's (now Analog Devices') guidelines for long 1-Wire networks describe a linear layout with branches shorter than 3 m. They call the unswitched star the hardest layout to make reliable and do not recommend it. Reflections from the end of one branch can corrupt data.

If the sensors really are in different directions, there is a simple way out in ESPHome: create several buses on different GPIO pins, one per direction. Each bus then stays a short, linear line.

ESPHome configuration for one sensor

The configuration has two parts: the bus (one_wire) and the sensor (dallas_temp).

one_wire:
  - platform: gpio
    pin: GPIO4

sensor:
  - platform: dallas_temp
    name: "Hot water tank"
    update_interval: 60s

With only one device on the bus, you do not need an address. ESPHome picks the only sensor it finds. update_interval defaults to 60 seconds, and resolution defaults to 12 bits, so you can leave both out.

Find each sensor's address

With more than one sensor, each dallas_temp entry needs either address or index. To find the addresses, flash the configuration with the one_wire bus defined. You do not need any sensor entries yet, because the bus is scanned even with no sensors configured. Then open the device logs.

At start-up, the configuration dump of the bus contains a line Found devices: followed by one line per sensor, with the address and the model, for example 0x...28 (DS18B20). The last byte of the address is the family code, and for a DS18B20 that is 28.

To tell which address is which probe, connect one probe at a time and note its address. Or warm one probe in your hand and see which reading rises. Write the address on a label and stick it to the cable. You will thank yourself when you replace one.

Configuration with several sensors

one_wire:
  - platform: gpio
    pin: GPIO4
    id: heating_bus

sensor:
  - platform: dallas_temp
    one_wire_id: heating_bus
    address: 0x1234567812345628
    name: "Heating flow"

  - platform: dallas_temp
    one_wire_id: heating_bus
    address: 0x8765432187654328
    name: "Heating return"

The addresses above are placeholders. Use the ones from your log.

You could use index: 0, index: 1 and so on instead of addresses. The ESPHome docs warn that the index follows the order of the hardware addresses, and that order can change when sensors are swapped, added or removed. With indexes, replacing one probe can silently move "flow" readings to "return", and your heating automations will then react to the wrong pipe. Addresses avoid that. When a probe dies, you update one address and nothing else moves.

one_wire_id is only required when the device has more than one bus, but setting it from the start makes adding a second bus later painless.

Calibration and lower resolution

To correct a constant offset measured against a reference thermometer, add a filter:

  - platform: dallas_temp
    one_wire_id: heating_bus
    address: 0x1234567812345628
    name: "Heating flow"
    filters:
      - offset: -0.3

Set the value from your own comparison, not from the example. If the error differs at low and high temperatures, ESPHome also has a calibrate_linear filter that takes pairs of measured and true values.

resolution can be lowered to 9, 10 or 11 bits. ESPHome then waits less for each conversion: 94 ms at 9 bits instead of 750 ms at 12. For a freezer alarm, 0.5 °C steps are plenty. For heating, the default 12 bits is usually the better choice.

Using it in Home Assistant

The sensors appear in the ESPHome integration as temperature entities in °C. A few ideas:

  • Heating: the difference between flow and return tells you how much heat the system gives off. A template sensor can calculate it, and a flow temperature that is too high can trigger a notification.
  • Freezer: a numeric state trigger above, say, -15 °C for 15 minutes, so that a door opened for a moment does not raise an alarm. Pick the threshold yourself.
  • Hot water tank: run a circulation pump or an immersion heater only when the water really needs it.

ESPHome gives these sensors the measurement state class, so Home Assistant also keeps long-term statistics for them. You get a year of history without changing any recorder settings.

Common problems

  • Found no devices! in the log: no pull-up resistor, a wrong pin, or DQ and VDD swapped. Check the wiring before the YAML.
  • 1-wire bus is held low: the data line is stuck at 0 V. Look for a short to GND, a damaged probe, or a wrong pin.
  • A reading of exactly 85 °C: that is the sensor's power-on reset value, not a measurement. ESPHome drops it when it detects a reading caused by a sensor reset. If you still see it regularly, look at the power supply and the connections.
  • Warnings about invalid CRC or scratch pad checksum: the data got corrupted on the way. Usually the cause is a too-long cable, a star layout, or a loose joint. Try a stronger pull-up within the range ESPHome recommends, shorten the branches, or split the bus.
  • Readings swapped after replacing a probe: you used index. Switch to address.
  • "Out of range" error for an index: ESPHome found fewer sensors than the index expects. Check which probe dropped off the bus.
  • Temperature a degree or more off: a counterfeit chip or a probe with a long cable in a warm spot. Compare against a reference and add an offset.