跳到主要内容

STM32 开发环境搭建

根据自己使用的操作系统和开发库，跳转至对应的段落。

⚙️ 通用【基于 HAL 库】（目前最快的方法）​

一、安装 STM32CubeMX​

打开 https://www.st.com.cn/zh/development-tools/stm32cubemx.html

别急着下载，先注册一个账户并登陆，之后也要用到。

找到产品型号 STM32CubeMX-MacA，点击获取最新版本。

二、安装 Visual Studio Code​

自行安装。

三、安装 Visual Studio Code 插件​

插件市场搜索 stm32，找到官方的插件，下载它的预览版（截止目前，该插件的正式版仍未发布）。该预览版会连带安装大约十多个依赖插件。

安装完成后，使用 CubeMX 创建工程并用 VSCode 打开，插件会自动识别该 CubeMX 工程，同时下载安装对应的工具链（内网环境需要较长时间等待）。

插上烧录器，插件大概率会自动识别并安装相应驱动。如果未能正常识别，可以手动下载相应驱动并安装。

🖥 Windows​

本教程使用 Keil5 工具链（标准库），基于 STM32F103C8T6 开发板，ST-LINK V2 调试器，与 Bilibili-江协科技 配套。

请检查自己的设备，仔细审查与本教程不一致的地方，防止烧毁芯片。

提示

由于工具链安装形式在不断更新，本教程所提供的方法不一定是当下最便捷的方法。

一、安装 Keil MDK​

前往 Keil 产品下载界面，选择对应的产品：STM32 选择 MDK-Arm，51 单片机选择 C51。

提示

下载前会要求填写表格，随便填就行。

安装 Keil5 MDK：一直点 Next 就行，你可以自定义安装目录，但需注意命名规范。

安装完成后先关闭软件，避免误点击弹窗，再进行下一步操作。

信息

如果之前已安装过 C51，在安装时可选择 C51 的目录，这样两个软件就可以共存了。若没有安装过，安装时最好选择默认目录，避免造成问题。

Keil 安装界面

二、安装 STM32 支持包​

启用魔法。

提示

如果不知道怎么启用魔法，直接跳过这个步骤。

打开 Keil5，点击 Pack Installer。

Pack Installer

等待列表加载完毕（时间可能较长）。

下拉列表，找到 STMicroelectronics 并展开，根据你的芯片型号点击 Install 下载对应的支持包。

安装支持包

注意

不要点击红框外的 Install，只安装 Device Specific 部分。图片中为已经安装后的场景，Up to date 表示已经安装完成。

等待安装完毕（时间可能较长）。

信息

如果使用魔法的效果不理想，可以在 Output 找到链接，复制到迅雷下载，手动安装。

安装完毕后，关闭该窗口页面，此时弹出提示框询问是否重载支持包，点击是。

重载支持包

三、使用 keygen 完成注册​

下载 注册机 并解压。

注意

浏览器可能会弹出安全警告，选择忽视即可。

关闭 Keil5，重新以管理员身份运行。

依次点击：左上角 File → License Management，复制 CID。

License Management

打开注册机。

注意

此处会响起嵌入式の小曲，可以在打开注册机前静音。

将刚刚复制的 CID 粘贴进注册机，Target 处选择对应的软件（Arm 或 C51），点击 Generate，将生成的 LIC 复制下来。

注册机界面

返回 Keil5，粘贴并添加该 LIC。

将 ST-LINK 插入电脑。

Windows 64 位：

方法一【已安装 Keil】：使用 Keil 软件目录自带驱动，一般位于 Keil5/ARM/STLink/USBDriver/dpinst_amd64.exe。目录下还有很多驱动，可以根据自己的烧录器选择。

方法二【未安装 Keil】：前往 意法半导体官网 下载。

Windows On Arm：

使用魔改版驱动：stsw-link009_v3_ARM64_UNSIGNED.zip

注意

安装前需要禁用系统驱动签名验证。你都用 WOA 了，这个应该不难吧。

或者手动在可用驱动列表中选取，将其安装为通用串行总线设备 → Win USB。

提示

安装完成后，注意检查设备管理器中 ST-LINK 一栏能否正常识别。

五、安装 USB 转串口驱动【可选】​

将 USB 转串口工具插入电脑。检查设备管理器能否读取该设备（部分转串口工具免驱）。

安装该驱动，注意只适用于 CH340：CH340Driver.zip

六、安装 Compiler Version5​

由于在 Keil 官网安装的最新版 MDK 默认使用最新版 V6 Compiler（Clang），使用 V6 编译 V5 项目时会出现大量 error。此时，你需要将项目迁移至 V6，或安装 V5。

V5 已经不再接受官方维护。你需要前往 https://developer.arm.com/documentation/ka005198/latest/ 安装 5.x 版的 Compiler，将安装路径的 bin/ 等文件夹复制至 Keil 目录下的 ARMCC/ 文件（若无，自行创建），并手动指定 Target 的编译器路径。

