Building a Linux distro for OrangePi with Buildroot
Tags: linux, embedded, buildroot, orangepi
Published: 2021-04-03 17:49:07

---
title: Building a Linux distro for OrangePi with Buildroot
published: true
description: How to build a Linux distro image for OrangePi Zero from scratch, using Buildroot.
tags: linux, embedded, buildroot, orangepi
cover_image: https://i.imgur.com/E4kN8uY.png
---

*"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.

#### Introduction

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](https://buildroot.org/), developed by the same maintainers of [uClibc](https://www.uclibc.org/).

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](http://www.orangepi.org/orangepizero/) 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](https://www.cnx-software.com/wp-content/uploads/2019/07/Orange-Pi-Zero-LTS-Allwinner-H2-SBC-Large.jpg)

#### 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](https://imgur.com/YBpzogL.png)

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

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

:penguin: 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.

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

:wrench: 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](https://www.raspberrypi.org/), 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](https://buildroot.org/download.html) or [Github repository](https://github.com/buildroot/buildroot) for cloning.

```shell
wget https://buildroot.org/downloads/buildroot-2021.02.tar.gz
tar zxf buildroot-2021.02.tar.gz
cd buildroot-2021.02/
```

#### 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 

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

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

Now you should have the follow interface:

![Buildroot Menuconfig](https://imgur.com/ViESXPH.png)

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:

    make

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

```shell
ls -lh output/images/sdcard.img 
-rw-r--r-- 1 uilian uilian 71M mar 27 17:54 sdcard.img
```

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

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](https://linux.die.net/man/1/dd) command:

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

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](https://imgur.com/4vLBHJq.jpg)

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](https://imgur.com/zjW7ZR9.png)

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

    lsusb
    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

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](https://linux.die.net/man/8/picocom), but you can use what you prefer.

    sudo picocom -b 115200 -f n /dev/ttyUSB0


#### 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:
```

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](https://linux.die.net/man/1/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](https://linux.die.net/man/8/wpa_supplicant) program. First, we need to update its configuration file. On the Orange Pi terminal, let's execute:

    vi /etc/wpa_supplicant.conf

Replace the default `network` session by:

```
network={
    ssid="MY HOME NETWORK NAME"
    psk="MY HOME PASSWORD"
    id_str="home"
}
```

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

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](https://udhcp.busybox.net/README.udhcpc) command.

```
udhcpc -i wlan0
udhcpc: started, v1.33.0
udhcpc: sending discover
udhcpc: sending select for 192.168.0.18
udhcpc: lease of 192.168.0.18 obtained, lease time 3600
deleting routers
adding dns 1.1.1.1
adding dns 8.8.8.8
```

And we check just running a simple ping test.

```
ping -I wlan0 8.8.8.8
PING 8.8.8.8 (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=113 time=34.668 ms
64 bytes from 8.8.8.8: seq=1 ttl=113 time=26.845 ms
```

#### Conclusion

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.