Break apart 1-Wire doc (#5082)

Author: kbx81

changelog/2024.6.0.rst

@@ -14,7 +14,7 @@ ESPHome 2024.6.0 - 19th June 2024
     HTTP Request OTA Updates, components/ota_http_request, system-update.svg, dark-invert
     Managed Updates, components/update/http_request, system-update.svg, dark-invert
 
-    1-Wire, components/one_wire, one-wire.svg
+    1-Wire, components/one_wire/index, one-wire.svg
     GDK101, components/sensor/gdk101, gdk101.jpg
     Beken SPI, components/light/beken_spi_led_strip, color_lens.svg, dark-invert
 
@@ -138,7 +138,7 @@ need to do unless you were overriding some of the safe mode specific configurati
 
 Up until now, the ``dallas`` sensor platform contained the only 1-wire implementation in ESPHome.
 There had been requests to add support for other 1-wire based components, so :ghuser:`ssieb` has
-made a new top level :doc:`1-wire </components/one_wire>` component that will allow for this.
+made a new top level :doc:`1-wire </components/one_wire/index>` component that will allow for this.
 In doing so, the ``dallas`` sensor platform has been removed, and replaced with ``dallas_temp``
 to allow for other Dallas sensors to be implemented that are not temperature sensors.
 

components/index.rst

@@ -160,7 +160,7 @@ Hardware Peripheral Interfaces/Busses
 
 .. imgtable::
 
-    1-Wire, components/one_wire, one-wire.svg
+    1-Wire, components/one_wire/index, one-wire.svg
     CAN Bus, components/canbus/index, canbus.svg
     I²C Bus, components/i2c, i2c.svg
     I²S Audio, components/i2s_audio, i2s_audio.svg
@@ -191,12 +191,25 @@ I/O Expanders/Multiplexers
     WeiKai SPI/I²C UART/IO Expander, components/weikai, wk2168.jpg
     XL9535, components/xl9535, xl9535.svg
 
+1-Wire Bus
+----------
+
+Platforms which specifically support or extend the :doc:`/components/one_wire/index`, allowing communication with
+1-Wire-based devices.
+
+.. imgtable::
+
+    DS2484, components/one_wire/ds2484, ds2484.svg
+    GPIO, components/one_wire/gpio, gpio.svg
+
 CAN Bus
 -------
 
+Platforms which specifically support or extend the :doc:`/components/canbus/index`, allowing communication with
+CAN-based devices.
+
 .. imgtable::
 
-    CAN Bus, components/canbus/index, canbus.svg
     ESP32 CAN, components/canbus/esp32_can, esp32.svg
     MCP2515, components/canbus/mcp2515, mcp2515.svg
 
@@ -1125,6 +1138,7 @@ ESPHome depends on and welcomes contributions from our community. If you'd like
     binary_sensor/index
     camera/index
     canbus/index
+    one_wire/index
     climate/index
     cover/index
     fan/index

components/one_wire.rst

@@ -0,0 +1,36 @@
+1-Wire Bus via DS2484
+=====================
+
+.. seo::
+    :description: Instructions for setting up a Dallas (Analog Devices) 1-Wire bus via a DS2484 IC to communicate with 1-wire devices in ESPHome
+    :image: one-wire.svg
+    :keywords: Dallas, onewire, 1-wire
+
+The ``ds2484`` platform provides access to 1-Wire busses via DS2484 device using the :ref:`I²C Bus <i2c>` for
+communication.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    one_wire:
+      - platform: ds2484
+        active_pullup: true
+
+Configuration variables:
+************************
+
+- **active_pullup** (*Optional*, defaults to ``false``): enables DS2484 `active_pullup`.
+- **strong_pullup** (*Optional*, defaults to ``false``): enables DS2484 `strong_pullup`.
+- **address** (*Optional*, int): The I²C address of the device. Defaults to ``0x18``.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Required if you have
+  multiple 1-Wire busses.
+- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :doc:`/components/i2c`. Required if you
+  have configured multiple I2C busses.
+
+See Also
+--------
+
+- :doc:`index`
+- :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/one_wire/ds2484.rst

@@ -0,0 +1,33 @@
+1-Wire Bus via GPIO
+===================
+
+.. seo::
+    :description: Instructions for setting up a Dallas (Analog Devices) 1-Wire bus via a GPIO pin to communicate with 1-wire devices in ESPHome
+    :image: one-wire.svg
+    :keywords: Dallas, onewire, 1-wire
+
+The ``gpio`` platform uses the CPU to generate the bus signals on an on-board GPIO pin.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    one_wire:
+      - platform: gpio
+        pin: GPIOXX
+
+Configuration variables:
+************************
+
+- **pin** (**Required**, number): The pin which will be use for bus communication. Note that 1-wire is a bi-directional
+  bus so the selected GPIO pin must support both input and output. This must be a GPIO pin internal to the
+  microcontroller and cannot be a pin located on an I/O expander or similar device.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Required if you have
+  multiple busses.
+
+See Also
+--------
+
+- :doc:`index`
+- :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/one_wire/gpio.rst

@@ -0,0 +1,40 @@
+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 pull-up resistor of about 4.7KΩ. A resistor of
+*about* 4.7KΩ connected between ``3.3V`` and the 1-Wire bus's GPIO/data pin should suffice. Values ± 1KΩ will generally
+work fine as well, provided you don't have unusually long wires.
+
+Platforms
+---------
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
+
+Obtaining Sensor IDs
+--------------------
+
+To find device addresses, simply start the firmware on your device with a ``one_wire`` hub configured and observe the
+log output. Note that you don't need to define the individual sensors just yet, as scanning will occur even with no
+sensors configured.
+
+Here's an example log:
+
+.. 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/images/dallas-log.png renamed to components/one_wire/images/dallas-log.png

@@ -9,7 +9,7 @@ Dallas Temperature Sensor
 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
+and similar 1-Wire temperature sensors.  A :doc:`1-Wire bus </components/one_wire/index>` is
 required to be set up in your configuration for this sensor to work.
 
 .. code-block:: yaml
@@ -29,7 +29,7 @@ Configuration variables:
   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.
+- **one_wire_id** (*Optional*, :doc:`/components/one_wire/index`): 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>`.