Build and Flashing

Overview

This chapter describes how to set up the GCC build environment, covering both Windows and Linux platforms:

Windows platform: using Windows 10 64-bit as an example
Linux platform: using Ubuntu 22.04 x86_64 as an example

Environment Setup

Preparing the GCC Build Environment

The required softwares and version requirements are as shown in the following table.

Software	Version
cmake	3.20 or later
ninja	1.10.1 or later
make	3.82 or later
ccache	4.5.1 or later
python3	Recommended 3.10 or later
wget	Recommended latest
7zip	Recommended latest

Manually installing the above softwares directly into the operating system may pollute the existing software environment or cause version compatibility issues.

To address this, Realtek provides a software suite that contains all the necessary softwares and supports running in an independent environment.

Once configured, the Ameba SDK development environment is isolated within the current terminal session. The system environment outside this terminal remains unaffected, effectively avoiding software version compatibility issues.

The detailed steps for configuring the software environment on Linux and Windows are described below.

Download the compressed package and extract it to the /opt/rtk-toolchain folder.
```
mkdir /opt/rtk-toolchain
cd /opt/rtk-toolchain
wget https://github.com/Ameba-AIoT/ameba-toolchain/releases/download/prebuilts-v1.0.3/prebuilts-linux-1.0.3.tar.gz
tar -xzf prebuilts-linux-1.0.3.tar.gz
```
If you encounter network issues when downloading, try to use the aliyun url:
```
wget https://rs-wn.oss-cn-shanghai.aliyuncs.com/prebuilts-linux-1.0.3.tar.gz
```
Note

The compressed package needs to be extracted to the default /opt/rtk-toolchain path. If need to change the path, refer to change toolchain path .
Install Python manually since a portable version of Python cannot be provided under Linux.
```
sudo apt install python3 python3-pip python3-venv
```
Note
- Run python --version to check version of Python, recommended to use version greater than 3.10.
- If pip version is outdated, it’s recommended to update using the command: pip install --upgrade pip.
- If there are multiple versions of Python on the host, you can use the command update-alternatives --install /usr/bin/python python /usr/ bin/python3.x 1 to select a specific version of Python, where x in python3.x 1 represents the desired version number.
- If you encounter the error command 'python' not found, try running the following command to solve the issue: ln -s /usr/bin/python3 /usr/bin/python

Install dependencies

sudo apt install libssl-dev libncurses-dev

Enter into the root directory of SDK and run source env.sh, which will automatically configure the environment variables.

source env.sh

PIP CHECK... All packages are installed correctly!
================================================================================
|  Setup complete. The Ameba SDK is now ready for use.
|  Go to the project root directory and run ameba.py
|  Usage:      ameba.py [COMMAND] [ARGS]
|  Build:      ameba.py build
|  Select SoC: ameba.py soc
|  Help:       ameba.py help
================================================================================
(.venv)

Note

The environment variables will be reset after terminal closed. Therefore, the scripts need to be run again when you open a new terminal.

Create a new folder C:\rtk-toolchain under Disk C.
Download the compressed package and extract it to the C:\rtk-toolchain folder.
Download Link

Users in mainland China are advised to use the aliyun link.
- Download from GitHub
- Download from aliyun
Note

The compressed package needs to be extracted to the specified C:\rtk-toolchain path. If you need to change the path, refer to change toolchain path.

Navigate to the SDK root directory and double-click the env.bat script. This will automatically configure the environment variables, then you can type commands in this opened terminal.

PIP CHECK... All packages are installed correctly!
================================================================================
|  Setup complete. The Ameba SDK is now ready for use.
|  Go to the project root directory and run ameba.py
|  Usage:      ameba.py [COMMAND] [ARGS]
|  Build:      ameba.py build
|  Select SoC: ameba.py soc
|  Help:       ameba.py help
================================================================================
(.venv) C:\sdk>

Note

If users want to use a Unix-like command-line environment such as Git Bash or MSYS2 on Windows, open a new terminal in the SDK root directory and run source env.sh.

Tip

This method relies on Python virtual environment. If you encounter Python system errors, such as messages indicating that a DLL dynamic library missing, try to remove the .venv folder in the root directory of the SDK and then run the env.bat script again. This will automatically reinstall the Python virtual environment.

Installing the Toolchain (TODO)

The installation and update of the cross-compilation toolchain are handled automatically.

When building an SoC project for the first time, the required toolchain will be automatically installed to the following default paths:

Linux：/opt/rtk-toolchain
Windows：C:\rtk-toolchain

Please note that different MCUs may require different toolchain versions. The system will automatically check for updates and upgrade the toolchain with every build.

If an error message pops up, please resolve the issue according to the message and try to build again.

After the installation is complete, the following files will be present under the rtk-toolchain directory:

|--- prebuilts-[win/linux]-1.x.x
|
|--- asdk-1x.3.1-xxxx     # for ARM
|
|--- [vsdk-10.3.1-xxxx]   # for RISC-V (if required)

Note

If you already have a downloaded toolchain archive, move the archive to the installation path and run ameba.py build again.
If you encounter the error Download Failed, check your network connection. If the issue persists, refer to change download source.
If you encounter the error Create Toolchain Dir Failed. May Not Have Permission, try creating the folder manually. If the issue persists, refer to change the default installation path.

