NUWA 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 GCC environment includes the CMake compilation environment, Python environment, and other tool software, as shown in the table below。

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	3.10 or later
wget	Recommended latest
7zip	Recommended latest

Users can download the software package provided by Realtek and configure environment variables by scripts. This method will not affect the user’s original software environment and can avoid compatibility issues caused by software version differences.

LinuxWindows

1. 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 .

2. 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 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

3. Install dependencies

   sudo apt install libssl-dev libncurses5s
   

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

   source ameba.sh
   
   PIP CHECK... All packages are installed correctly!
   ========================================================
   |  First choose IC platform: cd [IC]_gcc_project
   |  Configure command: menuconfig.py
   |  Build command: build.py
   ========================================================
   (.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.

Installing the Toolchain (TODO)

By default, the toolchain will be automatically installed in default path when building the project at the first time:

• Linux：/opt/rtk-toolchain

• Windows：C:\rtk-toolchain

1. Before the compilation, the build scripts will check if the toolchain exists and if the version of the toolchain match the lastest version. Once error occurs, you should fix the error according to the prompts on the screen and try building again.

2. 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 any issues with the download, please verify that your host machine can correctly access GitHub. If you cannot access GitHub, use the following commands to switch the download source:

   build.py -D USE_ALIYUN_URL=True
   

3. If you need to modify the toolchain installation path, create an environment variable RTK_TOOLCHAIN_DIR in your system and assign it the modified installation path.

   LinuxWindows

   1. Open the ~/.bashrc file and add the following line at the end:

      export RTK_TOOLCHAIN_DIR="/path/to/your/toolchain/dir"
      

   2. To make the environment variable take effect immediately, please run:

      source ~/.bashrc
      

Note

• If you already have a downloaded toolchain archive, move the archive to the installation path and run build.py again.

• If you encounter the error Download Failed, check your network connection. If the issue persists, refer to Step 2.

• If you encounter the error Create Toolchain Dir Failed. May Not Have Permission, try creating the folder manually. If the issue persists, refer to Step 3 to change the default installation path.

• If you encounter the error Unzip Failed, the compressed package might be corrupted. Delete it manually from the installation path and run build.py again.

After completing the above steps, the following files will be present under the rtk-toolchain path:

|--- prebuilts-[win/linux]-1.x.x
|
|--- asdk-10.3.1-xxxx
|
|--- vsdk-10.3.1-xxxx

Installing Python Dependencies

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

./nuwa.py setup

Creating an Application

NUWA SDK is based on Zephyr and 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:

NUWA_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 NUWA_SDK/images directory. To flash the firmware, use ImageTool located in NUWA_SDK/tools/ameba/ImageTool. Refer to the Image Tool user guide for flashing instructions.