Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install sftool

It will make the sftool command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall sftool uninstalls.

Back to the crate overview.

Readme

sftool

A command-line utility for SiFli SoC serial communication tool.

English | 中文

Overview

SFTool is an open-source command-line utility specifically designed for SiFli series SoCs (System on Chip). It enables communication with chips through serial interfaces, supporting various operations including writing data to flash memory, resetting chips, and more.

Features

Multi-chip Support: SF32LB52, SF32LB56, SF32LB58
Multiple Storage Types: NOR flash, NAND flash, and SD card
Configurable Serial Parameters: Customizable baud rates and port settings
Reliable Flash Operations: Write with verification and compression support
Flexible Reset Options: Configurable before/after operations
Cross-platform: Works on Linux, macOS, and Windows

Installation

Install from Crates.io

cargo install sftool

Install from Git

cargo install --git https://github.com/OpenSiFli/sftool sftool

Build from Source

# Clone the repository
git clone https://github.com/OpenSiFli/sftool.git
cd sftool

# Build with Cargo
cargo build --release

# The compiled binary will be located at
# ./target/release/sftool

Usage

Basic Command Format

sftool [OPTIONS] COMMAND [COMMAND_OPTIONS]
sftool [OPTIONS] config <FILE>

Global Options

-c, --chip <CHIP>: Target chip type (currently supports SF32LB52, SF32LB56, SF32LB58)
-m, --memory <MEMORY>: Memory type [nor, nand, sd] (default: nor, case-insensitive)
-p, --port <PORT>: Serial port device path
-b, --baud <BAUD>: Baud rate for flash/read operations (default: 1000000)
--before <OPERATION>: Operation before connecting to the chip [default_reset, no_reset, no_reset_no_sync] (default: default_reset)
--after <OPERATION>: Operation after tool completion [soft_reset, no_reset] (default: soft_reset)
--connect-attempts <ATTEMPTS>: Number of connection attempts, negative or 0 for infinite (default: 3)
--compat: Compatibility mode, enable if you frequently encounter timeout errors or checksum failures

JSON Config (sftool_param.json)

You can describe a command in a JSON file (for automation) and run it with the config subcommand:

sftool config sftool_param.json

# CLI options can override or fill missing fields in the JSON
sftool -c SF32LB52 -p /dev/ttyUSB0 config sftool_param.json

The JSON file does not need to include every field; CLI options and defaults are merged first, and validation fails only if required values are still missing. The schema is in sftool_param_schema.json in the repository.

Write Flash Command

# Linux/Mac
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash [OPTIONS] <file@address>...

# Windows
sftool -c SF32LB52 -p COM9 write_flash [OPTIONS] <file@address>...

Write Flash Options

--verify: Verify flash data after writing
-u, --no-compress: Disable data compression during transfer
-e, --erase-all: Erase all flash regions before programming (not just write regions)
<file@address>: Binary file and its target address. The @address part is optional if the file format contains address information

Read Flash Command

sftool -c SF32LB52 -p /dev/ttyUSB0 read_flash <address> <size> <output_file>

Erase Flash Command

sftool -c SF32LB52 -p /dev/ttyUSB0 erase_flash <address> <size>

Examples

Linux/Mac Examples

# Write single file to flash
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash app.bin@0x12020000

# Write multiple files to different addresses
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash bootloader.bin@0x12010000 app.bin@0x12020000 ftab.bin@0x12000000

# Write and verify
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash --verify app.bin@0x12020000

# Erase all flash before writing
sftool -c SF32LB52 -p /dev/ttyUSB0 write_flash -e app.bin@0x12020000

# Read flash memory
sftool -c SF32LB52 -p /dev/ttyUSB0 read_flash 0x12020000 0x100000 firmware_backup.bin

# Erase flash region
sftool -c SF32LB52 -p /dev/ttyUSB0 erase_flash 0x12020000 0x100000

Windows Examples

# Write multiple files to different addresses
sftool -c SF32LB52 -p COM9 write_flash bootloader.bin@0x12010000 app.bin@0x12020000 ftab.bin@0x12000000

# Other operations are similar to Linux/Mac

Supported File Formats

Binary files (.bin): Raw binary data
Intel HEX files (.hex): Intel HEX format
ELF files: Executable and Linkable Format (address information extracted automatically)

Troubleshooting

Common Issues

Connection timeouts: Try enabling compatibility mode with --compat
Permission denied on Linux/Mac: Add your user to the dialout group or use sudo
Port not found: Check if the device is properly connected and the port path is correct
Checksum failures: Enable compatibility mode and try lower baud rates

Getting Help

# Show general help
sftool --help

# Show help for specific command
sftool write_flash --help

Library Usage

This tool is built on top of the sftool-lib Rust library. You can integrate the library into your own Rust projects:

[dependencies]
sftool-lib = "0.1.7"

See the sftool-lib documentation for API details.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and Pull Requests.