SDK Introduction

SDK Description

The FreeRTOS SDK for Realtek Ameba-IoT series products is hosted on GitHub: https://github.com/Ameba-AIoT/ameba-rtos.

This SDK includes basic functions such as Wi-Fi and Bluetooth (BT), and can serve as the foundational SDK for development. For advanced features, such as AI Voice, TensorFlow Lite (tflite), GUI, Audio, etc., they are hosted and maintained in separate repositories.

Note

These advanced features depend on the base SDK. It is recommended to use the base SDK version specified by the official instead of directly using the latest version, to ensure compatibility and stability.

The SDK consists of the following four parts:

SDK
  ├── amebaxxx_gcc_project        Used to configure and compile firmware, including Kconfig, cmake, ld, library, etc.
  ├── component                   Components such as FreeRTOS, SoC, mbed API, Wi-Fi, network, etc.
  ├── tools                       Tools
  └── cmake                       Compilation abstraction layer

project

Each SoC has a corresponding project directory amebaxxx_gcc_project, which serves as the compilation entry point for that SoC. Each SoC may include multiple MCUs, and each MCU has its own subdirectory project_xx under amebaxxx_gcc_project, containing the default main program entry, linker script, and CMake build configuration files for Bootloader and Application Image.

The amebaxxx_gcc_project directory also contains the following subdirectories:

  • utils: Script tools used for debugging and configuration files required for automated compilation

  • menuconfig: Configuration system supporting make menuconfig, generated during configuration

  • build: Generated after CMake compilation, stores intermediate files

amebaxxx_gcc_project/
  ├── project_xx/              Private configuration directory for each MCU
  ├── project_xx/              Private configuration directory for each MCU; there will be multiple directories if the SoC contains multiple MCUs
  │   ├── src/                 Main program source code
  │   ├── inc/                 Header files such as FreeRTOSConfig.h and build_info.h
  │   └── asdk/                ld, CMake build system
  ├── utils/                   Debugging and automated build scripts and configurations
  ├── menuconfig/              Configuration item definitions supporting make menuconfig, generated after configuration
  └── build/                   Generated after CMake compilation, stores intermediate files

component

This directory contains the core functional components of the SDK, which are called by upper-layer applications. Common components are listed in the following table:

Item

Description

at_cmd

AT command support module

audio

Audio codec driver, supports: alc5616/alc5640/alc5651/alc5660/alc5679/alc5680/sgtl5000

bluetooth

Bluetooth protocol stack source code and related library files

example

application examples, including:atcmd_host,network,ota,usb,peripherals, etc.

file_system

File system implementation, includes: fatfs, littlefs, ftl, kv, vfs, etc.

lwip

LWIP protocol stack APIs and source code

network

Network protocol support, includes:

  • cJSON

  • CoAP

  • DHCP

  • HTTP/2

  • HTTP Client (httpc)

  • HTTP Server (httpd)

  • mDNS

  • MQTT

  • Ping

  • iPerf

  • SNTP

  • WebSocket

  • XML

os

FreeRTOS real-time operating system source code and OS APIs wrapper layer implementation

soc

SoC-related core modules, includes:

  • app: System monitoring and Shell tools

  • loader: Bootloader and GDB Loader

  • cmsis: Arm header files defining CPU registers and basic operation APIs

  • cmsis-dsp: Arm CMSIS-DSP digital signal processing library

  • fwlib: Low-level drivers such as Audio Codec, SPORTS, UART, I2C, SPI, Timer, PWM, etc.

  • img3: Trustzone support (may not be enabled)

  • hal: Mbed APIs encapsulated based on Raw APIs

  • misc: Other miscellaneous functions such as crashdump, OTA, PMU, etc.

  • swlib: Standard software library functions provided by ROM, such as _memcpy, _memcmp, etc.

  • usrcfg: User-defined configuration files

ssl

Secure communication protocol stack, implemented based on mbed TLS

usb

USB class drivers and verification code

utils

Utility modules, includes:

  • IPC (Inter-Processor Communication)

  • Ringbuffer

  • Unit Test Framework

wifi

Wi-Fi functional module, provides the following interfaces:

  • WIFI NIC mode: Used as a traditional Wi-Fi card

  • R-mesh: Realtek Wi-Fi Mesh

  • CSI: Wi-Fi sensing

  • KVR: Wi-Fi roaming

  • WPS: Wi-Fi Protected Setup

  • MCC: Wi-Fi multi-channel coexistence

  • Promisc: Wi-Fi promiscuous mode, capable of receiving all packets on current channel

  • Fast connect: Rapid connection after Wi-Fi restart

tools

This directory contains tools required during IC development.

Item

Description

TraceTool

Used for printing logs and sending commands Trace Tool

ImageTool

Used for downloading firmware Image Tool

DownloadServer

Socket-based OTA server program

DownloadServer (HTTP)

HTTP-based OTA server program

iperf

Used for Wi-Fi throughput testing

littlefs

Generates the littlefs file system

meta_tools

VSCode plugin SDK-side adaptation toolset

Critical Header Files

The following table lists some key header files in the SDK and their descriptions:

Item

Description

Location

basic_types.h

  • RTK_SUCCESS/RTK_FAIL

  • TRUE/FALSE

  • ENABLE/DISABLE

  • ON/OFF

  • NULL

  • u8/u16/u32/u64

  • BOOL

  • BIT x

  • …

component/soc/amebaxxx/fwlib/include

section_config.h

Definitions of various sections in the linker script:

  • BOOT_RAM_DATA_SECTION

  • IMAGE2_RAM_TEXT_SECTION

  • …

ameba_soc.h

Provides Raw APIs for low-level drivers (recommended to use)

Compared to mbed APIs, Raw APIs offer more flexible, rich, and efficient hardware configuration interfaces

mbed API headers

High-level encapsulation interfaces based on Raw APIs, providing relatively simplified functionality

component/soc/amebaxxx/hal