Merge pull request #1270 from kernelkit/rpi4-doc

Update RPi64 docs a bit [skip ci]
2026-07-30 04:33:00 +02:00 · 2025-11-21 10:54:12 +01:00
parent 9a8d13191b 834f325097
commit ca86421715
2 changed files with 308 additions and 45 deletions
@@ -1,59 +1,322 @@
-# Raspberry Pi 3B/4B
+# Raspberry Pi 3B/4B/CM4

-## Support level
+## Overview

-Full support for base board but not any extension board on the GPIOs.
-Other RPi boards of the same generation may work as well, but may need
-some additional testing/work.  A few CM4 variants have been tested and
-seem to work as expected, but YMMV as always.
+The Raspberry Pi is one of the most popular single-board computers with full
+Infix support for networking features, making it an excellent platform for
+learning, prototyping, and lightweight network applications.

-### Touch screen
+### Hardware Features

-The [Raspberry Pi touch display v1][0] is supported on the 4B, including
-touch functionality.  There are multiple touchscreens on the market for
-Raspberry Pi, but currently only the official first version with 800x480
-resolution is supported.  Infix supplies all drivers required to utilize
-the hardware, but you need to add the actual graphical application in a
-container.
+**Raspberry Pi 3B:**

-There are some important considerations you need to know about when
-using Infix for graphical applications.  The container needs access to
-`/dev/dri/` to be able to access the graphics card, it also need access
-to `/run/udev` to be able to find the input devices.
+- Broadcom BCM2837B0 ARM Cortex-A53 quad-core processor @ 1.4 GHz
+- 1 GB LPDDR2 RAM
+- microSD card slot for storage
+- 4x USB 2.0 ports
+- Fast Ethernet (100 Mbps)
+- Dual-band WiFi (2.4 GHz + 5 GHz) and Bluetooth 4.2
+- HDMI port
+- GPIO header (40-pin)

