为什么选择 ESP-IDF ?

使用的系统环境

• 操作系统: macOS 15.7.4
• 开发版: 正点原子 ESP32 AI BOX1

[!TIP] 我们以后将频繁参考的正点原子官方资料 http://www.openedv.com/docs/boards/esp32/ATK-DNESP32S3BVXX.html

配置开发环境

安装 Rust

[!TIP] 官方更推荐使用 Rustup 安装 Rust, 而非通过第三方包管理工具 brew. ESP-IDF-Template 也更推荐使用 Rustup 进行安装 [^1] https://rust-lang.org/tools/install/

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

随后运行 source "$HOME/.cargo/env" 或重启你的 Shell, 校验安装:

rustup update

给 Rust 包管理工具 Cargo 换源

国内特殊的网络环境需要换源才能实现高速的依赖下载, 笔者这里推荐 北京外国语大学开源软件镜像站, 详见:

• https://mirrors.bfsu.edu.cn/help/crates.io-index/
• https://mirrors.bfsu.edu.cn/help/crates.io-index.git/

安装 ESP-IDF 及其工具链

根据 ESP-IDF-Template 中 Prerequisites 部分

In particular, do NOT clone, install and activate the ESP-IDF which is mentioned further down this page, as it is not necessary at all (though supported, but not for a beginner setup)

作为初学者的我们应让 ESP-IDF-SYS 来管理 ESP-IDF, 而非自己手动安装

安装系统级依赖

brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake

安装 Python

笔者电脑里面有一套 Python 开发环境, 所以使用 pyenv 来管理 Python 环境来避免环境紊乱

brew install pyenv

若重启 Shell 后无法检测到 pyenv 命令, 请参考 PyENV 官方文档

pyenv install -l  # 查看最新版本
pyenv install 3.14  # 安装目前的最新版本
pyenv global 3.14
pyenv rehash
python --version  # 校验安装

[!TIP] python --version 版本不对? 看看 pyenv versions 命令结果输出的版本由何设置, 或尝试 rm ~/.python-version.

安装 ESP Rust 相关工具

根据 ESP-IDF-Template 中 Prerequisites 部分

cargo install cargo-generate
cargo install ldproxy
cargo install espup # ESP32-S3 属于 Xtensa，要用 espup 来装 Espressif Rust 工具链
cargo install espflash
cargo install cargo-espflash

根据 ESP-RS, 仅安装最小依赖

espup install --targets esp32s3 --std
. "$HOME/export-esp.sh"

推荐将环境加载持久化进 Shell, 将 ~/.zshrc 改成你的 Shell 用户配置文件

echo '. "$HOME/export-esp.sh"' >> ~/.zshrc

安装 VSCode 插件

在安装 VSCode 插件之前, 笔者更推荐安装以下的 Rust 的额外 lint 工具 和 官方格式化工具

rustup component add clippy rustfmt

运行以下命令或手动安装以下两个 VSCode 插件

code --install-extension rust-lang.rust-analyzer
code --install-extension Slint.slint

推荐添加以下两个 VSCode 配置, 它做了两件事

• 将检查命令从 cargo check 改为 cargo clippy
• 在保存时自动格式化代码

{
  "rust-analyzer.check.command": "clippy",
  "[rust]": {
    "editor.formatOnSave": true
  }
}

搭建最小 Bootstrap

创建 ESP-IDF 项目

用官方模板生成项目, 在项目文件夹中运行如下命令, 根据 ESP-IDF-TEMPLATE

cargo generate esp-rs/esp-idf-template cargo

我选择的选项如下

➜  CLionProjects cargo generate esp-rs/esp-idf-template cargo
⚠️   Favorite `esp-rs/esp-idf-template` not found in config, using it as a git repository: https://github.com/esp-rs/esp-idf-template.git
🤷   Project Name: esp32-s3-slint-rs
🔧   Destination: /Users/xiaoyouchr/CLionProjects/esp32-s3-slint-rs ...
🔧   project-name: esp32-s3-slint-rs ...
🔧   Generating template ...
✔ 🤷   Which MCU to target? · esp32s3
✔ 🤷   Configure advanced template options? · true
✔ 🤷   ESP-IDF version (master = UNSTABLE) · v5.5.3  # 不建议选择 master 分支, 不稳定
✔ 🤷   Use latest GIT versions of the esp-idf-* crates instead of released crates.io versions? · false   # 不建议从 Git 仓库拉取最新版本, 不稳定
✔ 🤷   Installation location of managed ESP-IDF · workspace
✔ 🤷   Configure project to use Dev Containers (VS Code and GitHub Codespaces)? · false
✔ 🤷   Configure project to support Wokwi simulation with Wokwi VS Code extension? · false   # Wokwi is World's most advanced ESP32 simulator
✔ 🤷   Add CI files for GitHub Action? · true    # GitHub 自动构建工作流

