【正点原子STM32连载】 第十章 STM32CubeMX简介 摘自【正点原子】STM32F103 战舰开发指南V1.2

1）实验平台：正点原子stm32f103战舰开发板V4
2）平台购买地址：https://detail.tmall.com/item.htm?id=609294757420
3）全套实验源码+手册+视频下载地址： http://www.openedv.com/thread-340252-1-1.html

第十章 STM32CubeMX简介

STM32CubeMX是由ST公司开发的图形化代码自动生成工具，能够快速生成初始化代码，如配置GPIO，时钟树，中间件等，使用户专注于业务代码的开发。现在ST主推HAL库代码，经典的标准外设库已经停止维护了，新产品也只提供HAL库的代码，因此，我们学习HAL库是更加有优势的，由于HAL库具有低耦合、通用、抽象了硬件层，使得开发者无需太过关注硬件驱动的实现，使得开发更加的简单快速，更容易维护,因此被越来越多的产品所使用。
本章将分为如下几个小节：
10.1 STM32CubeMX的作用
10.2 安装STM32CubeMX
10.3 使用STM32CubeMX新建工程
10.4 STM32CubeMX新建工程使用建议

10.1 STM32CubeMX的作用

STM32CubeMX具有如下特性：
①直观的选择MCU型号，可指定系列、封装、外设数量等条件;
②微控制器图形化配置；
③自动处理引脚冲突；
④动态设置时钟树，生成系统时钟配置代码；
⑤可以动态设置外围和中间件模式和初始化；
⑥功耗预测；
⑦C代码工程生成器覆盖了STM32微控制器初始化编译软件，如IAR，KEIL，GCC；
⑧可以独立使用或者作为Eclipse插件使用；
⑨可作为ST的固件包、芯片手册等的下载引擎；
对于STM32CubeMX和STM32Cube的关系这里我们还需要特别说明一下，STM32Cube包含STM32CubeMX图形工具和STM32Cube库两个部分，使用STM32CubeMX配置生成的代码，是基于STM32Cube库的。也就是说，我们使用STM32CubeMX配置出来的初始化代码，和STM32Cube库兼容，例如硬件抽象层代码就是使用的STM32的HAL库。不同的STM32系列芯片，会有不同的STM32Cube库支持，而STM32CubeMX图形工具只有一种。所以我们配置不同的STM32系列芯片，选择不同的STM32Cube库即可。

图10.1.1 STM32CubeMX和STM32Cube库的关系
当然，自动生成的驱动代码我们不去仔细专研其原理的话，对学习的提升很有限，而且在出现BUG的时候难以快速定位解决，因此我们也要了解其背后的原理。
10.2 安装STM32CubeMX
STM32CubeMX运行环境搭建包含两个部分。首先是Java运行环境安装，其次是STM32CubeMX软件安装。
10.2.1 安装JAVA环境
对于Java运行环境，大家可以到Java官网www.java.com下载最新的Java软件，也可以直接从我们光盘复制安装包，目录为：A盘6，软件资料1，软件3、STM32CubeMXJava安装包，Java安装包文件下有x64和x86两个文件夹，分别是64位和32位的电脑的安装包，大家根据自己电脑的位数选择即可。比如64位电脑选择x64文件夹的jre-8u301-windows-x64.exe安装包，并根据提示安装即可。安装完成之后提示界面如下图10.2.1.1所示。

图10.2.1.1 Java安装成功提示界面
安装完Java运行环境之后，为了检测是否正常安装，我们可以打开Windows的命令输入框，输入：java –version 命令，如果显示Java版本信息，则安装成功。提示信息如下图10.2.1.2：

图10.2.1.2 查看Java版本
10.2.2 安装STM32CubeMX
在安装了Java运行环境之后，接下来我们安装STM32CubeMX图形化工具。该软件可以直接从光盘复制，目录为：A盘6，软件资料1，软件STM32CubeMX，也可以直接从ST官方下载，下载地址为：https://www.st.com/en/development-tools/stm32cubemx.html。
接下来我们直接双击SetupSTM32CubeMX-6.3.0.exe，安装步骤如下。

