default

Example of the component esp-idf-lib/onewire v1.2.1
# 1-Wire bus example

## What it does

The example puts one DS18B20 on a 1-Wire bus, reads its temperature once a
second and prints it. The bus is bit-banged by the `onewire` component, the
sensor is driven by the `ds18x20` component, so the example doubles as a
demonstration of how a device driver uses the bus.

The bus pin and the ROM address of the sensor are taken from `menuconfig`; the
address is the part that has to be changed, because it is unique to every
sensor.

## Requirements

* An ESP32 series board and a DS18B20 (or a DS18S20, a DS1822, a DS1825 or a
  MAX31850 — anything `ds18x20` understands).
* A pull-up resistor from DQ to 3.3 V. The driver enables the internal pull-up of
  the pin, which is enough for one sensor on short leads, but a 4.7 kΩ external
  resistor is what the datasheet asks for and what makes it reliable.

## Wiring

| Signal | Default pin | Where it comes from |
| --- | --- | --- |
| DQ | 17 | `CONFIG_EXAMPLE_ONEWIRE_GPIO` |
| VDD | 3.3 V | — |
| GND | GND | — |

The default depends on the target: 17 on ESP32, ESP32-S2 and ESP32-S3, 4 on
ESP32-C2, C3, C5, C6, C61, H2 and P4.

A DS18B20 in the 3-pin package is powered from VDD and GND. The 2-pin version
is powered from the bus itself (parasitic power) and needs a strong pull-up
during the conversion; the `ds18x20` driver handles that when it is asked to
wait for the conversion, but the external transistor of the datasheet is still
the reliable way to do it.

## Configure, build, flash

```sh
idf.py set-target esp32
idf.py menuconfig
```

Under `Example configuration`:

* `GPIO Number of 1-Wire bus, or DQ` — the pin the sensor hangs on
* `Address of the sensor` — the 64-bit ROM code of your sensor

The ROM code printed by the scanner in the `ds18x20` component's `default`
example is exactly the value to paste here. A wrong address means no answer,
not a wrong temperature.

Then:

```sh
idf.py build flash monitor
```

## Example output

```
I (1234) ds18x20_test: Sensor 27041685c771ff28: 22.50°C
I (2234) ds18x20_test: Sensor 27041685c771ff28: 22.44°C
```

If the sensor does not answer, the error is printed with its name, for example
`ESP_ERR_INVALID_CRC` (the ROM code or the wiring is wrong) or
`ESP_ERR_INVALID_RESPONSE` (the sensor did not convert, which happens to a
parasitically powered one without a strong pull-up).

## Notes

* The address is printed as eight bytes in the order the bus sends them, so the
  first two characters are the family code (`28` for a DS18B20).
* Only one sensor is read here to keep the example short. A bus with several
  sensors is the `multi` example of the `ds18x20` component.
* The internal pull-up is weak (~45 kΩ). With longer wires, several sensors or
  parasitic power, "random" CRC errors are almost always the pull-up and the
  wiring, not the driver.

To create a project from this example, run:

idf.py create-project-from-example "esp-idf-lib/onewire=1.2.1:default"

or download archive (~3.58 KB)