安装 Slint 依赖

根据 https://docs.slint.dev/latest/docs/rust/slint/docs/mcu/

cargo add slint@1.16 --no-default-features --features "compat-1-2 unsafe-single-threaded libm renderer-software"
cargo add --build slint-build@1.16

最小 Slint UI

根据 https://docs.slint.dev/latest/docs/rust/slint/docs/mcu/

ui/app.slint

export component App inherits Window {
    width: 320px;
    height: 240px;

    Rectangle {
        background: #1f2937;

        Text {
            x: 16px;
            y: 16px;
            text: "ESP32-S3 + Slint + Rust";
            color: white;
            font-size: 18px;
        }

        Text {
            x: 16px;
            y: 48px;
            text: "compile-only skeleton";
            color: #cbd5e1;
            font-size: 14px;
        }
    }
}

然后编辑 build.rs, 将 ui/app.slint 生成成 Rust 代码, 供 slint::include_modules!(); 引入.

build.rs

fn main() {
    embuild::espidf::sysenv::output();

    let config = slint_build::CompilerConfiguration::new()
    .with_style("fluent".into())
    .embed_resources(slint_build::EmbedResourcesKind::EmbedForSoftwareRenderer);
    slint_build::compile_with_config("ui/app.slint", config).unwrap();
}

随后运行 cargo build, 编译一下 Slint 文件, 防止在编辑 ui/main.rs 时报错.

最小主函数

根据 https://docs.slint.dev/latest/docs/rust/slint/docs/mcu/#the-platform-trait

ui/main.rs

slint::include_modules!();

use std::boxed::Box;
use std::rc::Rc;
use std::time::{Duration, Instant};

use slint::platform::software_renderer::MinimalSoftwareWindow;
use slint::platform::{Platform, PlatformError};

struct EspPlatform {
    window: Rc<MinimalSoftwareWindow>,
    start: Instant,
}

impl Platform for EspPlatform {
    fn create_window_adapter(
        &self,
    ) -> Result<Rc<dyn slint::platform::WindowAdapter>, PlatformError> {
        // Since on MCUs, there can be only one window, just return a clone of self.window.
        // We'll also use the same window in the event loop.
        Ok(self.window.clone())
    }

    fn duration_since_start(&self) -> Duration {
        self.start.elapsed()
    }
}

fn main() {
    // It is necessary to call this function once. Otherwise, some patches to the runtime
    // implemented by esp-idf-sys might not link properly. See https://github.com/esp-rs/esp-idf-template/issues/71
    esp_idf_svc::sys::link_patches();

    // Bind the log crate to the ESP Logging facilities
    esp_idf_svc::log::EspLogger::initialize_default();

    log::info!("Booting...");

    let window = MinimalSoftwareWindow::new(Default::default());
    window.set_size(slint::PhysicalSize::new(320, 240));

    slint::platform::set_platform(Box::new(EspPlatform {
        window: window.clone(),
        start: Instant::now(),
    }))
    .expect("failed to set Slint platform");

    let _ui = App::new().expect("failed to create Slint UI");

    log::info!("Slint initialized");

    loop {
        slint::platform::update_timers_and_animations();
        window.draw_if_needed(|_renderer| {
            // TODO: render to LCD
        });
        std::thread::sleep(Duration::from_millis(16));
    }
}

第一次烧录

插入 ESP32-S3-BOX 后运行 cargo run, 查看控制台日志, 发现

I (480) esp32_s3_slint_rs: Booting...
I (490) esp32_s3_slint_rs: Slint initialized

烧录成功~

正式点亮屏幕

//

驱动 Xl9555

驱动屏幕

加入触屏功能

增强 Xl9555 驱动

驱动触摸

在 Slint 中处理触摸信号

优化性能

超频 I80 总线

边渲染边上屏

异步处理触摸信号

驱动 Wi-Fi

增强 Xl9555 以驱动 I²C 总线

扫描 Wi-Fi

连接 Wi-Fi

其他说明

提高波特率以加快烧录速度

提高栈大小以及如何避免栈溢出

Windows 下长路径问题

