The Android Things console is no longer accepting new projects, and will be turned down for all existing projects on January 5, 2022. For more details, visit the FAQ page.

PIO CLI tool

This command line tool enables you to query and control the various interfaces supported by Peripheral I/O. You can use this tool to do the following:

  • Easily discover the pin names for a given developer board
  • Ensure peripheral devices are connected to the board correctly
  • Run basic functionality tests as well as scripted tests

Use an adb shell to access this tool.

Command reference

Issue commands from a command line on your development machine or from a script. The usage is:

pio command [arg]

where command can be one of the following:

Command Description
gpio General Purpose Input/Output (GPIO) pin control
i2c Inter-Integrated Circuit (I2C) bus control
list List all of the available interfaces. Optionally, provide a type of device to only list those device types.
pwm Pulse Width Modulation (PWM) device control
spi Serial Peripheral Interface (SPI) device control
uart Universal Asynchronous Receiver Transmitter (UART) device control

List command

Usage

pio list [device]

To list only devices of a certain type, specify device to be one of the following:

  • gpio
  • i2c
  • pwm
  • spi
  • uart

Example

$ pio list
gpio GPIO1_IO10
pwm PWM1
spi SPI3.0

$ pio list gpio
GPIO1_IO10

GPIO command

Usage

pio gpio name subcommand [arg]

name is the name of a valid GPIO pin.

subcommand can be one of the following:

Subcommand Description
write Set the GPIO output state.
  • Use 0 or 1 to designate the low or high logic state.
read Read from the specified GPIO.

Example

$ pio gpio GPIO1_IO10 write 0
$ pio gpio GPIO2_IO07 read
1

I2C command

Usage

pio i2c name address subcommand [arg]

name is the name of a valid I2C bus.

address is the address of an I2C device.

subcommand can be one of the following:

Subcommand Description
read-raw size Read size bytes from device.
read-reg-byte reg Read a byte from reg.
read-reg-word reg Read a word (2 bytes) from reg.
read-reg-buffer reg size Read size bytes from reg.
write-raw val [val ...] Write val to device.
write-reg-byte reg val Write byte val to reg.
write-reg-word reg val Write word val to reg.
write-reg-buffer reg val [val ...] Write val to reg.

Example

$ pio i2c I2C1 0x10 write-reg-byte 0x20 0x40
$ pio i2c I2C1 0x12 read-reg-byte 0x24
0x7F

PWM command

Usage

pio pwm name subcommand [arg] [opt]

name is the name of a valid PWM interface.

subcommand can be the following:

Subcommand Description
enable Enable or disable the PWM.
  • Use 0 or 1 to disable or enable the PWM.

opt can be any combination of the following:

Option Description
--duty Sets the duty cycle. Default is 50.0.
  • Use a number from 0 to 100.0.
--freq Sets the frequency (in Hertz). Default is 100.
  • Use a positive number.

Example

$ pio pwm PWM1 enable 1 --duty=55.0 --freq=200

SPI command

Usage

pio spi name subcommand arg [opt]

name is the name of a valid SPI interface.

subcommand can be one of the following:

Subcommand Description
write val [val ...] [opt ...] Write val with opt (optional parameters) to device.
read size [opt ...] Read size characters with opt from device.
transfer val [val ...] [opt ...] Write val to device with opt. Read an equal number of characters with opt from device.

opt can be any combination of the following:

Option Description
--freq Sets the frequency (in Hertz). Default is 200,000.
  • Use a number.
--mode Sets the device mode. Default is mode 0.
  • 0: [CPHA=0, CPOL=0]
  • 1: [CPHA=1, CPOL=0]
  • 2: [CPHA=0, CPOL=1]
  • 3: [CPHA=1, CPOL=1]
--bits Sets the bits per word. Default is 8.
  • Use a number.
--just Sets bit justification to LSB or MSB. Default is msb.
  • Set to lsb or msb.

Example

$ pio spi SPI3.0 write 0x20 0x40 --freq=250000
$ pio spi SPI3.1 transfer 0xD0 0x00 --just=lsb
0x00 0xDE

UART command

Usage

pio uart name subcommand [opt]

name is the name of a valid UART device.

subcommand can be one of the following:

Subcommand Description
write opt Write stdin to device.
read opt Read from UART device.
transfer opt Write to and read from the UART device.

opt can be any combination of the following:

Option Description
--readlen Number of characters to read from the device, only for read and transfer. Default is indefinite.
  • Use a number.
--baud Sets the baud rate (in Hertz). Default is 9600.
  • Use a number.
--stop Sets the number of stop bits. Default is 1.
  • Use a number.
--bits Sets the size of a character for the UART device. Default is 8.
  • Use a number.
--parity Sets the parity mode. Default is N: None.
  • N: None
  • E: Even
  • O: Odd
  • M: Mark
  • S: Space

Example

$ pio uart UART6 write --baud=9600 --bits=8 --stop=1 --parity=N # Input from file, pipe, or stdin
$ cat file.txt | pio uart UART6 write --baud=9600 --bits=8 --stop=1 --parity=N