Debug UART

WendyOS exposes a serial console on the primary UART for debugging, recovery, and interactive login. The UART is enabled by default on all supported hardware.

Hardware connections

Connect a 3.3 V USB-to-serial adapter to GPIO pins 14 (TXD) and 15 (RXD) on the 40-pin header, plus a GND pin.

The kernel and serial-getty use the serial0 alias, which the RPi firmware maps to the correct device for the model:

Baud rate

115200 baud, 8N1 (8 data bits, no parity, 1 stop bit).

This is set in two places:

1. Kernel command line: console=serial0,115200 (assembled by meta-raspberrypi)
2. systemd-serialgetty: SERIAL_CONSOLES = "115200;ttyS0" (RPi 4) or "115200;ttyAMA0" (RPi 5)

Enabling the UART

The UART is enabled at build time. In raspberrypi5-wendyos.conf / raspberrypi4-64-wendyos.conf:

ENABLE_UART = "1"

This causes rpi-config_%.bbappend to append the following to config.txt:

enable_uart=1

# RPi 4
dtoverlay=uart0

# RPi 5
dtoverlay=uart0-pi5

You can also enable it at runtime by editing /boot/config.txt:

enable_uart=1
dtoverlay=uart0       # RPi 4
# dtoverlay=uart0-pi5 # RPi 5

Then reboot.

systemd serial-getty

A login shell is provided on the serial console by serial-getty@<device>.service. The unit is installed via recipes-core/systemd/systemd-serialgetty.bbappend and configured for auto-login as root:

[Service]
ExecStart=-/sbin/agetty -a root -8 -L %I 115200 $TERM

The -a root flag means the UART console drops straight to a root shell without requiring a password. This is intentional for a development/embedded platform — disable or change it for production deployments by overriding the unit:

# Create a drop-in to require a password
mkdir -p /etc/systemd/system/serial-getty@ttyS0.service.d/
cat > /etc/systemd/system/serial-getty@ttyS0.service.d/require-password.conf << 'EOF'
[Service]
ExecStart=
ExecStart=-/sbin/agetty -8 -L %I 115200 $TERM
EOF
systemctl daemon-reload
systemctl restart serial-getty@ttyS0.service

Connecting from a host computer

# macOS (check /dev/tty.usbserial-* for your adapter)
screen /dev/tty.usbserial-XXXX 115200

# Linux
screen /dev/ttyUSB0 115200
# or
minicom -D /dev/ttyUSB0 -b 115200

# Using picocom
picocom -b 115200 /dev/ttyUSB0

Press Ctrl-A K (screen) or Ctrl-A X (minicom/picocom) to exit.

ACM serial console over USB

The USB gadget also exposes an ACM serial function alongside the network. This creates:

• /dev/ttyGS0 on the WendyOS device
• ttyACMx on the connected host (usually ttyACM0)

This is separate from the hardware UART and does not require any GPIO wiring. It is available whenever the USB gadget is active:

# On the host
screen /dev/ttyACM0 115200

The ACM device provides a shell session (via getty) on the device side at /dev/ttyGS0.

Kernel boot messages

Early kernel boot messages appear on the serial console before systemd starts. To capture them, connect the serial adapter before powering on the device.

To disable the quiet kernel splash and see all boot messages, remove quiet and splash from cmdline.txt if present.