linux-blackboard
Modern Linux for the RealDigital Blackboard based on buildroot
Star
Fork
Watch
12 1 0
Files
br2-external
README.md
README.md

Modern Linux for the RealDigital Blackboard #

The official Linux images for the RealDigital Blackboard are pretty ancient (Ubuntu 18.04 or 16.04). This repository attempts to build a modern Linux system for the Blackboard, without requiring any proprietary Xilinx tools.

Building and Running #

  • Clone this repo somewhere
  • Obtain a copy of Buildroot 2026.08.1 and extract the tarball
  • In the extracted buildroot directory, run:
    make BR2_EXTERNAL=path/to/your/cloned/linux-blackboard/br2-external zynq_blackboard_defconfig
./utils/add-custom-hashes
make
    (this will take a while, you're basically compiling an entire linux distro!)
  • After it's done building, flash output/images/sdcard.img to a microSD card and insert it into the Blackboard
  • Make sure the boot jumper is set to SD, and power the Blackboard on
  • Connect a serial terminal to the Zynq PS serial interface (note: the Blackboard has two serial interfaces (PS and PL), the one you want is probably the second one, e.g. /dev/ttyUSB1 or /dev/serial/by-id/usb-Xilinx_JTAG+Serial_<serial number>-if01-port0)

Status #

Working:

  • Serial
  • USB
  • Flashing ESP32
  • PS-connected GPIOs (use gpioset and gpioget from the command line)
  • Programming PL using fpgautil

Not working:

  • ESP32 Wi-Fi (see below)
  • Anything that requires PL IP (video, PL-connected GPIOs, etc)

Wi-Fi #

The Blackboard has an ESP32 on board which can in theory be used as a Wi-Fi adapter for the Linux system. So far, I have been unable to get this to work reliably, but the ESP32 firmware and kernel driver are included in the system.

To flash the ESP32 firmware, run (on the Blackboard) /opt/flash_esp32.sh. Then reboot (or reload the esp32_spi kernel module). You will likely experience a bunch of errors on the console, but if your board somehow works you should be able to connect to Wi-Fi using nmcli/nmtui.

Included software #

  • systemd (instead of the default busybox-based init)
  • esp-hosted SPI kernel driver and ESP32 firmware (run /opt/flash_esp32.sh to flash, note that Wi-Fi is unlikely to actually work)
  • Python 3
  • esptool
  • wpa_supplicant
  • NetworkManager
  • Some basic networking utilities (ip, ping, traceroute, curl)
  • libgpiod2 and associated commands (gpioset, gpioget, gpioinfo, etc)
  • picocom (useful for debugging the ESP32 via its serial port on /dev/ttyPS1)
  • Xilinx fpgautil (load bitstreams onto the FPGA with fpgautil -b file.bin - note the bitstream format is different from the standard .bit files!)
  • neofetch (of course)

Customising #

You can customise the buildroot configuration yourself (such as adding packages) by running make menuconfig before the final make. This will give a terminal-based menu where you can change the configuration. After saving and exiting the menu, running make will build the image with the new configuration.

Credits #

  • The Buildroot config is derived from configs for existing Zynq boards
  • The device tree is derived from the original RealDigital one, as well as ones for other Zynq boards in the linux and u-boot trees
  • The PS7 init code is taken from the original RealDigital repo (I'd love to be able to generate this using open source tools, but current open source tools don't support ddr configuration which is necessary for linux)
  • The included packages are derived from existing packages in upstream buildroot (this project needs a newer version of esp-hosted with device tree support as the ESP32 is not connected to SPI0, and the upstream python-esptool package has broken dependencies)
  • The firmware binaries in br2-external/board/realdigital/blackboard/overlay/opt/*.bin are compiled from Espressif's esp-hosted-linux and are licensed under the Apache License 2.0. (Integrating building the firmware with Buildroot is a future exercise.)