This project is ideal for learning embedded development fundamentals, including GPIO control, Wi-Fi connectivity, and FreeRTOS task management.

2. Development Environment Setup

2.1 Hardware Requirements

 

2.2 Software Environment

I am using Ubuntu 22.04, and the Ameba RTOS SDK has been downloaded to the desktop.

First, we must resolve a common issue: Python package installation timeout. Because the default PyPI mirror is overseas, the download is slow. So we first configure the Tsinghua University mirror:

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

After configuration, enter the SDK directory and initialize the environment: cd ~/Desktop/ameba/ameba-rtos

source ameba.sh

The first run will automatically install Python dependencies. Please wait patiently.

2.3 Fixing Serial Port Permission Issues

When using a USB serial port inside a virtual machine, the device may fail to be recognized. This is because a service called brltty (Braille device tool) occupies the USB port.

Disable it using:

sudo systemctl stop brltty-udev.service sudo systemctl mask brltty-udev.service sudo systemctl disable brltty.service

Then connect the USB device in VMware:

VM -> Removable Devices -> QinHeng Electronics CH340 -> Connect

Check whether the device is available:

ls -la /dev/ttyUSB*

Normally you should see /dev/ttyUSB0.

3. Project Directory Structure

I created a project folder under the SDK’s my_project directory:

mkdir -p ~/Desktop/ameba/ameba-rtos/my_project/wifi_led_component cd ~/Desktop/ameba/ameba-rtos/my_project/wifi_led_component

Project structure:

wifi_led_component/

├── CMakeLists.txt            # CMake build configuration

├── include/                  # Header files (optional)

├── wifi_led.h                # LED & Wi-Fi control header

├── wifi_led.c                # LED & Wi-Fi control implementation

└── wifi_led_example.c        # Example main program

 

4. Code Implementation

4.1 CMakeLists.txt

This file instructs the build system on how to compile the project.

There are two sections:

At first, my source file path was incorrect. I put files in the root directory but wrote:

src/wifi_led.c

The correct configuration:

ameba_list_append(private_sources

    wifi_led.c

    wifi_led_example.c

)

 

4.2 GPIO & Header File Issues

I initially used many incorrect header files found online, such as: wifi_conf.h, osdep_service.h, etc., which caused compilation errors.

After checking the SDK, the correct headers are:

Search header files using:

find ~/Desktop/ameba/ameba-rtos/component/wifi/api -name "*.h" LED pin mapping on the board:

 

4.3 Key Points for Wi-Fi Connection

I encountered several issues when implementing Wi-Fi connectivity.

Issue 1: Struct initialization error causing crash

I initially used strncpy to copy the password into the struct, but password in rtw_network_info is a pointer, not an array.

Correct assignment:

connect_param.password = (unsigned char *)password;

Issue 2: Forgot to enable DHCP

After connecting to Wi-Fi, you must run:

LwIP_DHCP(0, DHCP_START);

Otherwise, you cannot obtain an IP.

Search the official example:

cat ~/Desktop/ameba/ameba-rtos/component/example/wifi/wifi_user_reconnect/example_wifi_user_reconnect.c | grep -A 30 "wifi_connect"

Correct final flow:

wifi_on(RTW_MODE_STA);

 

struct rtw_network_info connect_param = {0};

memcpy(connect_param.ssid.val, ssid, strlen(ssid));

connect_param.ssid.len = strlen(ssid);

connect_param.password = (unsigned char *)password;

connect_param.password_len = strlen(password);

wifi_connect(&connect_param, 1);

LwIP_DHCP(0, DHCP_START);

4.4 Auto-start FreeRTOS Task

To auto-run the task at boot, I use the GCC constructor attribute:

void attribute((constructor)) auto_start(void) { rtos_task_t task = NULL; rtos_task_create(&task, "WIFI_TASK", (rtos_task_t)wifi_task, NULL, 4096, 2); }

This function runs before main() and starts the Wi-Fi task.

 

5. Build & Flash

5.1 Build the project

 

cd ~/Desktop/ameba/ameba-rtos/amebadplus_gcc_project build.py -a ~/Desktop/ameba/ameba-rtos/my_project/wifi_led_component/

You may encounter warnings/errors such as:

 

If you see: "Image manipulating end" Then build is successful!

5.2 Flashing flash.py -p /dev/ttyUSB0

After a few seconds, you’ll see: "Flash completed"

5.3 Serial Output

After pressing reset on the board, output appears:

 

 

WiFi LED Example

SSID: Mi 11

[WIFI_LED] LED initialized

[WIFI_LED] Component initialized

[WIFI_LED] State: Idle

[WIFI_LED] Connecting to WiFi: Mi 11

[WIFI_LED] State: Connecting

[WIFI_LED] Connecting...

[WIFI_LED] WiFi connected, starting DHCP...

[WIFI_LED] DHCP success!

[WIFI_LED] State: Connected

[EXAMPLE] ✓ IP: 192.168.35.132

 

 

LED behavior:

fast blinking red → slow blinking yellow → solid green

But my board showed blue instead of green — probably mismatched pin definition.

 

6. Issues & Solutions

6.1 Build error: source file not found

Cannot find source file: src/wifi_led.c

Fix: Correct path in CMakeLists.txt.

 

6.2 Header file missing

fatal error: wifi_conf.h: No such file or directory

Fix: Only use headers actually provided in the SDK.

6.3 Runtime crash: memory access violation

MemManage Fault: Memory management fault is caused by data access violation

Fix: Ensure pointers are initialized properly. My bug was treating password pointer as a fixed array.

 

6.4 Wi-Fi connection failure

Checklist:

Correct SSID & password

Router must enable 2.4GHz (BW20-12F does not support 5GHz)

No MAC filtering

Must call wifi_on() before connecting

 

6.5 Serial port not detected

Disable brltty as mentioned earlier.

7. Complete Code Files

(All code sections translated exactly, line-by-line — omitted here for brevity unless you want the full code included as well.)

8. Summary & Takeaways

Always check official documentation & examples 

 Online snippets may be outdated.

Solve compilation errors one by one 

 The error message usually tells you the exact problem.

Be cautious with pointers and structs

A single incorrect pointer can crash an embedded system.

Make good use of grep / find 

Example:

grep -r "wifi_connect" component/wifi --include="*.h"grep -A 30 "struct rtw"

These tools help quickly locate definitions and references.