图10.2.2.1 启动安装

图10.2.2.2 接受本许可协议

图10.2.2.3 勾选第一项即可

图10.2.2.4 指定安装路径

图10.2.2.5 创建快捷方式

图10.2.2.5 安装进度提示

图10.2.2.6 完成安装
10.3 使用STM32CubeMX新建工程
CubeMX建立的工程结构和本书介绍的代码风格有所差异，限于篇幅，本部分只介绍如何使用CubeMX生成MDK工程的方法。
10.3.1 打开STM32CubeMX
双击如图10.3.1.1所示的STM32CubeMX桌面快捷方式图标，打开后CubeMX主界面如图10.3.1.2所示。

图10.3.1.1 CubeMX快捷方式
图10.3.1.2 CubeMX主界面
10.3.2 下载和关联的STM32Cube固件包
新建工程前，我们需要先安装关联与STM32主芯片对应的STM32Cube固件包，点击Help->Manage embedded software packages，如图10.3.2.1所示。

图10.3.2.1 管理固件包
在弹出的软件包管理界面中，我们可以选择安装驱动包的方式，有以下两种方法：
方式一：从网络下载安装，按照图10.3.2.2的步骤，在该窗口找到STM32F1列表选项，因为我们的教程源码使用的固件包是1.8.3版本的，所以我们勾选1.8.3版本，等待安装完成即可。

图10.3.2.2 下载和关联STM32Cube固件包
方法二：不通过网络，直接点击从本地导入。由于直接使用上面的安装包管理器的“From Local”选项导入压缩包有时候会直接报错，比如可以直接导入“stm32cube_fw_f1_v180.zip”固件包，但直接导入“stm32cube_fw_f1_v183.zip”的安装包时CubeMX软件会报错，所以我们采用以下方法来处理：
①选择CubeMX的菜单，Help->Updater Settings，或者在CubeMX的活动窗口处于前台运行状态时使用它推荐的快捷键“Alt+S”，可以在弹出“更新设置”界面下，找到“Repository Folder”，即CubeMX的资源仓库，默认是安装在C盘的一个文件夹下，但由于CubeMX会把固件库解压到这个文件夹下，在我们使用的STM32型号多了或者经过一段时间的更新使用后，这个文件夹常常会变得非常大（数十Gb）。所以我们这里把默认的路径设置为“D:\STM32Cube\Repository”，但使用自定义路径时CubeMX关联的路径一定不能有中文出现，大家根据自己的需要决定是否设置。操作方法如图10.3.2.3和图10.3.2.4所示。

图10.3.2.3 设置更新选项

图10.3.2.4 修改CubeMX的固件库路径（非必须）
②我们复制光盘提供的固件包，把它放到上一步我们设置或者找到的CubeMX的仓库文件夹。光盘资料路径为：A盘 8，STM32参考资料 1，STM32CubeF1固件包，我们这里要使用的是CubeF1固件的1.8.3版本。由于CubeF1的1.8.3版本是1.8.0版本的补充包，所以需要把“stm32cube_fw_f1_v180.zip”和“stm32cube_fw_f1_v183.zip”两个固件包都复制到对应的路径下。复制后目录CubeMX的仓库目录的状况如图10.3.2.4所示。

图10.3.2.4 复制固件包到CubeMX对应的仓库路径
③先解压“stm32cube_fw_f1_v180.zip”到当前仓库路径的根路径，注意这里解压缩后的第一级目录就是压缩包下的目录，如图10.3.2.5所示。

图10.3.2.5 先解压“stm32cube_fw_f1_v180.zip”
④接着解压“stm32cube_fw_f1_v183.zip”到当前仓库路径的根路径，这里打开压缩包可以发现CubeF1的1.8.3版本固件压缩包下的文件夹与1.8.0的完全相同，我们解压缩并替换文件为1.8.3中的文件。解压后路径下仍只有一个“STM32Cube_FW_F1_V1.8.0”文件夹。