附：使用 CLion + CubeMX 工具链（标准库）​

Keil 还是太复杂了，有更现代化的 IDE 吗？有的，有的……

安装 Chocolatey (Choco)（若已安装，可以跳过这一步）：

以管理员身份运行 PowerShell，输入以下命令并按 Enter：

Get-ExecutionPolicy
注意

如果返回 Restricted，则需要临时更改它以允许脚本运行。如果返回 AllSigned 或 RemoteSigned 或 Unrestricted，则可以跳过以下步骤。

Set-ExecutionPolicy Bypass -Scope Process -Force

运行 Chocolatey 安装命令：

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

输入以下命令，检查是否安装成功：

choco --version

若输出显示未能识别 choco 命令，请检查在最初的安装步骤是否启用了 Powershell 的管理员身份。

安装 STM32CubeMX：参考 macOS 相应章节。

安装 CLion：参考 macOS 相应章节。

安装 OpenOCD（使用 Chocolatey）：

以管理员身份运行 PowerShell：

choco install openocd
openocd --version
# Open On-Chip Debugger 0.12.0 (2023-01-14-23:37)

查看识别情况：打开 CLion，点击齿轮图标 → 设置 → "构建、执行、部署/嵌入式开发"，点击测试 OpenOCD 和 Stm32CubeMX，若显示版本号，则已安装成功。

CLion 设置

安装交叉编译环境：

方法一【推荐】：前往官网下载 .exe 文件，然后勾选设置，将 /bin 的路径添加到系统 PATH 变量。

方法二【不推荐】：使用软件包管理器 (Chocolately) 安装（默认下载的包名为 gcc-arm-embedded，这个版本在作者的电脑会编译出错）。

安装 ST-LINK 驱动：参考上文。

配置标准库：参考 macOS 相应章节。

🍎 macOS (Arm)​

本教程使用 CLion 工具链和 HAL 库，基于 STM32F103C8T6 开发板，ST-LINK V2 调试器。

请检查自己的设备，仔细审查与本教程不一致的地方，防止烧毁芯片。

提示

由于工具链安装形式在不断更新，本教程所提供的方法不一定是当下最便捷的方法。

一、安装 Homebrew​

检查 homebrew 是否已安装。若已安装，跳过安装步骤：

brew --version

国内镜像源：

/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

一直进行下一步。如果 Git 或 XCode 下载进度缓慢，或一直查找软件，可以于官网手动安装。

拥有魔法：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git
git --version

二、安装 STM32CubeMX​

打开 https://www.st.com.cn/zh/development-tools/stm32cubemx.html

别急着下载，先注册一个账户并登陆，之后也要用到。找到产品型号 STM32CubeMX-MacA，点击获取最新版本。

三、安装 CLion​

在官网下载：CLion 或 ToolBox（方便管理 JetBrains 全家桶和软件更新）。

获得许可证：

【大学生】打开 https://www.jetbrains.com/shop/eform/classroom/faculty，填写个人资料，然后在电子邮箱中确认一个协议。申请成功后会获得一年许可证，过期后可以续期。

注意

注册时必须使用学校提供的学校邮箱，否则申请无法通过！

安装许可证：可选择在 CLion 中登陆账户，软件会自动识别账户中的许可证，或手动填写激活码。

安装简体中文插件：初次启动 CLion 可能会弹出提示询问是否安装，若没有提示，点击右上角齿轮图标 → Plugins → 搜索 Chinese，找到下载量最高的那个安装，重启 CLion 后界面为中文。

四、环境部署​

安装 OpenOCD：

brew install open-ocd

查看识别情况：打开 CLion，按下 Command + , 打开设置。找到 "构建、执行、部署/嵌入式开发"，若未显示黄色提示框，则已安装成功。

安装交叉编译环境：

brew install --cask gcc-arm-embedded
注意

不要使用以下命令安装残缺的开发环境，否则无法通过编译：

brew install arm-none-eabi-gcc arm-none-eabi-gdb
arm-none-eabi-gcc -v
arm-none-eabi-gdb -v

下载 ST-LINK 驱动：

brew install stlink

查看当前 stlink 设备（将 ST-LINK 接入电脑）：

st-info --probe

五、创建项目​

先使用 stlink 连接好开发板，方便软件自动识别。

启动 CLion，打开新建向导，选择 STM32CubeMX 项目。阅读提示，准备在 CubeMX 中配置开发板信息。

CLion 新建向导

可见底部有两个警告，我们必须消除所有警告才能创建项目。

启动 CubeMX，默认的配置可能是 STM32F030F4Px，我们需要改成自己使用的型号。

CubeMX 界面

