Skip to content
This repository was archived by the owner on Jan 27, 2025. It is now read-only.

Raspberry Pi

Jump to bottom
Noralf Trønnes edited this page Dec 10, 2023 · 3 revisions

Raspberry Pi

There are two images for the Raspberry Pi both supporting Pi Zero and Pi 4:

gud-raspberry-lite
Fast booting read-only image with no access to the SD card

gud-raspberry
Writeable filesystem, USB over IP and some debugging tools

How to install: Installing operating system images

USB connector

Raspberry Pi Zero

Connect the cable to the micro USB connector labeled USB.

Do not simultaneously power the board through the PWR connector (Using Both PWR and USB in OTG Mode on the Pi Zero)

Raspberry Pi 4

Connect the cable to the USB-C connector.

Options

Linux kernel commandline options (/boot/cmdline.txt):

  • rgb565 Only advertise the RGB565 format (default)
  • rgb888 Only advertise the RGB888 format
  • nocompression Disable lz4 compression
  • connectors= Set mask on which connectors to include (ex. pi4: connectors=0x01)
  • drm_dev= Set DRM device index
  • touch_dev= Set touch device index (=no to disable)
  • gcon Enable USB serial console (not on the lite image)
  • drm.debug= DRM debug level (kernel)
  • quiet Only show errors on the console (kernel)

rgb565 is used by default since GNOME Wayland ignores DRM_CAP_DUMB_PREFERRED_DEPTH and thus ends up using XRGB8888 over the wire.

(see /usr/bin/gud for how the non-kernel options are handled)

Composite video

I have had mixed results using the mainstream KMS driver and in the current stable kernel in doesn't even work on the Pi4. So use the firmware KMS driver instead.

Raspberry Pi Zero

The Pi Zero doesn't have a 4-pole jack like the other Pi's, but it does have TV out pads: Add RCA output to a Pi Zero

/boot/config.txt

# PAL
#sdtv_mode=2

[pi0]
#dtoverlay=vc4-kms-v3d,noaudio,nocomposite
dtoverlay=vc4-fkms-v3d

References

Raspberry Pi 4

/boot/config.txt

# PAL
#sdtv_mode=2

[pi4]
#dtoverlay=vc4-kms-v3d-pi4,noaudio
dtoverlay=vc4-fkms-v3d
enable_tvout=1

Enabling the composite output disables all other outputs.

References

Official Raspberry Pi Touch Display

The touchscreen doesn't work with the regular KMS driver so the firmware KMS version must be used. When a input touch device is detected /usr/bin/hidg-touch is started to create a bridge between the touch device and the HID gadget providing touch support on the host.

/boot/config.txt

[pi4]
#dtoverlay=vc4-kms-v3d-pi4,noaudio
dtoverlay=vc4-fkms-v3d-pi4

If it doesn't work, enable splash to see if anything shows up on the display:

/boot/config.txt

#disable_splash=1

USB over IP

Enable by renaming /boot/interfaces.pi[0|4] to /boot/interfaces. /etc/interfaces is symlinked to this file. DHCP is used by default and the IP address is shown on the display.

On the Raspberry Pi Zero W /boot/wpa_supplicant.conf needs to be filled in.

On the client

# Load kernel module if not builtin
$ sudo modprobe vhci-hcd

# Show available devices
$ usbip list --remote gud-pi.local
Exportable USB devices
======================
 - gud-pi.local
usbip-vudc.0: OpenMoko, Inc. : unknown product (1d50:6150)
           : /sys/devices/platform/usbip-vudc.0
           : (Defined at Interface level) (00/00/00)

# Attach
$ sudo usbip attach -r gud-pi.local -b usbip-vudc.0

# Show connections
$ sudo usbip port
Imported USB devices
====================
Port 00: <Port in Use> at High Speed(480Mbps)
       OpenMoko, Inc. : unknown product (1d50:614d)
       3-1 -> usbip://gud-pi.local:3240/usbip-vudc.0
           -> remote bus/dev 000/000

# Detach
$ sudo usbip detach -p 0

If you get this see possible solution:

libusbip: error: udev_device_get_sysattr_value failed
usbip: error: open vhci_driver

Host: systemd service template