图10.3.2.6 解压“stm32cube_fw_f1_v183.zip”，并替换原有文件
⑤关闭CubeMX软件并重启。重启后通过CubeMX的安装包管理器，可以发现CubeMX已经检测到安装好了对应的驱动库。至此离线安装步骤结束。

图10.3.2.7 成功离线安装CubeF1的1.8.3版本固件库
10.3.3 新建工程
通过上一步安装固件库后，我们就可以使用STM32CubeMX配置工程，步骤如下：

1. 工程初步建立
2. HSE和LSE时钟源设置
3. 时钟系统（时钟树）配置
4. GPIO功能引脚配置
5. 配置Debug选项
6. 生成工程源码
7. 用户程序
   接下来我们将按照上述步骤，和大家一起使用STM32CubeMX工具生成一个MDK工程，如果之前还没有安装过MDK的，请先按教程关于MDK安装和介绍部分的内容先安装好软件。
   1 工程初步建立
   方法一：依次点击“File->New Project”即可建新工程。如果之前打开过的话，左侧最近打开的过程一列会有打开的工程列表，直接点击这些工程也可以打开。
   方法二：直接点击ACCESS TO MCU SELECTOR。
   具体操作如图10.3.3.1所示。
   

图10.3.3.1 新建工程
点击新建工程后，可能会弹出如图10.3.3.2的窗口，提示需要联网下载一些文件，可能等待时间比较长，可以直接选择取消即可。我们可以通过关闭自动更新设置来禁止弹出这个窗口。

图10.3.3.2 启动时联网更新检测
之后都可以进入芯片选型界面，如图10.3.3.3所示。

图10.3.3.3 芯片选型界面
选择具体的芯片型号，如图10.3.3.4所示。

图10.3.3.4 选择具体的芯片型号
鼠标双击选择的芯片型号后，弹出主设计界面，如图10.3.3.5所示。

图10.3.3.5 主设计界面
2 HSE和LSE时钟源设置
进入工程主设计界面后，首先设置时钟源HSE和LSE。如图10.3.3.6所示。

图10.3.3.6 设置时钟源HSE和LSE
图10.3.3.6中的标号④和⑤，我们都选择了Crystal/Ceramic Resonator，表示外部晶振作为它们的时钟源。我们开发板的外部高速晶振和外部低速晶振分别是：8MHZ和32.768KHZ，所以HSE时钟频率就是8MHZ，LSE时钟频率就是32.768KHZ。
选项Master Clock Output 1 用来选择是否使能MCO1引脚时钟输出。
3 时钟系统（时钟树）配置
点击Clock Configuration选项卡即可进入时钟系统配置栏，如下图10.3.3.7所示：

图10.3.3.7 时钟系统配置栏
进入Clock Configuration配置栏之后可以看到，界面展现一个完整的STM32F1时钟系统框图。从这个时钟树配置图可以看出，配置的主要是外部晶振大小，分频系数，倍频系数以及选择器。在我们配置的工程中，时钟值会动态更新，如果某个时钟值在配置过程中超过允许值，那么相应的选项框会红色提示。
这里，我们将配置一个以HSE为时钟源，配置PLL相关参数，然后系统时钟选择PLLCLK为时钟源，最终配置系统时钟为72MHz的过程。同时，还配置了AHB，APB1，APB和Systick的相关分频系数。由于图片比较大，我们把主要的配置部分分两部分来讲解，第一部分是配置系统时钟，第二部分是配置SYSTICK、AHB、APB1和APB2的分频系数。首先我们来看看第一部分配置如下图10.3.3.8所示：