在搜索框中搜索对应型号后，单击列表进行选择，最后点击 "Start Project"。

开始配置（如果你是从"外传"章节跳转过来的，请不要进行如下操作，回到原本的位置）：

展开左上角 System Core → RCC，将 "High Speed Clock" 从 "Disable" 修改为 "Crystal/Ceramic Resonator"（晶振）。

RCC 配置

将 Debug 从 "No Debug" 修改为 "Serial Wire"（串行线调试）。

提示

GPIO 的配置是可选的，因为可以在生成的代码中修改，这里略过。

Clock 配置

配置项目名称和路径，工具链选择 CMake。

注意

CubeMX 不支持项目名称中含有某些符号，例如 &。否则在下面的步骤中会直接卡住。若要连接单词，_ 是可用的，例如 Motherboard_LED_Flashing。注意 "Project Location" 不要选择下一级目录，否则会自动在文件夹内再新建一个文件夹。

点击右上角 GENERATE CODE 后关闭弹层。点击 Close 关闭弹层。

返回 CLion 向导，选择刚刚在 CubeMX 中创建的项目路径。可见所有警告已消失。

CLion 向导

点击继续，会自动弹出另一个向导，点击下一步。勾选顶部"重载 CMake 项目"，选择 Debug-Debug 预设文件并启用，其它配置文件不要勾选启用。点击完成。

CMake 没报错就算成功。

CMake 项目

六、配置烧录器​

右上角点击编辑配置。

编辑配置

左上角加号添加配置 OpenOCD 下载并运行，按下图配置。

面板调试文件点击辅助选择图中对应的文件，并点击复制到项目并使用。

OpenOCD 配置

在编辑器页面修改刚刚复制的 cfg 文件，删除所有未注释的内容，修改其配置：

source [find interface/stlink.cfg]
source [find target/stm32f1x.cfg]
reset_config none

七、检查配置情况​

在 main.c 里写一个点灯小程序，检测能否正常编译并烧录：

#include "main.h"
#define LED_PIN GPIO_PIN_13
#define LED_GPIO_PORT GPIOC

void SystemClock_Config(void);
static void MX_GPIO_Init(void);

int main(void)
{
  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();
  while (1)
  {
    HAL_GPIO_TogglePin(LED_GPIO_PORT, LED_PIN);  // 切换LED状态
    HAL_Delay(500);  // 延迟500毫秒
  }
}

void SystemClock_Config(void)
{
  RCC_OscInitTypeDef RCC_OscInitStruct = {0};
  RCC_ClkInitTypeDef RCC_ClkInitStruct = {0};
  RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
  RCC_OscInitStruct.HSEState = RCC_HSE_ON;
  RCC_OscInitStruct.HSEPredivValue = RCC_HSE_PREDIV_DIV1;
  RCC_OscInitStruct.HSIState = RCC_HSI_ON;
  RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
  RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
  RCC_OscInitStruct.PLL.PLLMUL = RCC_PLL_MUL9;
  if (HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK)
  {
    Error_Handler();
  }
  RCC_ClkInitStruct.ClockType = RCC_CLOCKTYPE_HCLK|RCC_CLOCKTYPE_SYSCLK
                              |RCC_CLOCKTYPE_PCLK1|RCC_CLOCKTYPE_PCLK2;
  RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
  RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1;
  RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV2;
  RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV1;
  if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_2) != HAL_OK)
  {
    Error_Handler();
  }
}

static void MX_GPIO_Init(void)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};
  __HAL_RCC_GPIOC_CLK_ENABLE();
  __HAL_RCC_GPIOD_CLK_ENABLE();
  __HAL_RCC_GPIOA_CLK_ENABLE();
  HAL_GPIO_WritePin(GPIOC, GPIO_PIN_13, GPIO_PIN_RESET);
  GPIO_InitStruct.Pin = GPIO_PIN_13;
  GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_OD;
  GPIO_InitStruct.Pull = GPIO_NOPULL;
  GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
  HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);
}

void Error_Handler(void)
{
  __disable_irq();
  while (1) {}
}

#ifdef USE_FULL_ASSERT
void assert_failed(uint8_t *file, uint32_t line) {}
#endif

外传：使用标准库​

网上的大部分配置教程都是基于 HAL 库，那我们如果想要使用标准库，该怎么配置环境呢？

如果你没有进行如上任何环境配置的操作，请从指南的第一步开始，直到完成这一步后，回到这个位置，你就完成了此处的步骤 0。

选好开发板即可，不需要进行任何配置，直接 GENERATE CODE。

在意法半导体官网下载标准库文件，点击选择系列型号，注意不要点产品选择器。

在项目文件夹中，将自动生成的大部分文件删除；整理下载好的标准库文件夹，删除部分内容例如说明和发布文档，将部分内容剪切到项目文件夹。

整理好的结构大致如下：