Qt 一直把 Code less. Create more. Deploy everywhere 当做其宣传语. 笔者一直都在维护一个基于 Qt for Python 的项目, 很早之前就听说了 PySide6 项目可以部署到 Android 平台上[^1], 但是对系统环境要求十分苛刻, 互联网上也缺少相关文档, 就一直没有尝试此技术. 好在现在微软的 WSL 技术成熟, PySide6 也在 6.8.0 版本之后提供了预编译的轮子[^5], 遂开始了今天的探索.

[!TIP] 自 PySide6 6.7.3 之后[^5], pyside6-android-deploy 可以在 macOS 上运行.[^6]

搭建 WSL 环境

笔者使用的系统是 Windows 11, Qt for Python 的交叉编译要求的系统平台是 Linux[^1] 或者 macOS[^5], 所以需要搭建 WSL 环境, 这里笔者推荐的是 Ubuntu 24.04 LTS, 理由如下:

• PySide6-Android-Deploy 底层依赖 Buildozer, 而 Buildozer 的官方文档重点给的是 Ubuntu 平台的教程, 使用 Ubuntu 可以避免不必要的麻烦.
• 笔者原来常用的是 WSL Arch, WSL 本来安装多个子系统又极其方便, 安装新的 Ubuntu 系统还避免了环境问题.

[!IMPORTANT] 使用 WSL 2 而非 WSL 1 以避免不必要的麻烦 务必将程序源码放置在 WSL 分区 中, 不要在 Windows 分区上进行编译 Notes for WSL users

运行以下命令以安装 Ubuntu 24.04 LTS.

wsl --install -d Ubuntu

运行失败可以先尝试运行以下两个命令[^2]

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

配置基础编译环境

换源并更新软件源

将镜像源切换到国内镜像源, 这里推荐 北京外国语大学开源软件镜像站 , 请选用 DEB822 格式.

sudo apt update
sudo apt full-upgrade -y
sudo apt autoremove -y

安装系统依赖[^3] [^4]

笔者这里使用了 Buildozer 的官方文档[^3] 中推荐的 OpenJDK 17

sudo apt install -y \
  git zip unzip openjdk-17-jdk python3-pip python3-virtualenv \
  autoconf automake libtool pkg-config zlib1g-dev \
  libncurses5-dev libncursesw5-dev libtinfo6 \
  cmake libffi-dev libssl-dev autopoint gettext

安装 Python 环境

笔者自己项目推荐的 Python 版本是 3.11, Qt 官方预编译的 PySide6 for Android 也仅支持 cp3.11 而 Ubuntu 24.04 LTS 官方仓库默认没有 3.11, 遂使用 pyenv 安装 Python.

curl -fsSL https://pyenv.run | bash
cat >> ~/.bashrc <<'EOF'
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
EOF
source ~/.bashrc

pyenv install 3.11
pyenv global 3.11
python --version

切换系统 Java 版本

Ubuntu 24.04 LTS 似乎自带了较新版本的 JDK, 需要手动切换

sudo update-alternatives --config java
sudo update-alternatives --config javac

然后选带 java-17-openjdk / javac-17-openjdk 的那一项

环境自检

python3 --version
pip3 --version
java -version
git --version
cmake --version

新建 Python 虚拟环境

[!IMPORTANT] 建议将虚拟环境放在项目文件夹之外.[^6]

mkdir ~/venv
python -m venv ~/venv
source ~/venv/bin/activate
python -m pip install -U pip setuptools wheel

配置 Python 虚拟环境[^3]

source ~/venv/bin/activate
pip install buildozer setuptools cython==0.29.34

下载 Android NDK 和 SDK

下载 Android NDK 和 SDK 最简单的方法是通过 Qt for Python 仓库中的一个脚本[^6]

cd ~
git clone https://code.qt.io/pyside/pyside-setup
cd pyside-setup
pip install -r tools/cross_compile_android/requirements.txt
python tools/cross_compile_android/main.py --download-only --skip-update --auto-accept-license

Android NDK 和 SDK 会被下载到 ~/.pyside6_android_deploy/ 中

获取适用于 Android 平台的 PySide6 / Shiboken6 轮子

有三种方式可以获取适用于 Python 的 Qt Android 轮子文件[^6]

1. Qt for Python downloads page 或 Qt for Python CI Snapshot
2. qtpip download PySide6 --android --arch aarch64 (可用的架构包括 aarch64 和 x86_64, 仅适用于 Qt Commercial 用户)
3. 为 Android 交叉编译适用于 Python 的 Qt 轮子

笔者这里下载了 PySide6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl 和 shiboken6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl

mkdir ~/android-wheels
cd ~/android-wheels
wget https://download.qt.io/official_releases/QtForPython/pyside6/PySide6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl
wget https://download.qt.io/official_releases/QtForPython/shiboken6/shiboken6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl

