[PATCH] docs: iio: add documentation for ti-ads1015 driver

[PATCH] docs: iio: add documentation for ti-ads1015 driver

[Flaviu Nistor]

Add documentation for the ADS1015 ADC IIO driver, which describes channels,
IIO attributes, threshold events and ABI usage examples.

Signed-off-by: Flaviu Nistor <flaviu.nistor@gmail.com>
---
 Documentation/iio/index.rst      |   1 +
 Documentation/iio/ti-ads1015.rst | 129 +++++++++++++++++++++++++++++++
 2 files changed, 130 insertions(+)
 create mode 100644 Documentation/iio/ti-ads1015.rst

diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index d0fb32f4b80f..47ba249dae0b 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -43,3 +43,4 @@ Industrial I/O Kernel Drivers
    bno055
    ep93xx_adc
    opt4060
+   ti-ads1015
diff --git a/Documentation/iio/ti-ads1015.rst b/Documentation/iio/ti-ads1015.rst
new file mode 100644
index 000000000000..214e50c39821
--- /dev/null
+++ b/Documentation/iio/ti-ads1015.rst
@@ -0,0 +1,129 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=====================
+TI ADS1015 ADC driver
+=====================
+
+Driver for the Texas Instruments ADS1015 and related I2C analog-to-digital
+converters. The module name is ``ads1015``.
+
+Supported devices
+=================
+
+* `ADS1015 <https://www.ti.com/product/ADS1015>`_: 12-bit ADC, programmable data rate from 128 to 3300 samples/s.
+* `ADS1115 <https://www.ti.com/product/ADS1115>`_: 16-bit ADC, programmable data rate from 8 to 860 samples/s.
+* `TLA2024 <https://www.ti.com/product/TLA2024>`_: 12-bit ADC, programmable data rate from 128 to 3300 samples/s.
+
+The ADS1015 and ADS1115 provide a comparator; the TLA2024 does not.
+
+I2C address
+===========
+
+The ADDR pin selects the 7-bit I2C address.
+For ADS1015 and ADS1115, the possible addresses are:
+
+* ``0x48``: ADDR connected to GND
+* ``0x49``: ADDR connected to VDD
+* ``0x4a``: ADDR connected to SDA
+* ``0x4b``: ADDR connected to SCL
+
+For the TLA2024, the possible addresses are:
+
+* ``0x48``: ADDR connected to GND
+* ``0x49``: ADDR connected to VDD
+* ``0x4b``: ADDR connected to SCL
+
+
+Channel configuration
+======================
+
+The driver exposes four single-ended voltage channels (AIN0 through AIN3,
+measured relative to GND) and four differential channels (AIN0-AIN1,
+AIN0-AIN3, AIN1-AIN3, and AIN2-AIN3). Device Tree child nodes configure the
+initial settings for the corresponding conversion input. They do not restrict
+which IIO channels are available.
+
+The child node ``reg`` values select the conversion input as follows:
+
++---------+------------------+
+| ``reg`` | Conversion input |
++=========+==================+
+| 0       | AIN0 - AIN1      |
++---------+------------------+
+| 1       | AIN0 - AIN3      |
++---------+------------------+
+| 2       | AIN1 - AIN3      |
++---------+------------------+
+| 3       | AIN2 - AIN3      |
++---------+------------------+
+| 4       | AIN0 - GND       |
++---------+------------------+
+| 5       | AIN1 - GND       |
++---------+------------------+
+| 6       | AIN2 - GND       |
++---------+------------------+
+| 7       | AIN3 - GND       |
++---------+------------------+
+
+``ti,gain`` selects the full-scale input range using the following index:
+
++-------+--------------------------+
+| Index | Full-scale range         |
++=======+==========================+
+| 0     | +/- 6.144 V              |
++-------+--------------------------+
+| 1     | +/- 4.096 V              |
++-------+--------------------------+
+| 2     | +/- 2.048 V (default)    |
++-------+--------------------------+
+| 3     | +/- 1.024 V              |
++-------+--------------------------+
+| 4     | +/- 0.512 V              |
++-------+--------------------------+
+| 5     | +/- 0.256 V              |
++-------+--------------------------+
+
+For a channel node that omits ``ti,gain``, the default index is 2.
+
+``ti,datarate`` selects the data rate by index. For the ADS1015 and TLA2024,
+indices 0 through 7 select 128, 250, 490, 920, 1600, 2400, 3300, and 3300
+samples/s, respectively. For the ADS1115, they select 8, 16, 32, 64, 128,
+250, 475, and 860 samples/s. For a channel node that omits
+``ti,datarate``, the default index is 4.
+
+The ``label`` property is exposed through the channel's ``in_voltageY_label``
+sysfs attribute. Without a defined label, the datasheet input name is used
+(for example, ``AIN0`` or ``AIN0-AIN1``).
+
+IIO attributes
+==============
+
+Each voltage channel provides a raw reading, a label, scale, and sampling frequency.
+The scale and sampling frequency can be changed at runtime; their available
+values are listed by ``scale_available`` and ``sampling_frequency_available``.
+
+Threshold events
+================
+
+The ADS1015 and ADS1115 can report threshold events when the ALERT/RDY pin is
+connected to an interrupt. The driver supports one active comparator channel
+at a time, and threshold events cannot be enabled while buffered capture is
+active. The TLA2024 does not support threshold events.
+
+The rising threshold value sets the upper threshold. The falling threshold
+value sets the lower threshold; enabling the ``either`` event uses both values
+in window-comparator mode. The event period selects the comparator queue
+duration, which corresponds to 1, 2, or 4 consecutive conversions at the
+channel's configured sampling frequency.
+
+Usage examples
+--------------
+
+.. code-block:: bash
+
+	root:/sys/bus/iio/devices/iio:device0# cat name
+	ads1015
+	root:/sys/bus/iio/devices/iio:device0# cat in_voltage0_label
+	AN0
+	root:/sys/bus/iio/devices/iio:device0# cat in_voltage0_raw
+	750
-- 
2.34.1

