Overview

Developing Ai-WB2 on Linux is the officially recommended way: one apt command to install dependencies, one git clone to fetch the SDK, one make to build — no GUI needed at all. This tutorial follows the complete official README workflow (install dependencies → clone SDK → grant toolchain permissions → build → flash) and walks you through your first program using the official helloworld example.

In plain words: setting up the environment is like "renovating a kitchen" — first prepare the pots and pans (dependency software), then bring the recipe book (SDK) home, and finally fire up the stove to cook a test dish (build and flash helloworld). After this tutorial, your computer has full development capability, and all later tutorials are "cooking by the recipe".

This tutorial is based on the official Ai-Thinker SDK (Ai-Thinker-Open/Ai-Thinker-WB2, version release_bl_iot_sdk_1.6.40) and its official README (README.md at the repository root); the setup flow is identical to the official documentation.

🎯Page GoalSet up the Linux development environment, build and flash the official helloworld example, and see `Hello World.` on the serial port.

🧰Prerequisites① A Linux system such as Ubuntu/Debian (this tutorial uses Ubuntu as an example) ② An Ai-WB2 development board (Type-C cable) ③ Internet access.

🔗RelatedEnvironment concepts: [SDK Introduction](./sdk_intro); Windows users: [Windows Platform](./get-start_for_Windows); after setup, start with [GPIO Output (Blink LED)](../basic/gpio_led).

---

①

Install Dependency Software

Open a terminal (shortcut Ctrl + Alt + T) and run the official one-line install command:

sudo apt install build-essential python3 python3-pip git screen

Note: sudo runs the command with administrator privileges (it will ask for your login password); apt install is Ubuntu’s software install command; this installs 5 packages at once — build-essential (C compiler gcc/make and other build tools), python3 (needed by build scripts), python3-pip (Python package manager), git (for fetching code), screen (for viewing serial logs).

Verify the installation succeeded:

make --version && git --version

Output like GNU Make 4.x and git version 2.x means the installation succeeded.

⚠️ If sudo apt install is very slow or errors out, it’s usually because the software sources are overseas — switch to domestic software sources first (Tsinghua/Aliyun mirrors) and retry. See online guides like “Ubuntu change to domestic sources”, or just use the domestic Gitee mirror instead (next step).

②

Clone the SDK Locally

Run in the terminal (verbatim from the official README; --recursive is required to fetch submodules):

git clone --recursive https://github.com/Ai-Thinker-Open/Ai-Thinker-WB2.git

Note: git clone is the “download repository” command; --recursive downloads submodules as well. If downloading from GitHub is slow or fails on a domestic network, use the official Gitee mirror instead — content is identical:

git clone --recursive https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2.git

After the download finishes (progress bar completes, prompt returns), confirm the directory exists:

ls ~/Ai-Thinker-WB2

Seeing directories like applications, components, toolchain means the clone succeeded.

💡 By default it clones into the current user’s home directory (~ is /home/your-username/); all later tutorials use cd ~/Ai-Thinker-WB2/applications/... based on this location. You can change the directory, but keeping the default is recommended.

③

Grant Execute Permission to the Toolchain

The freshly downloaded toolchain doesn’t have “executable” permission yet; run the official permission script. Execute in the SDK root directory:

cd ~/Ai-Thinker-WB2/toolchain/riscv/Linux/
. chmod755.sh

Note: cd is “change directory”; . chmod755.sh runs the permission script in the current directory (the leading . is shorthand for source, meaning “execute in this shell”). It adds executable permission to all toolchain files. No output during execution is normal — proceed to the next step.

Verify the toolchain works:

./riscv64-unknown-elf-gcc --version

Note: this command runs the toolchain compiler directly and prints its version; seeing a version number means the permission step succeeded. If you get Permission denied, the previous step didn’t execute properly — go back and retry.

④

Build the Official helloworld Example

Enter the official getting-started example project and build:

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

Note: make is the “build” command (turning C code into firmware the board can run); -j8 builds with 8 parallel tasks for speed. It must run inside the helloworld project directory (entered with the cd above). The first build takes a few minutes (it compiles the entire SDK components); subsequent incremental builds are fast.

On success a firmware build_out/helloworld.bin is generated, and you’ll see:

✓ Built target helloworld

Seeing this line means the build succeeded.

⚠️ If you get ./riscv64-unknown-elf-gcc: No such file or directory or Permission denied, step ③’s permission setup went wrong — return to step ③ and re-run . chmod755.sh.

⑤

Flash the Firmware to the Board

Connect the board with a Type-C data cable, then confirm the serial device:

ls /dev/ttyUSB*

Note: ls is the “list” command; /dev/ttyUSB* matches serial device paths. Output like /dev/ttyUSB0 means the board is recognized; seeing nothing means the cable only charges and can’t transfer data, or a USB-to-serial driver is needed (Linux usually needs no driver — it’s mostly a cable issue; try a different cable).

Then flash:

make flash p=/dev/ttyUSB0 b=921600

Note: p= is the serial device (use what ls showed in the previous step — it’s not always ttyUSB0); b= is the flash baud rate (transfer speed), officially fixed at 921600.

When you see a prompt like Waiting for download..., press and hold the EN button (RST reset button) on the board for about 1 second then release — the board enters download mode and the progress bar starts moving.