至此, 编译环境配置完毕~

最小 Qt for Android Bootstrap

最小启动脚本

笔者在 ~/project 目录创建了 main.py 脚本

import sys

from PySide6.QtWidgets import QApplication, QLabel

if __name__ == "__main__":
    app = QApplication(sys.argv)
    label = QLabel("Qt for Android bootstrap")
    label.show()
    sys.exit(app.exec())

初始化 PySide6-Android-Deploy Spec 文件

cd ~/project
source ~/venv/bin/activate
pyside6-android-deploy \
  --init \
  --name "FirstQtBootstrap" \
  --wheel-pyside=/home/xiaoyouchr/android-wheels/PySide6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --wheel-shiboken=/home/xiaoyouchr/android-wheels/shiboken6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --sdk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-sdk \
  --ndk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-ndk/android-ndk-r27c

[!TIP] 由于不能使用 ~, 请将 /home/xiaoyouchr/ 改成你的家目录.

[!IMPORTANT] 应用名此时不应带有空格, 笔者在后文会提供 PATCH pyside6-android-deploy 脚本从而使应用名可以带有空格.

cd ~/project
source ~/venv/bin/activate
pyside6-android-deploy \
  --config-file /home/xiaoyouchr/project/pysidedeploy.spec \
  --wheel-pyside=/home/xiaoyouchr/android-wheels/PySide6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --wheel-shiboken=/home/xiaoyouchr/android-wheels/shiboken6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --sdk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-sdk \
  --ndk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-ndk/android-ndk-r27c \
  --keep-deployment-files \
  -v

cd ~/project
ls

发现 APK 已经生成到项目中啦! 插入手机, 安装部署产物~

cd ~/project
~/.pyside6_android_deploy/android-sdk/platform-tools/adb install ./FirstQtBootstrap-0.1-arm64-v8a-debug.apk

排查问题

哈哈, 如果你是一步一步按着教程走的, 那么不出意外地应该运行闪退咯~ 插入手机, 老实抓日志.

~/.pyside6_android_deploy/android-sdk/platform-tools/adb logcat | grep -i -E "FATAL EXCEPTION|AndroidRuntime|Qt|libc|python|shiboken|PySide|dlopen|UnsatisfiedLinkError|crash"

注意力惊人, 你在日志中敏锐的观察到:

04-14 16:38:55.135  5948  5976 E AndroidRuntime: java.lang.UnsatisfiedLinkError: dlopen failed: library "libpython3.11.so" not found: needed by /data/app/~~J1G-gyOzPqX3lOSadYNICQ==/org.firstqtbootstrap.firstqtbootstrap-d25iVR_yhfWeWlvi7dSXHg==/lib/arm64/libshiboken6.abi3.so in namespace clns-9

之后你运行了

unzip -l FirstQtBootstrap-0.1-arm64-v8a-debug.apk | grep -i "libpython3"

发现

-rwxr-xr-x 1 xiaoyouchr xiaoyouchr  5764168 Apr 14 16:22 libpython3.14.so

怎么回事呢, 为什么有 libpython3.14.so, 但没有 libpython3.11.so 呢?

PATCH pyside6-android-deploy 脚本

每次调用 pyside6-android-deploy 都会覆写 buildozer.spec 文件, 而修改 buildozer.spec 后直接手动调用 python -m buildozer android debug 又要自己手动处理复杂的依赖问题, 于是~ 修改 ~/venv/lib/python3.11/site-packages/PySide6/scripts/deploy_lib/android/buildozer.py 的奇技淫巧的想法油然而生.

使用你常用的编辑器打开 ~/venv/lib/python3.11/site-packages/PySide6/scripts/deploy_lib/android/buildozer.py

之后找到这行

self.set_value("app", "requirements", "python3,shiboken6,PySide6")

将其改成

self.set_value("app", "requirements", "python3==3.11.15,hostpython3==3.11.15,shiboken6,PySide6")

[!TIP] 增加上 hostpython==3.11.15 的原因是如果不加就会

[ERROR]: Build failed: python3 should have same version as hostpython3, 3.11.14 != 3.14.2

还注意到 buildozer.py 中有如下代码

# add p4a branch
# by default the master branch is used
# https://github.com/kivy/python-for-android/commit/b92522fab879dbfc0028966ca3c59ef46ab7767d
# has not been merged to master yet. So, we use the develop branch for now
# TODO: remove this once the above commit is merged to master
self.set_value("app", "p4a.branch", "develop")