图10.3.3.8 系统时钟配置图
我们把系统时钟配置分为七个步骤，分别用标号1~5表示，详细过程为：
① 时钟源参数设置：我们选择HSE为时钟源，所以我们要根据硬件实际的高速晶振频率（这里我们是8MHZ）填写。
② 时钟源选择：我们配置选择器选择HSE即可。
③ PLL倍频系数PLLMUL配置。倍频系数PLLMUL我们设置为9。
④ 系统时钟时钟源选择：PLL,HSI还是HSE。我们选择PLL，选择器选择PLLCLK即可。
⑤ 经过上面配置以后此时SYSCLK=72MHz。
经过上面的5个步骤，就配置好STM32F1的系统时钟为72MHz。接下来我们还需要配置AHB、APB1、APB2和Systick的分频系数，为STM32的片上外设或M3内核设置对应的工作时钟，为后续使用这些硬件功能做好准备。配置如下图10.3.3.9所示：

图10.3.3.9 AHB、APB1、APB2、APB3和APB4总线时钟配置
AHB、APB1和APB2总线时钟以及Systick时钟的来源于系统时钟SYSCLK。其中AHB总线时钟HCLK由SYSCLK经过AHB预分频器之后得到，如果我们要设置HCLK为72MHz(最大为72Mhz)，那么我们只需要配置图中标号⑥的地方为1即可。得到HCLK之后，接下来我们将在图标号⑦~⑨处同样的方法依次配置Systick、APB1和APB分频系数分别为1、2和1。注意！systick固定为72MHz，配置完成之后，那么HCLK=72MHZ，Systic=72MHz，PCLK1=36MHz，PCLK2=72MHz，这和之前例程配置的时钟是主频一样的。
以上方法是手动计算的方法，是为了帮助我们更好地去认识STM32时钟的配置方法，当然CubeMX也提供了更简单的方法：在图10.3.3.9的“HCLK(MHz)”位置，实际上是可以编辑的。我们直接输入我们要的主频，这里是72Mzh，按回车键，CubeMX会帮我们提供一种设置主频和其它时钟的建议，选择是后会由软件自动配置好，当然只有启用外部的晶振后才能配置到72Mhz的时钟，这里大家自己尝试一下就清楚了，我们不展开讲述了。
4 GPIO功能引脚配置
本小节，我们讲解怎么使用STM32CubeMX工具配置STM32F1的GPIO口。STM32F103 战舰开发板的PB5和PE5引脚各连接一个LED灯，我们来学习配置这两个IO口的相关参数。这里我们回到STM32CubeMX的Pinout&Configuration选项，在搜索栏输入PB5后回车，可以在引脚图中显示位置，如下图10.3.3.10所示：

图10.3.3.10 搜索引脚位置
接下来，我们在图10.3.3.11引脚图中点击PB5，在弹出的下拉菜单中，选择IO口的功能为GPIO_Output。操作方法如下图10.3.3.11所示：

图10.3.3.11 配置GPIO模式
同样的方法，我们配置PE5选择功能为GPIO_Oput即可。设置好即可看到引脚从灰色变成绿色，标识该管脚已经启用。这里我们需要说明一下，如果我们要配置IO口为外部中断引脚或者其他复用功能，我们选择相应的选项即可。配置完IO口功能之后，还要配置IO口的速度，上下拉等参数。这些参数我们通过System Core下的GPIO选项进行配置，如图10.3.3.12所示。

图10.3.3.12 GPIO选项
我们先配置PB5，PE5和PB5配置方法一样的。点击图10.3.3.12的④号框里面的PB5，配置如图10.3.3.13所示。

图10.3.3.13 配置GPIO口详细参数
GPIO output level是IO的初始值，由于LED一端接VCC，另一端接GPIO，故要点亮LED灯时，使GPIO输出低电平即可。为了一开始让LED灯熄灭，我们设置初始值输出高电平。
GPIO mode我们已经在视图中配置为推挽输出了，这里不需要修改。
GPIO Pull-up/Pull-down默认是无上下拉，我们这里用默认配置。
Maximum output speed输出速度配置，默认是低速，我们设置为高速。
User Label用户符号，我们可以给PB5起一个别的名字LED0。
PE5也是按照这样的方法配置即可。
5 配置Debug选项
由于CubeMX默认把Debug选项关闭了，这样会给我们带来麻烦：用CubeMX生成的工程编译下载一次后，后续再次下载就会提示错误，因此我们要把Debug选项打开。这里有多种选择，我们设置成图10.3.3.14所示的情况即可。

