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>

components/one_wire.rst

@@ -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>`__

components/sensor/dallas.rst

@@ -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>`__

components/sensor/dallas_temp.rst

@@ -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`

components/sensor/index.rst

@@ -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:

components/sensor/max31855.rst

@@ -46,7 +46,6 @@ See Also
 --------
 
 - :ref:`sensor-filters`
-- :doc:`dallas`
 - :doc:`dht`
 - :doc:`adc`
 - :doc:`max6675`

components/sensor/max31856.rst

@@ -52,7 +52,6 @@ See Also
 --------
 
 - :ref:`sensor-filters`
-- :doc:`dallas`
 - :doc:`dht`
 - :doc:`adc`
 - :doc:`max6675`

components/sensor/max31865.rst

@@ -61,7 +61,6 @@ See Also
 --------
 
 - :ref:`sensor-filters`
-- :doc:`dallas`
 - :doc:`dht`
 - :doc:`adc`
 - :doc:`max6675`

components/sensor/max6675.rst

@@ -55,7 +55,6 @@ See Also
 --------
 
 - :ref:`sensor-filters`
-- :doc:`dallas`
 - :doc:`dht`
 - :doc:`adc`
 - :doc:`sht3xd`

images/one-wire.svg

@@ -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>

index.rst

@@ -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