Overview

Running programs often need a soft reset (in plain words: make the board "reboot" like a computer, running the program from the start again): take effect after parameter changes, recover from exceptions, enter new firmware after OTA (over-the-air upgrade, in plain words: updating firmware over the network like a phone system update), etc. There are two ways to reset: power-on reset (POR, in plain words: like unplugging and re-plugging power — everything re-initializes, the most thorough) and system reset (in plain words: only restarts software without the full power-off flow, faster). This tutorial is based on the official helloworld example, demonstrating a countdown then calling bl_sys_reset_por() to trigger a software reset — after restart the program runs from the beginning.

In plain words: a soft reset is like a computer's "restart" — when your phone is stuck you press and hold the power button to restart it, and a program's settings change also needs a restart to take effect. Same with the board: calling the reset function while running makes the program immediately run from the start, similar to pressing the board's reset button manually — except it's controlled by code, no hands needed.

This tutorial is based on the official Ai-Thinker SDK (Ai-Thinker-Open/Ai-Thinker-WB2, version release_bl_iot_sdk_1.6.40) example applications/get-started/helloworld; the code can be found directly in your local SDK.

🎯Page GoalAfter a countdown print, call `bl_sys_reset_por()` to watch the board reboot automatically, mastering the soft reset API and the difference between the two reset ways.

🧰Prerequisites① Ai-WB2 development board (Type-C data cable) ② Environment set up per [SDK Installation](../sdk/sdk_intro).

🔗RelatedAfter reset the program restarts from `main`; the relationship between sleep wake and reset: [Sleep Mode](./sleep).

---

①

Enter the Example Project

Open a terminal and enter the official helloworld example project directory:

cd ~/Ai-Thinker-WB2/applications/get-started/helloworld

Note: cd is the “change directory” command and ~ means your user home directory. This enters the helloworld example project; all subsequent make commands must run in this directory. If it says No such file or directory, the path is wrong — see the FAQ at the end.

②

Write the Code

Open helloworld/main.c. The full code for this step has been moved to the end of this page:

📜 Full Code — in the “Full Code” section below, collapsed by default — click to expand, identical to the official example (applications/get-started/helloworld/helloworld/main.c).

Code highlights:

Code	Purpose
bl_sys_reset_por()	Simulates a power-on reset; without calling it the program never reboots — the core of this tutorial
vTaskDelay(1000 / portTICK_PERIOD_MS)	Delay 1 second before continuing; without it the countdown flashes by too fast to see
printf("Restarting now.\r\n")	Prints a notice before resetting; confirms “about to restart”, easy to observe

💡 The official SDK also has system reset bl_sys_reset_system() (soft reset, doesn’t reset external reset logic). For applications the two are usually no different: both restart the firmware with main re-executing.

③

Build the Project

Build in the project directory:

make -j8

Note: make is the “build” command, translating the source code into machine code the board can run; -j8 builds with 8 parallel cores, faster.

On success a firmware build_out/helloworld.bin is generated (firmware: the program burned into the board after compilation, like the board’s “operating system + your program”).

④

Flash the Firmware

Keep the board connected via USB, confirm the serial device, and flash:

make flash p=/dev/ttyUSB0 b=921600

Note: make flash is the “flash” command, writing the compiled firmware into the chip (flashing: the process of writing a program into the chip); p=/dev/ttyUSB0 is the serial device — change it to your computer’s actual port (like COM3 on Windows), b=921600 is the flash baud rate (transfer speed).

⏳ During flashing, press and hold the EN button on the board when prompted to enter download mode; wait for the progress bar to complete — that means the flash succeeded. If it keeps waiting or reports the serial port can’t open, see the FAQ at the end.

⑤

Run and Verify

After flashing, the board automatically restarts and runs. Open a serial assistant (baud rate 921600) and observe the logs:

Hello World.
Restarting in 10 seconds...
Restarting in 9 seconds...
...
Restarting in 0 seconds...
Restarting now.
Hello World.                  ← restarts from the beginning
Restarting in 10 seconds...
...

A countdown prints every 1 second; after 10 seconds Restarting now. prints and the board auto-reboots immediately, starting a new countdown round from Hello World. — over and over.

💡 Advanced verification: replace bl_sys_reset_por() with bl_sys_reset_system() and rebuild/re-flash to observe the behavior difference — both restart the firmware, but the system reset skips the full POR flow and resets faster.