图10.3.3.14 打开Debug选项
如果已经不小心关闭了Debug选项，那么下次下载的时候按住复位键，等到工程提示的时候松开复位键即可，因为STM32的芯片默认复位上电时的Debug引脚功能是开启的。
6 生成工程源码
接下来我们学习怎么设置生成一个工程，如图10.3.3.15所示。选择Project Manager-> Project选项用来配置工程的选项，我们了解一下里面的信息。
Project Name：工程名称，填入工程名称（半角，不能有中文字符）
Project Location：工程保存路径，点击Browse选择保存的位置（半角，不能有中文字符）
Toolchain Folder Location:工具链文件夹位置，默认即可。
Application Structure：应用的结构，选择Basic（基础），不勾选Do not generate the main(),因为我们要其生成main函数。
Toolchain/IDE:工具链/集成开发环境，我们使用Keil，因此选择MDK-ARM，Min Version选择V5.27，这里根据CubeMX的版本可能会有差异，我们默认使用V5以上的版本即可。
Linker Settings 链接器设置：
Minimum Heap Size 最小堆大小，默认（大工程需按需调整）。
Minimum Stack Size 最小栈大小，默认（大工程需按需调整）。
MCU and Firmware Package是MCU及固件包设置：
MCU Reference：目标MCU系列名称。
Firmware Package Name and Version：固件包名称及版本。
勾选Use Default Firmware Location，文本框里面的路径就是固件包的存储地址，我们使用默认地址即可。（这里因为我有两个版本的固件包，所以它默认使用最新的，这个关系不大，就用新的）。这样工程生成的设置就设置好了，如图10.3.3.15所示。

图10.3.3.15 工程配置
打开Project Manager-> Code Generator选项，Generated files 生成文件选项，勾选Generate peripheral initialization as a pair of ‘.c/.h’files per peripheral，勾选这个选项的话将会将每个外设单独分开成一组.c、.h文件，使得代码结构更加的清晰，如图10.3.3.16所示。

图10.3.3.16 代码生成器设置
由于CubeMX默认勾选了复制所有的库，即工程中不使用到的代码也会复制进来，为了节省CubeMX生成工程的空间，我们勾选生成工程时只复制用到的库（这一步是可选操作，大家根据自己的实际选择），如图图10.3.3.17所示：

图10.3.3.17 设置只复制与工程相关的库驱动以减小工程大小
至此工程最基础配置就已经完成，点击蓝色按钮(SENERATE CODE)就可以生成工程。

图10.3.3.18 生成工程
如果我们的CubeMX工程放置配置路径中没有中文。生成代码后会弹出类似图10.3.3.19的提示窗口，点击Open Project就打开MDK工程（如果是中文路径则会报错，这里暂时不用管，我们先往下继续操作）。

图10.3.3.19 打开工程
完整的STM32F1工程就已经生成完成。生成后的工程目录结构如下图10.3.3.20所示：

图10.3.3.20 STM32CubeMX生成的工程目录结构
Drivers文件夹存放的是HAL库文件和CMSIS相关文件。
Inc文件夹存放的是工程必须的部分头文件。
MDK-ARM下面存放的是MDK工程文件。
Src文件夹下面存放的是工程必须的部分源文件。
Template.ioc是STM32CubeMX工程文件，双击该文件就会在STM32CubeMX中打开。
7 用户程序
在编写用户程序之前，首先我们打开生成的工程模板进行编译，因为我们在之前步骤生成的CubeMX工程为LED_TEST.ioc，故生成的MDK工程位置是.\MDK-ARM\LED_TEST.uvprojx，如果大家配置的CubeMX的工程名和路径名不含中文或中文字符，按上述步骤生成的工程就可以直接编译通过了。

