lvgl/docs/details/integration/os/buildroot/image_generation.rst

RPi4 custom image 
#################

This chapter offers a detailed guide for creating a custom image for the 
Raspberry Pi 4 (RPi4). Key Buildroot components and concepts will be 
introduced. The process outlined here can be adapted for use with 
other boards. For advanced features not covered in this guide, please consult 
the `Buildroot manual <https://buildroot.org/downloads/manual/manual.html>`_

This guide was done on ``Ubuntu 22.04``

Prepare the workspace
*********************

The workspace is structured to utilize Buildroot without any modifications. 
Execute the following commands:

.. code-block:: 

    mkdir rpi4_buildroot_lvgl && cd rpi4_buildroot_lvgl
    mkdir resources && cd resources
    mkdir board 
    mkdir configs 
    touch Config.in && touch external.desc && touch external.mk 
    echo "name: rpi4_lvgl" >> external.desc
    echo "desc: rpi4 lvgl custom build" >> external.desc
    cd ..

Each folder utility will be explained throughout the guide.

Get Buildroot 
*************

First, according to the `Builroot Manual <https://buildroot.org/downloads/
manual/manual.html>`_, Buildroot requires certain packages to be installed 
before starting the build. Lets install them using Ubuntu's package manager.

.. code-block:: bash

    sudo apt install sed make binutils gcc g++ bash patch gzip bzip2 perl tar \
            cpio python3 unzip rsync wget libncurses-dev

Now that we have satisfied all the prerequisites lets download a stable release 
of Buildroot.

.. code-block:: bash

    git clone --branch 2024.08 --depth 1 https://github.com/buildroot/buildroot.git

Create RPi4 image 
*****************

Let's see if there is already a configuration for RPi4 in Buildroot: 

.. code-block:: bash

    cd buildroot
    make list-defconfigs | grep rasp

There is a build available for RPi4 62 bits: ``raspberrypi4_64_defconfig``.

You can also find all the configurations in the Buildroot repository
``buildroot > configs``

Start with this configuration as a base, but this configuration needs to be 
changed to meet lvgl requirements. So let's copy this base and keep it out of 
Buildroot. 

.. code-block:: bash

    # move to the project root
    cp buildroot/configs/raspberrypi4_64_defconfig resources/configs/raspberrypi4_lvgl_defconfig

Create a new file ``build.sh`` at the root of the project with this content: 

.. code-block:: bash

    #!/bin/bash
    SCRIPTPATH="$( cd "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"

    cd $SCRIPTPATH
    mkdir -p output
    cd buildroot
    make defconfig O=../output BR2_DEFCONFIG=../resources/configs/raspberrypi4_lvgl_defconfig

Make this file executable.

.. code-block:: bash 

    chmod +x build.sh
    ./build.sh

Running this script creates an output folder that contains everything the 
process will generate: 

    - Fetched resources 
    - Toolchain
    - Images 

This helps maintain a clean Buildroot directory. When the script is executed, 
an (almost) empty folder named ``output`` is created, as the build process has 
not yet begun. 

Let's modify the configuration with ``menuconfig``.

.. code-block:: bash 

    cd output
    make menuconfig

Change these configurations: 

    - System host name to ``lvgl-buildroot`` under ``system_configuration > System hostname``.
    - Root password to ``lvgl-buildroot``  under ``system_configuration > Root password``.
    - Enable SSH in ``target-packages > Networking applications > openssh``

.. _build-environment: 

Build the image

.. code-block:: bash

    make

What happened? 
**************

Let's explore the contents of the output folder and what it contains.

build 
=====

This folder contains the intermediate files and build artifacts for the various 
packages that are being compiled. Each package has its own subdirectory within 
the ``build`` folder, where the build process takes place. It includes files 
such as configuration files, source code, and object files that are generated 
as part of the build process.

host
====

The ``host`` folder contains files and binaries that are built for the host 
system rather than the target system. This includes tools and utilities that 
are needed to build packages or to run the build system itself. It may contain 
compilers, build tools, and libraries that are required to support the build 
process for the target.

.. _images:

images 
======

This directory holds the final output images generated for the target system, 
such as filesystem images, kernel images, or bootloader images. Depending on 
the configuration, you may find files like ``rootfs.tar``, ``zImage``, 
``uImage``, or others that are ready to be deployed onto the target hardware.

target 
======

The ``target`` folder contains the files that are specifically intended for the 
target system. This includes the root filesystem and any additional files that 
will be included in the target environment. The structure within this folder 
often mimics the directory structure of a standard Linux system, containing 
directories like ``bin``, ``lib``, ``etc``, ``usr``, and others, which hold the 
binaries, libraries, configuration files, and other necessary components for 
the target system to function properly.

.. _flash_the_image:

Flash the image  
***************

Insert the SD card into the laptop and check its mount point. It is typically 
labeled as sda or sdb, but you can use the lsblk command to confirm this 
information.

If it is mounted on /dev/sda, run the following command

.. code-block:: bash 

    sudo dd if=images/sdcard.img of=/dev/sda

As mentioned in :ref:`images`, the output image is in ``images`` and named 
``sdcard.img``. 

Connect an Ethernet cable to the RPi4 and ensure the laptop and the RPi4 are on 
the same network. 

You can use ``ifconfig`` or ``ip a`` to find your IP address. Then, use 
``nmap`` or any tool to scan the network and find the IP address of the 
RPi4.

.. code-block:: bash

    nmap -sn <YOUR_IP_ADDRESS>/24 | grep lvgl

All of this can be done with the UART instead of SSH if you don't want to 
connect the RPi4 to the network.