Each Jetson developer kit includes a 40-pin expansion header. Many of the pins can be used either as GPIO or as “special function I/O” (SFIO) such as I2C, I2S, etc. The 40‑pin header lets you connect a Jetson developer kit to off-the-shelf Raspberry Pi HATs (Hardware Attached on Top) such as Seeed Grove modules, SparkFun Qwiic products, and others.
The default configuration of all of the I/Os on Jetson developer kits is statically defined and programmed into the device when the system is flashed. To alter the configuration of the pins exposed by the 40‑pin expansion header prior to L4T release 32.3, you had to update the pin configuration using a pinmux spreadsheet for the appropriate platform, and then flash the new configuration to the developer kit. Although this might be an adequate means of updating a production system, a more convenient way of testing different pin configurations was needed for development.
Starting with L4T release 32.3, NVIDIA provides the Jetson-IO tool to simplify the configuration of the I/Os exposed by the 40‑pin expansion header. Jetson‑IO is a Python-based tool that runs on the developer kit and modifies the Device Tree Blob (DTB) firmware so that a new configuration for the 40‑pin expansion header is applied when the developer kit is rebooted.
Launching Jetson‑IO
To launch Jetson‑IO, enter this command on the developer kit:
$ sudo /opt/nvidia/jetson-io/jetson-io.py
Note
There are two known issues in L4T release 32.3.1 which prevent Jetson‑IO from working correctly:
• Launching Jetson‑IO fails with the following error:
$ sudo /opt/nvidia/jetson-io/jetson-io.py
Traceback (most recent call last):
File "/opt/nvidia/jetson-io/jetson-io.py", line 25, in <module>
from Jetson import board
ImportError: cannot import name 'board'
To resolve this issue, enter the following command:
• After L4T on Jetson Nano is upgraded to release 32.3.1 using the SD card image, launching Jetson-IO fails with the error message ‘No DTB found for NVIDIA Jetson Nano Developer Kit!’.
To resolve this issue, enter the following commands:
When you launch Jetson‑IO it displays the following screen. This main screen displays the current configuration of the 40‑pin header and offers you two options for configuring the I/O:
• Configure Jetson for compatible hardware: Lets you select from a list of configurations for hardware modules that can be attached to the 40‑pin expansion header.
• Configure 40‑pin expansion header: Displays a screen (below) which lets you specify which function to enable on the 40‑pin expansion header.
Compatible Hardware Screen
When you select the “configure for compatible hardware” option, Jetson‑IO displays a list of configurations for certain hardware modules.
Currently there are configurations for two hardware modules:
• Adafruit SPH0645LM4H (I2S MEMS Microphone)
• FE-PI Audio Z V2 (SGTL5000 I2S audio codec)
After you select a configuration, Jetson‑IO returns to the main screen, where it shows a diagram of the 40‑pin expansion header updated for that configuration.
You may select one of these actions:
• Save and reboot to reconfigure pins: Creates a new DTB by applying a Device Tree overlay for the configuration. It then updates the configuration file for booting Linux (/boot/extlinux/extlinux.conf) and reboots the developer kit.
Note that after configuration file has been updated you can still boot the developer kit to the previous configuration, because Jetson‑IO updates extlinux.conf by adding a new entry for the new configuration. The previous configuration is still in the file. When the target is booted, the bootloader lets you select either configuration (or any other that is defined in the file).
• Save and exit without rebooting: Creates a new DTB and updates extlinux.conf the same as “Save and reboot,” but does not reboot the developer kit. You can apply the new configuration by rebooting at a time of your choice.
• Discard pin changes: Discards changes and returns to the main screen.
• Exit: Terminates Jetson‑IO without making any changes.
40‑Pin Expansion Header Screen
When you select the “Configure 40‑pin expansion header” option on the main screen, Jetson‑IO displays a list of special functions that the 40‑pin header I/Os support. It shows the pins associated with the functions in parenthesis.
For example, on the NVIDIA® Jetson™ Nano Developer Kit, Jetson‑IO displays the following list of functions.
For more details on the supported functions, see the Technical Reference Manual for the Jetson SoC in your developer kit.
You may select or deselect functions according to your needs.
To accept the selected set of functions, select the “Back” option. Jetson‑IO returns to the main screen. It redisplays the main screen as it appears after the Compatible Hardware Screen, with one additional entry:
• Export as Device Tree Overlay: Exports the configuration of 40‑pin expansion header as a new Device Tree overlay.
Command Line Interface
If you prefer to configure the target’s 40‑pin expansion header from the command line instead of menus, NVIDIA provides a set of command line utilities that offer the same functionality. The following sections describe these utilities.
View 40‑Pin Header Configuration by Pin
NAME
config-by-pin.py - display configuration of the 40‑pin expansion header
SYNOPSIS
config-by-pin.py [OPTION]
DESCRIPTION
Displays the current configuration of the 40‑pin expansion header. The following switches specify the part(s) of the configuration to display. If no options are used, the entire configuration is displayed.
-h, --help
Displays a usage message and exits.
-p, --pin=NUMBER
Displays current configuration of the pin specified by NUMBER, which must be between 1 and 40.
EXAMPLES
sudo /opt/nvidia/jetson-io/config-by-pin.py
sudo /opt/nvidia/jetson-io/config-by-pin.py -p 5
Configure the 40‑Pin Header by Special Function
NAME
config-by-function.py - configure I/O functions for the 40‑pin expansion header
Displays and configures the I/O functions available on the 40‑pin expansion header.
-h, --help
Displays a usage message and exits.
-l, --list={all,enabled}
all lists all of the functions supported by the 40‑pin expansion header. enabled lists only the functions that currently are enabled.
-o, --out={dtb,dtbo}
Creates a new DTB or Device Tree overlay (DTBO) for the list of functions provided. If the command creates a new DTB file, the Linux boot configuration file (/boot/extlinux/extlinux.conf) is updated with a new option to boot using this DTB.
EXAMPLES
sudo /opt/nvidia/jetson-io/config-by-function.py -l all
config-by-hardware.py - configure Jetson for a hardware module
SYNOPSIS
config-by-hardware.py [-l]
config-by-hardware.py [-n NAME]
DESCRIPTION
Displays a list of the hardware module configurations supported by Jetson and configures Jetson for a given hardware module.
-h, --help
Displays a usage message and exits.
-n, --name=NAME
Configures Jetson for the hardware module specified by NAME. Note that this generates a new DTB file for the hardware module and updates the Linux boot configuration file /boot/extlinux/extlinux.conf with a new option to boot using this DTB.
-l, --list
Displays a list of available hardware module configurations.
You can use Jetson‑IO to support a custom hardware module by creating a Device Tree overlay for the hardware module. The following sections describe this process.
Device Tree Overlays
To add support for your custom hardware to Jetson‑IO you must understand how Jetson‑IO manages hardware add-ons. Support for hardware modules is handled by Device Tree overlay files (.dtbo files).
A Device Tree overlay for a hardware module must define:
• An overlay-name property that specifies a name for the hardware module
• A compatible property that indicates which combinations of Jetson module and carrier board the overlay supports
• The special-function IOs (if any) required on the 40‑pin expansion header
• The nodes and/or properties for any devices on the module, for example, external integrated circuits such as audio codecs
The overlay-name property must be a unique name that distinguishes the overlay from others. The compatible property must have one or more of the following, depending on what Jetson platforms are supported.
Jetson Platform
Compatible String
Jetson Nano (A02)
nvidia,p3449-0000-a02+p3448-0000-a02
Jetson Nano (B0x)
nvidia,p3449-0000-b00+p3448-0000-b00
Jetson TX2 series
nvidia,p2597-0000+p3310-1000
Jetson AGX Xavier series
nvidia,p2822-0000+p2888-0001
Jetson TX1
nvidia,p2597-0000+p2180-1000
Users can obtain the correct compatible string for their Jetson platform by entering the following command. If you have a Jetson Nano developer kit, this command also identifies the PCB revision.
$ cat /sys/firmware/devicetree/base/compatible
As an example, consider the FE-PI Audio Z V2 module. In the target’s /boot directory are overlay files with names matching the pattern:
*-fe-pi-audio-z-v2.dtbo
You can use the fdtdump utility to inspect the contents of the overlay files and view the overlay-name and compatible properties. For example, on the Jetson Nano developer kit you can display these properties by entering the command:
To create a simple Device Tree overlay to add a new custom property for the Jetson Nano (with A02 carrier board and A02 module) developer kit, create a file named my-overlay.dts on the target platform with the following contents:
The following hardware configurations are available:
1. Adafruit SPH0645LM4H
2. FE-PI Audio Z V2
3. My Jetson Overlay
$ sudo /opt/nvidia/jetson-io/config-by-hardware.py -n "My Jetson Overlay"
Creating a Custom Device Tree Overlay for the 40‑Pin Header
If you want to create an overlay for a custom hardware module that attaches to the 40‑pin expansion header, the simplest way to do so is to use Jetson‑IO to configure the 40‑pin header as needed and export the configuration as an overlay. You can do this with either the menu-oriented Jetson‑IO script or the associated config-by-... command line tools.
For example, to create an overlay for Jetson Nano (A02) that enables the I2S interface, enter this command:
You can modify the generated Device Tree source as necessary for your custom hardware, adding any additional nodes and/or properties that the hardware module requires. Then you can re-compile the Device Tree source and place it in the /boot/ directory for Jetson‑IO to use:
