Skip to content

USB Serial Console Guide

Jump to bottom Edit New page
Ahmad Amarullah edited this page Nov 5, 2026 · 5 revisions

🖥️ piBrick USB Serial Console Guide

The piBrick PocketCM5 has a built-in USB-to-serial interface that allows you to access the Linux terminal directly from a computer or mobile device.

This connection is useful for:

  • Monitoring boot messages from the earliest stage of startup.
  • Troubleshooting boot failures, including cases where the display remains blank.
  • Accessing the Linux terminal without an HDMI display or external keyboard.
  • Installing piBrick Linux drivers without HDMI or SSH access.
  • Performing initial setup before Wi-Fi or networking is configured.

📑 Table of Contents

🔌 1. Connect to the Serial Interface

USB Connection

  1. Make sure piBrick is powered off if you want to capture boot messages from the beginning.
  2. Connect a USB data cable from the bottom USB-C port on piBrick to your computer or mobile device.
  3. Set the side switch to the UP position.
  4. Wait for the USB-to-serial interface to be detected by the host.

You do not need to power on piBrick manually for the serial interface to be detected. The USB-to-serial interface can be detected while piBrick is off.

To capture early boot messages, connect to the serial terminal first, then power on piBrick.

Setting Value
USB port Bottom USB-C
Side switch UP
Baud rate 115200
Serial interface detected while piBrick is off Yes
Top USB-C port Used for CM5 eMMC flashing

Important: Use the bottom USB-C port for the serial console. The top USB-C port is used for the CM5 eMMC flashing process.

⚙️ 2. Configure the Linux Serial Console

If the serial interface is detected but Linux boot messages or a login prompt do not appear, configure the Raspberry Pi OS serial console.

2.1. Edit config.txt

Before booting piBrick, open the microSD card's boot partition on your computer and locate config.txt.

Add the following lines:

enable_uart=1
uart_2ndstage=1
dtparam=uart0_console=on

On recent Raspberry Pi OS installations, the file is typically located at /boot/firmware/config.txt after booting. When editing the card from another computer, open the boot partition and locate the file there.

Save the changes and safely eject the microSD card before inserting it into piBrick.

2.2. Configure cmdline.txt if Needed

If serial output or the login prompt is still unavailable, try adding the following parameter to the existing cmdline.txt:

console=ttyAMA0,115200

Important:

  • Keep cmdline.txt on a single line.
  • Add the parameter separated by a space; do not replace the existing contents.
  • Avoid duplicate or conflicting console= parameters.
  • The correct console device depends on the OS image and UART configuration.

These settings configure the Linux serial console. They are not required merely for the USB-to-serial interface to be detected by the host computer.

🌐 3. Connect from a Web Browser

You can access the piBrick serial console directly from a compatible web browser using piBrick Serial Shell. No separate terminal application is required.

Open the web application: https://serial.pibrick.net/

Requirements

  • A modern Chromium-based browser, such as Google Chrome or Microsoft Edge.
  • An HTTPS connection to the Serial Shell website.
  • A USB data cable connected to piBrick's bottom USB-C port.
  • The side switch in the UP position.
  • Browser permission to access the selected serial device.

Connection Steps

  1. Connect piBrick's bottom USB-C port to your computer using a USB data cable.
  2. Set the side switch to the UP position.
  3. Open piBrick Serial Shell.
  4. Choose Serial to use the browser's Web Serial API, or USB for a supported CH340 interface.
  5. Select the detected device and grant permission when the browser prompts you.
  6. Configure the baud rate to 115200 and use the serial settings required by the target device.
  7. Click or tap the terminal and press Enter if the Linux login prompt does not appear.

To capture early boot messages, connect to the serial device before powering on piBrick.

Browser Notes

  • Web Serial and WebUSB availability depends on the browser, operating system, and device.
  • The WebUSB option supports compatible CH340 adapters with VID 0x1A86 and PID 0x7523.
  • If the browser does not detect the device, check the cable, bottom USB-C port, side switch, and browser permissions.
  • See the piBrick Serial Shell for virtual keyboard controls, macros, mobile usage, and additional troubleshooting.

🐧 4. Connect from Linux

Linux typically detects piBrick as a serial device such as /dev/ttyACM0 or /dev/ttyUSB0.

4.1. Find the Serial Device

Run:

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

To monitor device detection while connecting piBrick, run:

sudo dmesg --follow

Look for a newly detected USB serial device.

4.2. Install screen

On Debian or Ubuntu-based systems, install screen if it is not already available:

sudo apt update
sudo apt install screen

4.3. Open the Serial Terminal

Connect at 115200 baud:

sudo screen /dev/ttyACM0 115200

Replace /dev/ttyACM0 with the actual device path detected on your system.

If the terminal is blank, press Enter after Linux starts. If you want to capture early boot messages, connect before powering on piBrick.

To exit screen, press Ctrl+A, then K, and confirm with Y.

Permission Issues

If you cannot access the serial device without sudo, check your Linux distribution's serial-device permissions and user groups.

🍎 5. Connect from macOS

macOS typically exposes USB serial devices under /dev/cu.*.

5.1. Find the Serial Device

Open Terminal and run:

ls /dev/cu.usbmodem* /dev/cu.usbserial* 2>/dev/null

Identify the device corresponding to piBrick.

5.2. Connect Using screen

If screen is available, run:

