1.\" 2.\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd September 2, 2019 28.Dt ADS111x 4 29.Os 30.Sh NAME 31.Nm ads111x 32.Nd driver for ADS101x and ADS111x i2c analog to digital converters 33.Sh SYNOPSIS 34To compile this driver into the kernel, 35place the following line in your 36kernel configuration file: 37.Bd -ragged -offset indent 38.Cd "device ads111x" 39.Ed 40.Pp 41Alternatively, to load the driver as a 42module at boot time, place the following line in 43.Xr loader.conf 5 : 44.Bd -literal -offset indent 45ads111x_load="YES" 46.Ed 47.Sh DESCRIPTION 48The 49.Nm 50driver provides support for the ADS101x/ADS111x family of analog 51to digital converter (ADC) devices. 52The supported devices are all similar to each other, varying in 53features such as resolution and number of input channels. 54The devices offer a number of configuration options which can be 55set via hints, FDT data, and 56.Xr sysctl 8 . 57.Pp 58The 59.Xr sysctl 8 60utility provides access to the voltage measurements made by the device. 61Each time the 62.Va dev.ads111x.<unit>.<channel>.voltage 63variable is accessed for a given channel, the driver switches the 64chip's internal mux to choose the right input pins for that channel, 65directs it to make a single measurement, and returns the measured value 66in microvolts. 67The amount of time required to make the measurement is a function 68of the sampling rate configured for the device. 69While device is directed to make a single measurement, it still averages 70the input values for the same amount of time as it would to emit one 71sample if it were in continuous mode. 72For example, if the sample rate were configured as 125 samples per 73second, a single measurement would require 8 milliseconds. 74.Pp 75For devices that support multiple input pins, the device datasheet 76describes mux settings to control how those pins are interpeted when 77making either single-ended or differential measurements. 78There are eight possible ways to combine the inputs from the four pins. 79The 80.Nm 81driver models that by creating a separate output channel for each of 82the eight combinations. 83To make a measurement on a given pin or pair of pins, you simply access 84the voltage variable for the channel number that corresponds the mux 85setting number (0 through 7) shown in the datasheet. 86When the driver is configured with hints or FDT data, it creates 87sysctl variables for just the channels specified in the config data. 88When there is no channel config data, it creates all eight possible 89channels so that you can access whichever one(s) you need. 90.Pp 91For devices that include an 92.Va alert 93output pin, the 94.Nm 95driver does not directly support the pin in terms of sensing or 96acting on changes in the pin state. 97However, you may connect the pin to a gpio input or fan controller 98or other external device, and use the driver's sysctl variables to 99configure behavior and threshold values for the pin. 100The driver avoids perturbing your settings as it does other 101manipulations to the config register. 102.Sh SYSCTL VARIABLES 103Sysctl variables are used to access the voltage measurements, and to 104change the configuration of the channels. 105All writeable variables may also be set as 106.Xr loader 8 107tunables. 108Channel numbers in these sysctl variables range from 0 through 7. 109.Bl -tag -width indent 110.It Va dev.ads111x.<unit>.config 111Provides access to the configuration register bits that control the 112alert pin configuration. 113Other bits which are controlled by the driver are masked out, and 114cannot be viewed or changed using this variable. 115.It Va dev.ads111x.<unit>.lo_thresh 116Sets the low threshold for activating the alert pin. 117.It Va dev.ads111x.<unit>.hi_thresh 118Sets the high threshold for activating the alert pin. 119.It Va dev.ads111x.<unit>.<channel>.rate_index 120Sets the sample rate for the channel. 121The device datasheet documents eight available sample rates, chosen 122by setting a value of 0 through 7 into the corresponding control 123register bits. 124This variable sets the value used for those bits when making a 125measurement on the given channel. 126.Pp 127Because measurements are always made in single-shot mode, think of 128this variable as controlling the averaging time for a single sample; 129the time to make a measurement is 1 / samplerate. 130.It Va dev.ads111x.<unit>.<channel>.gain_index 131Sets the programmable gain amplifier for the channel on devices 132which have an internal amplifier. 133The device datasheet documents eight available gain values, chosen 134by setting a value of 0 through 7 into the corresponding control 135register bits. 136This variable sets the value used for those bits when making a 137measurement on the given channel. 138.It Va dev.ads111x.<unit>.<channel>.voltage 139Reading this variable causes the device to make a measurement on 140the corresponding input pin(s) and return the voltage in microvolts. 141.Pp 142Note that this variable does not appear when you list multiple 143sysctl variables -- you must access it specifically by name, because 144accessing it triggers device I/O. 145.El 146.Sh HARDWARE 147The 148.Nm 149driver provides support for the following devices: 150.Pp 151.Bl -column -compact -offset indent "XXXXXXXX" "XXXXXXXX" 152.It ADS1013 Ta ADS1113 153.It ADS1014 Ta ADS1114 154.It ADS1015 Ta ADS1115 155.El 156.Sh FDT CONFIGURATION 157On an 158.Xr fdt 4 159based system, the 160.Nm 161device is defined as a slave device subnode 162of the i2c bus controller node. 163All properties documented in the 164.Va ads1015.txt 165bindings document can be used with the 166.Nm 167device. 168.Pp 169The following properties are required in the 170.Nm 171device subnode: 172.Bl -tag -width indent 173.It Va compatible 174One of the following: 175.Bl -column -compact -offset indent ".Dq ti,ads1013" ".Dq ti,ads1113" 176.It Dq ti,ads1013 Ta Dq ti,ads1113 177.It Dq ti,ads1014 Ta Dq ti,ads1114 178.It Dq ti,ads1015 Ta Dq ti,ads1115 179.El 180.It Va reg 181I2c slave address of device. 182.El 183.Pp 184Specific channels can be configured by adding child nodes to the 185.Nm 186node, as described in the standard ads1015.txt bindings document. 187If no channels are configured, sysctl variables will be created 188for all possible channels supported by the device type, otherwise 189only the specified channels are created. 190.Ss Example including channel configuration 191.Bd -unfilled -offset indent 192adc@48 { 193 compatible = "ti,ads1115"; 194 reg = <0x48>; 195 status = "okay"; 196 #address-cells = <1>; 197 #size-cells = <0>; 198 199 channel@6 { 200 reg = <6>; 201 ti,gain = <3>; 202 ti,datarate = <4>; 203 }; 204 channel@7 { 205 reg = <7>; 206 ti,gain = <1>; 207 ti,datarate = <7>; 208 }; 209}; 210.Ed 211.Sh HINTS CONFIGURATION 212On a 213.Xr device.hints 5 214based system, such as 215.Li MIPS , 216these values are configurable for 217.Nm : 218.Bl -tag -width indent 219.It Va hint.ads111x.<unit>.at 220The iicbus instance the 221.Nm 222instance is attached to. 223.It Va hint.ads111x.<unit>.<channel>.gain_index 224The amplifier gain, as described above for the sysctl variable 225.Va dev.ads111x.<unit>.<channel>.gain_index . 226.It Va hint.ads111x.<unit>.<channel>.rate_index 227The sample rate, as described above for the sysctl variable 228.Va dev.ads111x.<unit>.<channel>.rate_index . 229.El 230.Pp 231If no channels are configured, sysctl variables will be created 232for all possible channels supported by the device type, otherwise 233only the specified channels are created. 234.Sh SEE ALSO 235.Xr fdt 4 , 236.Xr sysctl 8 237.Sh HISTORY 238The 239.Nm 240driver first appeared in 241.Fx 13.0 . 242