This section will demonstrate examples of how to use the sensors and data lines on the board.
All examples will be performed via the Terminal/Console after establishing a serial port connection, so it is assumed that you have read the explanations about Terminal usage in the Quick Start section. You may choose one of the methods described in the relevant section: connecting to the Desktop image via a browser, connecting via SSH/Ethernet, or connecting via the console over the serial port.

​
1. Pinout

The Input/Output (I/O) pins on the board, referred to as the 40-pin expansion header, provide interfaces such as UART (serial port), I2C, SPI, PWM, and PCM. The purposes of the 40-pin I/O ports and their default interface assignments will be explained. In the next section, it will be described how the pins can be reconfigured for different uses using Device Tree Overlay files. For example, the pin named GPIO-7 is configured as SPI-MCU0 CS1 by default but can be converted to the UART-WKUP0 RX function by activating a file called Device Tree Overlay. Similarly, in the Gemstone VTOL project, since Bluetooth was not needed, the relevant pins were disabled and converted to UART-MAIN6.
PINSPINS
3v3 Power3v3 Power5v Power5v Power
I2C-MCU0 SDAGPIO-25v Power5v Power
I2C-MCU0 SCLGPIO-3GNDGND
GPIO-4GPIO-14UART-MAIN1 TX
GNDGNDGPIO-15UART-MAIN1 RX
GPIO-17GPIO-18PCM-McASP0 CLK
GPIO-27GNDGND
GPIO-22GPIO-23
3v3 Power3v3 PowerGPIO-24
SPI-MCU0 MOSIGPIO-10GNDGND
SPI-MCU0 MISOGPIO-9GPIO-25
SPI-MCU0 SCLKGPIO-11GPIO-8SPI-MCU0 CS0
GNDGNDGPIO-7SPI-MCU0 CS1
I2C-WKUP0 SDA (reserved)GPIO-0GPIO-1I2C-WKUP0 SCL (reserved)
GPIO-5GNDGND
GPIO-6GPIO-12PWM-ECAP0
PWM-1BGPIO-13GNDGND
PCM-McASP0 FSGPIO-19GPIO-16
GPIO-26GPIO-20PCM-McASP0 DIN
GNDGNDGPIO-21PCM-McASP0 DOUT

​
1.1. UART-MAIN1

This UART interface can be accessed via the /dev/ttyS3 device on the Gemstone board. To test the UART line from the command line, you can use the picocom program.
picocom is a serial terminal application that sends characters typed on the keyboard in real time to the specified serial port while also displaying data received from the other end. After connecting the TX and RX pins with a jumper cable, you can run the following command. If the connections are correct, you should see the characters you type on the screen. 
gemstone@t3-gem-o1:~$ picocom -b 115200 /dev/ttyS3
# picocom v3.1
#
# port is        : /dev/ttyS6
# flowcontrol    : none
# baudrate is    : 115200
# parity is      : none
# databits are   : 8
# stopbits are   : 1
# escape is      : C-a
# local echo is  : no
# noinit is      : no
# noreset is     : no
# hangup is      : no
# nolock is      : no
# send_cmd is    : sz -vv
# receive_cmd is : rz -vv -E
# imap is        :
# omap is        :
# emap is        : crcrlf,delbs,
# logfile is     : none
# initstring     : none
# exit_after is  : not set
# exit is        : no
#
# Type [C-a] [C-h] to see available commands
# Terminal ready
# Hello World

​
1.2. I2C-MCU0

This I2C interface can be accessed via the /dev/i2c-1 device on the Gemstone board. To view the peripheral devices connected to the bus, you can use the i2cdetect command.
An example output is provided below. In the command output, peripheral devices marked with UU (e.g., 0x30) are connected to the I2C bus but are in use by the Linux kernel, while those with a numeric address (e.g., 0x6b) are connected and idle. 
gemstone@t3-gem-o1:~$ i2cdetect -r -y 1
#      0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
# 00:                         -- -- -- -- -- -- -- --
# 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 30: UU -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 60: -- -- -- -- -- -- -- -- -- -- -- 6b -- -- -- --
# 70: -- -- -- -- -- -- -- --

​
1.3. I2C-WKUP0

This I2C interface is used to identify Hardware Attached on Top (HAT) devices connected to the board via the 40-pin expansion header. During boot, the EEPROM on the HAT is queried, and the device information is read. If no HAT will be connected to the board, these pins should be left unconnected.

​
1.4. SPI-MCU0

This SPI interface can be accessed via the /dev/spidev0.0 and /dev/spidev0.1 devices on the Gemstone board.
/dev/spidev0.0 corresponds to SPI-MCU0 CS0, and /dev/spidev0.1 corresponds to SPI-MCU0 CS1. To test the SPI line from the command line, you can use the spi-pipe program.
spi-pipe sends data from stdin to the SPI line specified by the --device setting and outputs the data received from the line to stdout. After connecting the MOSI and MISO pins with a jumper cable, you can run the following command. If the connections are correct, you should see the text “Hello World” on the screen. 
gemstone@t3-gem-o1:~$ printf '\x48\x65\x6c\x6c\x6f\x20\x57\x6f\x72\x6c\x64' | spi-pipe --device /dev/spidev0.0 --speed 1000000
# Hello World

​
1.5. PWM-1B

