pi-topOS - Official Documentation

Please note that this documentation is currently under active construction. We ask that you bear with us while we work to assemble this document!

Hello and welcome to pi-topOS's official documentation.

This is an evolving document that seeks to describe the current state of pi-topOS. As updates are released, the way that the OS behaves will change, and so too will this document.

Where there is notable information about earlier versions (such as serious bugs and usability issues), this document will seek to provide useful information.

Unless you have a very specific issue, you will need to make sure that you are using the latest version of pi-topOS and its software. Otherwise, you may find that this documentation does not accurately reflect what you are actually using.

👁 Overview

pi-topOS is the recommended way to use your pi-top.

pi-topOS is built on top of Raspberry Pi OS (formerly Raspbian), so a lot of things are identical. However there are some differences.

The underlying operating system (Raspberry Pi OS) handles much of the backbone functionality that pi-topOS depends on - things like the desktop environment, software update management, etc.

pi-topOS developers are not directly involved in the development of much of the low-level core features of pi-topOS. Rather, pi-topOS is 'downstream', and therefore directly benefits from this work done by the Raspberry Pi Foundation.

⚠️ In rare circumstances, unexpected changes to Raspberry Pi OS can cause breaking changes to pi-topOS. Fortunately, this is a rare occurrence!

So pi-topOS is built on top of Raspberry Pi OS. What's different?

pi-topOS extends upon Raspberry Pi OS to add additional functionality and usability improvements:

• Plug-and-Play functionality with pi-top hardware
• Modifying the user interface (including theming)
• Notification system
• Automatic software updater
• Simplified user onboarding/OS setup
• Additional settings for pi-top hardware
• ‘About’ page to show key information about the OS that is installed

For more information about pi-topOS, check out the technical details subsection of the pi-topOS knowledge base

What if I want to use Raspberry Pi OS?

Some users prefer to stick to Raspberry Pi OS and install the minimal device drivers to get Plug-and-Play functionality with pi-top hardware without the additional customisations of pi-topOS.

If you'd like to use a pi-top device with Raspberry Pi OS, take a look at this article.

What if I want to use another operating system?

⚠️ Other operating systems are not supported.

For a pi-top device to work properly, communication is required between the Raspberry Pi and the pi-top's onboard "Hub" (microcontroller unit, or MCU). At this time, the software for working with a pi-top is only available for Raspberry Pi OS-based systems.

Without this communication, all pi-top devices will be unable to power off correctly. The power button will need to be held in place for longer to force a hard shutdown, which is dangerous and could cause serious SD card corruption. Shutting down the Raspberry Pi via a 'soft shutdown' (asking the operating system to shut down, such as via the start menu) will turn off the Raspberry Pi, but the pi-top device will continue to be powered on.

Additionally, hardware will not work as intended - for instance, display brightness on pi-top laptops and the miniscreen on the pi-top [4]. For pi-top devices with an onboard battery, it will not be possible to determine its state.

If you are using an unsupported OS, it is recommended that you power off your Raspberry Pi via the start menu and wait until the Raspberry Pi has halted before powering off the pi-top hardware via the hardware power button.

🙋 FAQs

Why can't I update?

Check out our knowledge base article for guidance on updating issues.

Why can't I connect to Further?

Check out our knowledge base article for guidance on connecting to Further.

Why can't I use port 80?

Check out our knowledge base article for guidance on working with TCP port 80.

Why does my screen resolution keep resetting on reboot?

autorandr, HDMI forced output,

How does pi-topOS handle versioning?

See the glossary for more information about the previous versions and their respective names.

pi-topOS is based on Raspberry Pi OS, which is based on Debian. Debian changes every ~18 months.

Why is pi-topSPEAKER not mentioned/included in the pi-top Python SDK?

pi-topSPEAKERs are automatically configured and initialized via pt-device-manager. Because there are no desirable programmatic hardware settings, there is no exposed public API for this hardware.

Why does my pi-top [4] require a modified EEPROM?

