DEV Community

Cover image for Building a Linux distro for OrangePi with Buildroot
Uilian Ries
Uilian Ries

Posted on

Building a Linux distro for OrangePi with Buildroot

"If you wish to make an apple pie from scratch, you must first invent the universe." (Carl Sagan)

Or, If you want to blink a led, you must first build your system.


Building an embedded system, be it Linux or another kernel, from scratch, can be a difficult and time-consuming task in many cases. For such situations there are tools that automate the process of generating toolchains, dependencies and patches. Among them is Buildroot, developed by the same maintainers of uClibc.

On this post we will build an entire Linux distro for Orange Pi Zero, using Buildroot to save our time. To check if all worked, we will also access board's UART by its serial interface and connect to Wi-Fi.

Orange Pi Zero

The Orange PI Zero is another cheap single-board, similar to Raspberry Zero W.

It's equipped with Allwinner H2 SoC, which provides a Quad-core Cortex-A7 processor.

Orange Pi Zero - Top view

The Linux Embedded System

Before proceeding, let's look at the basic architecture of an embedded system based on Linux:

It can be divided in few layers:

System Layers

💻 The hardware is the physical part, where your device will be used to run the operating system and its applications.

👢 The bootloader is responsible for basic hardware initialization, through a configuration word, in addition to passing parameters, loading and executing the Linux Kernel.

🐧 The Kernel is the core of the system, performs device management, task scheduling and abstracts communication with the user. In this case we will use Linux as the target Kernel.

🐚 RootFS is where the user space is located, all applications (e.g shell, init, ..) and libraries (e.g. libc, zlib, openssl..) are stored there.

🔧 Toolchain is a set of tools to generate the system binaries, like the compiler, kernel header files, libc version and C headers.

Although many embedded platforms already offer Linux images ready to be used, such as Raspberry Pi, these images usually have a large number of packages already installed, making the product stuffed.

Buildroot is a tool designed for Linux, with the objective of generating an embedded Linux system through cross-compilation, all in a simplified and fast way. It is capable of generating all the components presented above, in a very friendly way, using a set of Makefiles that can be managed through a graphical interface.

How to install Buildroot

Buildroot is not an application, but a repository, so that, we can use its download page or Github repository for cloning.

tar zxf buildroot-2021.02.tar.gz
cd buildroot-2021.02/
Enter fullscreen mode Exit fullscreen mode

How to build the Linux image

First step is configuring Buildroot to use the default configuration for Orange Pi.

NOTE: You may not use root privileges for building operations.

make orangepi_zero_defconfig 
Enter fullscreen mode Exit fullscreen mode

Based on Orange Pi Zero default configuration, Buildroot will generate the file .config, used to build our entire system.

In addition to Orange Pi, Buildroot also supports other platforms. Pre-supported configurations are listed in the configs/ directory, but it is possible to list all of them using the command:

make list-defconfigs
Enter fullscreen mode Exit fullscreen mode

As you can see, Buildroot supports a large range of platforms, including Freescale, Banana Pi, Raspberry Pi and others.

Before building our image, let's take a look on Buildroot menu using its ncurses interface.

make menuconfig
Enter fullscreen mode Exit fullscreen mode

Now you should have the follow interface:

Buildroot Menuconfig

This menu helps us to customize our platform, currently it shows our .config definitions. We can change toolchain, Kernel version, libc flavor, applications, libraries for rootfs, init system, bootloader project, and more.

We will keep it as it is. If you change anything by mistake, just exit without saving, or run defconfig command again to regenerate a default configuration file.

Now let's build our system.

NOTE: This part takes around 2 hours and requires 7 GB on your disk and internet connection.

Buildroot will download all projects from sources, cross-build them to Orange Pi architecture and compile to a minimal image. To build the image, run:

Enter fullscreen mode Exit fullscreen mode

After some ☕ and if everything went correctly, you will have the follow file:

ls -lh output/images/sdcard.img 
-rw-r--r-- 1 uilian uilian 71M mar 27 17:54 sdcard.img
Enter fullscreen mode Exit fullscreen mode

Besides other files, here we are only interested on sdcard.img. That small file, contains all we need to run our platform, bootloader, kernel and rootfs.

How to prepare the SD Card

We will need a micro SD card to store our image. Its capacity should be bigger than our image. After connecting the SD card to your computer, we will need to discover where it is mounted:

sudo fdisk -l
Disk /dev/mmcblk0: 942 MiB, 987758592 bytes, 1929216 sectors
Enter fullscreen mode Exit fullscreen mode

It is mounted under /dev/mmcblk0, but may vary according your Linux distro.

To write our Linux system image in the SD card we will run dd command:

