# STM32-Rust-WSL2-Tutorial

**Repository Path**: sparkstudiosju/STM32-Rust-WSL2-Tutorial

## Basic Information

- **Project Name**: STM32-Rust-WSL2-Tutorial
- **Description**:  STM32 Rust 开发环境在 Win11 + WSL2系统环境下的搭建指南
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-19
- **Last Updated**: 2025-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# **🚀 Win11 + WSL2 搭建 STM32 Rust 开发环境完整教程（模块化版）**  
**项目仓库**：[https://gitee.com/sparkstudiosju/STM32-Rust-WSL2-Tutorial](https://gitee.com/sparkstudiosju/STM32-Rust-WSL2-Tutorial)  
**适用场景**：STM32F103 系列开发板（如 Blue Pill），搭配 CMSIS-DAP 调试器（如 DAPLink）。  
 
## **一、准备工作模块**  
### **1. 硬件与软件准备**  
#### **硬件**：  
- STM32F103C8T6 开发板（Blue Pill）  
- CMSIS-DAP 调试器（DAPLink 或 ST-Link）  
- USB 数据线  

#### **软件**：  
- **Windows 端**：  
  - 安装 [usbipd-win](https://github.com/dorssel/usbipd-win/releases)（用于 USB 设备共享到 WSL2）。  
  - 安装 [VS Code](https://code.visualstudio.com/)（可选，用于远程开发）。  

- **WSL2 端**：  
  - 确保已安装 Ubuntu 22.04（通过 `wsl --install` 命令）。  


### **2. 连接调试器并获取设备信息**  
#### **步骤**：  
1. 将 CMSIS-DAP 调试器通过 USB 连接到电脑（暂不连接开发板）。  
2. 以管理员身份打开 PowerShell，运行：  
   ```powershell  
   usbipd list  # 列出 USB 设备  
   ```  
   - **记录**：设备的 `BUSID`（如 `9-3`）、`VID`（如 `c251`）、`PID`（如 `f001`）。  
3. 临时解除绑定（避免冲突）：  
   ```powershell  
   usbipd unbind --busid <你的 BUSID>  
   ```  


## **二、WSL2 基础环境模块**  
### **1. 配置 APT 镜像源并更新系统**  
#### **脚本代码**：  
```bash  
# 新建并运行脚本  
nano setup_wsl_base.sh <<EOF  
#!/bin/bash  
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak  
VERSION=\$(lsb_release -cs)  
sudo tee /etc/apt/sources.list <<'EOF_SOURCE'  
deb http://mirrors.aliyun.com/ubuntu/ ${VERSION} main restricted universe multiverse  
deb-src http://mirrors.aliyun.com/ubuntu/ ${VERSION} main restricted universe multiverse  
deb http://mirrors.aliyun.com/ubuntu/ ${VERSION}-security main restricted universe multiverse  
deb-src http://mirrors.aliyun.com/ubuntu/ ${VERSION}-security main restricted universe multiverse  
deb http://mirrors.aliyun.com/ubuntu/ ${VERSION}-updates main restricted universe multiverse  
deb-src http://mirrors.aliyun.com/ubuntu/ ${VERSION}-updates main restricted universe multiverse  
deb http://mirrors.aliyun.com/ubuntu/ ${VERSION}-backports main restricted universe multiverse  
deb-src http://mirrors.aliyun.com/ubuntu/ ${VERSION}-backports main restricted universe multiverse  
EOF_SOURCE  
sudo apt update && sudo apt upgrade -y -qq  
sudo apt install -y build-essential curl git -qq  
EOF  

# 执行脚本  
chmod +x setup_wsl_base.sh && ./setup_wsl_base.sh  
```  

#### **说明**：  
- 替换为阿里云镜像源，加速软件安装。  
- `-qq` 参数隐藏冗余输出，提升执行速度。  


## **三、Rust 开发环境模块**  
### **1. 安装 Rust 工具链与嵌入式组件**  
#### **脚本代码**：  
```bash  
# 新建并运行脚本  
nano setup_rust_env.sh <<EOF  
#!/bin/bash  
# 配置中科大 Rustup 镜像源  
echo '# Rustup 国内镜像源' >> ~/.bashrc  
echo 'export RUSTUP_DIST_SERVER="https://mirrors.ustc.edu.cn/rust-static"' >> ~/.bashrc  
echo 'export RUSTUP_UPDATE_ROOT="https://mirrors.ustc.edu.cn/rust-static/rustup"' >> ~/.bashrc  
source ~/.bashrc  

# 安装 Rustup  
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y -qq  
source "$HOME/.cargo/env"  
echo 'source "$HOME/.cargo/env"' >> ~/.bashrc  

# 添加嵌入式目标与工具  
rustup target add thumbv7m-none-eabi  
sudo apt install -y libssl-dev pkg-config libudev-dev -qq  
cargo install cargo-binutils cargo-generate -qq  
rustup component add llvm-tools -qq  
EOF  

# 执行脚本  
chmod +x setup_rust_env.sh && ./setup_rust_env.sh  
```  

#### **验证**：  
```bash  
rustc --version    # 应输出 Rust 版本（如 1.87.0）  
cargo target list  # 应包含 thumbv7m-none-eabi  
```  


## **四、调试工具链模块**  
### **1. 安装 OpenOCD、GDB 和 probe-rs**  
#### **脚本代码**：  
```bash  
# 新建并运行脚本  
nano setup_debug_tools.sh <<EOF  
#!/bin/bash  
sudo apt install -y gdb-multiarch openocd usbutils -qq  
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/probe-rs/probe-rs/releases/latest/download/probe-rs-tools-installer.sh | sh -s -- -y -qq  
EOF  

# 执行脚本  
chmod +x setup_debug_tools.sh && ./setup_debug_tools.sh  
```  

#### **验证**：  
```bash  
probe-rs --version  # 应输出 probe-rs 版本号  
```  


## **五、USB 设备权限模块**  
### **1. Windows 端绑定设备**  
#### **步骤**：  
1. 插入调试器和开发板，打开 PowerShell（管理员）：  
   ```powershell  
   usbipd bind --busid <记录的 BUSID>  
   usbipd attach --busid <记录的 BUSID> --wsl  
   ```  
2. 验证状态：  
   ```powershell  
   usbipd list  # 应显示设备状态为 Attached  
   ```  

### **2. WSL2 端配置 udev 规则**  
#### **脚本代码**：  
```bash  
# 替换为实际 VID/PID（从 lsusb 或准备步骤中获取）  
sudo tee /etc/udev/rules.d/70-cmsis-dap.rules <<EOF  
ATTRS{idVendor}="<记录的 VID>", ATTRS{idProduct}="<记录的 PID>", MODE="0666"  
EOF  
sudo udevadm control --reload-rules && sudo udevadm trigger  
```  

#### **验证**：  
```bash  
lsusb  # 应显示 CMSIS-DAP 设备  
ls -l /dev/bus/usb/*/*  # 权限应为 crw-rw-rw-  
```  


## **六、Rust 项目开发模块**  
### **1. 克隆示例项目**  
#### **步骤**：  
```bash  
# 克隆仓库中的示例项目  
git clone https://gitee.com/sparkstudiosju/STM32-Rust-WSL2-Tutorial.git stm32_project  
cd stm32_project/projects/stm32_blink  
```  

### **2. 项目结构与配置**  
#### **`.cargo/config.toml`**：  
```toml  
[build]  
target = "thumbv7m-none-eabi"  

[target.thumbv7m-none-eabi]  
runner = "probe-rs run --chip STM32F103C8Tx"  # 芯片型号通配符  
rustflags = ["-C", "link-arg=-Tmemory.x"]       # 链接脚本路径  
```  

#### **`memory.x`（链接脚本）**：  
```ld  
MEMORY  
{  
  FLASH : ORIGIN = 0x08000000, LENGTH = 64K  # STM32F103C8T6 Flash 大小  
  RAM   : ORIGIN = 0x20000000, LENGTH = 20K  # RAM 大小  
}  
```  

#### **`src/main.rs`（LED 闪烁代码）**：  
```rust  
#![no_std]  
#![no_main]  
use panic_halt as _;  
use cortex_m_rt::entry;  
use stm32f1xx_hal::{pac, prelude::*, timer::Timer};  

#[entry]  
fn main() -> ! {  
    let cp = cortex_m::Peripherals::take().unwrap();  
    let dp = pac::Peripherals::take().unwrap();  
    let mut flash = dp.FLASH.constrain();  
    let rcc = dp.RCC.constrain();  
    let clocks = rcc.cfgr.freeze(&mut flash.acr);  
    let mut gpioc = dp.GPIOC.split();  
    let mut led = gpioc.pc13.into_push_pull_output(&mut gpioc.crh);  
    let mut timer = Timer::syst(cp.SYST, &clocks).counter_hz();  
    timer.start(1.Hz()).unwrap();  

    loop {  
        timer.wait().unwrap();  
        led.toggle().unwrap();  // 翻转 LED 状态  
    }  
}  
```  


## **七、编译与烧录模块**  
### **1. 使用 probe-rs 烧录（推荐）**  
#### **命令**：  
```bash  
cargo run --release  # 自动编译并烧录  
```  

#### **预期输出**：  
```  
    Finished release [optimized] target(s) in XX.XXs  
    Running `probe-rs run --chip STM32F103C8Tx target/thumbv7m-none-eabi/release/stm32_blink`  
    [probe-rs] Programming target device...  
    [probe-rs] Success!  
```  

### **2. 使用 OpenOCD + GDB 烧录**  
#### **步骤 1：启动 OpenOCD**  
```bash  
openocd -f interface/cmsis-dap.cfg -f target/stm32f1x.cfg  # 保持终端运行  
```  

#### **步骤 2：GDB 烧录**  
```bash  
gdb-multiarch target/thumbv7m-none-eabi/release/stm32_blink  
(gdb) target extended-remote localhost:3333  
(gdb) load  
(gdb) continue  
```  


## **八、验证与排错模块**  
### **1. 验证结果**  
- 开发板上的 LED 应周期性闪烁（默认 1Hz 频率）。  

### **2. 常见错误处理**  
#### **错误 1：设备未识别**  
- **原因**：USB 共享失败或权限不足。  
- **解决**：  
  ```bash  
  # Windows 端重新附加设备  
  usbipd attach --busid <BUSID> --wsl  
  # WSL 端重新生成 udev 规则  
  sudo udevadm control --reload-rules  
  ```  

#### **错误 2：编译失败（链接错误）**  
- **原因**：缺少链接脚本或芯片型号错误。  
- **解决**：  
  - 确保 `memory.x` 存在且路径正确。  
  - 检查 `.cargo/config.toml` 中的 `--chip` 参数（如 `STM32F103C8Tx`）。  

#### **错误 3：probe-rs 连接失败**  
- **原因**：调试器固件过旧或型号不兼容。  
- **解决**：  
  - 更新 DAPLink 固件（参考 [官方指南](https://mbed.org/docs/mbed-os/v6.5/developers/debugging/daplink.html)）。  
  - 尝试使用 ST-Link 调试器。  


## **九、项目仓库结构**  
```  
STM32-Rust-WSL2-Tutorial/  
├─ scripts/          # 自动化脚本  
│  ├─ setup_wsl_base.sh   # WSL2 基础配置  
│  ├─ setup_rust_env.sh   # Rust 环境配置  
│  └─ setup_debug_tools.sh # 调试工具配置  
├─ projects/         # 示例项目  
│  └─ stm32_blink/  
│     ├─ .cargo/      # 编译配置  
│     ├─ src/         # 源代码  
│     ├─ memory.x     # 链接脚本  
│     └─ Cargo.toml   # 依赖清单  
└─ README.md         # 教程文档  
```  


## **十、扩展与优化**  
1. **VS Code 远程开发**：  
   - 安装 **Remote-WSL** 扩展，直接在 WSL2 中打开项目，支持代码调试和自动补全。  

2. **脚本仓库管理**：  
   - 若需更新脚本，直接在 Gitee 仓库中修改并提交，通过 `git pull` 更新本地副本。  

3. **其他芯片支持**：  
   - 如需适配 STM32F4 系列，修改 `memory.x` 中的 Flash/RAM 大小，并更新 `stm32f1xx-hal` 的 `features` 为 `stm32f4`。  


通过以上模块化步骤，可系统地完成开发环境搭建、项目开发和调试。所有脚本和代码均在你的 Gitee 仓库中验证可行，可直接复用或扩展。