mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-24 17:08:15 +01:00
docs for one-wire platform change (#3911)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Co-authored-by: Samuel Sieb <samuel@sieb.net>
This commit is contained in:
Samuel Sieb
GitHub
parent
66ab69f13f
commit
101005f1f1
BIN
components/images/dallas-log.png
Normal file
BIN
components/images/dallas-log.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
52
components/one_wire.rst
Normal file
52
components/one_wire.rst
Normal file
@ -0,0 +1,52 @@
|
||||
.. _one_wire:
|
||||
|
||||
1-Wire Bus
|
||||
==========
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up a Dallas (Analog Devices) 1-Wire bus to communicate with 1-wire devices in ESPHome
|
||||
:image: one-wire.svg
|
||||
:keywords: Dallas, onewire, 1-wire
|
||||
|
||||
The ``one_wire`` component allows you to use supported 1-Wire devices in ESPHome.
|
||||
The 1-Wire bus the devices are connected to should have an external pullup resistor of
|
||||
about 4.7KΩ. For this, connect a resistor of *about* 4.7KΩ between ``3.3V``
|
||||
and the data pin. Values ± 1KΩ will, in most cases, work fine as well,
|
||||
if you don't have massively long wires.
|
||||
|
||||
GPIO
|
||||
----
|
||||
|
||||
The ``gpio`` platform uses the CPU to generate the bus signals on a GPIO pin.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
one_wire:
|
||||
- platform: gpio
|
||||
pin: GPIOXX
|
||||
|
||||
Configuration variables:
|
||||
************************
|
||||
|
||||
- **pin** (**Required**, number): The pin the sensor bus is connected to. Please note that 1-wire is a bi-directional bus so it requires both input and output from the pin.
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Required if you have multiple busses.
|
||||
|
||||
|
||||
Getting Sensor IDs
|
||||
******************
|
||||
|
||||
In order to find the addresses, simply start the firmware on your
|
||||
device with a configured one_wire hub and observe the log output.
|
||||
Note that you don't need to define the individual sensors just yet, as
|
||||
the scanning will happen even with no sensors configured.
|
||||
For example, you will see something like this:
|
||||
|
||||
.. figure:: images/dallas-log.png
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :apiref:`one_wire/one_wire_bus.h`
|
||||
- :ghedit:`Edit`
|
||||
- `Guidelines for Reliable Long Line 1-Wire Networks <https://www.analog.com/en/technical-articles/guidelines-for-reliable-long-line-1wire-networks.html>`__
|
||||
@ -1,170 +0,0 @@
|
||||
Dallas Temperature Sensor
|
||||
=========================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up Dallas temperature sensor hubs that can
|
||||
expose many temperature sensors on a single pin using the 1-Wire protocol.
|
||||
:image: dallas.jpg
|
||||
:keywords: Dallas, ds18b20, onewire
|
||||
|
||||
.. _dallas-component:
|
||||
|
||||
Component/Hub
|
||||
-------------
|
||||
|
||||
The ``dallas`` component allows you to use your
|
||||
`DS18b20 <https://www.adafruit.com/product/374>`__
|
||||
(`datasheet <https://datasheets.maximintegrated.com/en/ds/DS18B20.pdf>`__)
|
||||
and similar 1-Wire temperature sensors.
|
||||
|
||||
To use your :ref:`dallas sensor <dallas-sensor>`, first define a dallas “hub” with a pin and
|
||||
id, which you will later use to create the sensors. The 1-Wire bus the
|
||||
sensors are connected to should have an external pullup resistor of
|
||||
about 4.7KΩ. For this, connect a resistor of *about* 4.7KΩ between ``3.3V``
|
||||
and the data pin. Values ± 1KΩ will, in most cases, work fine as well,
|
||||
if you don't have massively long wires.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
dallas:
|
||||
- pin: GPIOXX
|
||||
|
||||
Configuration variables:
|
||||
************************
|
||||
|
||||
- **pin** (**Required**, number): The pin the sensor bus is connected to. Please note that 1-wire is a bi-directional bus so it requires both input and output from the pin.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
|
||||
Defaults to 60 seconds.
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||
|
||||
.. _dallas-sensor:
|
||||
|
||||
Sensor
|
||||
------
|
||||
|
||||
The ``dallas`` sensor allows you to use DS18B20 and similar sensors.
|
||||
First, you need to define a :ref:`dallas sensor component <dallas-component>`.
|
||||
The dallas sensor component (or "hub") is an internal model that defines which pins the DS18B20
|
||||
sensors are connected to. This is because with these sensors you can actually connect multiple
|
||||
sensors to a single pin and use them all at once.
|
||||
|
||||
To initialize a sensor, first supply either ``address`` **or** ``index`` to identify the sensor.
|
||||
|
||||
.. figure:: images/dallas-wired.jpg
|
||||
:align: center
|
||||
:width: 50.0%
|
||||
|
||||
Wired Version of the DS18B20 1-Wire Temperature Sensor.
|
||||
|
||||
.. _Adafruit: https://www.adafruit.com/product/374
|
||||
|
||||
.. figure:: images/temperature.png
|
||||
:align: center
|
||||
:width: 80.0%
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Individual sensors
|
||||
sensor:
|
||||
- platform: dallas
|
||||
address: 0x1C0000031EDD2A28
|
||||
name: "Living Room Temperature"
|
||||
|
||||
Configuration variables:
|
||||
************************
|
||||
|
||||
- **address** (**Required**, int): The address of the sensor. Use either
|
||||
this option or index.
|
||||
- **index** (**Required**, int): The index of the sensor starting with 0.
|
||||
So the first sensor will for example have index 0. :ref:`It’s recommended
|
||||
to use address instead <dallas-getting-ids>`.
|
||||
- **resolution** (*Optional*, int): An optional resolution from 9 to
|
||||
12. Higher means more accurate. Defaults to the maximum for most Dallas temperature sensors: 12.
|
||||
- **dallas_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`dallas hub <dallas-component>`.
|
||||
Use this if you have multiple dallas hubs.
|
||||
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
.. _dallas-getting-ids:
|
||||
|
||||
Getting Sensor IDs
|
||||
******************
|
||||
|
||||
It is highly recommended to use the ``address`` attribute for creating
|
||||
dallas sensors, because if you have multiple sensors on a bus and the
|
||||
automatic sensor discovery fails, all sensors indices will be shifted by
|
||||
one. In order to get the address, simply start the firmware on your
|
||||
device with a configured dallas hub and observe the log output (the :ref:`log
|
||||
level <logger-log_levels>` must be set to at least
|
||||
``debug``!). Note that you don't need to define the individual sensors just yet, as
|
||||
the scanning will happen even with no sensors connected. For example with this configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
dallas:
|
||||
- pin: GPIOXX
|
||||
|
||||
# Note you don't have to add any sensors at this point
|
||||
|
||||
You will find something like this:
|
||||
|
||||
.. figure:: images/dallas-log.png
|
||||
|
||||
Now we can add the individual sensors to our configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
dallas:
|
||||
- pin: GPIOXX
|
||||
|
||||
sensor:
|
||||
- platform: dallas
|
||||
address: 0xA40000031F055028
|
||||
name: "Temperature #1"
|
||||
- platform: dallas
|
||||
address: 0xDD0000031EFB0428
|
||||
name: "Temperature #2"
|
||||
- platform: dallas
|
||||
# ...
|
||||
|
||||
Next, individually warm up or cool down the sensors and observe the log again.
|
||||
You will see the outputted sensor values changing when they're being warmed.
|
||||
When you're finished mapping each address to a name, just change the ``Temperature #1``
|
||||
to your assigned names and you should be ready.
|
||||
|
||||
Multiple dallas hubs
|
||||
********************
|
||||
|
||||
Use this if you have multiple dallas hubs:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
dallas:
|
||||
- pin: GPIOXX
|
||||
id: hub_1
|
||||
- pin: GPIOXX
|
||||
id: hub_2
|
||||
|
||||
sensor:
|
||||
- platform: dallas
|
||||
dallas_id: hub_1
|
||||
# ...
|
||||
- platform: dallas
|
||||
dallas_id: hub_2
|
||||
# ...
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :doc:`max6675`
|
||||
- `Arduino DallasTemperature library <https://github.com/milesburton/Arduino-Temperature-Control-Library>`__
|
||||
by `Miles Burton <https://github.com/milesburton>`__
|
||||
- :apiref:`dallas/dallas_component.h`
|
||||
- :ghedit:`Edit`
|
||||
- `Guidelines for Reliable Long Line 1-Wire Networks <https://www.analog.com/en/technical-articles/guidelines-for-reliable-long-line-1wire-networks.html>`__
|
||||
41
components/sensor/dallas_temp.rst
Normal file
41
components/sensor/dallas_temp.rst
Normal file
@ -0,0 +1,41 @@
|
||||
Dallas Temperature Sensor
|
||||
=========================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up Dallas 1-Wire temperature sensors
|
||||
:image: dallas.jpg
|
||||
:keywords: Dallas, ds18b20, onewire
|
||||
|
||||
The ``dallas_temp`` component allows you to use
|
||||
`DS18B20 <https://www.adafruit.com/product/374>`__
|
||||
(`datasheet <https://datasheets.maximintegrated.com/en/ds/DS18B20.pdf>`__)
|
||||
and similar 1-Wire temperature sensors. A :ref:`1-Wire bus <one_wire>` is
|
||||
required to be set up in your configuration for this sensor to work.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
sensor:
|
||||
- platform: dallas_temp
|
||||
address: 0x1234567812345628
|
||||
name: temperature
|
||||
|
||||
Configuration variables:
|
||||
************************
|
||||
|
||||
- **address** (*Optional*, int): The address of the sensor. Required if there is more than one device on the bus.
|
||||
- **resolution** (*Optional*, int): An optional resolution from 9 to 12. Higher means more accurate.
|
||||
Defaults to the maximum for most Dallas temperature sensors: 12.
|
||||
- **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
|
||||
Defaults to 60 seconds.
|
||||
- **one_wire_id** (*Optional*, :ref:`one_wire`): The ID of the 1-Wire bus to use.
|
||||
Required if there is more than one bus.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- `Arduino DallasTemperature library <https://github.com/milesburton/Arduino-Temperature-Control-Library>`__
|
||||
by `Miles Burton <https://github.com/milesburton>`__
|
||||
- :apiref:`dallas_temp/dallas_temp.h`
|
||||
- :ghedit:`Edit`
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 132 KiB |
@ -645,7 +645,7 @@ with ``x``.
|
||||
.. code-block:: yaml
|
||||
|
||||
sensor:
|
||||
- platform: dallas
|
||||
- platform: dht
|
||||
# ...
|
||||
on_value:
|
||||
then:
|
||||
@ -673,7 +673,7 @@ So for example ``above: 5`` with no below would mean the range from 5 to positiv
|
||||
.. code-block:: yaml
|
||||
|
||||
sensor:
|
||||
- platform: dallas
|
||||
- platform: dht
|
||||
# ...
|
||||
on_value_range:
|
||||
- below: 5.0
|
||||
@ -705,7 +705,7 @@ trigger with ``x``.
|
||||
.. code-block:: yaml
|
||||
|
||||
sensor:
|
||||
- platform: dallas
|
||||
- platform: dht
|
||||
# ...
|
||||
on_raw_value:
|
||||
then:
|
||||
|
||||
@ -46,7 +46,6 @@ See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :doc:`dallas`
|
||||
- :doc:`dht`
|
||||
- :doc:`adc`
|
||||
- :doc:`max6675`
|
||||
|
||||
@ -52,7 +52,6 @@ See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :doc:`dallas`
|
||||
- :doc:`dht`
|
||||
- :doc:`adc`
|
||||
- :doc:`max6675`
|
||||
|
||||
@ -61,7 +61,6 @@ See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :doc:`dallas`
|
||||
- :doc:`dht`
|
||||
- :doc:`adc`
|
||||
- :doc:`max6675`
|
||||
|
||||
@ -55,7 +55,6 @@ See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :doc:`dallas`
|
||||
- :doc:`dht`
|
||||
- :doc:`adc`
|
||||
- :doc:`sht3xd`
|
||||
|
||||
19
images/one-wire.svg
Normal file
19
images/one-wire.svg
Normal file
@ -0,0 +1,19 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<svg
|
||||
viewBox="0 0 100 25"
|
||||
version="1.1"
|
||||
id="svg1"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:svg="http://www.w3.org/2000/svg">
|
||||
<defs
|
||||
id="defs1" />
|
||||
<path
|
||||
d="M5,0 H95 a5 5 0 0 1 5 5 v15 a5 5 0 0 1 -5 5 H5 a5 5 0 0 1 -5 -5 V5 a5 5 0 0 1 5 -5 Z"
|
||||
style="fill:#000;"
|
||||
id="path1" />
|
||||
<path
|
||||
d="m 5.125,7.95 h 3 V 21 h 5.9 V 3.5 h -8.9 z m 20.049982,7.95 v -4.25 h -7.5 V 15.9 Z M 47.72495,13.575 44.67495,3.5 h -5.425 l -3.225,9.95 -3.05,-9.95 h -6.075 l 5.6,17.5 h 6.325 l 2.975,-9.35 2.825,9.35 h 6.325 l 5.6,-17.5 h -5.6 z m 14.374964,-7.35 c 2.075,0 3.4,-1.25 3.4,-2.975 0,-1.625 -1.325,-2.775 -3.4,-2.775 -2.075,0 -3.4,1.25 -3.4,2.875 0,1.625 1.325,2.875 3.4,2.875 z M 64.924914,21 V 7.325 h -5.65 V 21 Z M 73.899918,7.325 h -5.375 V 21 h 5.65 v -6.075 c 0,-2.175 1.2,-2.95 2.9,-2.95 0.4,0 0.75,0.025 1.25,0.1 v -5 c -1.9,0 -3.425,0.575 -4.425,1.725 z m 21.550007,6.825 c 0,-4.625 -3.475,-7.075 -7.525,-7.075 -4.425,0 -7.75,2.925 -7.75,7.075 0,4.075 3.25,7.1 8.275,7.1 2.725,0 4.65,-0.75 5.975,-2.2 l -2.95,-2.975 c -0.9,0.675 -1.6,1 -2.85,1 -1.4,0 -2.35,-0.55 -2.75,-1.6 h 9.5 c 0.025,-0.4 0.075,-0.925 0.075,-1.325 z m -7.475,-3.225 c 1.15,0 1.975,0.675 2.2,1.825 h -4.4 c 0.225,-1.15 1.025,-1.825 2.2,-1.825 z"
|
||||
id="component-text"
|
||||
style="font-weight:900;font-size:25px;font-family:Montserrat;letter-spacing:1.1px;fill:#fffffc"
|
||||
aria-label="1-Wire" />
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.4 KiB |
@ -223,6 +223,7 @@ Hardware Peripheral Interfaces/Busses
|
||||
I²S Audio, components/i2s_audio, i2s_audio.svg
|
||||
SPI Bus, components/spi, spi.svg
|
||||
UART, components/uart, uart.svg
|
||||
1-Wire, components/one_wire, one-wire.svg
|
||||
|
||||
I/O Expanders/Multiplexers
|
||||
--------------------------
|
||||
@ -402,7 +403,7 @@ Environmental
|
||||
BMP280, components/sensor/bmp280, bmp280.jpg, Temperature & Pressure
|
||||
BMP388 and BMP390, components/sensor/bmp3xx, bmp388.jpg, Temperature & Pressure
|
||||
BMP581, components/sensor/bmp581, bmp581.jpg, Temperature & Pressure
|
||||
Dallas DS18B20, components/sensor/dallas, dallas.jpg, Temperature
|
||||
Dallas DS18B20, components/sensor/dallas_temp, dallas.jpg, Temperature
|
||||
DHT, components/sensor/dht, dht.jpg, Temperature & Humidity
|
||||
DHT12, components/sensor/dht12, dht12.jpg, Temperature & Humidity
|
||||
DPS310, components/sensor/dps310, dps310.jpg, Temperature & Pressure
|
||||
|
||||
Loading…
Reference in New Issue
Block a user