.
├── CMakeLists.txt
├── CMakePresets.json
├── cmake/
│   ├── gcc-arm-none-eabi.cmake
│   └── starm-clang.cmake
├── core/
│   ├── inc/
│   │   ├── main.h（使用CubeMX生成的）
│   │   ├── stm32f10x_conf.h
│   │   └── stm32f10x_it.h
│   └── src/
│       ├── main.c（删除CubeMX生成的并重写，可为空函数）
│       ├── stm32f10x_it.c
│       └── system_stm32f10x.c
├── drivers/
│   ├── cmsis/
│   │   ├── core_cm3.c / .h
│   │   ├── stm32f10x.h
│   │   └── system_stm32f10x.h
│   └── STM32F10x_StdPeriph_Driver/（直接复制过来）
│       ├── inc/（misc.h, stm32f10x_*.h ...）
│       └── src/（misc.c, stm32f10x_*.c ...）
├── linker/
│   └── STM32F103XX_FLASH.ld（CubeMX生成的）
├── startup/
│   └── startup_stm32f103xb.s（CubeMX生成的）
└── tools/
    └── openocd/
        └── stm32f103c8_blue_pill.cfg

修改 CMakeLists.txt，删除原有的所有内容，使用以下内容代替：

cmake_minimum_required(VERSION 3.22)
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_C_EXTENSIONS ON)

if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Debug)
endif()

set(CMAKE_PROJECT_NAME TEST_ENV_STD)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
project(${CMAKE_PROJECT_NAME} C ASM)

file(GLOB_RECURSE USER_SOURCES "core/src/*.c")
file(GLOB_RECURSE FW_SOURCES "drivers/STM32F10x_StdPeriph_Driver/src/*.c")
file(GLOB_RECURSE CMSIS_SOURCES "drivers/cmsis/*.c")
set(STARTUP_SCRIPT "startup/startup_stm32f103xb.s")

add_executable(${CMAKE_PROJECT_NAME}
    ${USER_SOURCES} ${FW_SOURCES} ${CMSIS_SOURCES} ${STARTUP_SCRIPT}
)

target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
    core/inc drivers/cmsis drivers/STM32F10x_StdPeriph_Driver/inc
)

target_compile_definitions(${CMAKE_PROJECT_NAME} PRIVATE
    USE_STDPERIPH_DRIVER STM32F10X_MD
)

set(LINKER_SCRIPT ${CMAKE_CURRENT_SOURCE_DIR}/linker/STM32F103XX_FLASH.ld)
target_compile_options(${CMAKE_PROJECT_NAME} PRIVATE
    -ffunction-sections -fdata-sections
)
target_link_options(${CMAKE_PROJECT_NAME} PRIVATE
    -T${LINKER_SCRIPT} -specs=nosys.specs
    -Wl,-Map=${CMAKE_PROJECT_NAME}.map -Wl,--gc-sections
)
list(REMOVE_ITEM CMAKE_C_IMPLICIT_LINK_LIBRARIES ob)

打开 cmake/gcc-arm-none-eabi.cmake，删除末尾以下内容：

set(CMAKE_EXE_LINKER_FLAGS "${TARGET_FLAGS}")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -T \"${CMAKE_SOURCE_DIR}/STM32F103XX_FLASH.ld\"")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} --specs=nano.specs")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-Map=${CMAKE_PROJECT_NAME}.map -Wl,--gc-sections")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--print-memory-usage")

修改 main.h 引入正确的头文件（原先为 HAL 库）。

修改 core_cm3.c，找到 730 行附近，按图片修改。

点击右上角小锤子图标，进行编译。无任何报错，则没有问题。

到这里全部的配置工作已经完成。如果你使用 stm32f103c8t6 开发板，这里也准备了 CLion 工程模板，直接打开即可：TEST_ENV_STD.zip

🐧 Linux (Arch)【基于标准库】​

本教程使用 CLion 工具链和标准库，基于 STM32F103C8T6 开发板，ST-LINK V2 调试器。

请检查自己的设备，仔细审查与本教程不一致的地方，防止烧毁芯片。

提示

由于工具链安装形式在不断更新，本教程所提供的方法不一定是当下最便捷的方法。

一、安装 CLion​

yay -S clion clion-jre clion-cmake
# or paru

二、安装 STM32CubeMX​

yay -S stm32cubemx
# or paru

三、安装工具链​

yay -S openocd stlink arm-none-eabi-gcc arm-none-eabi-gdb
# or paru

四、进行相应配置，或直接使用模板工程​

参考上文 macOS 五「创建项目」开始及之后的所有内容。

注意

Linux 系统文件路径严格区分大小写，使用模板工程时，需要修改 CMakeList.txt 中的头文件路径，然后重新加载 CMake 配置。否则会显示找不到头文件，无法通过编译。