✅ Expected result: after Restarting now. prints the board immediately reboots and Hello World. plus the countdown appear again — verified. If only one Hello World. prints and the log stalls with no countdown, the program didn’t run or the reset didn’t take effect — see the FAQ at the end.

---

API Summary for This Tutorial

bl_sys_reset_por()

Simulates power-on: resets peripherals and memory, re-initializes the system, then boots (the most thorough reset).

Return: never returns (the system resets and reboots immediately on call)

bl_sys_reset_system()

Soft-resets the system (skips the full POR flow, faster; some peripheral states may linger).

Return: never returns (the system resets and reboots immediately on call)

vTaskDelay(ms)

Suspends the current task for the given milliseconds, yielding CPU to other tasks meanwhile (the pre-reset countdown in this tutorial).

Parameters:

• ms: delay in milliseconds, values: any non-negative integer (internally converted to system ticks via pdMS_TO_TICKS)

Return: none

printf(fmt, ...)

Standard C library output to UART0, not subject to blog level filtering.

Parameters:

• fmt: format string, required
• ...: variadic args, optional

Return: the number of characters printed on success; negative on failure

---

Full Code

Below is the complete helloworld/main.c source, identical to the official example (applications/get-started/helloworld/helloworld/main.c):

📜 Click to expand the full helloworld/main.c code

/*
 * @Author: xuhongv@yeah.net xuhongv@yeah.net
 * @Date: 2022-10-03 15:02:19
 * @LastEditors: xuhongv@yeah.net xuhongv@yeah.net
 * @LastEditTime: 2022-10-08 14:55:16
 * @FilePath: \bl_iot_sdk_for_aithinker\applications\get-started\helloworld\helloworld\main.c
 * @Description: Hello world
 */
#include <stdio.h>
#include <string.h>
#include <FreeRTOS.h>
#include <task.h>
#include <blog.h>
#include "bl_sys.h"

void main(void)
{

    printf("Hello World.\r\n");
    for (int i = 10; i >= 0; i--)
    {
        printf("Restarting in %d seconds...\r\n", i);
        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }
    printf("Restarting now.\r\n");

    bl_sys_reset_por();
}

---

FAQ & Troubleshooting

⚠️ System hangs after calling the reset API (no response)
Cause: the reset was called in an interrupt context or while a task lock (interrupts disabled) was held
Fix: call the reset API from a normal task; to reset from an interrupt, defer to a task first (e.g. notify a task to reset via a queue)

⚠️ Can't boot again after reset (needs re-power)
Cause: corrupted firmware, or the reset cause register was accidentally changed and POR can't recover
Fix: re-flash the firmware; confirm the firmware passes OTA verification (failed upgrades auto-rollback, no repeated reboots)

⚠️ Repeated resets cause WiFi connection failures
Cause: reset intervals too short; the WiFi driver/RF hasn't released yet, and reconnecting too fast fails
Fix: delay 1~2 seconds before resetting (the official countdown considers exactly this); in business logic use a "wait after first reset + retry" mechanism

⚠️ Want to reset but not re-initialize peripherals
Cause: re-executing main re-initializes all peripherals
Fix: if only one module needs recovery, use vTaskDelete + recreate the task instead of a full-board reset; if data must survive the reset, save it to Flash

⚠️ Serial port won't open / /dev/ttyUSB0 not found
Cause: USB-to-serial driver not installed, port occupied, or (on Linux) no access permission
Fix: on Linux confirm the device is recognized with lsusb, run sudo chmod 666 /dev/ttyUSB0 or add your user to the dialout group and retry; on Windows check the COM port in Device Manager and install the CH340/CP210x driver

⚠️ Flashing stuck waiting / chip not found
Cause: download mode wasn't entered, the cable only charges and can't transfer data, or the baud rate is wrong
Fix: press and hold EN during flashing until the progress bar appears; try a data cable; confirm p= port and b=921600 are correct

⚠️ cd reports No such file or directory / no Makefile found
Cause: make ran outside the example project directory, or the SDK install path differs from the tutorial
Fix: cd ~/Ai-Thinker-WB2/applications/get-started/helloworld first, then run make; if ~/Ai-Thinker-WB2 doesn't exist, find the SDK with find ~ -name "Ai-Thinker-WB2"

Self-Check

The serial prints Restarting now. then the board immediately auto-reboots and prints Hello World. again — the soft reset is verified.