sudo dd if=output/images/sdcard.img of=/dev/mmcblk0 bs=4M status=progress conv=fdatasync
Enter fullscreen mode Exit fullscreen mode

Done, we need to insert the micro SD card in our Orange Pi and turn on. The first boot takes more time, led D7 should light up after few seconds.

If your board doesn't start, make sure your power supply provides 5VDC 2A and your card is well inserted.

Serial connection

Now is time to use the UART interface for communication. For that, we will need a USB/UART converter. It's a very cheap board with many variations available.

UART USB Converter

For this step, it's important use the correct connection order.

  • The Rx (receptor) from converter must be connected to Tx (transmitter) on the Orange Pi board.
  • The Tx (receptor) from converter must be connected to Rx (transmitter) on the Orange Pi board.
  • The GND (Ground), must be connected to GND from both sides.

UART pinout

To detect where your converter is connected, after connecting it to your USB, let's take a look on USB devices.

Bus 002 Device 012: ID 0403:6001 Future Technology Devices International, Ltd FT232 Serial (UART) IC

dmesg | grep FTDI
[49255.816532] ftdi_sio 2-1:1.0: FTDI USB Serial Device converter detected
[49255.816940] usb 2-1: FTDI USB Serial Device converter now attached to ttyUSB0
Enter fullscreen mode Exit fullscreen mode

Now we know that the UART converter is linked to /dev/ttyUSB0. It may vary according your Linux distro.

For this tutorial, I'll use picocom, but you can use what you prefer.

sudo picocom -b 115200 -f n /dev/ttyUSB0
Enter fullscreen mode Exit fullscreen mode

Orange Pi Login

After accessing the Orange Pi by its serial connection and turning it on, we will observe its initialization from the beginning.

The boot process is long, here we will list only few parts to give an idea about its output.

U-Boot SPL 2020.10 (Mar 27 2021 - 17:53:25 -0300)
DRAM: 256 MiB
Trying to boot from MMC1

U-Boot 2020.10 (Mar 27 2021 - 17:53:25 -0300) Allwinner Technology

CPU:   Allwinner H3 (SUN8I 1680)
Model: Xunlong Orange Pi Zero
DRAM:  256 MiB
MMC:   mmc@1c0f000: 0, mmc@1c10000: 1
Starting kernel ...

[    0.000000] Booting Linux on physical CPU 0x0
Welcome to Buildroot for the Orange Pi Zero
OrangePi_Zero login:
Enter fullscreen mode Exit fullscreen mode

The bootloader U-Boot recognizes the board, showing its hardware properties. After that, it starts the Linux kernel, passing a configuration word. Once loaded, Linux looks for the program init, which should start all user space services, session and so on.

The default username for login is root. No password is required, but if you want to add one, you may use passwd command.

Wi-Fi Connection

The Orange Pi Zero offer Wireless hardware support and the basic Buildroot configuration already integrates it. Let's configure our board to work with our Wi-Fi.

We will use wpa_supplicant program. First, we need to update its configuration file. On the Orange Pi terminal, let's execute:

vi /etc/wpa_supplicant.conf
Enter fullscreen mode Exit fullscreen mode

Replace the default network session by:

Enter fullscreen mode Exit fullscreen mode

Where you should replace SSID and PSK according your wireless network. Once configured, you have to start the client.

wpa_supplicant -B -Dnl80211 -iwlan0 -c/etc/wpa_supplicant.conf
Enter fullscreen mode Exit fullscreen mode

Now you should be authenticated and connected to your Wi-Fi, but no IP address is obtained yet. To request a new address by DHCP, we will use udhcpc command.

udhcpc -i wlan0
udhcpc: started, v1.33.0
udhcpc: sending discover
udhcpc: sending select for
udhcpc: lease of obtained, lease time 3600
deleting routers
adding dns
adding dns
Enter fullscreen mode Exit fullscreen mode

And we check just running a simple ping test.

ping -I wlan0
PING ( 56 data bytes
64 bytes from seq=0 ttl=113 time=34.668 ms
64 bytes from seq=1 ttl=113 time=26.845 ms
Enter fullscreen mode Exit fullscreen mode


Building a Linux system from scratch can be quite a challenge without having the right tools to assist. As we have seen, Buildroot is an important means when it comes to integrating all layers that form a complete image.

As next challenge, you can customize your image through menuconfig, adding packages and generating a new image.

Happy hacking.

Top comments (1)

blprasad profile image
B Lakshmana Prasad • Edited

Hi Uilian , I tried ,this is working for me, could you help me in how to compile a custom kernel module for latest kernel version (5.10) for Orange Pi zero, normal make file is not working for me. Some thing like an example hello world module with explanation would be helpful, I tried to compile but getting error while loading .ko .Thanks in Advance