Alternative Download Source

The toolchain compressed package is available on GitHub, and the system will attempt to download the toolchain from GitHub by default before the first build. If you encounter download issues or slow speeds, please try changing the download source using the following command:

ameba.py build -D USE_ALIYUN_URL=True

After executing this command, the toolchain will be downloaded from Aliyun, and compilation will proceed.

Modify Installation Path

If you do not wish to install the toolchain in the default path mentioned above, you can modify the installation path by setting the environment variable RTK_TOOLCHAIN_DIR. The setting method is as follows:

Open the ~/.bashrc file and add the following line at the end:
export RTK_TOOLCHAIN_DIR="/path/to/your/toolchain/dir"
To make the environment variable take effect immediately, please run:
source ~/.bashrc
Click Settings > System Properties > Environment Variables to create a new variable named RTK_TOOLCHAIN_DIR with the value set to the desired installation path.

To make the environment variable take effect, please reopen the terminal.

After modifying the installation path, please extract the Realtek software suite to this directory. The toolchain will be automatically installed into this directory when building.

Installing Python Dependencies

The following command creates a Python virtual environment and installs the required Python dependencies:

./nuwa.py setup

Creating an Application

SDK uses CMake as its build system. This build system is application-centric, combining application code with the Zephyr kernel source into a single unified binary. It primarily consists of two parts:

Zephyr base directory: contains Zephyr’s own source code, kernel configuration options, and build definitions.
Application directory: contains all files specific to the application, such as configuration options and source code.

A typical application directory structure is as follows:

<app>
├── CMakeLists.txt     Entry build script that integrates with the Zephyr build system
├── app.overlay        Application-specific Kconfig configuration file
├── prj.conf           Device Tree overlay file (optional)
├── VERSION            Version identifier file (optional)
└── src
    └── main.c         Main application source file

Building the Application

The Zephyr build system compiles and links all components of the application into a single firmware image, which can run on either simulated or real hardware.

As with any CMake-based system, the build process occurs in two phases:

Configuration Phase: The CMake command-line tool generates build files when a generator is specified. In Zephyr, this phase also includes:
- Generating build/zephyr/zephyr.dts and build/zephyr/include/generated/devicetree_generated.h based on DTS content and YAML bindings.
- Collecting all Kconfig files, loading default configurations, and combining them with DTS output to determine the final set of configuration options and dependencies, resulting in build/zephyr/.config and build/zephyr/include/generated/autoconf.h.
- Generating build system files, including CMakeCache.txt and build.ninja.
Build Phase: The native build tool (e.g., Ninja) executes the actual compilation and linking to produce the firmware binary. For more information on these concepts, refer to the CMake documentation: Introduction to CMake.

Build Command

The following command is used to build an application:

./nuwa.py build -d <device> -a <application> [-p]

Parameter descriptions:

build: executes the build subcommand.
-b BUILD_DIR: (optional) specifies the output directory for build artifacts. All files generated during the build are stored here; the directory name can be freely chosen.
-d <device>: specifies the target board (e.g., rtl872xda_evb). The build toolchain automatically searches for the required board configuration files under zephyr/boards/realtek/rtl8721f_evb.
-a <application>: specifies the path to the application (relative to the SDK root directory).
-p: forces a full rebuild. If build artifacts from a previous build exist in the build directory, omitting this flag results in an incremental build; including it triggers a clean rebuild.

Example: Building the Hello World Sample

./nuwa.py build -d rtl872xda_evb -a zephyr/samples/hello_world

Partial Clean

Removes files generated during the Build Phase (e.g., .obj, .elf, .hex), but retains configuration files from the Configuration Phase (e.g., .config):

west build -t clean or ./nuwa.py build -c

Full Clean (Pristine)

Removes all files generated in both the Build Phase and Configuration Phase:

west build -t pristine or ./nuwa.py build -p

Opening the Menuconfig Interface

Menuconfig is part of the build process and depends on intermediate files generated during the Configuration Phase. If the build directory is empty, menuconfig cannot be launched, as the build system has no knowledge of the specific application directory at that point:

west build -t menuconfig or ./nuwa.py config

Contents of the Build Directory

By default, the build directory has the following structure:

SDK/build
├── amebaxxx_gcc_project       Intermediate files for merging multiple MCU binaries
├── build.ninja                Ninja build script (auto-generated)
├── CMakeCache.txt             CMake cache configuration
├── CMakeFiles                 CMake intermediate files
├── cmake_install.cmake        Installation script (typically unused)
├── rules.ninja                Ninja rule definitions
└── zephyr                     Working directory for the Zephyr build system; most generated files are created and stored here

These build output files are written to the zephyr subdirectory within the build directory after running ninja:

.config: contains the configuration settings used to build the application.
Various object and archive files (.o and .a) containing compiled kernel and application code.
zephyr.elf: the final combined binary of the application and kernel. Other binary formats such as .hex and .bin are also supported.

Images Directory and Firmware Flashing

After a successful build using ./nuwa.py, the firmware intended for downloading via ImageTool is placed in the SDK/images directory. To flash the firmware, use ImageTool located in SDK/tools/ameba/ImageTool. Refer to the Image Tool user guide for flashing instructions.