screen /dev/cu.usbmodemXXXX 115200

Replace /dev/cu.usbmodemXXXX with the actual device path. The device name may differ depending on the USB serial interface.

To exit screen, press Ctrl+A, then K, and confirm with Y.

🪟 6. Connect from Windows

On Windows, use a serial terminal application such as Tera Term or PuTTY.

Recommended Applications

  • Tera Term — A terminal emulator with serial-port support.
  • PuTTY — A lightweight terminal application that supports serial connections.

Connection Steps

  1. Connect piBrick using the bottom USB-C port.
  2. Set the side switch to the UP position.
  3. Open Device Manager.
  4. Expand Ports (COM & LPT) and locate the USB serial device.
  5. Note the assigned COM port, such as COM4.
  6. Open Tera Term or PuTTY and select a serial connection.
  7. Select the detected COM port and set the baud rate to 115200.
  8. Open the connection.

To capture boot messages from the beginning, establish the serial connection before powering on piBrick.

If no COM port appears, check the cable, USB port, side switch position, and device detection.

🤖 7. Connect from Android

You can access the serial console from an Android device using a USB serial terminal application.

Recommended Application

Serial USB Terminal — Google Play

This application supports USB serial connections and can be used to monitor boot messages and interact with the Linux terminal.

Connection Steps

  1. Connect piBrick's bottom USB-C port to your Android device using a compatible USB data cable or OTG adapter.
  2. Set the side switch to the UP position.
  3. Open Serial USB Terminal.
  4. Grant USB access permission when prompted.
  5. Select the detected USB serial device.
  6. Set the baud rate to 115200 and connect.
  7. Power on piBrick after connecting if you want to monitor early boot messages.

Your Android device must support USB host/OTG functionality, and the application must support the detected USB serial interface.

🧰 8. Install piBrick Drivers Without HDMI or SSH

The USB serial console is particularly useful when setting up a fresh piBrick installation. You can install the piBrick Linux drivers without connecting an HDMI display or accessing the device over SSH.

This method requires:

  • A computer that can access the microSD card's boot partition.
  • A compatible operating system already installed on the microSD card.
  • The piBrick driver source repository.
  • A serial terminal connected to piBrick.

8.1. Copy the Driver Source to bootfs

Download or clone the driver repository on your computer:

piBrick Linux Drivers

git clone https://github.com/amarullz/pibrick-drivers.git

Locate the boot partition of the microSD card. Depending on the OS image and host operating system, it may appear as bootfs, boot, or a similarly named volume.

Copy the complete pibrick-drivers directory to the root of that boot partition.

The resulting directory structure should look similar to:

bootfs/
└── pibrick-drivers/
    ├── install.sh
    └── ...

The repository contents may change between releases, so copy the complete source tree rather than only install.sh.

Important: Do not overwrite existing Raspberry Pi boot files. Ensure the boot partition has enough free space for the driver source.

8.2. Boot piBrick and Open the Serial Console

  1. Safely eject the microSD card from your computer.
  2. Insert the card into piBrick.
  3. Connect the bottom USB-C port to your computer.
  4. Set the side switch to the UP position.
  5. Open your serial terminal at 115200 baud.
  6. Power on piBrick and wait for Linux to boot.

Log in when the serial console displays the login prompt.

8.3. Locate the Boot Partition

Once logged in, determine where the boot partition is mounted.

Recent Raspberry Pi OS installations commonly use /boot/firmware, while older installations may use /boot.

Check both locations:

ls /boot/firmware/pibrick-drivers
ls /boot/pibrick-drivers

Use the path that contains the copied pibrick-drivers directory.

8.4. Run the Driver Installer

For a recent Raspberry Pi OS installation where the directory is under /boot/firmware, run:

cd /boot/firmware/pibrick-drivers
sudo bash install.sh

If the directory is under /boot, run:

cd /boot/pibrick-drivers
sudo bash install.sh

Follow the installer's output and wait for the process to finish. If the installer requests a reboot, reboot piBrick and reconnect to the serial console.

8.5. Verify the Installation

After installation:

  1. Review the installer's output for errors.
  2. Reboot if requested.
  3. Reconnect to the serial console.
  4. Check that Linux starts normally and that the supported piBrick hardware features are working.

For additional setup instructions, see the Quick Start Guide.

🛠️ 9. Troubleshooting

USB Serial Device Not Detected

  • Verify that you are using the bottom USB-C port.
  • Check that the side switch is in the UP position.
  • Use a USB data cable rather than a charge-only cable.
  • Try another USB port or compatible cable.
  • On Android, verify USB OTG support and grant the application permission to access the device.

Terminal Is Blank

  • Press Enter after Linux has started.
  • Verify the baud rate is set to 115200.
  • Connect to the serial terminal before powering on piBrick to capture early boot output.
  • Check the config.txt and cmdline.txt settings if boot messages or a login prompt are unavailable.

Unreadable Output

Verify that the baud rate is 115200 and that the terminal uses standard serial settings: 8 data bits, no parity, and 1 stop bit.

Cannot Run the Driver Installer

  • Confirm that the complete pibrick-drivers directory was copied.
  • Check the boot-partition mount path.
  • Run the installer using sudo.
  • Verify that the boot partition has enough free space.
  • Read any error messages printed by the installer before retrying.

🔗 10. Useful Links

Add a custom footer
Add a custom sidebar

Clone this wiki locally