This PWM interface can be accessed via the /sys/class/pwm/pwmchip5/pwm1 device on the Gemstone board. For this device to be created, the export command must first be executed.
Then, the period and duty_cycle values in nanoseconds can be set to the desired values as shown in the example below. After enabling the device with the enable command, the PWM output can be obtained. 
gemstone@t3-gem-o1:~$ echo 1 | sudo tee /sys/class/pwm/pwmchip5/export
# 1
gemstone@t3-gem-o1:~$ echo 2000000 | sudo tee /sys/class/pwm/pwmchip5/pwm1/period     # 500 Hz
# 2000000
gemstone@t3-gem-o1:~$ echo 1000000 | sudo tee /sys/class/pwm/pwmchip5/pwm1/duty_cycle # 50%
# 1000000
gemstone@t3-gem-o1:~$ echo 1 | sudo tee /sys/class/pwm/pwmchip5/pwm1/enable
# 1

​
1.6. PWM-ECAP0

This PWM interface can be accessed via the /sys/class/pwm/pwmchip0/pwm0 device on the Gemstone board. 
gemstone@t3-gem-o1:~$ echo 0 | sudo tee /sys/class/pwm/pwmchip0/export
# 0
gemstone@t3-gem-o1:~$ echo 2000000 | sudo tee /sys/class/pwm/pwmchip0/pwm0/period     # 500 Hz
# 2000000
gemstone@t3-gem-o1:~$ echo 1000000 | sudo tee /sys/class/pwm/pwmchip0/pwm0/duty_cycle # 50%
# 1000000
gemstone@t3-gem-o1:~$ echo 1 | sudo tee /sys/class/pwm/pwmchip0/pwm0/enable
# 1

​
1.7. PCM-McASP0

Pulse-code Modulation (PCM), or Multichannel Audio Serial Port (McASP) as it is called in Texas Instruments SoCs, can be used in real-time audio processing applications requiring low-latency and high-quality digital audio streaming. The FS pin provides a frame-sync signal to an external audio device like a DAC, while the CLK pin similarly provides a clock signal. The DIN pin allows data input from a digital audio device like an I2S microphone, and the DOUT pin allows data output to a digital audio device like a DAC.

​
2. Device Tree

The configurations (UART, PWM, I2C, GPIO, …) that the 40-pin I/O ports on the board can be used for are defined in files called device tree overlays. To activate the desired configuration(s), the relevant overlay files must be found and provided to the bootloader as a list. For Texas Instruments ARM64-based SoCs, the source code for all overlay files is located in the t3gemstone/linux project under the arch/arm64/boot/dts/ti directory. Those for the T3-GEM-O1 board are named in the format k3-am67a-t3-gem-o1-<overlay_name>.dtso. Each overlay file includes information at the beginning about its purpose.

​
2.1. Example: Routing UART6 signals to the 40-pin HAT

By default, the T3-GEM-O1’s 40-pin HAT has only one serial port. For projects requiring multiple serial ports, other pins on the 40-pin HAT must be converted to serial ports.

​
2.1.1. Examining the Pinout

When examining the T3-GEM-O1’s pinout, it can be seen that pins 7 and 11 on the HAT can be used as UART6_RX and UART6_TX.

​
2.1.2. Finding the Relevant Overlay File

The next step is to determine which device tree overlay file provides the desired configuration.
All device tree overlay files are located in the /boot/overlays folder on the development board. They can be listed by running the ls /boot/overlays command. 
|-- boot
|   |-- overlays
|   |   |-- k3-am67a-t3-gem-o1-csi0-imx219.dtbo
|   |   |-- k3-am67a-t3-gem-o1-disable-imu.dtbo
|   |   |-- k3-am67a-t3-gem-o1-disable-leds.dtbo
|   |   |-- k3-am67a-t3-gem-o1-dsi-rpi-7inch-panel.dtbo
|   |   |-- k3-am67a-t3-gem-o1-gpio-fan.dtbo
|   |   |-- k3-am67a-t3-gem-o1-i2c1-400000.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-ecap0-gpio12.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-ecap1-gpio16.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-ecap2-gpio18.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-epwm0-gpio14.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-epwm0-gpio5-gpio14.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-epwm0-gpio5.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-epwm1-gpio13.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-epwm1-gpio6-gpio13.dtbo
|   |   |-- k3-am67a-t3-gem-o1-pwm-epwm1-gpio6.dtbo
|   |   |-- k3-am67a-t3-gem-o1-spi0-1cs.dtbo
|   |   |-- k3-am67a-t3-gem-o1-spi0-2cs.dtbo
|   |   |-- k3-am67a-t3-gem-o1-spidev0.dtbo
|   |   |-- k3-am67a-t3-gem-o1-uart-ttyama0.dtbo
|   |   |-- k3-am67a-t3-gem-o1-uart-ttys0.dtbo
|   |   |-- k3-am67a-t3-gem-o1-uart-ttys6.dtbo

​
2.1.3. Updating the uEnv.txt File

In this example, the k3-am67a-t3-gem-o1-uart-ttys6.dtbo overlay file will be used. For the bootloader to load this file before the operating system starts, it must be added to the overlays section in the /boot/uEnv.txt file as shown below. Overlay file names are added with a space between them. overlays=k3-am67a-t3-gem-o1-uart-ttyama0.dtbo k3-am67a-t3-gem-o1-spidev0.dtbo k3-am67a-t3-gem-o1-uart-ttys6.dtbo

​
2.1.4. Verification

After saving the changes, the board should be rebooted using the reboot command.
Then, the ls /proc/device-tree/chosen/overlays command can be used to check whether the overlay has been added. 
k3-am67a-t3-gem-o1-spidev0.kernel
k3-am67a-t3-gem-o1-uart-ttyama0.kernel
k3-am67a-t3-gem-o1-uart-ttys6.kernel
...
After completing the above steps successfully, the /dev/ttyS6 device will be created.