-Example of running Doom in Infix:
+**Raspberry Pi 4B:**
+
+- Broadcom BCM2711 ARM Cortex-A72 quad-core processor @ 1.5 GHz
+- 1 GB, 2 GB, 4 GB, or 8 GB LPDDR4 RAM (depending on model)
+- microSD card slot for storage
+- 2x USB 3.0 + 2x USB 2.0 ports
+- Gigabit Ethernet
+- Dual-band WiFi (2.4 GHz + 5 GHz) and Bluetooth 5.0
+- 2x micro-HDMI ports (up to 4K output)
+- GPIO header (40-pin)
+- PoE support (with add-on HAT)
+
+**Compute Module 4 (CM4):**
+
+- Same processor as Pi 4B
+- Compact form factor for embedded applications
+- Optional eMMC storage (0 GB, 8 GB, 16 GB, or 32 GB)
+- Requires carrier board for I/O connectivity
+- Various configurations tested and working
+
+### Default Network Configuration
+
+Infix comes preconfigured with:
+
+- **Ethernet port**: DHCP client enabled for internet connectivity
+- **WiFi interfaces** (wlan0, wlan1): Available for configuration as AP or client
+- **GPIO**: Available but extension boards not currently supported
+
+### Support Level
+
+Full support for base board networking and core functionality. GPIO extension
+boards (HATs) are not currently supported. Other Raspberry Pi boards of the
+same generation may work but may require additional testing.
+
+## Getting Started
+
+### Quick Start with SD Card
+
+The easiest way to get started is using a microSD card:
+
+1. **Download the SD card image:** [infix-rpi64-sdcard.img][2]
+2. **Flash the image to a microSD card:** see [this guide][0]
+3. **Boot the board:**
+   - Insert the microSD card into your Raspberry Pi
+   - Connect an Ethernet cable to your network
+   - Connect power (see [Power Supply Requirements](#power-supply-requirements))
+   - The board will boot automatically
+4. **Connect and login:**
+   - SSH to the DHCP-assigned IP address
+   - Default login: `admin` / `admin`
+
+> [!NOTE]
+> Raspberry Pi 3B and 4B boot with a factory configuration (`factory-config.cfg`)
+> that enables DHCP client on the Ethernet port. This means you can access
+> the device over the network without needing a serial console. Simply find
+> the assigned IP address and SSH in!
+>
+> **Compute Module 4 (CM4)** and some other variants do not have this factory
+> configuration, so you'll need to use a serial console for initial setup or
+> configure the carrier board accordingly.
+
+### First Boot Notes
+
+On first boot, Infix will:
+
+- Obtain an IP address via DHCP on the Ethernet port
+- Generate unique SSH host keys
+- Initialize the configuration system
+
+You can find the assigned IP address by:
+
+- Checking your DHCP server/router's client list
+- Using network scanning tools like `nmap` or `arp-scan`
+- Connecting via serial console and running `ip addr` (if needed)
+
+## Hardware-Specific Features
+
+### WiFi Configuration
+
+Both Pi 3B and Pi 4B include dual-band WiFi that can be configured as a
+client (station mode). See the [Infix WiFi documentation][9] for detailed
+configuration examples.
+
+To configure WiFi as a client, first store your WiFi password in the keystore:

 ```
-admin@example:/> configure
-admin@example:/config/> edit container doom
-admin@example:/config/container/doom/> set image docker://mattiaswal/alpine-doom:latest
-admin@example:/config/container/doom/> set privileged
-admin@example:/config/container/doom/> edit mount udev
-admin@example:/config/container/doom/mount/udev/> set type bind
-admin@example:/config/container/doom/mount/udev/> set target /run/udev/
-admin@example:/config/container/doom/mount/udev/> set source /run/udev/
-admin@example:/config/container/doom/mount/udev/> end
-admin@example:/config/container/doom/mount/xorg.conf/> set content U2VjdGlvbiAiT3V0cHV0Q2xhc3MiCiAgSWRlbnRpZmllciAidmM0IgogIE1hdGNoRHJpdmVyICJ2YzQiCiAgRHJpdmVyICJtb2Rlc2V0dGluZyIKICBPcHRpb24gIlByaW1hcnlHUFUiICJ0cnVlIgpFbmRTZWN0aW9uCg==
-admin@example:/config/container/doom/mount/xorg.conf/> set target /etc/X11/xorg.conf
-admin@example:/config/container/doom/mount/xorg.conf/> end
-admin@example:/config/container/doom/> edit volume var
-admin@example:/config/container/doom/volume/var/> set target /var
-admin@example:/config/container/doom/volume/var/> leave
-admin@example:/>
+admin@infix:/> configure
+admin@infix:/config/> edit keystore symmetric-key mywifi
+admin@infix:/config/keystore/…/mywifi/> set key-format wifi-preshared-key-format
+admin@infix:/config/keystore/…/mywifi/> set cleartext-key YourWiFiPassword
+admin@infix:/config/keystore/…/mywifi/> leave
+```
+
+Then configure the WiFi interface using the keystore reference:
+
+```
+admin@infix:/> configure
+admin@infix:/config/> edit interface wifi0
+admin@infix:/config/interface/wifi0/> set ipv4 dhcp-client
+admin@infix:/config/interface/wifi0/> set wifi ssid YourNetworkName
+admin@infix:/config/interface/wifi0/> set wifi secret mywifi
+admin@infix:/config/interface/wifi0/> set wifi country-code US
+admin@infix:/config/interface/wifi0/> leave
 ```

 > [!NOTE]
-> The `xorg.conf` [content mount][2] is a nifty detail of Infix that
-> allows you to keep all the relevant configuration in a single file.
-> The deta is "simply" `base64` encoded, so you do not really need the
-> features of the Infix CLI, everything can be set up remotely [using
-> `curl`][3] if you like.
+> The WiFi password (8-63 characters) is stored securely in the keystore as
+> `mywifi` (or any name you choose), which is then referenced in the WiFi
+> configuration. The country-code must match your location for regulatory
+> compliance (e.g., US, SE, DE, JP).

-### Pre-built images
+### Touch Screen Support

-Pre-built SD card images are available here: [infix-rpi64-sdcard.img][sdcard]
+The [Raspberry Pi Touch Display v1][10] (800x480 resolution) is supported on
+the Pi 4B, including touch functionality. To use graphical applications with
+the touch screen, you need to run them in a container with proper device
+access.

-[0]: https://www.raspberrypi.com/products/raspberry-pi-touch-display/
-[1]: https://github.com/kernelkit/infix/releases/download/latest-boot/infix-rpi64-sdcard.img
-[2]: https://kernelkit.org/infix/latest/container/#content-mounts
-[3]: https://kernelkit.org/infix/latest/scripting-restconf/
+#### Requirements for Graphical Applications
+
+Containers need:
+- Access to `/dev/dri/` for graphics card access
+- Access to `/run/udev` for input device detection
+- Privileged mode or specific capabilities
+
+#### Example: Running Doom with Touch Screen
+
+```
+admin@infix:/> configure
+admin@infix:/config/> edit container doom
+admin@infix:/config/container/doom/> set image docker://mattiaswal/alpine-doom:latest
+admin@infix:/config/container/doom/> set privileged
+admin@infix:/config/container/doom/> edit mount udev
+admin@infix:/config/container/…/udev/> set type bind
+admin@infix:/config/container/…/udev/> set target /run/udev/
+admin@infix:/config/container/…/udev/> set source /run/udev/
+admin@infix:/config/container/…/udev/> end
+admin@infix:/config/container/doom/> edit mount xorg.conf
+admin@infix:/config/container/…/xorg.conf/> set content U2VjdGlvbiAiT3V0cHV0Q2xhc3MiCiAgSWRlbnRpZmllciAidmM0IgogIE1hdGNoRHJpdmVyICJ2YzQiCiAgRHJpdmVyICJtb2Rlc2V0dGluZyIKICBPcHRpb24gIlByaW1hcnlHUFUiICJ0cnVlIgpFbmRTZWN0aW9uCg==
+admin@infix:/config/container/…/xorg.conf/> set target /etc/X11/xorg.conf
+admin@infix:/config/container/…/xorg.conf/> end
+admin@infix:/config/container/doom/> edit volume var
+admin@infix:/config/container/…/var/> set target /var
+admin@infix:/config/container/…/var/> leave
+```
+
+> [!NOTE]
+> The `xorg.conf` [content mount][3] is a useful Infix feature that allows you
+> to keep all configuration in a single file. The data is base64 encoded, and
+> everything can be set up remotely [using `curl`][4] if preferred.
+
+### Power Supply Requirements
+
+Proper power supply is critical for stable operation:
+
+- **Raspberry Pi 4B:** 5V/3A USB-C power supply (official recommended)
+- **Raspberry Pi 3B:** 5V/2.5A micro-USB power supply
+- **Compute Module 4:** Power requirements depend on carrier board
+
+Inadequate power can cause:
+- Random reboots or crashes
+- USB device failures
+- Network disconnections
+- Corrupted storage
+
+<img align="right" src="gpio-pinout.png" alt="GPIO Pinout" width=300 padding=10>
+
+### Serial Console Access (Optional)
+
+A serial console is useful for debugging but not required for Pi 3B/4B, since
+the factory configuration enables network access via DHCP. For CM4 and other
+variants without factory configuration, serial console access is required for
+initial setup.
+
+To connect via serial:
+
+1. Connect a USB-to-TTL serial adapter (3.3V) to GPIO pins:
+   - GND (black wire) → Pin 6 (Ground)
+   - TX → Pin 8 (GPIO 14, RXD)
+   - RX → Pin 10 (GPIO 15, TXD)
+   - **VCC (red wire) → Leave disconnected** (Pi has its own power supply)
+2. Use 115200 baud, 8 data bits, no parity, 1 stop bit (115200 8N1)
+3. Connect using `screen`, `minicom`, or similar terminal emulator
+
+The image shows the standard 40-pin GPIO header pinout. For serial console:
+- **Pin 6** (black) = Ground
+- **Pin 8** (orange) = TxD (UART) - connect to RX on your adapter
+- **Pin 10** (orange) = RxD (UART) - connect to TX on your adapter
+
+> [!WARNING]
+> Use only 3.3V serial adapters. 5V adapters will damage your Raspberry Pi!
+
+## Troubleshooting
+
+### Board won't boot
+
+- Verify the power supply meets requirements (see [Power Supply Requirements](#power-supply-requirements))
+- Check that the SD card is properly seated
+- Try re-flashing the SD card image
+- Look for the green LED activity indicator (should flash during boot)
+- Connect via serial console to see boot messages if needed
+
+### Can't find IP address
+
+- Ensure Ethernet cable is properly connected (look for link LED activity)
+- Verify your DHCP server is running and has available addresses
+- Check your router/DHCP server's client list for new devices
+- Use `nmap` or `arp-scan` to scan your network
+- Connect via serial console and run `ip addr` to see the assigned address
+
+### WiFi not working
+
+- Verify WiFi regulatory domain is set correctly
+- Check that SSID and password are correct
+- Ensure WiFi channel is supported in your region
+- Try connecting to a 2.4 GHz network first (better compatibility)
+
+### SD card corruption
+
+If the system becomes unresponsive or won't boot:
+
+- Always use proper shutdown procedures (don't just pull power)
+- Use a quality SD card (Class 10, A1, or better recommended)
+- Consider using a UPS or battery backup for critical deployments
+- Verify power supply meets requirements (see [Power Supply Requirements](#power-supply-requirements))
+
+### Container/Docker issues
+
+- Verify adequate RAM is available (check with `free -h`)
+- Ensure sufficient SD card space (check with `df -h`)
+- For Pi 3B, consider using lighter containers due to limited RAM
+
+## Additional Resources
+
+- [Infix Documentation][1]
+- [Flashing SD Card Guide][0]
+- [Infix Container Documentation][3]
+- [Scripting with RESTCONF][4]
+- [Release Downloads][8]
+- [Official Raspberry Pi Documentation][11]
+
+## Building Custom Images
+
+See the main Infix documentation for building from source. To build a custom
+Raspberry Pi image:
+
+```bash
+# Build the bootloader (only needed once or when bootloader changes)
+make O=x-boot rpi64_boot_defconfig
+make O=x-boot
+
+# Build main system
+make aarch64_defconfig
+make
+
+# Create SD card image
+./utils/mkimage.sh -od raspberrypi-rpi64
+```
+
+The resulting image will be in `output/images/infix-rpi64-sdcard.img`.
+
+### Customizing the Build
+
+You can customize the build by:
+- Modifying `board/aarch64/raspberrypi-rpi64/config.txt` for boot configuration
+- Adding packages to the Buildroot configuration
+- Customizing the device tree in `board/aarch64/raspberrypi-rpi64/dts/`
+
+## Performance Notes
+
+### Raspberry Pi 4B vs 3B
+
+The Pi 4B offers significant improvements over the 3B:
+- 3x faster processor
+- Up to 8x more RAM
+- Gigabit Ethernet (vs 100 Mbps)
+- USB 3.0 for faster storage and peripherals
+- Better thermal performance
+
+For network-intensive applications, the Pi 4B is strongly recommended.
+
+### Raspberry Pi as a Router
+
+While capable of basic routing tasks, be aware of limitations:
+- Single Ethernet port (consider USB Ethernet adapters for multi-port setups)
+- CPU-based packet processing (no hardware offload)
+- Best suited for home/lab use rather than high-throughput production
+
+For applications requiring multiple ports or high performance, consider
+dedicated networking hardware like the [Banana Pi R3][12].
+
+[0]: https://kernelkit.org/posts/flashing-sdcard/
+[1]: https://kernelkit.org/infix/latest/
+[2]: https://github.com/kernelkit/infix/releases/download/latest-boot/infix-rpi64-sdcard.img
+[3]: https://kernelkit.org/infix/latest/container/#content-mounts
+[4]: https://kernelkit.org/infix/latest/scripting-restconf/
+[8]: https://github.com/kernelkit/infix/releases/tag/latest-boot
+[9]: https://kernelkit.org/infix/latest/networking/#wifi
+[10]: https://www.raspberrypi.com/products/raspberry-pi-touch-display/
+[11]: https://www.raspberrypi.com/documentation/
+[12]: https://kernelkit.org/infix/latest/hardware/#banana-pi-bpi-r3