9. Command-Line Tools (CLI)

9.1. ‘pi-top’ Command

Utility to interact with pi-top hardware.

pi-top [-h] {battery,devices,display,support,imu,oled} ...

Where:

-h, --help

Show a help message and exits

{battery,devices,display,help,imu,oled}
battery:

Get battery information from a pi-top

devices:

Get information about device and attached pi-top hardware

display:

Communicate and control the device’s display

support:

Find support resources

imu:

Expansion Plate IMU utilities

oled:

Quickly display text in pi-top [4]’s miniscreen OLED display

9.1.1. pi-top battery

If the pi-top device has an internal battery, it will report its status.

pi-top battery [-h] [-s] [-c] [-t] [-w] [-v]

Where:

-h, --help

Show a help message and exits

-s, --charging-state

Optional. Return the charging state of the battery as an number, where:

  • -1: No pi-top battery detected

  • 0: Discharging

  • 1: Charging

  • 2: Full battery

-c, --capacity

Optional. Get battery capacity percentage %

-t, --time-remaining

Optional. Get the time (in minutes) to full or time to empty based on the charging state

-w, --wattage

Optional. Get the wattage (mAh) of the battery

-v, --verbose

If no argument is provided, this option will be used by default.

Report all the information available about the battery (charging state, capacity, time remaining and wattage)

Example:

pi@pi-top:~ $ pi-top battery
Charging State: 0
Capacity: 42
Time Remaining: 104
Wattage: -41

9.1.2. pi-top display

This command provides a way to control different display settings on pi-top devices with a built-in screen.

pi-top display [-h] {brightness,backlight,timeout}

Where:

-h, --help

Show a help message and exits

brightness

Control display brightness

backlight

Control display backlight

timeout

Set the timeout before the screen blanks in seconds (0 to disable)

9.1.2.1. pi-top display brightness

Request or change the value of the display’s brightness.

Note

This only works for the original pi-top, pi-topCEED and pi-top [3]. The pi-top [4] Full HD Touch Display uses hardware buttons to control the brightness, and is not controllable via this SDK.

pi-top display brightness [-h] [-v] [-i] [-d]
                             [brightness_value]

Where:

-h, --help

Show a help message and exits

-v, --verbose

Increase verbosity of output

-i, --increment_brightness

Increment screen brightness level

-d, --decrement_brightness

Decrement screen brightness level

brightness_value

Set screen brightness level; [1-10] on pi-top [1] and pi-topCEED, [1-16] for pi-top [3]

Using pi-top display brightness without arguments will return the current brightness value.

Note

The brightness_value range differs for different devices: for pi-top [3] is from 0-16; pi-top [1] and CEED is 0-10.

Example:

pi@pi-top:~ $ pi-top display brightness
16

9.1.2.2. pi-top display backlight

Using pi-top display backlight without arguments will return the current backlight status.

pi-top display backlight [-h] [-v] [{0,1}]

Where:

-h, --help

Show a help message and exits

-v, --verbose

Increase verbosity of output

{0,1}

Set the screen backlight state [0-1]

9.1.2.3. pi-top display blank_time

Set the time before the screen goes blank on inactivity periods.

Using pi-top display blank_time without arguments will return the screen’s timeout value.

pi-top display timeout [-h] [-v] [timeout_value]

Where:

-h, --help

Show a help message and exits

-v, --verbose

Increase verbosity of output

timeout_value

Timeout value in seconds. Set to 0 to disable.

9.1.3. pi-top devices

Finds useful information about the system and the attached devices that are being managed by pi-topd.

Running pi-top devices on its own will report back the current brightness value.

pi-top devices [-h] [--quiet] [--name-only] {hub,peripherals}

Where:

-h, --help

Show a help message and exits

--quiet, -q

Display only the connected devices

--name-only, -n

Display only the name of the devices, without further information

hub

Get the name of the active pi-top device

peripherals

Get information about attached pi-top peripherals

Example:

pi@pi-top:~ $ pi-top devices HUB =================================================== pi-top [4] (v5.4) PERIPHERALS =========================================== [ ✓ ] pi-top [4] Expansion Plate (v21.5) [ ] pi-top Touchscreen [ ] pi-top Keyboard [ ] pi-topPULSE [ ] pi-topSPEAKER (v1) - Left channel [ ] pi-topSPEAKER (v1) - Right channel [ ] pi-topSPEAKER (v1) - Mono [ ] pi-topSPEAKER (v2)

pi@pi-top:~ $ pt devices peripherals [ ✓ ] pi-top [4] Expansion Plate (v21.5) [ ] pi-top Touchscreen [ ] pi-top Keyboard [ ] pi-topPULSE [ ] pi-topSPEAKER (v1) - Left channel [ ] pi-topSPEAKER (v1) - Right channel [ ] pi-topSPEAKER (v1) - Mono [ ] pi-topSPEAKER (v2)

pi@pi-top:~ $ pt devices hub –name-only pi-top [4]

9.1.4. pi-top imu

Utility to calibrate the IMU included in the Expansion Plate.

pi-top imu calibrate [-h] [-p PATH]

Where:

-h, --help

Show a help message and exits

-p PATH, --path PATH

Directory for storing calibration graph data

Example:

pi-top imu calibrate --path /tmp

9.1.5. pi-top oled

Configure and display text/images directly onto pi-top [4]’s miniscreen OLED display.

pi-top oled [-h] {display,spi}

Where:

-h, --help

Show a help message and exits

display

Display text and images into the OLED

spi

Control the SPI bus used by OLED

9.1.5.1. pi-top oled display

Display text and images directly onto pi-top [4]’s miniscreen OLED display.

pi-top oled display [-h] [--timeout TIMEOUT] [--font-size FONT_SIZE] text

Where:

-h, --help

Show a help message and exits

-t, --timeout TIMEOUT

set the timeout in seconds

--font-size FONT_SIZE

set the font size

text

set the text to write to screen

Example:

pi@pi-top:~ $ pi-top oled display "hey!" -t 5

9.1.5.2. pi-top oled spi

Control the SPI bus used by the OLED. When using pi-top oled spi without arguments, the SPI bus currently used by the OLED will be returned.

pi-top oled spi [-h] {0,1}

Where:

-h, --help

Show a help message and exits

{0,1}

Optional. Set the SPI bus to be used by OLED. Valid options: 0 or 1

Example:

pi@pi-top:~ $ pi-top oled spi
1

pi@pi-top:~ $ pi-top oled spi 0

pi@pi-top:~ $ pi-top oled spi
0

9.1.6. pi-top support

Find information about support topics for your device.

pi-top support [-h] {links,health_check} ...

Where:

-h, --help

Show a help message and exits

{links,health_check}

Subcommands, please refer to the next sections.

9.1.6.2. pi-top support health_check

Perform a system wide check to help troubleshooting any problems with pi-top software and hardware.

pi-top support health_check