Raspberry Pi 4 boards earlier than the 1.4 PCB revision (All 8GB models have this, and this is now also the default for 2GB and 4GB models) require a modified EEPROM to power off correctly.

These newer boards hold the external reset until it is released by software (SPI bootloader) when the watchdog/soft reset occurs.

This means that the 5V rail on the USB bus will be off until the second stage bootloader has initialised or if halting it will stay off. On previous board revisions, this was not under software controls so 5V would be initialised when the XHCI/VLI automatically initialised, which could happen before halt.

Therefore, it is necessary to update the Raspberry Pi's internal EEPROM firmware to behave correctly. The following changes are made to the EEPROM:

WAKE_ON_GPIO=0
POWER_OFF_ON_HALT=1

⚠️ There is a very small risk of damage to Raspberry Pi HATs where 5V is powered but 3V3 is off (unless the HAT is designed to support that power configuration). Check with your HAT manufacturer to find out more.

🤖 Controlling pi-top Hardware

There are many ways to interact with hardware. However, pi-top have worked hard to offer a coherent programming experience for all. Consequently, this has led to the development of software development kits (SDKs).

Currently, it is possible to interact with a pi-top with 2 different SDKs:

• Python SDK
• .NET SDK

Check out the examples for each:

• Python examples
  • Documentation Recipes
  • In GitHub Repository
• .NET samples

🌀 Web Portal

What is web portal?

Web Portal is a web server application that serves up webpages when the IP address or hostname of the machine running the software is accessed via a web browser.

This provides a convenient way of accessing the device without the need for any of the following:

• spare mouse and/or keyboard
• a display

Instead, all you need is a device that can connect to your device via a web browser. The additional benefit of this is that it does not require a dedicated VNC or SSH client to access the device.

What is it currently used for?

Right now, it serves up webpages for user onboarding (OS setup, etc.).

What will it do in the future?

As the application continues to mature, we intend to build all of our GUI interfaces as web apps that are served via the web portal backend. Applications on the desktop will open in a native-looking window that points to the local server to present the GUI and handle user interaction.

This includes the OS updater, which currently uses a terminal window - an approach that can cause unintended issues for users.

How might this affect what I can do on pi-topOS?

The web portal requires TCP port 80. If you require port 80, then you will need to disable the web portal:

sudo systemctl disable pt-web-portal

⚠️ This will disable all of pi-top's own graphical applications that run on the desktop.

💁 Tips & Tricks

This section seeks to offer useful tips for working with pi-topOS, although many of these tips are more broadly useful.

Aliases

Aliases are a great way to shorten the amount you need to write in a terminal if you find yourself running the same commands over and over.

Read the Raspberry Pi's documentation for how to set this up.

Here are some potentially useful suggestions for you to get started with. Obviously, you can change the alias and the command that is called to suit your purposes. However, take care not to accidentally use the same name as a command on your system, as it will require additional maintenance effort.

Faster printing to pi-top [4] miniscreen

This alias will display some text onto a pi-top [4] miniscreen for 10 seconds.

Alias Line:

alias pt-write="pitop oled write -t10"

Usage:

pt-write "Hello World"

Technical Details

Dependency Graph

Below is a modified dependency graph of the pt-os top-level package that is installed on top of Raspberry Pi OS to produce pi-topOS:

Table Of pi-top Software Packages

Here is an outline of how the packages are organized:

Core Packages / System Management

• pt-os-core

Theming

• pt-icon-theme
• pt-plym-splash
• pt-ui-mods

Desktop

• pt-notifications
• pt-system-tools

GUIs

• pt-shutdown-helper
• web-renderer

Hardware

• i2c-tools-extra (Additional I2C utilities)
• pt-sys-oled
• pt-touchscreen

Here is a more comprehensive guide (work in progress) of the packages that currently comprise pi-topOS:

OS build process

In addition to installing the pt-os package, which in turn installs all other pi-topOS packages, the following changes are made during OS builds:

