1.. _w1_api:
2
31-Wire Bus
4##########
5
6Overview
7********
8
91-Wire is a low speed half-duplex serial bus using only a single wire plus
10ground for both data transmission and device power supply.
11Similarly to I2C, 1-Wire uses a bidirectional open-collector data line,
12and is a single master multidrop bus. This means one master initiates all data
13exchanges with the slave devices.
14The 1-Wire bus supports longer bus lines than I2C, while it reaches speeds of up
15to 15.4 kbps in standard mode and up to 125 kbps in overdrive mode.
16Reliable communication in standard speed configuration is possible with 10 nodes
17over a bus length of 100 meters. Using overdrive speed, 3 nodes on a bus of
1810 meters length are expected to work solid. Optimized timing parameters and
19fewer nodes on the bus may allow to reach larger bus extents.
20
21The implementation details are specified in the `BOOK OF IBUTTON STANDARDS`_.
22
23.. figure:: 1-Wire_bus_topology.drawio.svg
24   :align: center
25   :alt: 1-Wire bus topology
26
27   A typical 1-Wire bus topology
28
29
30.. _w1-master-api:
31
32W1 Master API
33=================
34
35Zephyr's 1-Wire Master API is used to interact with 1-Wire slave devices like
36temperature sensors and serial memories.
37
38In Zephyr this API is split into the following layers.
39
40* The link layer handles basic communication functions such as bus reset,
41  presence detect and bit transfer operations.
42  It is the only hardware-dependent layer in Zephyr.
43  This layer is supported by a driver using the Zephyr :ref:`uart_api` interface,
44  which should work on most Zephyr platforms.
45  In the future, a GPIO/Timer based driver and hardware specific drivers might
46  be added.
47* The 1-Wire network layer handles all means for slave identification and bus
48  arbitration.
49  This includes ROM commands like Match ROM, or Search ROM.
50
51   * All slave devices have a unique 64-bit identification number, which
52     includes a 8-bit `1-Wire Family Code`_ and a 8-bit CRC.
53   * In order to find slaves on the bus, the standard specifies an search
54     algorithm which successively detects all slaves on the bus.
55     This algorithm is described in the `1-Wire Search Algorithm Application Note`_.
56
57* Transport layer and Presentation layer functions are not implemented in the
58  generic 1-Wire driver and therefore must be handled in individual slave drivers.
59
60The 1-Wire API is considered experimental.
61
62
63Configuration Options
64*********************
65
66Related configuration options:
67
68* :kconfig:option:`CONFIG_W1`
69* :kconfig:option:`CONFIG_W1_NET`
70
71
72API Reference
73*************
74
751-Wire data link layer
76======================
77
78.. doxygengroup:: w1_data_link
79
801-Wire network layer
81====================
82
83.. doxygengroup:: w1_network
84
851-Wire generic functions and helpers
86====================================
87
88Functions that are not directly related to any of the networking layers.
89
90.. doxygengroup:: w1_interface
91
92
93.. _BOOK OF IBUTTON STANDARDS:
94   https://www.analog.com/en/resources/technical-articles/book-of-ibuttonreg-standards.html
95
96.. _1-Wire Family Code:
97   https://www.analog.com/en/resources/technical-articles/1wire-software-resource-guide-device-description.html
98
99.. _1-Wire Search Algorithm Application Note:
100   https://www.analog.com/en/resources/app-notes/1wire-search-algorithm.html
101