How to Use ADC on Torizon OS

Introduction

This article explains how to use the System on Modules' dedicated Analog-to-Digital Converter (ADC) and read analog inputs using the sysfs interface on Torizon OS. Additionally, it describes how to connect external ADCs and enable required drivers.

Toradex System on Modules collect analog inputs through dedicated ADCs. Since the features of ADCs may differ between modules, always check whether they meet your use case requirements. For detailed information, refer to your SoM's datasheet's Analog Inputs section. If you require additional inputs or a higher sampling rate, you ADC also use external ADCs.

The following sections are covered:

• Dedicated ADCs
• External ADCs

This article complies with the Typographic Conventions for Torizon Documentation.

Prerequisites

• A Toradex System on Module with Torizon OS installed.
• A configured build environment, as described in the Configure Build Environment for Torizon Containers article.
• An understanding of Peripheral Access Overview.

Dedicated ADCs

Connect Analog Inputs

To use dedicated ADCs, refer to the Analog Inputs section of your module datasheet. That section contains ADC feature details and available pins. For instance, the Verdin iMX8M Plus datasheet provides the following table:

X1 Pin#	Verdin Std Function	i.MX 8MP Ball Name	i.MX 8MP Function	I2C Port	Description
14	ADC_1	7	AIN1	I	Analog Input 1
12	ADC_4	6	AIN2	I	Analog Input 2
12	ADC_2	5	AIN3	I	Analog Input 3
14	ADC_3	4	AIN4	I	Analog Input 4

Then, refer to your carrier board datasheet or schematics to locate the pins that carry ADC signals. On the Verdin Development Board, those signals are available through the X49 connector as follows:

Pin	Signal Name	SODIMM Pin	I/O Type	Voltage	Description
1	ADC_1	2	I (Analog)	1.8V	Analog Input 1
2	ADC_4	4	I (Analog)	1.8V	Analog Input 2
3	ADC_2	6	I (Analog)	1.8V	Analog Input 3
4	ADC_3	8	I (Analog)	1.8V	Analog Input 4

Locate ADC data in the OS

On Torizon OS, ADC raw data outputs are listed in the /dev directory. The following command displays the available ADC outputs for the Verdin iMX8M Plus.

# ls -l /dev/*adc*
lrwxrwxrwx 1 root root 94 Apr 28  2022 /dev/verdin-adc1 -> /sys/devices/platform/soc@0/30800000.bus/30a20000.i2c/i2c-0/0-0049/iio:device0/in_voltage3_raw
lrwxrwxrwx 1 root root 94 Apr 28  2022 /dev/verdin-adc2 -> /sys/devices/platform/soc@0/30800000.bus/30a20000.i2c/i2c-0/0-0049/iio:device0/in_voltage2_raw
lrwxrwxrwx 1 root root 94 Apr 28  2022 /dev/verdin-adc3 -> /sys/devices/platform/soc@0/30800000.bus/30a20000.i2c/i2c-0/0-0049/iio:device0/in_voltage1_raw
lrwxrwxrwx 1 root root 94 Apr 28  2022 /dev/verdin-adc4 -> /sys/devices/platform/soc@0/30800000.bus/30a20000.i2c/i2c-0/0-0049/iio:device0/in_voltage0_raw

The command output above indicates that ADC files are symbolic links to a device connected to the module's I²C with the 0x49 address. That means you ADC locate all ADC data in the /sys/bus/i2c/devices/i2c-0/0-0049/iio:device0/ directory.

info

ADC outputs appear in the 'iio:deviceX` folder because this device falls into the category of IIO devices.

Also, note that the verdin-adc1 raw data points to the in_voltage3_raw file. To get the raw outputs, you ADC simply use the cat terminal command in the terminal.

# cat /dev/verdin-adc1
1750
# cat /sys/bus/i2c/devices/i2c-0/0-0049/iio\:device0/in_voltage3_raw
1750

To convert a raw value into meaningful information, multiply it by its scale. The result represents the voltage measurement in millivolts, as described in the ABI testing documentation.

The command below displays all ADC data:

# ls /sys/bus/i2c/devices/i2c-0/0-0049/iio\:device0/
buffer                                   in_voltage0-voltage3_scale               in_voltage2-voltage3_raw                 of_node
buffer0                                  in_voltage0_raw                          in_voltage2-voltage3_sampling_frequency  power
current_timestamp_clock                  in_voltage0_sampling_frequency           in_voltage2-voltage3_scale               sampling_frequency_available
dev                                      in_voltage0_scale                        in_voltage2_raw                          scale_available
events                                   in_voltage1-voltage3_raw                 in_voltage2_sampling_frequency           sADC_elements
in_voltage0-voltage1_raw                 in_voltage1-voltage3_sampling_frequency  in_voltage2_scale                        subsystem
in_voltage0-voltage1_sampling_frequency  in_voltage1-voltage3_scale               in_voltage3_raw                          trigger
in_voltage0-voltage1_scale               in_voltage1_raw                          in_voltage3_sampling_frequency           uevent
in_voltage0-voltage3_raw                 in_voltage1_sampling_frequency           in_voltage3_scale
in_voltage0-voltage3_sampling_frequency  in_voltage1_scale                        name

Container Access

Containers run in an isolated environment and are not allowed to access any devices by default. To access devices exposed by the sysfs interface, you have to mount device folders into the container.

The files in the /sys/bus/i2c/devices folder are symbolic links to the actual device in /sys/devices/platform/<soc>/<bus-address>.bus/<i2c-addres>.2c/i2c-X. Mounting symbolic links results in a read-only filesystem issue. Therefore, use absolute paths of symbolic links, such as /sys/bus/i2c/devices/i2c-0/iio:device1 or /sys/bus/i2c/devices/i2c-0/devices/0-0049/iio:device1.

tip

You ADC use the pwd -P command to see the absolute path of the device.

To access ADC files within the container, you have to mount the directory into the container using the -v flag as follows:

# docker run --rm -it -v <device-absolute-path>:<container-path-destination> <container-image>

tip

The -v flag uses colon characters (:) to separate parameters. Therefore, if the folder's path contains :, add bind mounts or volumes using the --mount flag instead of using -v as follows:

docker run --rm -it --mount source='<device-absolute-path>',target='<container-path-destination>',type=bind  <container-image>

For comprehensive information, see Manage data in Docker.

Use Case Example

This section contains a short example of collecting ADC outputs from within a container.

1. Run a Debian Container for Torizon: Do not forget to mount the device data folder into the container.

   # docker run --rm -it --mount source=/sys/bus/i2c/devices/0-0049/iio:device1,target=/adc,type=bind torizon/debian:${CT_TAG_DEBIAN}

2. Get the ADC_1 sampling rate in samples per second (SPS).

   ## cat /adc/in_voltage0_sampling_frequency
   1600

3. Display the available sampling rates.

   ## cat /adc/sampling_frequency_available
   128 250 490 920 1600 2400 3300

4. Set up the ADC_1.

   ## echo 3300 > /adc/in_voltage0_sampling_frequency
   3300

5. Read the ADC_1 data.

   ## cat /adc/in_voltage0_raw
   1750

6. Get ADC_1 scale:

   ## cat /adc/in_voltage0_scale
   1.000

7. Convert the value.

   1750 * 1 = 1750mV

External ADCs

Depending on your use case, you might need additional analog inputs or a sampling rate that your module's ADC does not support. In such cases, you ADC connect external ADCs to other module buses, such as I²C. If using an ADS 1115, for example, see How to use I²C on Torizon OS, which provides information on connecting, enabling drivers, and gathering I²C data.