/etc/systemd/system/[email protected]

[Unit]
Description=usbip client %i
After=network.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStartPre=-modprobe vhci-hcd
ExecStart=usbip attach -r %i -b usbip-vudc.0
ExecStop=/bin/sh -c "usbip detach -p $(usbip port | grep -B2 %i | grep '<Port in Use>' | sed -E 's/^Port ([0-9][0-9]).*/\\1/')"

[Install]
WantedBy=multi-user.target

Start

$ sudo systemctl start [email protected]

ArchLinux has a package for this: usbip-systemd

sshd

If a file /boot/ssh is present sshd is started having passwordless root login.

References

Debug

There are 3 debug consoles available (only GPIO UART on lite)

  • UART on the GPIO header as is common on the Pi's. Enabled by default.
  • Serial console on the USB interface (ttyACM0). Enable by adding to <boot>/cmdline.txt: gcon
  • Console on the HDMI display (tty1). Enable by removing quiet from <boot>/cmdline.txt.
  • ssh when networking is enabled. Add an empty file: /boot/ssh

Username is root, no password.

Make filesystem(s) writeable

# rw [boot|root]

Display gadget startup script is located at: /etc/init.d/S70gud which is symlinked to /usr/bin/gud

Debug tools

Not available on the lite image.

# modetest -M vc4 -s 32:1024x768@RG16 # test the device locally
# vcdbg log msg # show DT overlay loading log
# dtc -I fs /proc/device-tree # show Device Tree
# evtest # show touch events
# trace-cmd record -o /tmp/trace.dat -p function_graph -l <func> # trace enter/exit of func
# trace-cmd report -i /tmp/trace.dat # show trace result

USB debug console

screen can be used to attach to the USB console from the host

$ screen /dev/ttyACM0 115200

Kill session: Ctrl-A k

Prevent ModemManager from capturing/messing with /dev/ttyACM0 (on the host)

One off, just stop it (or disable if not needed):

$ sudo systemctl stop ModemManager

USB Power

A Raspberry Pi4 as a USB gadget will at least violate the USB spec unconfigured state when powering up.
Does it really matter? I don't know.

USB 2.0: 7.3.2 Bus Timing/Electrical Characteristics

Supply Current

Parameter Min. Max.
High-power Hub Port (out) 500 mA
Low-power Hub Port (out) 100 mA
High-power Function (in) 500 mA
Low-power Function (in) 100 mA
Unconfigured Function/Hub (in) 100 mA

Raspberry Pi power specs

Typical bare-board active current consumption

Board Current
Raspberry Pi 4 Model B 600mA
Raspberry Pi Zero W/WH 150mA
Raspberry Pi Zero 120mA

References

Issues

  • USB controller driver (dwc2) doesn't handle timeouts. If the gadget hits one of the 10 second timeouts in the DRM subsystem (eg. missing vblank), it will not be able to recover (the host driver gives up after 5 seconds).

  • Running sudo lsusb -v -d 1d50:614d in a loop will eventually (1-15 attempts) run into a timeout when reading status: cannot read device status, Resource temporarily unavailable (11). This will lock up USB on the device probably due to the broken timeout handling. Don't know why it timeouts in the first place though. Restarting the USB gadget service gets it going again (S70gud).

  • dwc2 doesn't report disconnects, but not important if power goes away as well... Ref: usb/dwc2: Set correct state on gadget disconnect

  • fbdev emulation doesn't work with a USB gadget that has 2 connectors supporting 1024x768 which is not in a disconnected state. It will try to clone the outputs something the USB protocol does not support. Ref: drm_client_target_cloned()

  • nano hangs or crashes if long strings are pasted in

  • vc4 HDMI connection status is updated using polling every 10 seconds. This means that to ensure detection of a monitor swap, wait 10 seconds before plugging in. Pi Zero has a hpd-gpio (HotPlugDetect), but there's no interrupt handler.

TODO/maybe

  • Stop the firmware from enabling HDMI output to prevent modeset flicker during boot.
  • Invert gud_flush led trigger on the Pi Zero making it double as a power led.

Please help in keeping this wiki accurate and useful. Anyone with a github account can contribute.

Clone this wiki locally