• Change the default pi user password to pi-top
• Enable VNC Server by default
• Add pi-top software repository
• Force HDMI out of HDMI1 on Raspberry Pi 4 to allow for VNC without a connected display
• Force HDMI blanking
• Enable hardware interfaces (SPI, I2C) used by pi-tops by default to allow detection on first boot
• Enable extra video codecs in Raspberry Pi GPU firmware; adding native support for Raspberry Pi Camera
• Sette GPU memory allocation to 128MB
• Configure a DHCP server on pi-top [4]’s USB-OTG port
• Sette up dynamic swap for better performance
• Change hostname from 'raspberrypi' to 'pi-top' Setting default locale and keyboard layout to US
• Customize color scheme, font and icons

Device Drivers

TODO: how device manager, SDK, common library and pi-top hardware all work together

TODO: how pi-topOS software hot-loads kernel modules using dtoverlay and dtparam for hardware interfaces. how interfaces are enabled/disabled or handled automatically

• I2C
• UART - pi-topPULSE microphone
• SPI - pi-top [4] miniscreen
• I2S - pi-topPULSE and pi-topSPEAKER
  • pi-top [3]'s onboard HDMI-to-I2S conversion
  • enabling volume control with hifiberry-alsactl.restore

TODO: communication protocols (e.g. ZMQ, udev, systemd), which modules require them, why, and how to handle strange "gotchas".

🕵️ Troubleshooting

This section of the documentation aims to provide useful information to assist with identifying issues with pi-topOS. Be sure to check out our FAQ section, that aims to address the most common questions/problems that people have.

Collecting and Reviewing System Information

Find out how to collect useful information about your pi-top device's operating system and hardware state, and understand how to decipher/use it.

Collecting System Information

On pi-topOS you can run the following command:

pi-top support health_check

This will generate some potentially useful information about the state of the device.

⚠️ WARNING: It is recommended that you review this data carefully before passing it to someone else - it may reveal personal information about your setup that you may not wish for others to know about.

Do not give this information to anyone you do not trust without first checking its contents.

Interpreting System Information

Raspberry Pi Device Information

Identifies the Raspberry Pi model type, and provides information about the state of the Raspberry Pi device, such as bootloader configuration, EEPROM version and GPU information.

pi-top Devices

Identifies what type of pi-top device the Raspberry Pi identifies that it is communicating with, and if any pi-top peripherals are connected or not.

System Information

Provides information about the active kernel, as well as pi-topOS build information.

Interfaces/Boot Settings/Misc (via raspi-config)

Shows information that can be determined via the 'raspi-config' tool.

Network Settings

Shows key network information, such as hostname, WiFi country, interfaces, IP addresses, etc.

pi-top Software Information

Shows the current state of pi-top software provided as systemd services, as well as the version of each pi-top software package.

pi-top Device Information

Provides hardware-level detail about the state of the pi-top hub.

📘 Glossary

Sirius

Latest version of pi-topOS.

Polaris

Previous version of pi-topOS.

Buster

Current version of Debian that pi-topOS Sirius is based on.

Bullseye

Upcoming version of Debian that the next version of pi-topOS will be based on.

✍️ Contributing to pi-topOS

Want to contribute? Read on for guidelines, best practices, links, and more!

There are a tonne of ways that an enthusiastic maker, student or professional can contribute!

Cool Project?

Got a cool project to share? Tell us about it in the forum!

Want to make things better?

Have you found a bug, or want to suggest a feature? We'd love to know more.

Before you get started, it's important that you understand which GitHub repository to file an Issue into.

Is your bug report or feature request in relation to Python development with pi-top hardware? Check out the pi-top Python SDK and pi-top Python Common Library repositories on GitHub.

pi-topOS also has other packages that are hosted in GitHub repositories - check out the Technical Details page for more information.

In most cases, these repositories are NOT the right place for a GitHub Issue, as the scope of their functionality is typically more limited than the scope of a usability issue or bug.

⚠️ If you are not sure which GitHub repository is the right one, then try reporting/suggesting to the forum first.

Bug? Usability Issue?

Is It A Bug? Do We Know About it? Is It Documented?