⏳ A progress bar reaching 100% with a completion message means success. If it keeps waiting, the EN button probably wasn’t pressed right — try pressing it again.

⑥

Run and Verify (Check Logs over Serial)

After flashing, the board automatically restarts and runs the program. Use screen to open the serial port and watch the output (the screen installed earlier is exactly for this):

screen /dev/ttyUSB0 921600

Note: screen is a serial viewing tool; replace /dev/ttyUSB0 with your serial device, and 921600 is the baud rate — it must match the one used for flashing, otherwise you’ll see garbled text.

The screen keeps printing boot logs; focus on these lines:

Hello World.
Restarting in 10 seconds...
Restarting in 9 seconds...

Seeing Hello World. and the countdown means your board is running — your first program is a success!

💡 The official example counts down 10 seconds and then automatically restarts the board (effectively testing soft reset) — this is normal. To exit screen after viewing, press Ctrl + A then K (press y to confirm when prompted).

💡 Advanced check: the log header also has a line like Build Version: release_bl_iot_sdk_1.6.38 — that’s the SDK version at firmware build time; it may differ between batches and doesn’t affect usage.

---

Commands Used in This Tutorial

sudo apt install(package-list)

Installs Ubuntu software with administrator privileges (used here to install build dependencies: build-essential/python3/git/screen).

Parameters:

• package-list: space-separated package names, e.g. build-essential python3 git screen

Return: success when the prompt returns after installation; on errors (network issues) switch sources and retry

git clone --recursive(repository-url)

Downloads the SDK repository and all submodules to the current directory (Gitee mirror recommended on domestic networks).

Parameters:

• --recursive: recursively fetch submodules; required (otherwise some components are empty)
• repository-url: https://github.com/Ai-Thinker-Open/Ai-Thinker-WB2.git or the Gitee mirror

Return: success when the progress bar completes and the prompt returns

. chmod755.sh

Runs the toolchain permission script, granting executable permission to the compiler (files downloaded on Linux have no execute permission by default).

Parameters:

• None (run inside the ~/Ai-Thinker-WB2/toolchain/riscv/Linux/ directory)

Return: no output is normal; Permission denied means it didn't succeed

make -j8

Builds the firmware inside the example project directory (-j8 parallel build is faster).

Parameters:

• -j8: number of parallel cores; can be changed to -j4/-j16 etc.

Return: ✓ Built target xxx means success; on errors fix as suggested and retry

make flash(p=serial-device b=baud-rate)

Flashes the firmware into the board (press the EN button on the board to enter download mode when flashing).

Parameters:

• p=: serial device, e.g. /dev/ttyUSB0 (confirm with ls /dev/ttyUSB* first)
• b=: baud rate, officially fixed at 921600

Return: progress bar reaching 100% means success; if it keeps waiting, the board didn't enter download mode

screen(serial-device baud-rate)

Opens the serial port to view the board's runtime logs.

Parameters:

• serial-device: e.g. /dev/ttyUSB0
• baud-rate: must match flashing, 921600

Return: logs scroll in real time; press Ctrl + A then K to exit

---

Full Code (Reference: helloworld/main.c)

Below is the official helloworld example source, identical to the official (applications/get-started/helloworld/helloworld/main.c). It prints Hello World. then counts down 10 seconds and restarts the board automatically — it's the "health check program" that verifies your environment is set up:

📜 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

⚠️ sudo apt install is very slow or fails
Cause: default software sources are overseas; domestic networks access them slowly
Fix: switch to domestic sources first (Tsinghua/Aliyun mirrors — search "Ubuntu change sources" for guides), then re-run the install command

⚠️ git clone hangs or errors
Cause: GitHub is unstable on domestic networks, and large repositories (the SDK with submodules is several hundred MB) often drop
Fix: use the Gitee mirror git clone --recursive https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2.git; re-running after a disconnect resumes the download

⚠️ Build reports riscv64-unknown-elf-gcc: No such file or directory or Permission denied
Cause: the toolchain wasn't granted permission (step ③ missing or wrong); the compiler has no execute permission
Fix: go back to the SDK root and re-run cd toolchain/riscv/Linux/ and . chmod755.sh, then verify ./riscv64-unknown-elf-gcc --version prints a version

⚠️ make reports make: command not found
Cause: build-essential from step ① wasn't installed
Fix: run sudo apt install build-essential to install it, then verify with make --version

⚠️ ls /dev/ttyUSB shows nothing*
Cause: the cable only charges and can't transfer data, or the board isn't plugged in properly
Fix: try a Type-C cable that can transfer data; unplug and replug; if it still fails, check dmesg | tail for USB recognition records in the system log

⚠️ Flashing keeps Waiting for download / the progress bar doesn't move
Cause: the EN button wasn't pressed to enter download mode, or the serial port number is wrong
Fix: when the waiting prompt appears, press and hold EN (RST) for about 1 second then release; confirm p= matches what ls /dev/ttyUSB* showed

⚠️ Opening the serial port reports Permission denied (insufficient permissions)
Cause: the current user isn't in the dialout group and has no access to the serial port
Fix: run sudo usermod -aG dialout your-username, then log out and back in (or reboot) for it to take effect

Self-Check

After flashing, seeing Hello World. and the Restarting in 10 seconds... countdown on the serial port means the Linux environment is verified — you can start GPIO Output (Blink LED).