显然此 Commit 已经被合并到了主分支, 为了避免不必要的风险, 建议将这行代码也注释掉. 笔者还发现了这段代码上次被维护是两年前, 最后维护者是 adrianghc, 这位大佬曾为 QtAsyncIO 的推近付出过巨大的精力. 可惜最后还是从 Qt 公司离职了. 这段代码的维护工作最终也不了了之~

重新运行部署脚本并在 Android 设备上安装

cd ~/project
source ~/venv/bin/activate
pyside6-android-deploy \
  --init \
  --name "FirstQtBootstrap" \
  --wheel-pyside=/home/xiaoyouchr/android-wheels/PySide6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --wheel-shiboken=/home/xiaoyouchr/android-wheels/shiboken6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --sdk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-sdk \
  --ndk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-ndk/android-ndk-r27c
pyside6-android-deploy \
  --config-file /home/xiaoyouchr/project/pysidedeploy.spec \
  --wheel-pyside=/home/xiaoyouchr/android-wheels/PySide6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --wheel-shiboken=/home/xiaoyouchr/android-wheels/shiboken6-6.10.3-6.10.3-cp311-cp311-android_aarch64.whl \
  --sdk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-sdk \
  --ndk-path=/home/xiaoyouchr/.pyside6_android_deploy/android-ndk/android-ndk-r27c \
  --keep-deployment-files \
  -v
~/.pyside6_android_deploy/android-sdk/platform-tools/adb install ./FirstQtBootstrap-0.1-arm64-v8a-debug.apk

看到以下画面, 最小 Bootstrap 运行成功了~

迁移你的 PySide6 应用到 Android 平台

压缩包体

注意到我们的最小 Bootstrap 在安装后占用存储空间高达 381MB, 这显然是不可接受的.

cd ~/project
unzip -l FirstQtBootstrap-0.1-arm64-v8a-debug.apk

发现很多没有用到的依赖也被打包进去了

...
   201504  1981-01-01 01:01   lib/arm64-v8a/libQt6Nfc_arm64-v8a.so
    51360  1981-01-01 01:01   lib/arm64-v8a/libQt6OpenGLWidgets_arm64-v8a.so
   518176  1981-01-01 01:01   lib/arm64-v8a/libQt6OpenGL_arm64-v8a.so
   603040  1981-01-01 01:01   lib/arm64-v8a/libQt6PdfQuick_arm64-v8a.so
    98296  1981-01-01 01:01   lib/arm64-v8a/libQt6PdfWidgets_arm64-v8a.so
  4382256  1981-01-01 01:01   lib/arm64-v8a/libQt6Pdf_arm64-v8a.so
...

需要手动修改 ~/venv/lib/python3.11/site-packages/PySide6/scripts/deploy_lib/android/recipes/PySide6/__init__.tmpl.py, 让其仅复制必要的依赖即可.

使应用名支持空格

找到 buildozer.py 中的

self.set_value("app", "title", pysidedeploy_config.title)
self.set_value("app", "package.name", pysidedeploy_config.title)

将 title 改成你的应用名称, 比如

self.set_value("app", "title", "Ghost Downloader 3")
self.set_value("app", "package.name", pysidedeploy_config.title)

调试指南

在进行迁移工作的过程中, 闪退是常有的事情, 我们可以在启动程序前运行

adb logcat -c
adb logcat | rg -i "FATAL EXCEPTION|AndroidRuntime|Qt|libc|python|shiboken|PySide|dlopen|UnsatisfiedLinkError|Permission|SecurityException|EACCES|denied|storage|crash > crash.log"

打开你的 PySide6 on Android 程序, 在崩溃后立即按下 Ctrl + C 结束 adb logcat. 之后使用你常用的编辑器打开 crash.log, 搜索字符串 python :, 就能看到 Python 在 stdout 和 stderr 输出的日志, 之后一步一步解决即可~

导入必要依赖

你的 PySide6 肯定使用了其他的依赖, 请你使用你常用的编辑器打开 ~/venv/lib/python3.11/site-packages/PySide6/scripts/deploy_lib/android/buildozer.py 之后找到这行

self.set_value("app", "requirements", "python3==3.11.15,hostpython3==3.11.15,shiboken6,PySide6")

在里面加上你需要安装的依赖

结语

到此为止, 你已经成功地将你的 PySide6 程序部署到了 Android 设备上了. 感谢阅读~

[^1]: Taking Qt for Python to Android

[^2]: Manual installation steps for older versions of WSL

[^3]: Buildozer documentation

[^4]: P4A documentation

[^5]: PYSIDE6 2766

[^6]: pyside6-android-deploy: the Android deployment tool for Qt for Python