Think you've found a bug? We're keen (though obviously not happy) to hear about it.

If it seems like quite a fundamental bug (such as an issue with updating), then check out the troubleshooting section first - we might already be aware of it or even have a solution for you! Otherwise, we ask that you check the forum to see if anyone else is having the issue.

If you are running Python code and getting an Exception, this may not be a bug.

If you are not confident in what the issue is, then please reach out on the forum!

Have you checked the documentation? For example, the pi-top Python SDK has documentation.

Still think you've got a bug? Let's figure out the best place to write up your bug report.

If you are having a bad time with pi-topOS and its software, then there is a bug.

If the documentation is confusing or missing, then this is a bug.

Where To Submit Bug Report?

Is your bug report in relation to Python development with pi-top hardware? Check out the pi-top Python SDK and pi-top Python Common Library GitHub repositories.

If you are unsure about where to post the issue, then create a forum post about the issue you are having so that someone can help you direct you to the best place to submit the Issue.

How To Submit Bug Report?

A good, well-documented bug report is the most effective way to help improve the quality of pi-top code.

Check out this one-page checklist outlining how to write a great bug report (or you can read its more thorough accompanying blog post!).

Use GitHub's Markdown to style your Issue. For example, if you are providing a Python code snippet, write it like so:

```python
print("code here")
```

Feature Suggestion?

Do We Know About it?

Think you've found a bug? We'd love to hear about it!

First of all, it's important to check the forum and see if someone else has already had the same, or similar, idea. It is easier to prioritise work that has multiple users requesting the same thing!

Where To Submit Feature Suggestion?

Is your feature request in relation to Python development with pi-top hardware? Check out the pi-top Python SDK repository on GitHub.

If you are unsure about where to post the issue, then create a forum post about the issue you are having so that someone can help you direct you to the best place to submit the Issue.

How To Submit Feature Suggestion?

A well-described feature suggestion is a highly effective way to help us understand user needs and tailor pi-topOS to those needs, improving the quality of pi-topOS.

Provide the following information:

• Problem or Possibility
  • Concise summary of the problem that this suggestion would solve, or the possibility it would enable (For example: "I'm always frustrated when [...]")
• Proposed Solution
  • Description of the enhancement that you would like to see
• Alternative Solutions
  • Description of any alternative solutions or features you've considered, if relevant
• Additional Context
  • Any other context or screenshots about the suggestion here.

Use GitHub's Markdown to style your Issue. For example, if you are providing a Python code snippet, write it like so:

```python
print("code here")
```

Code Submission? Pull Request?

We ❤️ code contributions - see you on GitHub!

⚙️ Building And Deploying (CI)

This section outlines how pi-topOS software packages are built and deployed (Continuous Integration).

Building

All software installed by pi-top onto pi-topOS is provided as Debian packages, and uses standard Debian packaging tools.

Because some of our software requires code to be compiled for Raspberry Pi's ARM architecture, and the fact that most CI tools do not offer ARM host machines to build on, pi-top packages are built in a Docker container, leveraging Docker's buildx functionality. This allows all packages to be built in an environment that emulates ARM hardware, where needed. Packages that will work on multiple architectures are built without hardware emulation to speed up builds.

All public GitHub repositories have GitHub Actions for building (and testing, where relevant).

Deploying

At the moment, pi-top packages are deployed to pi-top's apt repository using a private self-hosted Jenkins instance. See the future plans below for how we intend to update the deployment flow.

Future development plans

• Push to apt repositories directly from GitHub repositories
• Build pi-topOS using GitHub Actions
  • Migrate to Docker builds
• Provide repositories for all packages deployed to pi-top's apt repository
  • Import source using gbp --import-orig
  • Watch upstream for updates via debian/watch
  • Only needs to provide debian/ and build CI
• Run tests as part of Debian packaging (via debian/rules)

Links

• deb-build-docker
• test-run-docker
• SDK GitHub Actions workflows

🔗 Links

pi-top Links

• Knowledge Base
• Forum

Raspberry Pi Links

• Raspberry Pi Technical Documentation