diff --git a/board/aarch64/raspberrypi-rpi64/README.md b/board/aarch64/raspberrypi-rpi64/README.md index 80a844bf..919c539c 100644 --- a/board/aarch64/raspberrypi-rpi64/README.md +++ b/board/aarch64/raspberrypi-rpi64/README.md @@ -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 + +GPIO Pinout + +### 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 diff --git a/board/aarch64/raspberrypi-rpi64/gpio-pinout.png b/board/aarch64/raspberrypi-rpi64/gpio-pinout.png new file mode 100644 index 00000000..4ea58730 Binary files /dev/null and b/board/aarch64/raspberrypi-rpi64/gpio-pinout.png differ