SDK Examples

Introduction

There are two kinds of examples in the SDK.

Application examples
Peripheral examples

This chapter illustrates the contents of examples and how to build example source code.

Items	Path	Description
Application example	{SDK}\component\example	xml, ssl, …
Peripheral example	{SDK}\component\example\peripheral	ADC, UART, I2C, SPI, Timer, …

The peripheral examples are demos of peripherals. Most examples consist of raw and mbed folders, you can choose raw or mbed demos as you like.

Items	Path	Description
mbed	{SDK}\component\example\peripheral\{peripheral}\mbed	mbed APIs are used.
raw	{SDK}\component\example\peripheral\{peripheral}\raw	Low-level driver APIs are used.

In each folder of example, there are C source files, header files, CMakeLists.txt and README.md. You should check for detailed configurations of the example according to README.md.

Note

The examples are shared by all Realtek SoC, so you need to refer to README.md for detailed information of different ICs.

README.md: Technical documentation with:
- Example description
- HW configurations
- Software configurations
- Expected behavior
- Support ICs

The entry function of example is app_example(), and each example has its own app_example().

The app_example() in main.c under {SDK}\amebaxxx_gcc_project\project_xxx\src is compiled with weak properties. When the example is built, app_example() in the example file is marked as a strong symbol, and app_example() in the main.c file will be ignored.

_WEAK void app_example(void)
{

}

// default main
int main(void)
{
   ...
   app_example();
   ...
   /* enable schedule, start kernel */
   vTaskStartSchedule();
}

The examples normally run on KM4. To run example, you only need to:

Check software and hardware settings in README.md of the example. If the user needs to configure the project, you can execute ./menuconfig.py -f /.../prj.conf to configure it. For an introduction to prj.conf, see conf file introduction. Execute in the terminal:
```
./menuconfig.py -f ../component/example/.../prj.conf
```
Add compile options ./build.py -a {example folder name} when building the project, and replace {example folder name} with the specific folder name of this example. The path of {example folder name} includes the directory above CMakeLists.txt.

Application Example

For example, if you want to build xml example to start an xml example thread, you need to:

Set the macro in SDK according to README.md in {SDK}\component\example\xml

SDK
  └── component                   include FreeRTOS、SoC、mbed API、Wi-Fi、network
      ├── ...
      └── example                 application example
          ├── peripheral          All peripheral drivers and module codes used by the application
          ├── ssl
          ├── storage
          ├── ...
          └── xml
              ├── app_example.c
              ├── CMakeLists.txt
              ├── example_xml.c
              ├── example_xml.h
              └── README.md

Enter ./build.py -a xml for terminal.
```
./build.py -a xml
```

Peripheral Example

For example, if you want to build peripheral/raw/I2C/raw_i2c_dma_mode example to start an peripheral/raw/I2C/raw_i2c_dma_mode example thread, you need to:

Set the macro in SDK according to README.md in {SDK}\component\example\xml\peripheral\raw\I2C\raw_i2c_dma_mode

SDK
  └── component                   include FreeRTOS、SoC、mbed API、Wi-Fi、network
      ├── ...
      └── example                 application example
          ├── ...
          ├── peripheral          All peripheral drivers and module codes used by the application
          │   ├── mbed
          │   └── raw
          │       ├── ...
          │       └── I2C
          │           ├── ...
          │           └── raw_i2c_dma_mode
          │               ├── app_example.c
          │               ├── CMakeLists.txt
          │               ├── example_raw_i2c_dma_mode.c
          │               ├── example_i2c_ext.h
          │               └── README.md
          ├── ssl
          ├── storage
          └── xml

Enter ./build.py -a raw_i2c_dma_mode for terminal.
```
./build.py -a raw_i2c_dma_mode
```