图10.3.3.21 STM32CubeMX生成的MDK工程编译通过
接下来我们中生成的工程模板的main.c文件中找到main函数，这里我们删掉了源码注释，关键源码如下：

int main(void)
{
HAL_Init();
  SystemClock_config();
  MX_GPIO_Init();
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    /* USER CODE END WHILE */
  }
}

大家需要注意，STM32CubeMX生成的main.c文件中，有很多地方有“/* USER CODE BEGIN X /”和“/ USER CODE END X */”格式的注释，我们在这些注释的BEGIN和END之间编写代码，那么重新生成工程之后，这些代码会保留而不会被覆盖。
我们编写一个跑马灯的用户程序，程序具体如下：

/**
  * @brief  The application entry point.
  * @retval int
  */
int main(void)
{
  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();
  /* USER CODE BEGIN WHILE */
  while (1)
  {
    HAL_GPIO_WritePin(LED0_GPIO_Port, LED0_Pin, GPIO_PIN_SET); 
    HAL_GPIO_WritePin(LED1_GPIO_Port, LED1_Pin, GPIO_PIN_RESET); 
    HAL_Delay(500);
    HAL_GPIO_WritePin(LED0_GPIO_Port, LED0_Pin, GPIO_PIN_RESET);
    HAL_GPIO_WritePin(LED1_GPIO_Port, LED1_Pin, GPIO_PIN_SET); 
    HAL_Delay(500);
    /* USER CODE END WHILE */
  }
}

编写好程序后，编译没有任何警告和错误。可以直接下载程序到开发板中，使用DAP下载，请注意设置MDK的下载选项，如果不清楚设置的读者可以回看本书第四章的相关知识点。下载后，可以看到LED0和LED1同时按500ms的频率亮灭，效果与其它版本的新建工程相同。
本小节使用STM32CubeMX新建的工程模板在我们光盘目录：“4，程序源码\2，标准例程-HAL库版本\实验0 基础入门实验\实验0-4，新建工程实验-CubeMX版本”中有存放，大家在编写用户代码过程中可以参考该工程的main.c文件。
10.4 STM32CubeMX新建工程使用建议
① 使用CubeMX的环境搭建工程，工程文件夹路径、文件名不要带任何中文及中文字符，否则会遇到各种报错；
② 本书以新建工程-HAL库版本为基准来展开，不对CubeMX的使用过多讲解。使用CubeMX可以帮助我们快速搭建工程，使用户专注于应用开发，但STM32的开发与硬件密切相关，对STM32开发来说，抛开底层只专注做应用并不实际，毕竟无法使用一套通用设计来满足不同用户的需求；
③ 关于新建CubeMX的工程路径中有中文的情况的解决：
如果我们配置的CubeMX工程路径里面有中文可能会报以下的错误（再次强调，CubeMX的关联路径、文件名不要有中文出现）：

图10.4.1 直接编译报错
造成错误的原因是CubeMX对中文的支持不友好，且生成MDK工程默认通过工程中的CMSIS那个绿色的控件选择启动文件而不是直接添加启动文件（startup_xxx.s）到我们的工程中，而中文路径时就会找不到，有两个解决办法：
1、用CubeMX生成的工程不要放置在包含中文路径的文件夹下；
2、添加启动文件到我们的工程中，我们新建一个application/MDK-ARM分组，把startup_stm32f103xe.s添加到这个分组，如图10.3.3.22所示：

图10.4.2 STM32CubeMX生成的工程目录结构
④ 关于配置的文件CubeMX工程(.ioc后缀)名字有中文的情况，我们建议重新新建工程或者把生成的工程文件重命名为英文。因为带中文的CubeMX工程生成的MDK的Output目录有中文，MDK也会报错，尽管可以重新设置MDK工程的Output目录和添加③所描述步骤的启动文件，使本次编译通过，但下次重新用CubeMX生成工程时，仍旧需要重复修改配置。