Re: [PATCH] docs: iio: add documentation for ti-ads1015 driver

[Jonathan Cameron]

On Wed, 21 Oct 2026 09:33:50 +0300
Flaviu Nistor <flaviu.nistor@gmail.com> wrote:

> Add documentation for the ADS1015 ADC IIO driver, which describes channels,
> IIO attributes, threshold events and ABI usage examples.
> 
Hi Flaviu
This is missing the 'why'?

We don't tend to add per driver documentation unless there are some
oddities or unique aspects that aren't described by more generic
documentation.  The actual features are all discoverable so documenting
those rarely makes sense.

If you have a reason that it makes sense to document this specific
driver then state that clearly in this patch description.

Thanks,
Jonathan


> Signed-off-by: Flaviu Nistor <flaviu.nistor@gmail.com>

Re: [PATCH] docs: iio: add documentation for ti-ads1015 driver

[Flaviu Nistor]

On Wed, Oct 21, 2026 at 10:22 PM, Jonathan Cameron wrote:
>On Wed, 21 Oct 2026 09:33:50 +0300
>Flaviu Nistor <flaviu.nistor@gmail.com> wrote:
>
>> Add documentation for the ADS1015 ADC IIO driver, which describes channels,
>> IIO attributes, threshold events and ABI usage examples.
>> 
>Hi Flaviu
>This is missing the 'why'?
>

Hello Jonathan,

the "why" seems to be a misunderstanding on my side. I had the impression that is it a
good practice (even expected) that each driver also has a documentation (as I see a much
higher driver doc coverage in hwmon subsystem for example). When I have send a patch for
this driver adding label support I observed that it has no documentation.
Now is clear that this is no the case (at least for IIO subsystem), so please ignore
this patch. Sorry for the noise.

Best regards,
Flaviu

>We don't tend to add per driver documentation unless there are some
>oddities or unique aspects that aren't described by more generic
>documentation.  The actual features are all discoverable so documenting
>those rarely makes sense.
>
>If you have a reason that it makes sense to document this specific
>driver then state that clearly in this patch description.
>
>Thanks,
>Jonathan
>
>
> Signed-off-by: Flaviu Nistor <flaviu.nistor@gmail.com>