ADS111x(4)

💖 ADS111x(4) 💖

hiii bestie, welcome to the Kernel Interfaces Manual page for ads111x(4). yes we're doing kernel drivers today and yes it's gonna be cute. sit down, grab a boba, we're decoding an ADC 🧋✨

---

🌸 NAME 🌸

ads111x — driver for ADS101x and ADS111x i2c analog to digital converters

✨ SYNOPSIS ✨

Want this driver baked into your kernel? Bestie, just drop this line into your kernel configuration file:

device ads111x

Or, if you'd rather load it as a module at boot time, put this in loader.conf(5):

ads111x_load="YES"

either way works, it's giving ✨options✨

🦋 DESCRIPTION 🦋

okay so. The ads111x driver is the support system for the whole ADS101x/ADS111x family of analog to digital converter (ADC) devices. All the supported devices are basically siblings — same vibe, but they vary in features like resolution and how many input channels they have. And they come with a bunch of configuration options that you can set through hints, FDT data, and sysctl(8). three whole ways to customize, we love a flexible icon 💅

Sysctl(8) is how you get at the voltage measurements the device makes. Every time you touch the dev.ads111x.<unit>.<channel>.voltage variable for a given channel, the driver flips the chip's internal mux to pick the right input pins for that channel, tells it to take one single measurement, and hands you back the measured value in microvolts. How long that takes is a function of the sampling rate configured for the device. And here's the tea: even while the device is directed to make a single measurement, it still averages the input values for the same amount of time it would to emit one sample if it were in continuous mode. For example, if the sample rate were configured as 125 samples per second, a single measurement would require 8 milliseconds. math is math 🧮

For devices that support multiple input pins, the device datasheet describes mux settings that control how those pins get interpreted when making either single-ended or differential measurements. There are eight possible ways to combine the inputs from the four pins. The ads111x driver models that by creating a separate output channel for each of the eight combinations. So to make a measurement on a given pin or pair of pins, you just access the voltage variable for the channel number that corresponds to the mux setting number (0 through 7) shown in the datasheet. easy! When the driver is configured with hints or FDT data, it creates sysctl variables for just the channels specified in the config data. And when there's no channel config data at all? It creates all eight possible channels so you can access whichever one(s) you need. generous queen 👑

For devices that include an alert output pin, the ads111x driver does not directly support the pin in terms of sensing or acting on changes in the pin state. sad but true. However — you can connect that pin to a gpio input or a fan controller or some other external device, and then use the driver's sysctl variables to configure behavior and threshold values for the pin. The driver is polite about it too: it avoids perturbing your settings while it does other manipulations to the config register. considerate king 🫶

---

👑 SYSCTL VARIABLES 👑

Sysctl variables are how you access the voltage measurements and change the configuration of the channels. All writeable variables may also be set as loader(8) tunables. Channel numbers in these sysctl variables range from 0 through 7.

• dev.ads111x.<unit>.config — gives you access to the configuration register bits that control the alert pin configuration. other bits that are controlled by the driver are masked out, and cannot be viewed or changed using this variable. hands off those, bestie 🙈
• dev.ads111x.<unit>.lo_thresh — sets the low threshold for activating the alert pin.
• dev.ads111x.<unit>.hi_thresh — sets the high threshold for activating the alert pin.
• dev.ads111x.<unit>.<channel>.rate_index — sets the sample rate for the channel. The device datasheet documents eight available sample rates, chosen by setting a value of 0 through 7 into the corresponding control register bits. This variable sets the value used for those bits when making a measurement on the given channel.

Because measurements are always made in single-shot mode, think of this variable as controlling the averaging time for a single sample; the time to make a measurement is 1 / samplerate.

• dev.ads111x.<unit>.<channel>.gain_index — sets the programmable gain amplifier for the channel on devices which have an internal amplifier. The device datasheet documents eight available gain values, chosen by setting a value of 0 through 7 into the corresponding control register bits. This variable sets the value used for those bits when making a measurement on the given channel.
• dev.ads111x.<unit>.<channel>.voltage — reading this variable causes the device to make a measurement on the corresponding input pin(s) and return the voltage in microvolts.

Note that this variable does not appear when you list multiple sysctl variables — you must access it specifically by name, because accessing it triggers device I/O. it's shy. it only comes out when called directly 😭

---

🔥 HARDWARE 🔥

The ads111x driver provides support for the following devices:

• ADS1013
• ADS1113
• ADS1014
• ADS1114
• ADS1015
• ADS1115

six icons, all supported 💅

---

🌈 FDT CONFIGURATION 🌈

On an fdt(4) based system, the ads111x device is defined as a slave device subnode of the i2c bus controller node. All properties documented in the ads1015.txt bindings document can be used with the ads111x device.

The following properties are required in the ads111x device subnode:

• compatible — one of the following:

“ti,ads1013     “ti,ads1113””
“ti,ads1014     “ti,ads1114””
“ti,ads1015     “ti,ads1115””

• reg — I2c slave address of device.

Specific channels can be configured by adding child nodes to the ads111x node, as described in the standard ads1015.txt bindings document. If no channels are configured, sysctl variables will be created for all possible channels supported by the device type — otherwise only the specified channels are created. your choice, your rules ✨

🎀 Example including channel configuration 🎀

here's what it looks like in the wild, bestie:

adc@48 {
    compatible = "ti,ads1115";
    reg = <0x48>;
    status = "okay";
    #address-cells = <1>;
    #size-cells = <0>;

    channel@6 {
        reg = <6>;
        ti,gain = <3>;
        ti,datarate = <4>;
    };
    channel@7 {
        reg = <7>;
        ti,gain = <1>;
        ti,datarate = <7>;
    };
};

ate that up, no crumbs 🍽️

---

🍓 HINTS CONFIGURATION 🍓

On a device.hints(5) based system, such as MIPS, these values are configurable for ads111x:

• hint.ads111x.<unit>.at — the iicbus instance the ads111x instance is attached to.
• hint.ads111x.<unit>.<channel>.gain_index — the amplifier gain, as described above for the sysctl variable dev.ads111x.<unit>.<channel>.gain_index.
• hint.ads111x.<unit>.<channel>.rate_index — the sample rate, as described above for the sysctl variable dev.ads111x.<unit>.<channel>.rate_index.

If no channels are configured, sysctl variables will be created for all possible channels supported by the device type, otherwise only the specified channels are created. (yes, same rule as FDT. consistent behavior is the vibe 🌸)

---

💜 SEE ALSO 💜

fdt(4), sysctl(8)

---

⭐ HISTORY ⭐

The ads111x driver first appeared in FreeBSD 13.0. a whole era 💫

---

and that's the page, bestie!! you now know more about i2c ADCs than 99% of the group chat, fr fr. this manual page came from the Debian project and is dated September 2, 2019 — go off, historical document 👑💖

go forth and measure some microvolts. periodt. 🦋✨