Skip to content

SiFli-SDK

This guide takes you from an unboxed SF32 development board to a running hello_world example over UART using SiFli-SDK, the official RT-Thread-based SDK for SF32 devices.

If you plan to use Arduino, Zephyr, or MicroPython, it is still worth running this guide once. It proves that the board, cable, serial port, flash flow, and baseline toolchain are working before you add another framework.

What You'll Need

Hardware

  • An SF32 development board, such as the SF32LB52-DevKit-LCD, or another board identified from the SF32 Family.
  • A USB Type-C data cable connected to the board's USB-to-UART port, not a charge-only cable or a secondary USB-function port.
  • A computer running Windows, macOS, or Linux.

Software

  • git
  • A C/C++ toolchain bootstrapped by uv (SiFli-SDK's installer pulls the compiler, debugger, and Python environment for you)
  • The SiFli-SDK repository itself

Official references

Prefer an IDE?

SiFli also publishes a SiFli-SDK-CodeKit extension for VS Code that wraps the SDK setup, build, and flash flow into guided actions. See SiFli CodeKit if you prefer that workflow.

Install the Toolchain

For a reproducible baseline, use a published release tag rather than main. At the time of this review, v2.5.1 is the latest published tag; check the official release list before starting in case a newer tag is available. The release/v2.5 branch receives updates for that release line but can move over time.

Install uv, the package/environment manager SiFli-SDK's scripts are built on:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the SDK:

mkdir -p ~/OpenSiFli && cd ~/OpenSiFli
git clone --recursive -b v2.5.1 https://github.com/OpenSiFli/SiFli-SDK

Run the installer, then load the SDK environment into your shell:

cd SiFli-SDK
./install.sh
. ./export.sh

Install uv (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Clone the SDK:

mkdir C:\OpenSiFli
cd C:\OpenSiFli
git clone --recursive -b v2.5.1 https://github.com/OpenSiFli/SiFli-SDK

Run the installer, then load the SDK environment:

cd SiFli-SDK
.\install.ps1
.\export.ps1

SiFli-SDK contains submodules

GitHub's "Download ZIP" option will not include the required submodules. Use git clone --recursive. If you already cloned without submodules, run git submodule update --init --recursive from the SDK root.

Working from mainland China?

Before installing, set SIFLI_SDK_MIRROR_CHINA to 1 in your shell: use export SIFLI_SDK_MIRROR_CHINA=1 on macOS/Linux or $env:SIFLI_SDK_MIRROR_CHINA = "1" in PowerShell. You can also clone from the Gitee mirror instead of GitHub. See the install guide for details.

install.sh / install.ps1 downloads the matching compiler, debugger, and Python dependencies. Re-run it when the SDK version changes. export.sh / export.ps1 activates that environment in your current terminal; run it each time you open a new terminal to build. On Windows, run the .ps1 scripts from PowerShell.

Choose the Board Target

The value supplied to scons --board is the board directory name under customer/boards. Choose the target that matches the memory and display configuration fitted to your kit; the names below are case-sensitive.

SiFli-SDK Development Kit Build Targets

Development kit Exact scons --board target(s)
SF32LB52-DevKit-Core-3p3 sf32lb52-core_e8r16
sf32lb52-core_n16r16
SF32LB52-DevKit-LCD sf32lb52-lcd_52d
sf32lb52-lcd_n16r8
sf32lb52-lcd_a128r16
SF32LB52-DevKit-Nano sf32lb52-nano_n4
sf32lb52-nano_n16r16
sf32lb52-nano_a128r16
Huangshan-Pi (SF32LB52-LCHSPI-ULP) sf32lb52-lchspi-ulp
SF32LB56-DevKit-LCD sf32lb56-lcd_a128r12n1
sf32lb56-lcd_n16r12n1
SF32LB58-DevKit-LCD sf32lb58-lcd_a128r32n1_dsi
sf32lb58-lcd_a128r32n1_qspi
sf32lb58-lcd_n16r32n1_dpi
sf32lb58-lcd_n16r32n1_dsi
sf32lb58-lcd_n16r32n1_qspi
sf32lb58-lcd_n16r64n4

For a dual-core board, omitting a core suffix builds the HCPU configuration. Use _hcpu explicitly when helpful, or add _lcpu to build the LCPU configuration; for example, scons --board=eh-lb551_lcpu. If your board configuration is absent from this table, use SiFli's supported boards list as the current source of truth.

Build the "Hello World" Example

With the environment loaded, build the RT-Thread hello_world example for your board:

cd example/get-started/hello_world/rtt/project
scons --board=sf32lb52-lcd_n16r8 -j8

Replace sf32lb52-lcd_n16r8 with your board name. See the supported boards list for available names. -j8 builds with 8 parallel jobs; adjust it for your machine. This command omits a core suffix, so it builds HCPU and writes binaries to build_sf32lb52-lcd_n16r8_hcpu/. If you specify an _lcpu target, the output directory uses the _lcpu suffix instead.

Need custom settings?

Run sdk.py menuconfig --board=<board_name> from the project directory to open the interactive configuration menu. Press Esc twice, then choose to save the configuration when prompted.

Flash the Board

Keep the board connected via USB, then run the download script produced by the build:

./build_sf32lb52-lcd_n16r8_hcpu/uart_download.sh

When prompted, enter the serial-device path shown by your operating system. On macOS, use the /dev/cu.* device (for example /dev/cu.usbserial-12345678), not /dev/tty.*; on Linux, use the matching device path, such as /dev/ttyUSB0.

build_sf32lb52-lcd_n16r8_hcpu\uart_download.bat

When prompted with please input serial port number, type just the number from your COM port (e.g. 19 for COM19) and press Enter.

Tip

If the download tool does not enter UART download mode, reset the board immediately before starting the transfer. Follow the board-specific flash instructions if the problem persists.

See It Run

Once flashing completes, reset the board or let it reset automatically. Open a serial terminal at the board's default baud rate. You should see boot output and the hello_world example output over UART.

Success Check

You are ready to move on when:

  • The project builds without errors.
  • The UART download script completes.
  • The serial console shows readable boot output.
  • The hello_world example prints after reset.

Where to Go Next

  • Pick your chip: compare the LB52, LB55, LB56, and LB58 series on the SF32 Family Overview.
  • Explore more examples: beyond hello_world, the SDK ships examples for BLE, classic Bluetooth, LVGL graphics, audio, and low-power modes.
  • Prefer a different framework: continue with Arduino, Zephyr, or MicroPython.
  • Stuck: check the SiFli FAQ for common toolchain, J-Link, and debugging issues.

Record Your Working Baseline

For a repeatable setup, record the SDK tag or branch, exact scons --board target, host operating system, serial port, and the download procedure that worked for your board. Recheck the official supported-boards list and release list when updating the SDK or switching boards.

Last updated: