氵工的博客

校区2 录取名单多维度分析报告

Sun, 21 Jun 2026 16:40:00 GMT

校区 2 录取名单多维度分析报告

2 个专业 · 37 名报考考生 · 32 名录取 · 初试四科拆解 + 复试综合分析

数据校验

光电信息工程： 报考 19 人，录取 17 人，初试名单中有复试成绩的 17 人与录取名单 17 人完全匹配。

仪器仪表工程： 报考 18 人，录取 15 人。初试名单中有复试成绩的 15 人中，有一位考生的复试总分存在微小差异（a.xlsx 记录为 364.72，ss.xlsx 记录为 394.72），可能是数据录入笔误，建议核实。其余 14 人完全匹配。

未录取考生共 5 人（仪器仪表 3 人、光电信息 2 人），均为初试名单中有记录但无复试总分。

一、核心指标汇总

专业	报考	录取	录取率	政治均分	英语均分	数学均分	专业课均分	初试均分	初试标准差	初试最高	初试最低
仪器仪表工程	18	15	83.3%	56.9	78.2	120.0	117.8	372.9	25.7	424	344
光电信息工程	19	17	89.5%	54.8	74.2	110.9	120.4	360.3	27.8	404	320

二、各科目成绩分布箱线图

箱线图展示中位数、四分位距和极端值。箱体越窄说明成绩越集中。

要点：

仪器仪表工程的数学中位数明显高于光电信息工程（约 125 vs 110），但离散度也更大
光电信息工程的专业课整体偏高，中位数约 125 分
两个专业的政治和英语分布较为接近

三、各科目均分对比

要点：

仪器仪表工程的数学均分（120.0）比光电信息工程（110.9）高出近 10 分
光电信息工程的专业课均分（120.4）略高于仪器仪表工程（117.8）
政治和英语两科差异不大，政治仪器仪表略高、英语仪器仪表也略高
总体来看，仪器仪表工程初试均分更高（372.9 vs 360.3），主要由数学拉开差距

四、各专业综合实力雷达图

将各维度归一化后对比，面积越大代表综合实力越强。

要点：

仪器仪表工程在数学和英语维度上明显领先
光电信息工程在专业课维度上稍有优势
两者政治水平接近

五、各科成绩分布直方图

要点：

政治成绩两个专业都集中在 50-65 分区间
英语集中在 70-85 分
数学分布范围最广（74-145），是拉开差距的关键科目
专业课集中在 105-135 区间
数学的标准差最大，是区分考生水平的核心科目

六、各科成绩堆叠柱状图

每位考生的四科成绩堆叠展示，按初试总分降序排列，× 标记未录取考生。

要点：

可以直观看出数学和专业课是初试总分的最大贡献项
未录取考生（×标记）往往出现在初试总分较低的区间，但也有个别初试成绩不低却未录取的情况（可能复试表现不佳）

七、初试各科占比分析

要点：

两个专业的科目占比结构非常相似——数学和专业课各占约 31-32%，是初试的两大支柱
英语占约 20-21%
政治占比最小，仅约 15%
这意味着数学和专业课是决定初试排名最重要的科目

八、各科目相关系数热力图

颜色越绿表示正相关越强，越红表示负相关越强。

要点：

数学与初试总分的相关性最高（约 0.78），再次印证数学是拉分关键
专业课与总分的相关性也较强（约 0.69）
政治和英语与总分的相关性较弱
值得注意的是，数学与专业课呈中等正相关（约 0.3），说明数学好的考生专业课往往也不差

九、初试总分 vs 复试总分散点图

每个点代表一名录取考生，× 代表未录取考生（仅有初试成绩）。

要点：

整体呈正相关趋势——初试分高的考生复试总分也倾向于更高
但散布程度较大，说明复试确实能显著改变排名
光电信息工程中出现了一些初试分不高但复试总分较高的案例（逆袭者）

十、初试分数段人数分布

浅色柱表示所有报考考生，深色柱表示最终录取考生。

要点：

仪器仪表工程在 390-410 高分段录取率 100%
370-390 分段是竞争最激烈的区间
光电信息工程的分布更加均匀，从 320 到 404 都有录取，低分段（320-330）也有考生成功录取（可能复试逆袭）

十一、初试/复试对总成绩的贡献占比

基于公式 总成绩 ≈ 初试×0.5 + 复试×2.5 推算。

要点：

两个专业的初试和复试贡献占比非常接近（初试约 48-50%，复试约 50-52%），复试权重略高
说明在这个校区，复试表现对最终录取的影响与初试几乎同等重要，甚至略占上风

十二、复试”逆袭”分析

绿色=复试后排名提升，红色=复试后排名下降。

要点：

仪器仪表工程中有考生排名变化幅度达 5 位以上，复试逆袭空间较大
光电信息工程的排名变化相对温和，多数在±3 名以内，初试高分的”护城河”更稳固

十三、推算复试成绩分布

假设 总成绩 = 初试×0.5 + 复试×2.5，反推复试面试得分。

要点：

推算的复试成绩集中在 78-90 分区间
仪器仪表工程复试均值约 84 分，光电信息工程复试均值约 84 分，两者非常接近
复试分数分布相对集中，区分度不如初试大

十四、录取 vs 未录取考生各科对比

要点：

由于未录取样本量较小（各 2-3 人），统计意义有限
但可以观察到：未录取考生并非所有科目都弱，往往是个别科目（尤其是数学或专业课）拖了后腿

综合分析结论

1. 数学是拉分之王

数学与初试总分相关性最高（~0.78），标准差最大，是决定初试排名的核心科目。仪器仪表工程数学均分（120.0）显著高于光电信息（110.9），直接拉开了初试差距。

2. 专业课紧随其后

专业课与总分相关性约 0.69，是第二大拉分科目。光电信息工程的专业课均分（120.4）略高于仪器仪表（117.8）。

3. 政治英语是”稳定器”

政治和英语的分数区间窄、标准差小，很难靠这两科拉开差距，但如果严重偏低会成为短板。

4. 复试权重与初试相当甚至略高

复试对总成绩的贡献约 50-52%，说明复试表现至关重要。仪器仪表工程的复试逆袭空间更大，排名变动幅度可达 5 位以上。

5. 录取率较高

仪器仪表工程录取率 83.3%（15/18），光电信息工程录取率 89.5%（17/19），整体录取率较高，竞争烈度中等。

6. 备考建议

如果目标是仪器仪表工程，应重点攻克数学（拉开差距）同时保证专业课不拖后腿
如果目标是光电信息工程，数学同样是关键，但专业课也很重要，需要均衡发展
复试准备不可忽视，尤其是仪器仪表工程方向

7. 与另一校区对比

该校区仅有 2 个专业（vs 另一校区 4 个专业），招生规模更小（32 人 vs 94 人），但数据结构相似——复试占比均在 50%以上，体现了统一的录取评价体系。

本报告由 Python + matplotlib 自动生成

录取名单多维度分析报告

Sun, 21 Jun 2026 07:30:00 GMT

录取名单多维度分析报告

4 个专业 · 94 名录取考生 · 初试/复试/总成绩全面拆解

数据概览

本报告基于录取名单中 4 个专业的 94 名考生数据（已排除 1 名强军计划考生）进行分析。

经回归验证，总成绩计算公式为：总成绩 = 初试 × 0.5 + 复试 × 2.5，即初试和复试各占总成绩的 50%。

“仪器科学技术”（1 人）已合并入”仪器科学与技术”（16 人），共 17 人。

专业	录取人数	初试均分	复试均分	总均分	初试占比	复试占比
光学工程	30	376.7	81.7	392.6	48.0%	52.0%
光电信息工程	31	400.5	81.0	402.8	49.7%	50.3%
仪器科学与技术	17	353.6	78.2	372.4	47.5%	52.5%
仪器仪表工程	15	382.9	81.1	394.3	48.6%	51.4%

一、各专业成绩分布箱线图

箱线图展示了三个维度的分数分布。箱体越窄说明成绩越集中，须线越长说明极端值越多。

要点：

光电信息工程初试分数跨度最大（372~439），复试分布也最分散
光学工程和仪器仪表工程的初试和复试分布都相对集中
仪器科学与技术的初试标准差最大（24.4 分），说明该专业录取考生的初试水平差异最为悬殊

二、成绩密度分布曲线（KDE）

核密度估计图能更直观地看出各专业分数的”集中地带”和”多峰”现象。

要点：

光电信息工程的初试成绩明显偏向高分段（集中在 390~410），形成了”高分密集”的特征
仪器科学与技术的初试密度曲线偏向低分段（340~360 区间），峰值明显左移
复试方面各专业分布较为接近，但仪器科学与技术的复试密度峰值也略低于其他专业

三、初试 vs 复试散点图

每个点代表一名考生，虚线为等总成绩线。位于图上方的考生复试表现相对更强，位于右侧的考生初试更强。

要点：

光电信息工程的考生散布在更高初试分数段（右侧），其中一位初试 439 分的考生极为突出
仪器科学与技术则集中在左下方（初试相对较低）
各专业的星号（均值点）显示初试和复试成绩之间并没有强烈的线性关系，说明复试成绩并非初试的简单”复制”

四、初试/复试对总成绩的贡献占比

由于公式是 初试×0.5 + 复试×2.5，初试满分 250、复试满分 250，权重相等。但实际录取考生的初试/复试比例因人而异。

要点：

所有专业的初试占比在 47.5%~49.7% 之间，复试占比 50.3%~52.5%，差异非常小
仪器科学与技术的复试占比最高（52.5%），说明该专业录取考生的复试表现在总成绩中贡献更大——如果复试发挥好，在总排名中更有优势
光电信息工程初试占比最高（49.7%），初试高分考生更占优势

五、各专业初试/复试成绩直方图

将复试成绩×5 对齐到初试的 500 分制进行对比。虚线为各专业均值。

要点：

光学工程的初试分布呈近似正态，集中在 365~385 区间
光电信息工程则明显右偏，高分考生占比大
仪器科学与技术的初试分布最”扁平”，低分段和高分段都有人
仪器仪表工程虽然人数最少，但初试集中在 370~400 区间，较为均匀

六、初试分数段人数对比

将初试成绩分段，对比各专业在不同分数段的人数分布。

要点：

390~410 分段是”黄金区间”，光电信息工程在此段人数最多
410+高分段几乎只有光电信息工程
仪器科学与技术主要集中在 330~370 的中低分段
光学工程则均匀分布在 350~410 区间

七、各专业综合实力雷达图

综合初试均分、复试均分、总均分、成绩集中度、录取规模等维度进行归一化对比。

要点：

光电信息工程在初试均分、总均分上明显领先，面积最大
光学工程在复试均分上表现最好
仪器科学与技术各维度均处于较低水平，但录取人数（17 人）在四个专业中排第三
仪器仪表工程的各项指标处于中间水平

八、复试”逆袭”分析

横向条形图展示每位考生因复试表现导致的排名变化。绿色=复试后排名提升，红色=排名下降。

要点：

仪器科学与技术的排名变化幅度最大，有考生的排名提升或下降了 7-8 位，说明复试对该专业的最终录取排名影响最大
光电信息工程的排名变化相对小，初试高分考生的”护城河”更深

九、初试排名 vs 最终排名变化

对角线表示初试排名=最终排名（复试没有改变排名）。绿色区域=复试后排名提升，红色=下降。

要点：

如果蓝点大幅偏离对角线，说明复试显著改变了排名
仪器科学与技术中排名变化最剧烈，部分初试排名靠后的考生通过复试”翻盘”进入了前列

十、复试翻盘率

定义”翻盘”为最终排名比初试排名提升 ≥ 3 名。翻盘率越高，说明复试对最终结果的影响越大。

要点：

仪器科学与技术的翻盘率最高，复试改变命运的概率最大
光电信息工程翻盘率最低，初试高分考生优势稳固，复试难以大幅改变排名

十一、成绩离散度与竞争强度

变异系数(CV)衡量分数的相对分散程度；极差(最高-最低)反映录取考生的分差。

要点：

仪器科学与技术的初试变异系数和极差都最大（初试极差达 88 分），说明该专业录取门槛相对灵活，高低分差距大
光电信息工程的复试极差较小（14.7 分），复试打分相对集中、区分度有限

十二、核心指标汇总表

综合分析结论

1. 初试与复试权重

从公式上看，初试和复试各占 50%，但实际效果因专业而异：

光电信息工程的初试均分最高（400.5），初试优势更难被复试翻盘
仪器科学与技术初试均分最低（353.6），复试对排名的影响最大

2. 光电信息工程：“初试为王”

该专业录取考生的初试分数段极高（均分 400.5），初试占比也最大（49.7%），且翻盘率最低。如果你初试能拿到 400+，在该专业的优势非常稳固。

3. 仪器科学与技术：“复试决胜”

该专业初试均分最低但复试翻盘率最高，成绩分布最分散，说明复试发挥对最终录取至关重要。初试不理想但复试出色的考生有机会逆袭。

4. 光学工程：“均衡稳定”

初试和复试分布都较为集中和均匀，没有明显的偏科特征，竞争相对公平和可预测。

5. 仪器仪表工程：“中间路线”

各项指标处于中等水平，初试集中度高（标准差 14.6），复试表现中等，整体波动较小。

6. 整体趋势

四个专业的复试占比均在 50%~52.5%之间，说明复试成绩在实际录取中的权重略高于初试（因为复试满分 100×2.5=250，而大多数考生初试在 350-410 之间，×0.5 后只有 175-205 分，复试的边际影响力更大）。

本报告由 Python + matplotlib 自动生成

STM32N657X0H3Q Nucleo VSCode Debug Configuration Guide

Mon, 08 Jun 2026 03:39:51 GMT

STM32N657X0H3Q Nucleo VSCode Debug Configuration Guide

Problem Recap

In the previous article, I covered the complete workflow of compiling, signing, and flashing via STM32 Programmer. In LRUN mode, both FSBL and Application can be flashed independently and run correctly. However, one critical issue remained — source-level debugging in VSCode was not working.

When starting a debug session, the program would break at a library function around RETR=Map Memory. According to ST Community forum tutorials, this breakpoint should allow single-step debugging as usual — but in practice, the debugger disconnected from the board shortly after hitting the break, and the session terminated.

Initially, I suspected TrustZone security domain configuration — perhaps RIF resource isolation was preventing the debugger from accessing the secure state. After systematic troubleshooting, this possibility was ruled out.

Root Cause Analysis

A careful inspection of launch.json revealed the root cause: the stldr file configuration was wrong.

I’m using the New Clone board (NUCLEO-N657X0-Q), but the configuration mistakenly referenced settings for the DK board (STM32N6570-DK). The stldr (External Loader) file acts as the bridge between the debugger and external Flash. An incorrect loader means the debugger can’t properly access external memory, causing the connection to fail.

launch.json Configuration Breakdown

After fixing the stldr configuration, other settings were also adjusted. Here’s the complete configuration with field explanations:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "stlinkgdbtarget",          // Debugger type: ST-Link GDB target
            "request": "launch",
            "name": "NUCLEO-N657X0-Q Debug (FSBL + Appli)",
            "origin": "snippet",
            "cwd": "${workspaceFolder}",
            "preBuild": "${command:st-stm32-ide-debug-launch.build}",   // Build command
            "runEntry": "BOOT_Application",                             // Entry function name
            // SVD file path (replace the path prefix with your actual STM32CubeProgrammer installation directory)
            "svdPath": "...\\STM32CubeProgrammer\\SVD\\STM32N657.svd",
            "imagesAndSymbols": [
                {
                    // Application image: symbol for source mapping, image for flashing
                    "symbolFileName": "${workspaceFolder}/Appli/build/Template_FSBL_LRUN_Appli.elf",
                    "imageFileName": "${workspaceFolder}/Appli/build/Appli-trusted.elf"
                },
                {
                    // FSBL image: both point to the same ELF (FSBL doesn't need a separate trusted file)
                    "symbolFileName": "${workspaceFolder}/FSBL/build/Template_FSBL_LRUN_FSBL.elf",
                    "imageFileName": "${workspaceFolder}/FSBL/build/Template_FSBL_LRUN_FSBL.elf"
                }
            ],
            "serverExtLoader": [
                {
                    // External Loader: NUCLEO-N657X0-Q stldr file (New Clone board, NOT DK board)
                    "loader": "...\\STM32CubeProgrammer\\bin\\ExternalLoader\\MX25UM51245G_STM32N6570-NUCLEO.stldr",
                    "initialize": false
                }
            ]
        }
    ]
}

Path Note: The ...\\STM32CubeProgrammer\\ prefix above represents STM32CubeProgrammer’s installation directory. Replace it with your actual path, such as C:\\Program Files\\STMicroelectronics\\STM32Cube\\STM32CubeProgrammer\\ or your custom directory.

Key Configuration Fields

Field	Purpose	Notes
`runEntry`	Debugger entry function	LRUN mode on NUCLEO-N657X0-Q must be `BOOT_Application`
`svdPath`	SVD file path providing peripheral register descriptions	Point to the SVD folder under STM32CubeProgrammer
`symbolFileName`	ELF symbol file for source-level debugging	Must match compiled binary path
`imageFileName`	Flash image	Appli uses `Appli-trusted.elf` (signed), FSBL uses the compiled `.elf` directly
`serverExtLoader`	External Flash loader configuration	Make sure to select the stldr matching your board

Configuration Insights

FSBL vs Appli ELF Configuration

There’s an important distinction between FSBL and Application image configuration:

FSBL: Both symbolFileName and imageFileName point to the same .elf file, because FSBL uses the compiled ELF directly for both debugging and signing
Application: symbolFileName points to the compiled ELF (with debug symbols), while imageFileName points to Appli-trusted.elf (the signed image)

This is because the Application needs to be signed (with a V2.3 Header) to be recognized by Boot ROM or FSBL, while debugging requires the original unstripped ELF for source-code mapping.

Signing File Notes

The naming convention for signing artifacts was also somewhat confusing in the original configuration. Key distinction:

.elf — Compiler-generated ELF with debug symbols
-trusted.elf — Image file post-signing, with Header added
-trusted.bin — Pure binary post-signing, with Header added

Application uses Appli-trusted.elf as its image file, while FSBL doesn’t require a separate trusted version.

Debug Workflow Summary

With the corrected configuration, the complete VSCode debug workflow is:

Ensure BOOT1 = 2-3 (DEV mode)
In VSCode, select the NUCLEO-N657X0-Q Debug (FSBL + Appli) configuration
Set breakpoints in Application code
Press F5 to start debugging
FSBL runs automatically → loads Appli into SRAM → jumps to execution → breakpoints hit

Pitfall Summary

Symptom	Possible Cause	Solution
Debug connection drops immediately	stldr mismatch (DK vs New Clone board)	Check and fix `serverExtLoader` stldr path
Breakpoint hits library function then exits	Security domain blocking debugger	Check RIF configuration for debug permissions
`Appli-trusted.elf` not found	Signed image not generated post-build	Verify CMake POST_BUILD signing script
Can’t single-step in debug	Symbol file path incorrect	Confirm `symbolFileName` points to the correct `.elf` file

STM32N657X0H3Q Nucleo Development Board Debug Log

Sat, 06 Jun 2026 16:00:00 GMT

STM32N657X0H3Q Nucleo Development Board Debug Log

This board is ridiculous — TrustZone, FSBL, OTP… why is everything so complicated?

1. Debugging Journey

First Attempt: SRAM Mode

Following the familiar F1 and F4 workflow, I configured the project in CubeMX and loaded it into VS Code for debugging. Surprisingly, debugging actually worked.

But it wouldn’t run standalone — after a Reset, the code just disappeared. Looking back, this was because I was using SRAM mode: the code was loaded directly into SRAM for debugging. The benefit was being able to see results and debug in real-time, but the problem was that the code wasn’t actually being stored anywhere. Storing code requires writing it to Flash, which means configuring the XSPI interface.

Pitfall: The NUCLEO-N657X0-Q has no internal Flash. Code must be stored in external XSPI Flash. When debugging in SRAM mode, power loss means code loss — this explains why the code “disappeared” after Reset.

XSPI + XIP Mode Attempt

XIP stands for Execute In Place — the program runs directly from external Nor Flash without copying to SRAM. XSPI (eXtended SPI) is ST’s serial peripheral interface protocol for communicating with external Flash. The configuration process is quite involved.

I attempted the XSPI approach but got nowhere. Problems kept piling up — flashing and debugging both threw errors. The official forum post was configured for the DK board, and I’m not sure if there are differences between DK and the NUCLEO board, so I gave up.

Pitfall: XIP mode configuration is extremely complex, requiring:

Memory-Mapped Mode configuration so the CPU can access external Flash via bus

External Flash .stldr loader file (STM32CubeProgrammer needs the correct External Loader)

Correct linker script (STM32N657XX_ROMxspi*.ld)

-align parameter when signing

The DK board (Development Kit) and NUCLEO board may have different configurations. Official tutorials target the DK board, so many settings don’t apply to NUCLEO.

LRUN Mode: Success

LRUN (Load and Run) uses FSBL + Application working together. FSBL initializes the system and copies the Application code to SRAM. My understanding: the PC pointer is transferred to Application just before entering the infinite loop. So the infinite loop never executes. I placed the LED blink before the infinite loop, before entering Application.

Then things went smoothly — compile and flash. After compilation, sign the binaries, then flash each one separately. Theoretically you should flash FSBL first, then Application. But in practice, the onboard program should already be in LRUN mode, so flashing either one works fine. It’s just a matter of FSBL pointers — Application is its own program, no real difference.

One important note: when flashing, you need to select the external memory settings — that .stldr file. Select the one matching this board, then proceed. When flashing, I got a “Core locked” popup. Previously it showed “Write Protection PROTECTION” — not sure why.

Pitfall: “Core locked” or “Write Protection PROTECTION” during flashing is usually an Option Bytes issue. Try:

Hold Reset while flashing

Use Mass Erase to erase the entire chip

Check BOOT jumpers are correctly set (DEV mode: BOOT1 = 2-3)

Also, you need to load the correct External Loader (.stldr file) in CubeProgrammer before flashing, otherwise external Flash won’t be recognized.

2. Hardware Platform & Key Concepts

2.1 Chip & Development Board

Chip: STM32N657X0H3QU
Board: NUCLEO-N657X0-Q (MB1940)
Architecture: ARM Cortex-M55 with Helium (MVE) + TrustZone
Clock: 600 MHz
Flash: No internal Flash, relies on external XSPI Nor Flash
RAM: 2MB AXISRAM (0x3400_0000 ~ 0x3420_0000)

STM32N6 differs from F1/F4 series in several key ways:

No internal Flash: Code must be stored in external XSPI Flash
TrustZone: Secure and Non-Secure worlds are isolated, requiring proper RIF configuration
Dual-domain architecture: Secure and Non-Secure domains are separate
OTP Fuses: One-time programmable fuses for high-speed mode configuration
FSBL mechanism: First Stage Boot Loader

2.2 LED Pins

Color	Pin	Note
Green LED	PG.00 (LED_GREEN)	Appli main loop control
Blue LED	PG.08 (LED_BLUE)	Appli main loop control
Red LED	PG.10 (LED_RED)	FSBL debug indicator

Correction: Previous notes listed PG.08 as yellow, but it’s actually blue (LED_BLUE). The silkscreen on NUCLEO-N657X0-Q matches the BSP definition.

2.3 Boot Mode (Boot Pin)

The board has 3 Boot pin positions (headers 1, 2, 3), selected via jumpers:

Boot Pin Configuration

Pin	Headers 1-2 Short	Headers 2-3 Short
BOOT0	0 (Low)	1 (High)
BOOT1	0 (Low)	1 (High)

Boot Modes

Mode	BOOT0	BOOT1	Description
DEV (Debug)	Any (0 or 1)	1 (Headers 2-3)	IDE loads program to RAM, source-level debugging
Boot from Flash	0 (Headers 1-2)	0 (Headers 1-2)	Boot from external XSPI Flash, standalone
Reserved	1	0	Reserved
System ROM	0	0	Built-in chip ROM (rarely used)

Note: In DEV mode, BOOT0 can be anything, only BOOT1 = 1 is required (jumper on 2-3).

2.4 Boot ROM Startup Sequence

After power-on, the STM32N6 Boot ROM searches for bootable code in this order:

Order	Address	Description
1	`0x7000 0000`	Primary: External XSPI Flash (FSBL or headered program)
2	Internal ROM	Factory-installed BootLoader (if any)
3	RAM	If nothing else found, try booting from RAM

Note: Address 0x7000 0000 is the mirror start address of external Flash. Physical Flash is accessed via XSPI interface. Only signed programs at this address are recognized by Boot ROM.

2.5 Glossary

Abbr.	Full Name	Meaning
LRUN	Load & Run	Code copied from external Flash to internal RAM for execution
XIP	eXecute In Place	Code executes directly from external Flash, no RAM copy
XSPI	eXtended SPI	ST’s serial peripheral interface protocol for external Flash communication
FSBL	First Stage Boot Loader	First-stage bootloader
OTP	One-Time Programmable	One-time programmable fuses

2.6 Linker Script Naming Convention

Format: ROM_location_RUN_RAM_location

Linker Script	Meaning
`STM32N657XX_LRUN`	Appli in internal RAM (loaded by FSBL)
`STM32N657XX_ROMxspi1`	Appli in external XSPI1 Flash, execute in place
`STM32N657XX_ROMxspi2`	Appli in external XSPI2 Flash, execute in place
`STM32N657XX_LRUN_RAMxspi2`	Appli in RAM, loaded from XSPI2 Flash
`STM32N657XX_ROMxspi1_RAMxspi3`	Appli in XSPI1, RAM in XSPI3

3. FSBL Load & Run Mode

3.1 Architecture Overview

FSBL LRUN mode divides the system into two independent subprojects:

Subproject	Responsibility	Execution Location
FSBL	Initialize OTP, configure XSPI2, read/copy Appli, jump	Internal RAM (0x3400_0000)
Appli	User application, controls LEDs and peripherals	Internal RAM (0x3400_0400)

3.2 FSBL Code Analysis

FSBL core code in FSBL/Src/main.c:

int main(void)
{
    SCB_EnableICache();
    SCB_EnableDCache();
    HAL_Init();
    SystemClock_Config();  // Configure 600MHz system clock

    // OTP configuration (required on first flash)
#ifndef NO_OTP_FUSE
    if(OTP_Config() != 0){
        Error_Handler();
    }
#endif

    MX_GPIO_Init(); // Initialize LED (PG.10)
    MX_XSPI2_Init(); // Initialize XSPI2 interface
    MX_EXTMEM_Init();
    BOOT_Application();   // Copy Appli to RAM and jump

    while (1) { __NOP(); }  // Never reaches here
}

FSBL execution flow:

Enable caches: ICache + DCache
Configure clock: 600MHz
OTP configuration: Set VDDIO3_HSLV fuse (only needed on first flash)
Initialize GPIO: Configure LED pin PG.10 (debug)
Initialize XSPI2: Communicate with external Flash
Initialize external memory: MX_EXTMEM_Init()
Jump to execution: BOOT_Application() copies Appli to RAM and jumps

3.3 OTP Configuration Details

OTP_Config() configures VDDIO3_HSLV fuse bits:

#define BSEC_HW_CONFIG_ID    124U
#define BSEC_HWS_HSLV_VDDIO3 (1U<<15)  // VDDIO3 high-speed mode enable

⚠️ Warning: OTP fuses are one-time write, irreversible. Confirm before configuring. Disable NO_OTP_FUSE macro on first flash.

3.4 Appli Code Analysis

Appli code in Appli/Src/main.c:

int main(void)
{
    SystemCoreClockUpdate();
    MPU_Config();
    SCB_EnableICache();
    SCB_EnableDCache();
    HAL_Init();
    BSP_LED_Init(LED_GREEN);
    SystemIsolation_Config();  // Configure RIF resource isolation
    MX_GPIO_Init();

    while (1)
    {
        HAL_GPIO_TogglePin(GPIOG, GPIO_PIN_0);  // Green LED
        HAL_GPIO_TogglePin(GPIOG, GPIO_PIN_8);  // Blue LED
        HAL_Delay(750);
    }
}

SystemIsolation_Config() configures TrustZone resource isolation:

static void SystemIsolation_Config(void)
{
    __HAL_RCC_RIFSC_CLK_ENABLE();
    HAL_GPIO_ConfigPinAttributes(GPIOG, GPIO_PIN_0, GPIO_PIN_SEC|GPIO_PIN_NPRIV);
    HAL_GPIO_ConfigPinAttributes(GPIOG, GPIO_PIN_8, GPIO_PIN_SEC|GPIO_PIN_NPRIV);
    HAL_GPIO_ConfigPinAttributes(GPIOG, GPIO_PIN_10, GPIO_PIN_SEC|GPIO_PIN_NPRIV);
}

3.5 Skip FSBL and Run Appli Directly

You can skip FSBL and flash Appli directly if any of these conditions are met:

OTP already configured (VDDIO3_HSLV set)
Chip has built-in FSBL at 0x7000 0000
Boot ROM supports direct loading from 0x7010 0000

Steps:

Sign Appli: Appli-trusted.bin
Flash to 0x7010 0000
Reset, chip boots from external Flash

Pitfall: If the chip has no built-in FSBL and Boot ROM doesn’t support direct loading, skipping FSBL will cause the chip to not find executable code and hang.

4. Build Configuration

4.1 Toolchain

Tool	Path
GCC ARM Compiler	`C:\Users\Q\AppData\Local\stm32cube\bundles\gnu-tools-for-stm32\14.3.1+st.2`
STM32Cube Firmware	`C:\Users\Q\STM32Cube\Repository\STM32Cube_FW_N6_V1.3.0\`
Signing Tool	`C:\APPS\Programmer\bin\STM32_SigningTool_CLI.exe`

4.2 Build Commands

cd build/Debug
cube-cmake --build . --target clean
cube-cmake --build . --target all

4.3 CMake POST_BUILD Configuration (Auto-Signing)

find_program(OBJCOPY arm-none-eabi-objcopy PATHS
    C:/Users/Q/AppData/Local/stm32cube/bundles/gnu-tools-for-stm32/14.3.1+st.2/bin
    NO_DEFAULT_PATH
)

add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
    COMMAND ${OBJCOPY} -O binary $<TARGET_FILE:${CMAKE_PROJECT_NAME}> 
            ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin
    COMMENT "Generating binary"
)

add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
    COMMAND ${OBJCOPY} -O ihex $<TARGET_FILE:${CMAKE_PROJECT_NAME}> 
            ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.hex
    COMMENT "Generating HEX"
)

# Auto-signing (runs automatically after build, no manual signing needed)
find_program(SIGNING_TOOL C:/APPS/Programmer/bin/STM32_SigningTool_CLI.exe)
add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
    COMMAND ${SIGNING_TOOL} -bin ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin 
            -nk -of 0x80000000 -t fsbl
            -o ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}-trusted.bin 
            -hv 2.3 -align -s
    COMMENT "Signing ${CMAKE_PROJECT_NAME}.bin"
)

4.4 NO_OTP_FUSE Macro Configuration

FSBL build macros in FSBL/mx-generated.cmake:

set(MX_Defines_Syms 
    USE_HAL_DRIVER 
    STM32N657xx 
    NO_OTP_FUSE # Comment this out to enable OTP configuration
)

Configuration	Description
Disable `NO_OTP_FUSE`	Required on first flash, FSBL will auto-configure OTP fuses
Enable `NO_OTP_FUSE`	For development, skip OTP configuration

4.5 Build Outputs

File	Location
FSBL.elf / .bin / .hex	`FSBL/build/Template_FSBL_LRUN_FSBL.*`
Appli.elf / .bin / .hex	`Appli/build/Template_FSBL_LRUN_Appli.*`
FSBL-trusted.bin	`FSBL/build/Template_FSBL_LRUN_FSBL-trusted.bin`
Appli-trusted.bin	`Appli/build/Template_FSBL_LRUN_Appli-trusted.bin`

5. Signing & Flashing

5.1 Why Signing is Required

STM32N6’s external Flash stores critical firmware. The chip’s Boot ROM only loads images with correctly signed Headers. The signing tool adds a V2.3 format header to the .bin file.

5.2 Manual Signing Commands

# Appli signing
& "C:\APPS\Programmer\bin\STM32_SigningTool_CLI.exe" `
    -bin "C:\APPS\COPRO\MCU\CUBEMX\N6_MX\Template_FSBL_LRUN\Appli\build\Template_FSBL_LRUN_Appli.bin" `
    -nk -of 0x80000000 -t fsbl `
    -o "C:\APPS\COPRO\MCU\CUBEMX\N6_MX\Template_FSBL_LRUN\Appli\build\Template_FSBL_LRUN_Appli-trusted.bin" `
    -hv 2.3 -align -s

# FSBL signing
& "C:\APPS\Programmer\bin\STM32_SigningTool_CLI.exe" `
    -bin "C:\APPS\COPRO\MCU\CUBEMX\N6_MX\Template_FSBL_LRUN\FSBL\build\Template_FSBL_LRUN_FSBL.bin" `
    -nk -of 0x80000000 -t fsbl `
    -o "C:\APPS\COPRO\MCU\CUBEMX\N6_MX\Template_FSBL_LRUN\FSBL\build\Template_FSBL_LRUN_FSBL-trusted.bin" `
    -hv 2.3 -align -s

5.3 Signing Parameter Reference

Parameter	Description
`-bin`	Input .bin file path
`-nk`	No Key, development mode, no actual signature verification
`-of 0x80000000`	Option flags address offset
`-t fsbl`	Binary type: FSBL type
`-hv 2.3`	Header version (N6 requires 2.3)
`-align`	Required, payload aligned to 0x400
`-s`	Silent mode, no overwrite confirmation popup

5.4 Flash Addresses

File	Address
`Appli-trusted.bin`	`0x7010_0000`
`FSBL-trusted.bin`	`0x7000_0000` (optional)

5.5 Post-Flash Behavior

Stage	Behavior
FSBL initialization	Red LED (PG.10) blinks 3 times
Jump to Appli	Green (PG.00) and Blue (PG.08) LEDs blink alternately

5.6 External Loader (.stldr)

When flashing external XSPI Flash, CubeProgrammer needs the corresponding External Loader file:

Board	Loader File
NUCLEO-N657X0-Q	`NUCLEO_N657X0_Q.stldr` (usually in CubeProgrammer installation directory)

Location: Usually at C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\ExternalLoader\.

Pitfall: Without loading the correct .stldr file, CubeProgrammer cannot recognize external Flash, causing errors or failure to write during flashing.

6. Debugging Methods

6.1 DEV Mode Debugging (Recommended)

Set BOOT1 = 2-3 (DEV mode)
IDE loads FSBL/build/Template_FSBL_LRUN_FSBL.elf to RAM
Set breakpoints in Appli code
Debug/Run
FSBL runs → loads Appli → breakpoints hit

6.2 Flash Mode

No source-level debugging possible. Rely on LED / UART / ITM.

7. Project File Structure

Template_FSBL_LRUN/
├── CLAUDE.md              # Project documentation
├── SKILL.md              # Skill documentation
├── README.md              # Official documentation
├── Template_FSBL_LRUN.ioc # CubeMX configuration
│
├── FSBL/                  # FSBL subproject
│   ├── Src/
│   │   ├── main.c         # FSBL main program
│   │   ├── extmem.c       # External memory initialization
│   ├── Inc/
│   │   ├── main.h
│   │   └── extmem.h
│   ├── mx-generated.cmake # Build macros
│   ├── CMakeLists.txt
│   └── STM32N657XX_LRUN.ld
│
├── Appli/                 # Appli subproject
│   ├── Src/
│   │   ├── main.c # Appli main program
│   ├── Inc/
│   │   ├── main.h
│   │   └── stm32n6xx_nucleo_conf.h
│   ├── mx-generated.cmake
│   ├── CMakeLists.txt
│   └── STM32N657XX_LRUN.ld
│
├── Drivers/               # HAL drivers (in-project)
├── Secure_nsclib/          # Secure/non-secure call library
├── gcc-arm-none-eabi.cmake # Toolchain configuration
└── mx-generated.cmake       # Main CMake configuration

8. References

ST Official Community Posts

ST Official PDFs

rm0486 — STM32N657xx ARM-based 32-bit MCUs
um3234 — How to proceed with Boot ROM on STM32N6 MCUs
an6265 — Getting started with STM32N6 MCUs in STM32CubeIDE
an5967 — Getting started with hardware development for STM32N6 MCUs
um3249 — Getting started with STM32CubeN6 for STM32N6 series
pm0273 — STM32 Cortex-M55 MCUs Programming Manual
Nucleo-N657X0-Q Schematic (en.mb1940-n657x0q-c02-schematic)
um3417 — STM32N6 Nucleo144 board MB1940

9. Quick Troubleshooting Guide

Symptom	Possible Cause	Solution
Flash error “Core locked”	Option Bytes locked	Hold Reset while flashing, or Mass Erase
Flash error “Write protection”	Read protection RDP enabled	Use Mass Erase
Flash mode not running	Missing `-align` in signature	Re-sign with `-align`
Flash mode not running	OTP not configured	On first flash, disable NO_OTP_FUSE so FSBL configures OTP
Chip unresponsive	Debugger disconnected	Press Reset, reconnect
Breakpoints not hitting in debug	Using Flash mode	Switch to DEV mode, BOOT1=2-3
No .bin file after build	CMakeLists.txt missing post-build	Add objcopy commands
Signing “binary not found”	PowerShell quoting issue	Use `& "..."` or run in CMD

STM32 SimpleFOC Position Servo: From Zero to Stable, Full Record of 2 Hard Bug Fixes

Mon, 01 Jun 2026 02:30:00 GMT

1. Project Background

Building a FOC position servo system from scratch using STM32F103C8T6 (Blue Pill) to drive a 2804 gimbal motor.

The “from scratch” here doesn’t start from the SimpleFOC library — it starts from CubeMX-generated HAL code, with hand-written FOC core algorithm, PID controller, encoder driver, and serial command parsing. The entire development cycle took about two weeks, with debugging taking 80% of the time.

End result: motor holds position rock-solid, pushed two turns and released, it returns along the same path. PID parameters adjustable online with no transient spikes. Behind this: 2 real bug localizations and fixes — plus records of several “thought this was the root cause” false leads.

Hardware Architecture

STM32F103C8T6 (72MHz)
├── TIM1 CH1/CH2/CH3 (PA8/PA9/PA10) → SimpleFOC Mini IN1/IN2/IN3
├── PA11 GPIO OUT → SimpleFOC Mini ENABLE
├── I2C1 PB8(SCL) / PB9(SDA) → AS5600 magnetic encoder (0x36)
├── USART1 PB6(TX) / PB7(RX) → USB-TTL (115200 8N1)
└── TIM2 (1098Hz interrupt) → Control loop tick

MCU: STM32F103C8T6, 72MHz, 64KB Flash, 20KB RAM
Driver: SimpleFOC Mini (3-phase half-bridge)
Encoder: AS5600 12-bit magnetic encoder (I2C interface)
Motor: 2804 gimbal motor, 12-slot 14-pole (7 pole pairs), low resistance

Software Architecture

main loop (110Hz)
  ├─ TIM2 interrupt → foc_tick flag
  ├─ Sensor read → AS5600 (software I2C)
  ├─ Angle unwrapping → single-turn absolute → cumulative angle
  ├─ PID control → D-on-measurement + low-pass filter
  ├─ SVPWM → three-phase sine wave (center-aligned PWM)
  └─ UART command parsing → ? T90 Kp0.1 ...

2. False Lead: Hardware I2C Freeze?

Symptom

Motor runs normally for 30~60 seconds, then suddenly “loses power” — encoder reading freezes at a certain value, rotating the motor by hand produces no corrective torque, and auto-print stops. Recovery after power cycle, repeats after running for a while.

Investigation

D command (encoder diagnostics) showed a different value than the ? status command during one failure — ? reported Raw=1445, D reported Raw=4030. Ruled out encoder hardware fault.
I2C error count stayed at 0 — HAL didn’t report errors, but returned stale register values, suggesting the I2C peripheral may have entered a “fake success” state.
Checking STM32F103 Errata: I2C peripheral can freeze in BUSY state under specific bus timing conditions, software cannot recover via normal means, only peripheral reset works.

Attempted Fix

// When readings stay unchanged for 100 consecutive times, try resetting I2C peripheral
__HAL_RCC_I2C1_FORCE_RESET();
__HAL_RCC_I2C1_RELEASE_RESET();
HAL_I2C_Init(&hi2c1);

Result

After switching to software I2C, the problem persisted. The real root cause was later found to be uint16_t tick overflow — after fixing that, everything stabilized. The software I2C changes were kept (more reliable), but I2C itself was not the root cause of this symptom.

Lesson: One symptom can have multiple “suspects.” Fixing A doesn’t mean you fixed it. When you can’t confirm the root cause, look for the most directly reproducible clue first (time pattern).

3. False Lead: PID Positive Feedback?

Symptom

After power-on, motor doesn’t hold position, rotates continuously. Sending T90 causes motor to accelerate instead of stopping.

Investigation

Checked PID setpoint/measurement parameter passing — logic seemed possibly wrong.

Result

Actual code inspection revealed PID sign parameters were not inverted — this wasn’t a real bug. The real cause of the symptom was also uint16_t tick overflow — the control loop wasn’t running at all.

Lesson: Without trace tools, it’s easy to interpret “not running” as “running wrong.” First confirm whether code is actually executing, then analyze runtime behavior.

4. False Lead: Stack Overflow?

Symptom

Motor “dies” every few tens of seconds — auto-print stops, motor 吸附在磁极位 (stuck at magnetic pole position), serial commands unresponsive.

Investigation

Checked stack size: _Min_Stack_Size = 0x400 (only 1KB) in STM32F103XX_FLASH.ld
snprintf + %f pulls in _printf_float, single call chain stack consumption >700 bytes
Tried expanding stack to 2KB + changing large buffers to static

Result

Problem persisted after changes. Real root cause was still uint16_t tick overflow.

Lesson: In embedded, snprintf + %f does eat stack, but that wasn’t the issue here. Hypothesis + fix + verify — don’t keep trusting a fix that isn’t working.

5. Bug #1 — uint16_t Tick Overflow + C Integer Promotion Trap

This is the bug that actually solved the problem. After fixing it, the system ran stably.

Symptom

Motor “freezes” every ~60 seconds — auto-print stops, motor unresponsive, but serial commands still work. Observed tick_count wrapping from 65535 back to 0 (uint16_t overflow), exactly matching the failure timestamps.

Root Cause Analysis

This is an obscure bug caused by C language Integer Promotion rules:

volatile uint16_t tick_count = 0;
static uint16_t last_ctrl_tick = 65530;

// What you see:
if (tick_count - last_ctrl_tick >= 10)

// What the compiler actually generates:
// uint16_t - uint16_t → promoted to signed int (32-bit)
if ((int)tick_count - (int)last_ctrl_tick >= 10)
//  When tick_count wraps to 0:
//  (int)0 - (int)65530 = -65530
//  -65530 >= 10 ? → false → control update never fires!

C11 Standard §6.3.1.1: when uint16_t (narrower than int) participates in arithmetic, it’s first promoted to int (signed). The unsigned wrap-around behavior is destroyed during promotion.

This is a very subtle bug — the code logic looks correct (unsigned subtraction naturally wraps), but the compiler turns it into signed arithmetic, producing a negative number on overflow, making the comparison 永远不成立 (never true).

Fix

Change tick_count and related variables to uint32_t:

volatile uint32_t tick_count = 0;       // Overflows in 49 days, won't trigger during runtime
static uint32_t last_ctrl_tick = 0;
static uint32_t print_tick = 0;

On 32-bit ARM, uint32_t = unsigned int, same rank as signed int. C standard’s “usual arithmetic conversions” specify unsigned wins when ranks are equal, so uint32_t - uint32_t stays in unsigned domain. This is the principle fix — not just delaying overflow, but ensuring subtraction always happens in unsigned domain.

Lesson: In embedded C, subtraction of uint8_t and uint16_t is unreliable — either cast strongly (uint16_t)(a - b), or use uint32_t directly. This bug took two days to locate at the compiler level. Confirmed effective fix: change uint16_t to uint32_t.

6. Bug #2 — PID_Reset D Term Velocity Spike

This bug is real too — it causes transient shock when adjusting PID parameters.

Symptom

Sending kp0 (set Kp to 0) via serial, motor suddenly kicks hard and flies out. After that, even restoring Kp, the motor has drifted to an unknown position.

Root Cause

PID_Reset clears prev_measurement to zero. In the next control cycle:

velocity = (measurement - 0) / 0.009s
         = (155° - 0°) / 0.009s
         = 17,200°/s

D_out = -Kd × 300 →瞬间饱和 → motor gets kicked by 40% duty cycle

Fix: Sentinel Value

#define PID_MEAS_UNINIT (-1e10f)  // Legal angle 0~2π can never be here

void PID_Init(...) {
    pid->prev_measurement = PID_MEAS_UNINIT;
}

void PID_Reset(...) {
    pid->integral = 0.0f;
    pid->prev_measurement = PID_MEAS_UNINIT;  // Sentinel
    // deriv_filtered not cleared, first frame D skipped, re-accumulate from zero
}

float PID_Update(...) {
    if (pid->prev_measurement < -1e9f) {
        // First frame → skip D, just record current value
        pid->prev_measurement = measurement;
        D_out = 0.0f;
    } else {
        // Normal D calculation
    }
}

Effect: No transient shock when adjusting PID parameters.

Lesson: Reset functions cannot blindly zero everything. Any stateful variable must use a sentinel value to mark “uninitialized” state during Reset.

7. Lessons Summary

#	Issue	Category	Conclusion
1	I2C BUSY	False lead	Changed to software I2C, but root cause was uint16_t overflow
2	PID sign	False lead	Parameters actually not inverted; real cause was control loop not running
3	Stack overflow	False lead	Expanded stack, but root cause was still uint16_t overflow
4	uint16_t integer promotion	Real bug	Confirmed fix: change to uint32_t
5	PID Reset D spike	Real bug	Confirmed fix: sentinel value

Both real bugs were traced to root cause and fixed. The three “suspects” were actually symptoms’ side effects rather than root causes — when uint16_t overflow caused the control loop to stop, all “control not working” manifestations were mistakenly thought to have independent root causes.

Not finding the root cause means not truly fixed. The same symptom may have multiple people shouting about it, but you can only trust the first (most timely) clue — time patterns are the best debug information.

Full source code: GitHub - simpleFOC_1

Delta Parallel Robot — Building a Kinematics Library from Scratch

Thu, 14 May 2026 23:00:00 GMT

Recently I finished writing the kinematics library for a Delta parallel robot. Let me record the process and key data.

Mechanical Parameters

Parameter	Value	Description
Rb	115 mm	Static platform radius (center to motor shaft)
Re	75 mm	Moving platform radius (center to ball joint, 150/2)
L1	125 mm	Driving arm (big arm) length
L2	338 mm	Passive arm (small arm/rod) length

Core Kinematics

Inverse Kinematics (IK)

Given end-effector position (x, y, z), find three motor angles θ₁, θ₂, θ₃.

For each leg, transform the problem to a local coordinate system, simplifying to planar 2R linkage inverse kinematics:

x_local·sin(θ) - z_local·cos(θ) = (d² + L1² - L2²) / (2·L1)

Solution:

θ = φ + π/2 + α

where φ = atan2(z_local, x_local), α = acos((L1² + d² - L2²) / (2·L1·d)).

Key detail: The projection of the passive arm outside the rotation plane needs to be processed as effective length L2_eff = sqrt(L2² - y_local²).

Forward Kinematics (FK)

Given θ₁, θ₂, θ₃, find end-effector position. Use Newton iteration to solve for the three-sphere intersection point, converging to error < 1e-6 mm.

MATLAB Verification Results

Verified IK→FK consistency in MATLAB, error is 0.0000 mm at all test points.

Workspace

Scanned with 20mm grid, total 5928 reachable points:

Z (mm)	Max Radius (mm)
-460	14
-440	103
-400	192
-360	247
-300 ~ -200	247
-100	247

The workspace is dome-shaped, Z range approximately -460 ~ -100 mm, maximum horizontal radius approximately 250mm.

Code Organization

deltarobot/
├── inc/
│   ├── delta_common.h        → vectors, angles, utilities
│   ├── delta_param.h         → mechanical parameter struct
│   ├── delta_kinematics.h    → IK/FK/Jacobian
│   ├── delta_trajectory.h    → trajectory planning (interpolation + S-curve)
│   └── delta_control.h       → three-axis coordinated control interface
├── src/
│   ├── delta_kinematics.cpp
│   ├── delta_trajectory.cpp
│   └── delta_control.cpp
├── scripts/
│   ├── verify_delta.m         → kinematics verification + workspace calculation
│   └── workspace.m            → workspace visualization
└── README.md

Next Steps

Run IK calculation on STM32F407
Cooperate with stepper motors DRV8825/TMC2209 for open-loop position control
Later add encoder for closed-loop

STM32 Library Design Notes 2

Wed, 13 May 2026 16:05:13 GMT

Stage 1: Newbie Village - Hardcoding

Scenario

We have a small car chassis control program that needs to control two DC motors.

Code

// Beginner approach: write specific operations each time
void main(void) {
    // Left wheel forward
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 500);

    HAL_Delay(1000);

    // Right wheel forward
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, 500);

    HAL_Delay(1000);

    // Stop left wheel
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 0);

    // Stop right wheel
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, 0);
}

Problems

Code duplication: Each operation requires writing a bunch of register/library function calls
Not portable: Changing MCU requires modifying all files
Unreadable: Looking at the code, you can’t tell it’s “controlling motors”, only that it’s “operating GPIO and PWM”
Hard to maintain: To change motor logic, you need to find all the places it’s called

Core Pain Point

Business logic (making the car go forward) is mixed with hardware operations (pulling GPIO high, writing PWM)

Stage 2: Function Encapsulation (Gathering Repeated Code)

Concept

Package hardware operations into functions; upper layers call function names without looking at internal implementation.

Code

// motor_hw.c - Hardware operation encapsulation
void motor_left_forward(uint16_t speed) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, speed);
}

void motor_left_stop(void) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 0);
}

void motor_right_forward(uint16_t speed) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, speed);
}

void motor_right_stop(void) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, 0);
}

// main.c - Business logic becomes clearer
void main(void) {
    motor_left_forward(500);
    motor_right_forward(500);
    HAL_Delay(1000);
    motor_left_stop();
    motor_right_stop();
}

Advantages

Improved code readability
Hardware operations concentrated in one file, changing MCU only requires modifying this file

New Problems

Function proliferation: Each action gets its own function (turn left, turn right, forward, backward, with acceleration…), function count explodes
Inconsistent parameters: Some functions use uint16_t speed, others use float duty
Poor extensibility: Adding a new motor requires writing 4 new functions

Stage 3: Parameter-Driven (Using Parameters Instead of Function Names)

Concept

Don’t write separate functions for each action; instead, write one “generic function” and use parameters to distinguish actions.

Code

// Use one function instead of multiple
void motor_control(uint8_t id, uint8_t action, int16_t speed) {
    switch(id) {
        case 0:  // Left wheel
            if (action == FORWARD) {
                HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);
                __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, speed);
            } else if (action == STOP) {
                HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
                __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 0);
            }
            break;
        case 1:  // Right wheel
            // Similar...
            break;
    }
}

// Usage
motor_control(0, FORWARD, 500);
motor_control(1, FORWARD, 500);
HAL_Delay(1000);
motor_control(0, STOP, 0);
motor_control(1, STOP, 0);

Advantages

Function count reduced from motor_count × action_count to 1
Adding new actions only requires adding case, no new functions needed

New Problems

Too many parameters: Want to support acceleration? Add parameter uint8_t accel; want to support direction? Add parameter uint8_t dir… parameter list keeps growing
Type unsafe: Passing wrong value for action parameter (passing 255 instead of FORWARD), compiler doesn’t complain
Poor readability: What does motor_control(0, 1, 500) mean? Need to check documentation or function definition

Evolution: Using Struct for Parameter Passing

// Pack multiple parameters into one struct
typedef struct {
    uint8_t motor_id;      // 0=left wheel, 1=right wheel
    uint8_t action;        // FORWARD, BACKWARD, STOP
    int16_t speed;         // -1000 ~ 1000
    uint8_t accel_rate;    // 0-10
    uint32_t duration_ms;  // Duration
} MotorCommand_t;

void motor_control(MotorCommand_t* cmd) {
    // Execute based on fields in cmd
}

// Usage
MotorCommand_t cmd = {.motor_id=0, .action=FORWARD, .speed=500, .accel_rate=5, .duration_ms=1000};
motor_control(&cmd);

Advantages

Clear parameters with field names
Adding parameters only requires modifying the struct, not the function signature

Stage 4: State Machine + Non-Blocking (Letting the CPU Do Other Things)

Problem

Previous approaches are all blocking: HAL_Delay(1000) makes the CPU wait idly for 1 second, doing nothing.

Concept

Turn “waiting” into “periodic checking”: each call does only a small step, then returns. Main loop continuously calls until complete.

Code

typedef struct {
    int16_t target_speed;
    int16_t current_speed;
    uint32_t start_time;
    uint32_t duration;
    uint8_t is_active;
} MotorState_t;

MotorState_t motors[2];

void motor_start(uint8_t id, int16_t speed, uint32_t ms) {
    motors[id].target_speed = speed;
    motors[id].duration = ms;
    motors[id].start_time = get_tick_ms();  // Get current time
    motors[id].is_active = 1;
}

void motor_update(void) {
    for (int i = 0; i < 2; i++) {
        if (!motors[i].is_active) continue;

        uint32_t elapsed = get_tick_ms() - motors[i].start_time;

        if (elapsed >= motors[i].duration) {
            // Time's up, stop
            motors[i].is_active = 0;
            set_pwm(i, 0);
        } else {
            // Still running
            set_pwm(i, motors[i].target_speed);
        }
    }
}

// Main loop (non-blocking)
void main(void) {
    motor_start(0, 500, 1000);  // Left wheel runs for 1 second
    motor_start(1, 500, 1000);  // Right wheel runs for 1 second

    while (1) {
        motor_update();  // Call every 10ms

        // During these 10ms间隙, can do other things
        read_sensors();
        check_emergency();

        delay_ms(10);
    }
}

Core Changes

Blocking	Non-Blocking
`HAL_Delay(1000)`	`motor_start(..., 1000)` + main loop polling
CPU idles for 1 second	CPU checks every 10ms, works on other things the rest of the time
Can only execute actions sequentially	Can handle multiple tasks simultaneously

Stage 5: Struct Encapsulation for Multiple Instances (Preparing for Polymorphism)

Problem

Currently each motor is global state; adding a new motor requires manual copy-paste of code.

Concept

Package motor-related data and methods into a struct, operate via pointers.

Code

// Motor "class"
typedef struct Motor_t {
    // Properties (data)
    int16_t target_speed;
    int16_t current_speed;
    uint32_t start_time;
    uint32_t duration;
    uint8_t is_active;
    uint8_t id;

    // Methods (function pointers)
    void (*start)(struct Motor_t* self, int16_t speed, uint32_t ms);
    void (*update)(struct Motor_t* self);
} Motor_t;

// Method implementations
void motor_start_impl(Motor_t* self, int16_t speed, uint32_t ms) {
    self->target_speed = speed;
    self->duration = ms;
    self->start_time = get_tick_ms();
    self->is_active = 1;
}

void motor_update_impl(Motor_t* self) {
    if (!self->is_active) return;

    if (get_tick_ms() - self->start_time >= self->duration) {
        self->is_active = 0;
        set_pwm(self->id, 0);
    } else {
        set_pwm(self->id, self->target_speed);
    }
}

// Create instances
Motor_t left_motor = {
    .id = 0,
    .start = motor_start_impl,
    .update = motor_update_impl,
};

Motor_t right_motor = {
    .id = 1,
    .start = motor_start_impl,
    .update = motor_update_impl,
};

// Usage
void main(void) {
    left_motor.start(&left_motor, 500, 1000);
    right_motor.start(&right_motor, 500, 1000);

    while (1) {
        left_motor.update(&left_motor);
        right_motor.update(&right_motor);
        delay_ms(10);
    }
}

Key Point: `self` Pointer

Each method’s first parameter is self, pointing to the instance that called it. This allows the same motor_update_impl function to operate on different motor data.

Stage 6: Hardware Abstraction (Changing MCU Without Modifying Upper Layer Code)

Problem

Currently set_pwm() function still directly calls HAL library; changing MCU requires modifying this function’s internals.

Concept

Abstract hardware operations into an operations table (function pointer collection); upper layers only call the operations table, not HAL directly.

Code

// Hardware operations table (abstraction layer)
typedef struct {
    void (*pwm_set)(uint8_t channel, uint16_t duty);
    uint32_t (*get_tick)(void);
    void (*delay_ms)(uint32_t ms);
} Hardware_t;

// STM32 implementation
static void stm32_pwm_set(uint8_t ch, uint16_t duty) {
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1 + ch, duty);
}

static uint32_t stm32_get_tick(void) {
    return HAL_GetTick();
}

Hardware_t STM32_Hardware = {
    .pwm_set = stm32_pwm_set,
    .get_tick = stm32_get_tick,
    .delay_ms = HAL_Delay,
};

// Upper layer code depends on abstraction, not concrete implementation
Hardware_t* HW = &STM32_Hardware;  // Change platform by modifying only this line

// Motor control code changed to
void motor_update_impl(Motor_t* self) {
    // ...
    HW->pwm_set(self->id, self->target_speed);
}

Effect

Platform	Code that needs to change
STM32	Implementations of `stm32_pwm_set` and similar functions
ESP32	Write a set of `esp32_pwm_set` and similar functions, then `HW = &ESP32_Hardware`
Simulation testing	Write a set of mock functions, run on PC

Upper layer business logic (motor control, chassis control) doesn’t need a single line of code change!

Stage 7: Polymorphism (Same Interface, Different Behaviors)

Scenario

Now we have two types of motors:

DC motor: Needs PID closed-loop control
Stepper motor: Needs pulse signaling control

Problem

Their behaviors are completely different, but we want the upper layer to use a unified interface: motor_update()

Solution: Operations Table + Derived Structs

// ========== Step 1: Define common interface ==========
typedef struct Motor_t Motor_t;
typedef struct {
    void (*update)(Motor_t* self);
    void (*set_speed)(Motor_t* self, int16_t speed);
} MotorOps_t;

struct Motor_t {
    MotorOps_t* ops;  // Operations table (tells how to operate)
    uint8_t id;
    // Other common properties...
};

// ========== Step 2: Implement DC motor ==========
typedef struct {
    Motor_t base;           // Inherit common part
    int16_t target_speed;
    int16_t current_speed;
    float kp, ki, kd;       // PID parameters
} DCMotor_t;

static void dc_update(Motor_t* self) {
    DCMotor_t* dc = (DCMotor_t*)self;
    // PID calculation
    int16_t error = dc->target_speed - dc->current_speed;
    int16_t output = error * dc->kp;
    HW->pwm_set(self->id, output);
}

static void dc_set_speed(Motor_t* self, int16_t speed) {
    DCMotor_t* dc = (DCMotor_t*)self;
    dc->target_speed = speed;
}

static MotorOps_t dc_ops = {
    .update = dc_update,
    .set_speed = dc_set_speed,
};

// ========== Step 3: Implement stepper motor ==========
typedef struct {
    Motor_t base;           // Inherit common part
    int32_t target_steps;
    int32_t current_steps;
} StepperMotor_t;

static void stepper_update(Motor_t* self) {
    StepperMotor_t* stepper = (StepperMotor_t*)self;
    if (stepper->current_steps < stepper->target_steps) {
        // Send one pulse
        HW->gpio_toggle(self->id);
        stepper->current_steps++;
    }
}

static void stepper_set_speed(Motor_t* self, int16_t speed) {
    StepperMotor_t* stepper = (StepperMotor_t*)self;
    stepper->target_steps = speed;  // Here speed actually represents steps
}

static MotorOps_t stepper_ops = {
    .update = stepper_update,
    .set_speed = stepper_set_speed,
};

// ========== Step 4: Create objects ==========
DCMotor_t dc_motor_obj = {
    .base = { .ops = &dc_ops, .id = 0 },
    .target_speed = 0,
    .kp = 1.5,
};

StepperMotor_t stepper_obj = {
    .base = { .ops = &stepper_ops, .id = 1 },
    .target_steps = 0,
};

Motor_t* motors[2] = {
    (Motor_t*)&dc_motor_obj,
    (Motor_t*)&stepper_obj,
};

// ========== Step 5: Unified calling ==========
void main(void) {
    motors[0]->ops->set_speed(motors[0], 500);
    motors[1]->ops->set_speed(motors[1], 1000);

    while (1) {
        for (int i = 0; i < 2; i++) {
            motors[i]->ops->update(motors[i]);  // Same call, different behavior!
        }
        delay_ms(10);
    }
}

The Magic of Polymorphism

motors[0] (DC motor):
    motors[0]->ops->update → executes dc_update() → PID calculation → set PWM

motors[1] (stepper motor):
    motors[1]->ops->update → executes stepper_update() → send pulse → take one step

The same code motors[i]->ops->update(motors[i]), but does completely different things!

Summary: Architecture Evolution Roadmap

Stage	Core Concept	Key Code Characteristics	Problem Solved
1. Hardcoding	Write wherever needed	Register operations scattered everywhere	None
2. Function encapsulation	Package hardware operations	`motor_left_forward()`	Readability, centralized modification
3. Parameter-driven	Use parameters to distinguish behavior	`motor_control(id, action, speed)`	Reduce function count
4. Non-blocking	State machine + polling	`motor_start()` + `motor_update()`	CPU not idle
5. Multiple instances	Struct encapsulation	`Motor_t` + `self` pointer	Support multiple objects
6. Hardware abstraction	Operations table	`Hardware_t` + function pointers	Cross-platform portability
7. Polymorphism	Each object has its own operations table	`MotorOps_t` + derived structs	Same interface, different behaviors

Finally: When to Use Which?

Project Scale	Recommended Stage	Reason
1-2 files, personal toy	Stage 2-3	Sufficient, no over-engineering
Multiple modules, team development	Stage 4-5	Maintainability matters
Platform-switching product	Stage 6	Hardware abstraction is essential
Multiple device types (motors, lights, sensors)	Stage 7	Polymorphism makes extension simple

STM32 库设计笔记2

Wed, 13 May 2026 16:05:13 GMT

第一阶段：新手村——硬编码

场景

我们有一个小车的底盘控制程序，需要控制两个直流电机。

代码

// 新手写法：每次用到就写具体操作
void main(void) {
    // 左轮前进
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 500);
    
    HAL_Delay(1000);
    
    // 右轮前进
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, 500);
    
    HAL_Delay(1000);
    
    // 停止左轮
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 0);
    
    // 停止右轮
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, 0);
}

问题

代码重复：每个操作都要写一堆寄存器/库函数
不可移植：换 MCU 要改所有文件
不可读：看代码不知道是在“控制电机”，只知道在“操作 GPIO 和 PWM”
不可维护：要改电机逻辑，需要找遍所有调用的地方

核心痛点

业务逻辑（让车前进）和硬件操作（拉高 GPIO、写 PWM）混在一起

第二阶段：函数封装（把重复代码收起来）

思路

把硬件操作包成函数，上层调用函数名，不看内部实现。

代码

// motor_hw.c - 硬件操作封装
void motor_left_forward(uint16_t speed) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, speed);
}

void motor_left_stop(void) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 0);
}

void motor_right_forward(uint16_t speed) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_SET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, speed);
}

void motor_right_stop(void) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_RESET);
    __HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, 0);
}

// main.c - 业务逻辑变清晰了
void main(void) {
    motor_left_forward(500);
    motor_right_forward(500);
    HAL_Delay(1000);
    motor_left_stop();
    motor_right_stop();
}

优点

代码可读性提升
硬件操作集中在一个文件，换 MCU 只改这个文件

新问题

函数泛滥：每个动作一个函数（左转、右转、前进、后退、带加速度…），函数数量爆炸
参数不统一：有的函数用 uint16_t speed，有的用 float duty
扩展性差：增加新电机需要写 4 个新函数

第三阶段：传参驱动（用参数代替函数名）

思路

不要为每个动作单独写函数，而是写一个“通用函数”，用参数区分动作。

代码

// 用一个函数代替多个
void motor_control(uint8_t id, uint8_t action, int16_t speed) {
    switch(id) {
        case 0:  // 左轮
            if (action == FORWARD) {
                HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_SET);
                __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, speed);
            } else if (action == STOP) {
                HAL_GPIO_WritePin(GPIOA, GPIO_PIN_0, GPIO_PIN_RESET);
                __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, 0);
            }
            break;
        case 1:  // 右轮
            // 类似...
            break;
    }
}

// 使用
motor_control(0, FORWARD, 500);
motor_control(1, FORWARD, 500);
HAL_Delay(1000);
motor_control(0, STOP, 0);
motor_control(1, STOP, 0);

优点

函数数量从 电机数 × 动作数 减少到 1 个
新增动作只需加 case，不用加函数

新问题

参数越来越多：要支持加速度？加参数 uint8_t accel；要支持方向？加参数 uint8_t dir… 参数列表越来越长
类型不安全：action 参数传错值（传了 255 而不是 FORWARD），编译器不报错
可读性变差：motor_control(0, 1, 500) 是什么意思？要看文档或函数定义

进化：用结构体传参

// 把多个参数打包成一个结构体
typedef struct {
    uint8_t motor_id;      // 0=左轮, 1=右轮
    uint8_t action;        // FORWARD, BACKWARD, STOP
    int16_t speed;         // -1000 ~ 1000
    uint8_t accel_rate;    // 0-10
    uint32_t duration_ms;  // 持续时间
} MotorCommand_t;

void motor_control(MotorCommand_t* cmd) {
    // 根据 cmd 里的字段执行
}

// 使用
MotorCommand_t cmd = {.motor_id=0, .action=FORWARD, .speed=500, .accel_rate=5, .duration_ms=1000};
motor_control(&cmd);

优点

参数清晰，有字段名
扩展参数只需改结构体，不用改函数签名

第四阶段：状态机 + 非阻塞（让 CPU 能干别的事）

问题

前面的写法都是阻塞的：HAL_Delay(1000) 会让 CPU 傻等 1 秒，啥也不能做。

思路

把“等待”变成“周期性检查”：每次调用只做一小步，然后返回。主循环不断调用，直到完成。

代码

typedef struct {
    int16_t target_speed;
    int16_t current_speed;
    uint32_t start_time;
    uint32_t duration;
    uint8_t is_active;
} MotorState_t;

MotorState_t motors[2];

void motor_start(uint8_t id, int16_t speed, uint32_t ms) {
    motors[id].target_speed = speed;
    motors[id].duration = ms;
    motors[id].start_time = get_tick_ms();  // 获取当前时间
    motors[id].is_active = 1;
}

void motor_update(void) {
    for (int i = 0; i < 2; i++) {
        if (!motors[i].is_active) continue;
        
        uint32_t elapsed = get_tick_ms() - motors[i].start_time;
        
        if (elapsed >= motors[i].duration) {
            // 时间到，停止
            motors[i].is_active = 0;
            set_pwm(i, 0);
        } else {
            // 还在运行中
            set_pwm(i, motors[i].target_speed);
        }
    }
}

// 主循环（非阻塞）
void main(void) {
    motor_start(0, 500, 1000);  // 左轮转1秒
    motor_start(1, 500, 1000);  // 右轮转1秒
    
    while (1) {
        motor_update();  // 每10ms调用一次
        
        // 这10ms间隙可以做其他事
        read_sensors();
        check_emergency();
        
        delay_ms(10);
    }
}

核心变化

阻塞式	非阻塞式
`HAL_Delay(1000)`	`motor_start(..., 1000)` + 主循环轮询
CPU 空转 1 秒	CPU 每 10ms 检查一次，其他时间干活
只能顺序执行动作	可以同时处理多个任务

第五阶段：结构体封装多实例（为多态做准备）

问题

目前每个电机是全局状态，要加新电机需要手动复制粘贴代码。

思路

把电机相关的数据和方法打包成一个结构体，用指针操作。

代码

// 电机"类"
typedef struct Motor_t {
    // 属性（数据）
    int16_t target_speed;
    int16_t current_speed;
    uint32_t start_time;
    uint32_t duration;
    uint8_t is_active;
    uint8_t id;
    
    // 方法（函数指针）
    void (*start)(struct Motor_t* self, int16_t speed, uint32_t ms);
    void (*update)(struct Motor_t* self);
} Motor_t;

// 方法实现
void motor_start_impl(Motor_t* self, int16_t speed, uint32_t ms) {
    self->target_speed = speed;
    self->duration = ms;
    self->start_time = get_tick_ms();
    self->is_active = 1;
}

void motor_update_impl(Motor_t* self) {
    if (!self->is_active) return;
    
    if (get_tick_ms() - self->start_time >= self->duration) {
        self->is_active = 0;
        set_pwm(self->id, 0);
    } else {
        set_pwm(self->id, self->target_speed);
    }
}

// 创建实例
Motor_t left_motor = {
    .id = 0,
    .start = motor_start_impl,
    .update = motor_update_impl,
};

Motor_t right_motor = {
    .id = 1,
    .start = motor_start_impl,
    .update = motor_update_impl,
};

// 使用
void main(void) {
    left_motor.start(&left_motor, 500, 1000);
    right_motor.start(&right_motor, 500, 1000);
    
    while (1) {
        left_motor.update(&left_motor);
        right_motor.update(&right_motor);
        delay_ms(10);
    }
}

关键点：`self` 指针

每个方法第一个参数都是 self，指向调用它的实例。这样同一个 motor_update_impl 函数可以操作不同的电机数据。

第六阶段：硬件抽象（换 MCU 不改上层代码）

问题

目前 set_pwm() 函数里还是直接调用 HAL 库，换 MCU 需要改这个函数内部。

思路

把硬件操作也抽象成操作表（函数指针集合），上层只调用操作表，不直接调用 HAL。

代码

// 硬件操作表（抽象层）
typedef struct {
    void (*pwm_set)(uint8_t channel, uint16_t duty);
    uint32_t (*get_tick)(void);
    void (*delay_ms)(uint32_t ms);
} Hardware_t;

// STM32 实现
static void stm32_pwm_set(uint8_t ch, uint16_t duty) {
    __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1 + ch, duty);
}

static uint32_t stm32_get_tick(void) {
    return HAL_GetTick();
}

Hardware_t STM32_Hardware = {
    .pwm_set = stm32_pwm_set,
    .get_tick = stm32_get_tick,
    .delay_ms = HAL_Delay,
};

// 上层代码依赖抽象，不依赖具体
Hardware_t* HW = &STM32_Hardware;  // 换平台只改这一行

// 电机控制代码改为
void motor_update_impl(Motor_t* self) {
    // ...
    HW->pwm_set(self->id, self->target_speed);
}

效果

平台	需要改的代码
STM32	`stm32_pwm_set` 等函数的实现
ESP32	写一套 `esp32_pwm_set` 等函数，然后 `HW = &ESP32_Hardware`
模拟测试	写一套 mock 函数，在 PC 上跑

上层业务逻辑（电机控制、底盘控制）一行代码都不用改！

第七阶段：多态（同一个接口，不同行为）

场景

现在有两种电机：

直流电机：需要 PID 闭环控制
步进电机：需要发脉冲控制

问题

它们的行为完全不同，但我们希望上层能用统一的接口：motor_update()

解决方案：操作表 + 派生结构体

// ========== 第一步：定义通用接口 ==========
typedef struct Motor_t Motor_t;
typedef struct {
    void (*update)(Motor_t* self);
    void (*set_speed)(Motor_t* self, int16_t speed);
} MotorOps_t;

struct Motor_t {
    MotorOps_t* ops;  // 操作表（告诉怎么操作）
    uint8_t id;
    // 其他通用属性...
};

// ========== 第二步：实现直流电机 ==========
typedef struct {
    Motor_t base;           // 继承通用部分
    int16_t target_speed;
    int16_t current_speed;
    float kp, ki, kd;       // PID参数
} DCMotor_t;

static void dc_update(Motor_t* self) {
    DCMotor_t* dc = (DCMotor_t*)self;
    // PID 计算
    int16_t error = dc->target_speed - dc->current_speed;
    int16_t output = error * dc->kp;
    HW->pwm_set(self->id, output);
}

static void dc_set_speed(Motor_t* self, int16_t speed) {
    DCMotor_t* dc = (DCMotor_t*)self;
    dc->target_speed = speed;
}

static MotorOps_t dc_ops = {
    .update = dc_update,
    .set_speed = dc_set_speed,
};

// ========== 第三步：实现步进电机 ==========
typedef struct {
    Motor_t base;           // 继承通用部分
    int32_t target_steps;
    int32_t current_steps;
} StepperMotor_t;

static void stepper_update(Motor_t* self) {
    StepperMotor_t* stepper = (StepperMotor_t*)self;
    if (stepper->current_steps < stepper->target_steps) {
        // 发一个脉冲
        HW->gpio_toggle(self->id);
        stepper->current_steps++;
    }
}

static void stepper_set_speed(Motor_t* self, int16_t speed) {
    StepperMotor_t* stepper = (StepperMotor_t*)self;
    stepper->target_steps = speed;  // 这里 speed 实际表示步数
}

static MotorOps_t stepper_ops = {
    .update = stepper_update,
    .set_speed = stepper_set_speed,
};

// ========== 第四步：创建对象 ==========
DCMotor_t dc_motor_obj = {
    .base = { .ops = &dc_ops, .id = 0 },
    .target_speed = 0,
    .kp = 1.5,
};

StepperMotor_t stepper_obj = {
    .base = { .ops = &stepper_ops, .id = 1 },
    .target_steps = 0,
};

Motor_t* motors[2] = {
    (Motor_t*)&dc_motor_obj,
    (Motor_t*)&stepper_obj,
};

// ========== 第五步：统一调用 ==========
void main(void) {
    motors[0]->ops->set_speed(motors[0], 500);
    motors[1]->ops->set_speed(motors[1], 1000);
    
    while (1) {
        for (int i = 0; i < 2; i++) {
            motors[i]->ops->update(motors[i]);  // 同一个调用，不同行为！
        }
        delay_ms(10);
    }
}

多态的魔力

motors[0]（直流电机）:
    motors[0]->ops->update → 执行 dc_update() → PID 计算 → 设 PWM

motors[1]（步进电机）:
    motors[1]->ops->update → 执行 stepper_update() → 发脉冲 → 走一步

同样的代码 motors[i]->ops->update(motors[i])，做的是完全不同的事情！

总结：架构演化路线图

阶段	核心思想	关键代码特征	解决的问题
1. 硬编码	写到哪算哪	寄存器操作散落各处	无
2. 函数封装	硬件操作打包	`motor_left_forward()`	可读性、集中修改
3. 传参驱动	用参数区分行为	`motor_control(id, action, speed)`	减少函数数量
4. 非阻塞	状态机 + 轮询	`motor_start()` + `motor_update()`	CPU 不空转
5. 多实例	结构体封装	`Motor_t` + `self` 指针	支持多个对象
6. 硬件抽象	操作表	`Hardware_t` + 函数指针	跨平台移植
7. 多态	每个对象有自己的操作表	`MotorOps_t` + 派生结构体	同一接口，不同行为

最后：什么时候用哪种？

项目规模	推荐阶段	理由
1-2 个文件，个人玩具	阶段 2-3	够用，不折腾
多个模块，团队开发	阶段 4-5	可维护性重要
需要换平台的产品	阶段 6	硬件抽象是刚需
有多种设备类型（电机、灯、传感器）	阶段 7	多态让扩展变得简单

Wheel-Legged Robot 2-DOF Closed-Loop Linkage Forward and Inverse Kinematics Derivation

Mon, 04 May 2026 06:00:00 GMT

1. Problem Background

Each leg of a wheel-legged robot needs both wheel rolling and leg obstacle-crossing capabilities. The mechanism design discussed here uses two coaxial motors, transmitting power to the wheel through a figure-8 shaped double parallelogram linkage, achieving decoupled control of leg swinging and wheel steering.

Compared to traditional belt drive or gear drive solutions, this all-linkage mechanism has advantages of zero backlash, high structural stiffness, no wearing parts, making it especially suitable for wheel-legged robot applications requiring high-precision end-effector position control.

flowchart TD
  M["Motor A (θa)"] --> A["bar_a (three-arm杆 O-P1-P2)"]
  M2["Motor B (θb)"] --> B["bar_b (two-arm杆 O-P3)"]
  A --> D["bar_d (three-arm直杆 P1-P4-P5)"]
  B --> C["bar_c (two-arm杆 P3-P4)"]
  C --> D
  D --> E["bar_e (two-arm杆 P5-P6)"]
  A --> F["bar_f (three-arm直杆 P2-P6-P7)"]
  E --> F
  F --> W["P7 — Hub motor (end-effector)"]

Two parallelograms nested in a figure-8 shape:

Parallelogram 1: O – P1 – P4 – P3, side lengths 48.4 × 57.3 mm
Parallelogram 2: P1 – P2 – P6 – P5, side lengths 59 × 32.4 mm

The key point is: all three-arm bars (bar_a, bar_d, bar_f) are straight bars (three points collinear). This geometric constraint is the core prerequisite for subsequent analytical simplification.

2. Forward Kinematics Derivation

The goal of forward kinematics is: given motor angles θa,θb\theta_a, \theta_bθa,θb, find the position of end-effector P7P_7P7.

2.1 Point Coordinates Step-by-Step Solution

Step 1 — P1, P2 on bar_a

Using O as origin, rotated by θa\theta_aθa:

P1=LOP1[cos⁡θasin⁡θa]=48.4[cos⁡θasin⁡θa]P2=LOP2[cos⁡θasin⁡θa]=107.4[cos⁡θasin⁡θa]\begin{aligned} P_1 &= L_{OP1} \begin{bmatrix}\cos\theta_a \\ \sin\theta_a\end{bmatrix} = 48.4 \begin{bmatrix}\cos\theta_a \\ \sin\theta_a\end{bmatrix} \\[6pt] P_2 &= L_{OP2} \begin{bmatrix}\cos\theta_a \\ \sin\theta_a\end{bmatrix} = 107.4 \begin{bmatrix}\cos\theta_a \\ \sin\theta_a\end{bmatrix} \end{aligned}P1P2=LOP1[cosθasinθa]=48.4[cosθasinθa]=LOP2[cosθasinθa]=107.4[cosθasinθa]

Here LOP2=48.4+59=107.4L_{OP2} = 48.4 + 59 = 107.4LOP2=48.4+59=107.4, because bar_a is a straight bar, P1 lies on the O–P2 line.

Step 2 — P3 on bar_b

P3=Lb[cos⁡θbsin⁡θb]=57.3[cos⁡θbsin⁡θb]P_3 = L_b \begin{bmatrix}\cos\theta_b \\ \sin\theta_b\end{bmatrix} = 57.3 \begin{bmatrix}\cos\theta_b \\ \sin\theta_b\end{bmatrix}P3=Lb[cosθbsinθb]=57.3[cosθbsinθb]

Step 3 — P4 on bar_d (intersection of two circles)

From parallelogram 1, we know ∣P1P4∣|P_1P_4|∣P1P4∣, ∣P3P4∣|P_3P_4|∣P3P4∣ are fixed values, so P4 is the intersection of two circles:

Circle center P1P_1P1, radius LP1P4=57.3L_{P1P4} = 57.3LP1P4=57.3
Circle center P3P_3P3, radius Lc=48.4L_c = 48.4Lc=48.4

The analytical solution process for intersection of two circles is as follows. Let vector v=P3−P1\mathbf{v} = P_3 - P_1v=P3−P1, distance between centers d=∥v∥d = \|\mathbf{v}\|d=∥v∥, then:

a=LP1P42−Lc2+d22dh=LP1P42−a2P4=P1+adv±hdRv\begin{aligned} a &= \frac{L_{P1P4}^2 - L_c^2 + d^2}{2d} \\[4pt] h &= \sqrt{L_{P1P4}^2 - a^2} \\[4pt] P_4 &= P_1 + \frac{a}{d}\mathbf{v} \pm \frac{h}{d}\mathbf{R}\mathbf{v} \end{aligned}ahP4=2dLP1P42−Lc2+d2=LP1P42−a2=P1+dav±dhRv

Where R=[0−110]\mathbf{R} = \begin{bmatrix}0 & -1 \\ 1 & 0\end{bmatrix}R=[01−10] is the 90∘90^\circ90∘ rotation matrix, the ±\pm± sign corresponds to two assembly modes, denoted as branch_d=±1\mathrm{branch}\_d = \pm 1branch_d=±1.

2.2 Core Simplification: Straight Bar Constraint

After obtaining P4, the direction angle of bar_d is:

θd=atan2(P4−P1)\theta_d = \text{atan2}(P_4 - P_1)θd=atan2(P4−P1)

Because bar_d is a straight bar, P5 is collinear with P1, P4, and ∣P1P5∣=32.4|P_1P_5| = 32.4∣P1P5∣=32.4, so:

P5=P1+32.457.3(P4−P1)P_5 = P_1 + \frac{32.4}{57.3} (P_4 - P_1)P5=P1+57.332.4(P4−P1)

Substituting the relationship of parallelogram 2: P6=P2+P5−P1P_6 = P_2 + P_5 - P_1P6=P2+P5−P1, eliminating P5:

P6=P2−32.457.3(P4−P1)P_6 = P_2 - \frac{32.4}{57.3} (P_4 - P_1)P6=P2−57.332.4(P4−P1)

Note that the direction of P4−P1P_4 - P_1P4−P1 is the same as P3P_3P3 (opposite sides of parallelogram are parallel), and P3=Lb[cos⁡θb,sin⁡θb]TP_3 = L_b[\cos\theta_b, \sin\theta_b]^TP3=Lb[cosθb,sinθb]T, so:

P6=P2−32.4[cos⁡θbsin⁡θb]P_6 = P_2 - 32.4 \begin{bmatrix}\cos\theta_b \\ \sin\theta_b\end{bmatrix}P6=P2−32.4[cosθbsinθb]

bar_f is also a straight bar, P7 is in the opposite extension direction of P2→P6, ∣P2P7∣=128|P_2P_7| = 128∣P2P7∣=128:

P7=P2+128[cos⁡θbsin⁡θb]P_7 = P_2 + 128 \begin{bmatrix}\cos\theta_b \\ \sin\theta_b\end{bmatrix}P7=P2+128[cosθbsinθb]

2.3 Final Analytical Expression

Substituting P2=107.4[cos⁡θa,sin⁡θa]TP_2 = 107.4[\cos\theta_a, \sin\theta_a]^TP2=107.4[cosθa,sinθa]T:

P7=[107.4cos⁡θa+128cos⁡θb107.4sin⁡θa+128sin⁡θb]\boxed{P_7 = \begin{bmatrix} 107.4\cos\theta_a + 128\cos\theta_b \\ 107.4\sin\theta_a + 128\sin\theta_b \end{bmatrix}}P7=[107.4cosθa+128cosθb107.4sinθa+128sinθb]

infographic list-grid-badge-card
data
  title Physical Meaning
  desc The mechanism is equivalent to a standard 2R planar robotic arm
  items
    - label First Link
      desc O → P₂, length L₁ = 107.4 mm, angle θa
      icon mdi/link-variant
    - label Second Link
      desc P₂ → P₇, length L₂ = 128 mm, angle θb
      icon mdi/link-variant
    - label End-effector
      desc Hub motor position P₇
      icon mdi/wheel

This conclusion is very elegant: Regardless of how the double parallelogram bends, the position of end-effector P₇ depends only on the rotation angles of the two motors, and has nothing to do with the posture of all intermediate links. This is thanks to the straight bar constraint and the geometric properties of nested parallelograms — the kinematics of intermediate joints are completely "absorbed".

3. Inverse Kinematics Derivation

Inverse kinematics: Given end-effector position P7=(x,y)P_7 = (x, y)P7=(x,y), find θa,θb\theta_a, \theta_bθa,θb.

3.1 Cosine Law

Let r=x2+y2r = \sqrt{x^2 + y^2}r=x2+y2 (distance from P7 to origin), ϕ=atan2(y,x)\phi = \text{atan2}(y, x)ϕ=atan2(y,x).

From the geometric relationship of a 2R robotic arm:

cos⁡α=r2+L12−L222L1r\cos\alpha = \frac{r^2 + L_1^2 - L_2^2}{2 L_1 r}cosα=2L1rr2+L12−L22 α=arccos⁡(r2+107.42−12822×107.4×r)\alpha = \arccos\left(\frac{r^2 + 107.4^2 - 128^2}{2 \times 107.4 \times r}\right)α=arccos(2×107.4×rr2+107.42−1282)

3.2 Two Solutions

θa=ϕ±α\theta_a = \phi \pm \alphaθa=ϕ±α

The positive sign corresponds to elbow-down, the negative sign corresponds to elbow-up (two arm configurations).

θb=atan2(y−L1sin⁡θa, x−L1cos⁡θa)\theta_b = \text{atan2}\left( y - L_1\sin\theta_a,\; x - L_1\cos\theta_a \right)θb=atan2(y−L1sinθa,x−L1cosθa)

3.3 Workspace and Singular Configurations

The workspace is an annular region:

∣L1−L2∣≤r≤L1+L2|L_1 - L_2| \leq r \leq L_1 + L_2∣L1−L2∣≤r≤L1+L2

That is 20.6 mm≤r≤235.4 mm20.6 \text{ mm} \leq r \leq 235.4 \text{ mm}20.6 mm≤r≤235.4 mm.

Three singular configurations:

Condition	Meaning	Solution Situation
r=L1+L2=235.4r = L_1 + L_2 = 235.4r=L1+L2=235.4	Fully extended	Single solution (θa=θb\theta_a = \theta_bθa=θb)
$r =	L_1 - L_2	= 20.6$
r=0r = 0r=0	End-effector coincides with origin	Infinitely many solutions

Near singular configurations, the mechanism's force transmission performance degrades sharply — a small end-effector force may produce large torques at the joints. This is also an inherent problem of 2R robotic arms, and singular regions should be avoided during trajectory planning.

4. Code Implementation

4.1 Intersection of Two Circles

This is the geometric foundation for the entire numerical solution — given two circle centers and radii, find the intersection points.

def circle_intersection(c1, r1, c2, r2):
    """Returns (p_left, p_right), returns (None, None) when no solution."""
    v = c2 - c1
    d = np.linalg.norm(v)

    if d < 1e-12:          # Concentric circles
        return None, None
    if d > r1 + r2 + 1e-10 or d < abs(r1 - r2) - 1e-10:
        return None, None  # No intersection

    a = (r1**2 - r2**2 + d**2) / (2.0 * d)
    h = np.sqrt(max(r1**2 - a**2, 0.0))
    p_mid = c1 + (a / d) * v

    if h < 1e-10:
        return p_mid.copy(), p_mid.copy()  # Tangent

    perp = np.array([-v[1], v[0]]) / d
    return p_mid + h * perp, p_mid - h * perp

The positive/negative sign of the perp vector distinguishes the two solutions — corresponding to two assembly modes.

4.2 Forward Kinematics Solver

def solve_linkage(theta_a, theta_b, params, prev_theta_d=None, prev_theta_f=None):
    # 1. P1, P2 on bar_a
    P1 = rotate_vec(np.array([params.L_OP1, 0.0]), theta_a)
    P2 = rotate_vec(params._a2_local, theta_a)

    # 2. P3 on bar_b
    P3 = params.L_b * np.array([np.cos(theta_b), np.sin(theta_b)])

    # 3. Find P4 via circle intersection
    p4_left, p4_right = circle_intersection(P1, params.L_P1P4, P3, params.L_c)
    # prev_theta_d used for branch continuity in trajectory tracking

    # 4. bar_d direction → P5
    theta_d = np.arctan2((P4 - P1)[1], (P4 - P1)[0])
    P5 = P1 + rotate_vec(params._d5_local, theta_d)

    # 5. Find P6 via circle intersection
    p6_left, p6_right = circle_intersection(P2, params.L_P2P6, P5, params.L_e)

    # 6. bar_f direction → P7 (end-effector)
    theta_f = np.arctan2((P6 - P2)[1], (P6 - P2)[0])
    P7 = P2 + rotate_vec(params._f7_local, theta_f)

    return {'P7': P7, 'theta_d': theta_d, 'theta_f': theta_f, ...}

The entire solution process is completed entirely with trigonometric functions and square roots, without any iteration, making it a pure analytical forward solution.

4.3 Inverse Kinematics

def solve_inverse(P7_target, params, elbow=1):
    L1, L2 = params.L_OP2, params.L_P2P7
    x, y = P7_target
    r = np.hypot(x, y)

    if r > L1 + L2 + 1e-6 or r < abs(L1 - L2) - 1e-6:
        return []  # Outside workspace

    cos_alpha = (r**2 + L1**2 - L2**2) / (2.0 * L1 * r)
    alpha = np.arccos(np.clip(cos_alpha, -1.0, 1.0))
    phi = np.arctan2(y, x)

    solutions = []
    for sgn in ([-1, 1] if elbow == 0 else [elbow]):
        theta_a = phi + sgn * alpha
        theta_b = np.arctan2(
            y - L1 * np.sin(theta_a),
            x - L1 * np.cos(theta_a),
        )
        solutions.append({'theta_a': theta_a, 'theta_b': theta_b})

    return solutions

The elbow parameter controls which inverse solution is returned: +1 elbow up, -1 elbow down, 0 returns both solutions.

5. Four Assembly Modes

The ±\pm± choice in circle intersection brings four assembly modes (branch_d × branch_f), corresponding to different assembly methods of the actual mechanism:

infographic list-grid-badge-card
data
  title Four Assembly Modes
  desc Combination of ± solutions from two circle intersections → Four assembly modes
  items
    - label "Convex-Convex (−1, −1)"
      desc P₄ is to the left of P₁→P₃, P₆ is to the left of P₂→P₅
    - label "Convex-Concave (−1, +1)"
      desc P₄ is to the left of P₁→P₃, P₆ is to the right of P₂→P₅
    - label "Concave-Convex (+1, −1)"
      desc P₄ is to the right of P₁→P₃, P₆ is to the left of P₂→P₅ (★ default mode)
    - label "Concave-Concave (+1, +1)"
      desc P₄ is to the right of P₁→P₃, P₆ is to the right of P₂→P₅

Among them, branch_d=+1, branch_f=−1\mathrm{branch}\_d = +1,\ \mathrm{branch}\_f = -1branch_d=+1, branch_f=−1 (concave-convex) corresponds to the case where both parallelograms are convex quadrilaterals, which is also the default mode where the 2R simplification holds.

In the other three modes, the parallelograms will have different degrees of concavity, but the analytical derivation framework for forward and inverse kinematics remains the same — just select the corresponding ±\pm± branch during solving. However, note that in non-default modes, the relative orientation between end-effector P₇ and motor shaft changes, and trajectory planning should distinguish from the default mode.

5.1 Branch Keeping in Trajectory Tracking

During trajectory tracking, each frame's solve_linkage passes in the previous frame's θd,θf\theta_d, \theta_fθd,θf, and selects the solution closer to the previous frame among the two circle intersection solutions. This maintains the same assembly mode during continuous motion, avoiding jumps.

# Select P4 closer to previous frame (maintain branch_d continuity)
P4 = p4_left if norm(p4_left - P4_prev) <= norm(p4_right - P4_prev) else p4_right

Similarly, P6's branch selection uses the same nearest-neighbor decision strategy. The complete branch-keeping logic is as follows:

def select_branch(p_left, p_right, p_prev):
    """Select the intersection point closer to the previous frame from the two"""
    if p_prev is None:
        return p_left  # First frame, default to first
    d_left = norm(p_left - p_prev)
    d_right = norm(p_right - p_prev)
    return p_left if d_left <= d_right else p_right

These two branch selection algorithms together ensure that both parallelograms maintain continuous assembly state during trajectory tracking, avoiding motion discontinuities or mechanism jamming caused by "frame skipping".

5.2 Assembly Mode Selection Basis

The default mode (concave-convex, +1, −1) is the most natural scheme for physical assembly — both parallelograms remain convex externally, the mechanism's force condition is optimal, and it directly corresponds to the 2R simplified model, facilitating kinematics planning.

Under certain special motion requirements (such as needing to avoid obstacles, change end-effector pose range, or optimize force transmission angle), other assembly modes can be selected. Assembly mode switching needs to transition naturally when the mechanism passes through singular configurations (two circles tangent, h=0h = 0h=0) — at this point the two solutions coincide, and the branch can be safely switched.

6. Verification

θa\theta_aθa	θb\theta_bθb	P7P_7P7 (Analytical)	P7P_7P7 (Numerical)
0°	90°	(107.4, 128.0)	(107.4, 128.0) ✓
30°	120°	(29.0, 164.6)	(29.0, 164.6) ✓
0°	0°	(235.4, 0.0)	(235.4, 0.0) ✓
−30°	45°	(183.5, 36.8)	(183.5, 36.8) ✓

The above verification shows that the analytical derivation and numerical solution are completely consistent, and the forward and inverse kinematics solvers are correct and reliable.

7. Summary

This figure-8 shaped double parallelogram mechanism cleverly utilizes the straight bar collinearity constraint, making the seemingly complex linkage transmission chain ultimately simplify to a 2R planar robotic arm. Both forward and inverse kinematics have closed-form analytical solutions, requiring no numerical iteration, making it very suitable for embedded real-time control scenarios.

If you're interested in the complete code, the project is open source on GitHub:

GitHub - 729DHS/linkage-2dof

https://github.com/729DHS/linkage-2dof

# Quick try
git clone https://github.com/729DHS/linkage-2dof.git
cd linkage-2dof
uv sync
python main.py interactive   # Interactive sliders
python main.py anim          # Generate animation
python main.py ik            # Inverse kinematics demo

This World is Both Cruel and Gentle - Reflections

Tue, 21 Apr 2026 06:52:26 GMT

Notes on “This World is Both Cruel and Gentle”

I had long heard about Sun Ge’s book, and read it recently. It did leave me with some reflections.

People nowadays always talk about stability, but stability is the biggest lie of all, and extremely hard to find. From my observation, only those earning a hundred thousand or two hundred thousand per year in the public sector could demand this, but clearly this requirement is extremely high.

People fear uncertainty. Bill Gates called Hewlett-Packard when he was twelve years old. The first step is extremely difficult to take; people are afraid of rejection, afraid of embarrassment, failure, afraid things won’t develop as expected.

Why I’ve Never Looked for a Stable Job

But who cares? Payment is by the word. The faster you translate and the more words you produce, the more money you can earn. And translators don't know their readers. Most people's attitude is to muddle through, speed up and finish the manuscript, and couldn't care less about publishing quality or the troubles, misleadings, and deviations they cause to readers. Very few people care about the dignity of the translation profession, or about your struggles and pains during translation. You gradually discover that a good translation and a bad translation are treated the same, with absolutely no difference; no one values diligence, effort, or talent. A conscientious person feels awkward in such an environment, while a loafer who loves stability finds it like discovering their own organization. At that time, I was immersed in translation. I overheard discussions among these veteran office workers mentioned in "Ode to Joy." All day they discussed their dream: when they could infiltrate an even more stable industry, one with lower quality requirements and even less regard for professional dignity; all day they thought most about how to cut corners, reduce materials, and make it even easier on this basis—there's no laziest, only lazier; their biggest daily hobby is to discourage newcomers who believe they can change something, achieve something, or take their work seriously.

The so-called “stability” is more like the soldiers in “Soldier Assault” who slack off in the grassland fifth squad, doing nothing, getting a paycheck and idling—that’s the so-called stability. When they see Xu Sanuo persisting day after day, they feel uneasy. It’s like a dorm full of people gaming, where the person who studies seriously is the odd one, because they disrupt the group’s stability.

Especially now with the sluggish social environment, people are more inclined to lie flat. As if you, as a striver, are the odd one. Not only do they want to slack off, they want to drag you down. As a striver, you’re called an idiot, but clearly, success still belongs to a minority. Those who lie flat will never succeed.

Ninety percent of people make ninety-nine percent of the choices, yet want one percent of the results—that clearly won’t work. Those who study seriously day after day, why shouldn’t success belong to them?

In my view, Sun Ge is more of a typical example—persisting at all costs for one thing. I always think I’m unlucky, that what I do doesn’t yield good results. But thinking about it carefully, I still haven’t truly put in genuine effort. Maybe I’ve only put in half an effort.

Do What Is Correct When Viewed from the Future

Courage and vision are essential prerequisites for success.

If an entrepreneur has met Bill Gates and Musk, they will no longer be satisfied with being merely an outstanding county-level entrepreneur. The sense of deserving is very important. Some people feel they don’t deserve it, or subconsciously think they don’t deserve it. All people are born equal, with two arms and two legs. We’re no different. The conveniences of birth are not reasons to divide people into classes or levels.

Focus on increments rather than stock

Don’t limit your gaze to immediate interests. Long-term investment, even if at a loss, if it can exchange for greater returns in the future, then it is worth it.

ALL IN to a Magnificent Cause

The internet has opened a new era, where connections between people have become unprecedentedly convenient. It has also opened a virtual parallel space.

When deciding to undertake a great cause, you must have the determination to ALL IN.

ALL IN doesn’t mean having no retreat, nor is it blind impulse. It requires keen judgment and perception of the future, having seventy to eighty percent certainty, and believing in your own judgment. Especially when changing careers, starting a business, or starting from scratch.

JLC FreeRTOS LED Demo

Thu, 02 Apr 2026 14:48:50 GMT

Tutorial: FreeRTOS Multi-Task Basics and GPIO Control

0. Experiment Overview

This experiment is a mandatory introduction to Embedded Real-Time Operating Systems (RTOS). By creating two tasks with different priorities to control two LEDs blinking at different frequencies, it visually demonstrates FreeRTOS’s multi-task scheduling, priority preemption, and time management mechanisms.

Learning Objectives

Understand the concept of a FreeRTOS “Task” and how it differs from bare-metal while(1).

Master the method of configuring FreeRTOS tasks using STM32CubeMX.

Deeply understand the meaning of each parameter in osThreadNew when creating a task.

Learn to analyze the scheduling behavior of tasks with different priorities.

1. Prerequisites

1.1 What is a FreeRTOS Task?

In a bare-metal program, we typically execute code sequentially within a dead loop while(1). In an RTOS, the program is split into multiple independent “tasks”. Each task appears to 独占 CPU, but the OS kernel (Scheduler) rapidly switches between tasks based on priority and time slice, achieving macroscopic “parallelism”.

1.2 Hardware Basics

MCU: STM32F407 (Cortex-M4)
LED Connections:
- LED1 -> PB2 (Push-Pull Output)
- LED2 -> PB8 (Push-Pull Output)
Clock: System main frequency 168MHz, SysTick or TIM14 provides the heartbeat tick.

2. Principle Analysis

2.1 Task Priority and Scheduling

This experiment creates two tasks:

Task PB2: Priority Normal (higher)
Task PB8: Priority Low (lower)

Scheduling Rules: FreeRTOS uses priority-based preemptive scheduling.

When a higher-priority task is ready, the CPU immediately executes it.
Only when the higher-priority task enters blocking state (e.g., calling osDelay) does the lower-priority task get a chance to run.
In this experiment, both tasks spend most of their time in osDelay blocking, so they alternate execution without interfering with each other.

2.2 Time Delay (`osDelay`)

osDelay(1000): Means the task is suspended for 1000 system ticks.
Assuming the system tick frequency is 1000Hz (1ms), the delay time is 1 second.
Key Point: During the delay, this task does not consume CPU resources; the CPU can execute other ready lower-priority tasks. This is the core of efficient multi-tasking.

3. In-Depth Code Analysis

The following teaching breakdown is based on Core/Src/main.c.

3.1 Task Attribute Definitions

In the global variable section of main.c, the task’s “ID card” is defined.

JLC FreeRTOS Encoder + PWM + LED

Thu, 02 Apr 2026 14:48:50 GMT

EC11 Encoder LED Brightness Control Project

1. Project Overview

This project is based on the STM32F407 microcontroller and FreeRTOS operating system, implementing the function of controlling LED brightness using an EC11 encoder. The project uses three tasks (threads) working together to achieve non-blocking encoder reading, button detection, and LED brightness control.

2. Technical Framework

2.1 Hardware Platform

Microcontroller: STM32F407
Encoder: EC11 rotary encoder (connected to PD12 and PD13)
Button: PC13 (encoder’s built-in press function)
LED: PB8 (brightness controlled via PWM)
Timer: TIM10 (for PWM output)

2.2 Software Architecture

Development Environment: STM32CubeMX + VScode
Operating System: FreeRTOS
Library: STM32 HAL library
Code Structure: Standard STM32 HAL project structure + FreeRTOS task management

3. Code Structure Analysis

3.1 Header Files

#include "main.h"
#include "cmsis_os.h"

Includes the main header file and CMSIS-OS header file, which define the basic configuration of the STM32 HAL library and FreeRTOS-related functions.

3.2 Global Variable Definitions

/* USER CODE BEGIN PV */
uint8_t led_enabled = 1;
uint16_t pwm_duty = 0;
const uint16_t pwm_arr = 65535;
const uint16_t pwm_step = 1000;
/* USER CODE END PV */

led_enabled: LED enable state (1=on, 0=off)
pwm_duty: PWM duty cycle (0-65535)
pwm_arr: PWM auto-reload value (timer period)
pwm_step: PWM change step per encoder rotation

3.3 Task Handle Definitions

/* USER CODE BEGIN EV */
osThreadId_t EncoderTaskHandle;
osThreadId_t KEYTaskHandle;
osThreadId_t LEDTaskHandle;
/* USER CODE END EV */

Defines handles for three tasks, used for task management.

3.4 Task Function Prototypes

/* USER CODE BEGIN FunctionPrototypes */
void EncoderTask(void *argument);
void KEYTask(void *argument);
void LEDTask(void *argument);
/* USER CODE END FunctionPrototypes */

3.5 Encoder State Table

const int8_t enc_table[16] = {
    0, -1,  1,  0,
    1,  0,  0, -1,
   -1, 0,  0,  1,
    0,  1, -1,  0
};

The state table for encoder rotation direction detection, used for table-lookup calculation of rotation direction.

4. Main Function Implementation

4.1 Main Function

int main(void)
{
  /* System Initialization */
  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();
  MX_TIM10_Init();
  MX_FREERTOS_Init();

  /* Start PWM Output */
  if (HAL_TIM_PWM_Start(&htim10, TIM_CHANNEL_1) != HAL_OK)
  {
    Error_Handler();
  }

  /* Start Task Scheduler */
  osKernelStart();

  /* Will never execute here */
  while (1)
  {
  }
}

The main function first performs system initialization, then configures GPIO, TIM10 timer, and FreeRTOS, and starts PWM output and the task scheduler.

4.2 Task Initialization

void MX_FREERTOS_Init(void)
{
  /* Create Tasks */
  EncoderTaskHandle = osThreadNew(EncoderTask, NULL, &EncoderTask_attributes);
  KEYTaskHandle = osThreadNew(KEYTask, NULL, &KEYTask_attributes);
  LEDTaskHandle = osThreadNew(LEDTask, NULL, &LEDTask_attributes);
}

Uses the osThreadNew function to create three tasks and set task attributes.

4.3 Encoder Task

void EncoderTask(void *argument)
{
  static uint8_t enc_last = 0;
  uint8_t enc_current;
  int8_t enc_dir;

  for (;;)
  {
    /* Read encoder state */
    enc_current = ((GPIOE->IDR & GPIO_PIN_12) >> 12) | ((GPIOE->IDR & GPIO_PIN_13) >> 12);

    /* Calculate rotation direction */
    enc_dir = enc_table[(enc_last << 2) | enc_current];
    enc_last = enc_current;

    /* Adjust PWM duty cycle based on direction */
    if (enc_dir > 0 && pwm_duty < pwm_arr)
    {
      pwm_duty += pwm_step;
      if (pwm_duty > pwm_arr) pwm_duty = pwm_arr;
    }
    else if (enc_dir < 0 && pwm_duty > 0)
    {
      pwm_duty -= pwm_step;
      if (pwm_duty > pwm_arr) pwm_duty = 0; // Prevent overflow
    }

    osDelay(10);
  }
}

The Encoder task uses a lookup table to detect encoder rotation direction and adjusts the PWM duty cycle accordingly.

4.4 KEY Task

void KEYTask(void *argument)
{
  static uint8_t key_state = 0;
  static uint32_t key_time = 0;

  for (;;)
  {
    /* Button debounce processing */
    if (HAL_GPIO_ReadPin(GPIOC, GPIO_PIN_13) == GPIO_PIN_RESET)
    {
      if (key_state == 0)
      {
        key_state = 1;
        key_time = osKernelGetTickCount();
      }
      else if (key_state == 1)
      {
        if (osKernelGetTickCount() - key_time > 50)
        {
          key_state = 2;
          /* Toggle LED enable state */
          led_enabled = !led_enabled;
        }
      }
    }
    else
    {
      key_state = 0;
    }

    osDelay(10);
  }
}

The KEY task implements button debounce processing. When a button press is detected, it toggles the LED enable state.

4.5 LED Task

void LEDTask(void *argument)
{
  for (;;)
  {
    /* Control LED brightness based on PWM duty cycle and LED enable state */
    uint16_t out = led_enabled ? (uint16_t)(pwm_arr - pwm_duty) : pwm_arr;
    __HAL_TIM_SET_COMPARE(&htim10, TIM_CHANNEL_1, out);

    osDelay(50);
  }
}

The LED task controls LED brightness via TIM10 PWM output. Since PB8 is active-low, the PWM duty cycle needs to be inverted.

4.6 TIM10 Timer Initialization

static void MX_TIM10_Init(void)
{
  TIM_OC_InitTypeDef sConfigOC = {0};

  htim10.Instance = TIM10;
  htim10.Init.Prescaler = 0;
  htim10.Init.CounterMode = TIM_COUNTERMODE_UP;
  htim10.Init.Period = 65535;
  htim10.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
  htim10.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE;
  if (HAL_TIM_Base_Init(&htim10) != HAL_OK)
  {
    Error_Handler();
  }
  if (HAL_TIM_PWM_Init(&htim10) != HAL_OK)
  {
    Error_Handler();
  }
  sConfigOC.OCMode = TIM_OCMODE_PWM1;
  sConfigOC.Pulse = 0;
  sConfigOC.OCPolarity = TIM_OCPOLARITY_HIGH;
  sConfigOC.OCFastMode = TIM_OCFAST_DISABLE;
  if (HAL_TIM_PWM_ConfigChannel(&htim10, &sConfigOC, TIM_CHANNEL_1) != HAL_OK)
  {
    Error_Handler();
  }
  HAL_TIM_MspPostInit(&htim10);
}

The TIM10 timer initialization function configures the timer’s basic parameters and PWM output channel.

4.7 GPIO Initialization

static void MX_GPIO_Init(void)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};

  /* GPIO Ports Clock Enable */
  __HAL_RCC_GPIOC_CLK_ENABLE();
  __HAL_RCC_GPIOD_CLK_ENABLE();
  __HAL_RCC_GPIOB_CLK_ENABLE();

  /* Configure PC13 as input */
  GPIO_InitStruct.Pin = GPIO_PIN_13;
  GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
  GPIO_InitStruct.Pull = GPIO_PULLUP;
  HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);

  /* Configure PD12 and PD13 as input */
  GPIO_InitStruct.Pin = GPIO_PIN_12|GPIO_PIN_13;
  GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
  GPIO_InitStruct.Pull = GPIO_PULLUP;
  HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);
}

The GPIO initialization function configures input pins for the button and encoder.

5. Technical Details

5.1 Encoder Working Principle

The EC11 encoder is a rotary position sensor that detects rotation direction through the phase difference between two output signals (Phase A and Phase B). When the encoder rotates clockwise, Phase A leads Phase B; when rotating counterclockwise, Phase B leads Phase A.

This project uses a lookup table to detect rotation direction. By reading the states of Phase A and Phase B, it calculates the current state code, then looks up the rotation direction based on the previous state code and current state code.

5.2 PWM Control Principle

PWM (Pulse Width Modulation) is a technique that controls a signal by changing the pulse width. In LED control, the PWM duty cycle (ratio of high-level time to the entire period) determines the LED’s average brightness. Higher duty cycle means brighter LED; lower duty cycle means dimmer LED.

This project uses the TIM10 timer to generate a PWM signal. The timer clock is 84MHz (APB2 bus clock), prescaler is 0, and auto-reload value is 65535, so the PWM frequency is:

PWM frequency = Timer clock / (Prescaler + 1) / (Auto-reload value + 1) = 84MHz / 1 / 65536 ≈ 1281Hz

5.3 FreeRTOS Task Management

FreeRTOS is an open-source real-time operating system that provides task management, queues, semaphores, and other features. This project uses FreeRTOS task management to create three tasks:

Encoder Task: Normal priority, responsible for reading encoder state and calculating rotation direction
KEY Task: Low priority, responsible for detecting button state
LED Task: Low priority, responsible for controlling LED brightness

The task scheduler determines which task gets CPU control based on task priority and state.

5.4 Button Debounce Processing

Buttons generate mechanical bouncing when pressed and released, causing multiple triggers. This project implements software debounce by detecting the sustained duration of the button state to determine whether the button is truly pressed. When the button state is sustained for more than 50ms, the button is considered pressed.

5.5 Inter-Task Communication

The current project uses global variables for inter-task communication. The Encoder task updates the pwm_duty variable, the KEY task updates the led_enabled variable, and the LED task reads these variables to control LED brightness.

6. Workflow

System Initialization:
- Configure system clock
- Initialize GPIO
- Initialize TIM10 timer
- Initialize FreeRTOS
Task Creation:
- Create Encoder task
- Create KEY task
- Create LED task
Task Execution:
- Encoder Task:
  - Read encoder state
  - Calculate rotation direction
  - Adjust PWM duty cycle based on direction
- KEY Task:
  - Detect button state (with debounce)
  - Toggle LED enable state when button is pressed
- LED Task:
  - Control LED brightness based on PWM duty cycle and LED enable state

7. Code Optimization Suggestions

7.1 Use Queues Instead of Global Variables

The current code uses global variables to pass data. It is recommended to use FreeRTOS queues for inter-task communication to improve code reliability and maintainability. For example:

// Create queue
osMessageQueueId_t pwmQueue = osMessageQueueNew(1, sizeof(uint16_t), NULL);

// Send message
osMessageQueuePut(pwmQueue, &pwm_duty, 0, 0);

// Receive message
osMessageQueueGet(pwmQueue, &pwm_duty, NULL, 0);

7.2 Add Parameter Configuration

Parameters like PWM step size and button debounce time can be defined as configurable macros for easy adjustment:

#define PWM_STEP          1000    // PWM change step
#define KEY_DEBOUNCE_MS   50      // Button debounce time
#define ENCODER_DELAY     10      // Encoder detection delay
#define LED_UPDATE_DELAY  50      // LED update delay

7.3 Add Error Handling

Add error handling at critical operations to improve system stability:

if (HAL_TIM_PWM_Start(&htim10, TIM_CHANNEL_1) != HAL_OK)
{
  Error_Handler();
}

7.4 Optimize Task Priority

Adjust task priority according to actual requirements to ensure critical tasks respond in a timely manner:

Encoder Task: Higher priority to ensure timely response to encoder input
KEY Task: Medium priority
LED Task: Lower priority because brightness updates do not require real-time response

7.5 Add Status Indicator

A LED status indicator can be added. For example, when the LED is on, use another LED to indicate the status:

if (led_enabled)
{
  HAL_GPIO_WritePin(GPIOB, GPIO_PIN_9, GPIO_PIN_SET);
}
else
{
  HAL_GPIO_WritePin(GPIOB, GPIO_PIN_9, GPIO_PIN_RESET);
}

8. Testing Methods

Basic Function Test:
- Rotate the encoder and observe LED brightness changes
- Press the encoder’s button and observe the LED on/off state
Performance Test:
- Quickly rotate the encoder to test system response speed
- Press the button multiple times to test the debounce function
Boundary Test:
- Rotate the encoder to minimum brightness and test whether it stops correctly
- Rotate the encoder to maximum brightness and test whether it stops correctly
Stability Test:
- Run for a long time to test system stability
- Perform repeated operations to test system reliability

9. Project Structure

FreeRTOS\F02_Encoder_PWM_LED_1\
├── Core\
│   ├── Inc\
│   │   ├── main.h
│   │   └── stm32f4xx_hal_conf.h
│   └── Src\
│       ├── main.c
│       ├── stm32f4xx_hal_msp.c
│       ├── stm32f4xx_it.c
│       └── sysmem.c
├── Drivers\
│   ├── CMSIS\
│   │   ├── Device\
│   │   └── Include\
│   └── STM32F4xx_HAL_Driver\
│       ├── Inc\
│       └── Src\
├── FreeRTOS\
│   ├── CMSIS_RTOS_V2\
│   └── Source\
└── README.md

10. Key Technical Points

FreeRTOS Task Creation and Management: Use osThreadNew to create tasks and set task priority and stack size.
Encoder Reading Algorithm: Use a lookup table to implement encoder rotation direction detection, improving detection speed and accuracy.
PWM Control: Use TIM10 PWM mode to control LED brightness, achieving smooth brightness adjustment.
Button Debounce: Implement software debounce to improve button detection reliability.
Inter-Task Communication: Currently uses global variables. It is recommended to use queues for inter-task communication.
STM32 HAL Library Usage: Use HAL library functions to configure GPIO, timers, and other peripherals.
Code Standards: Follow STM32 HAL library code standards and comment style.

11. Project Features

Modular Design: Functions are divided into three independent tasks, making it easy to maintain and extend.
Real-time Response: FreeRTOS achieves real-time task scheduling, ensuring encoder input and button operations respond promptly.
Smooth Control: PWM technology achieves smooth LED brightness adjustment, avoiding sudden brightness changes.
Reliability: Button debounce is implemented, improving system reliability.
Scalability: The code structure is clear, making it easy to add new features or modify existing ones.

12. Application Scenarios

The EC11 encoder-controlled LED brightness technology implemented in this project can be applied to various scenarios:

Lighting Control: Adjust indoor lighting brightness
Device Parameter Adjustment: Adjust various device parameters such as volume and speed
Dashboard Control: Control dashboard display brightness
Smart Home: Adjust smart lamp brightness
Industrial Control: Adjust device output power

13. Summary

This project successfully implements EC11 encoder-controlled LED brightness functionality, achieving non-blocking operation through FreeRTOS task management. The project structure is clear, the code is concise, and the functionality is complete. It can serve as a reference example for learning FreeRTOS and STM32 PWM control.

Through this project, you can master the following technologies:

GPIO and timer configuration for STM32 microcontrollers
FreeRTOS task creation and management
Encoder reading and rotation direction detection
PWM control technology
Button debounce processing
Inter-task communication methods

These technologies are very practical in embedded system development and can be applied to various scenarios requiring user input and output control.

嘉立创筑基派FreeRTOS编码器+PWM+LED

Thu, 02 Apr 2026 14:48:50 GMT

EC11 编码器控制 LED 亮度项目

1. 项目概述

本项目基于 STM32F407 微控制器和 FreeRTOS 操作系统，实现了使用 EC11 编码器控制 LED 亮度的功能。项目通过三个任务（线程）协同工作，实现了无阻塞的编码器读取、按键检测和 LED 亮度控制。

2. 技术框架

2.1 硬件平台

微控制器：STM32F407
编码器：EC11 旋转编码器（连接到 PD12 和 PD13）
按键：PC13（编码器自带的按下功能）
LED：PB8（通过 PWM 控制亮度）
定时器：TIM10（用于 PWM 输出）

2.2 软件架构

开发环境：STM32CubeMX + VScode
操作系统：FreeRTOS
库函数：STM32 HAL 库
代码结构：标准 STM32 HAL 项目结构 + FreeRTOS 任务管理

3. 代码结构分析

3.1 头文件和包含部分

#include "main.h"
#include "cmsis_os.h"

包含了主头文件和 CMSIS-OS 头文件，其中定义了 STM32 HAL 库的基本配置和 FreeRTOS 的相关函数。

3.2 全局变量定义

/* USER CODE BEGIN PV */
uint8_t led_enabled = 1;
uint16_t pwm_duty = 0;
const uint16_t pwm_arr = 65535;
const uint16_t pwm_step = 1000;
/* USER CODE END PV */

led_enabled：LED 使能状态（1=开启，0=关闭）
pwm_duty：PWM 占空比（0-65535）
pwm_arr：PWM 自动重载值（定时器周期）
pwm_step：每次旋转编码器的 PWM 变化步长

3.3 任务句柄定义

/* USER CODE BEGIN EV */
osThreadId_t EncoderTaskHandle;
osThreadId_t KEYTaskHandle;
osThreadId_t LEDTaskHandle;
/* USER CODE END EV */

定义了三个任务的句柄，用于任务管理。

3.4 任务函数原型

/* USER CODE BEGIN FunctionPrototypes */
void EncoderTask(void *argument);
void KEYTask(void *argument);
void LEDTask(void *argument);
/* USER CODE END FunctionPrototypes */

3.5 编码器状态表

const int8_t enc_table[16] = {
    0, -1,  1,  0,
    1,  0,  0, -1,
   -1,  0,  0,  1,
    0,  1, -1,  0
};

编码器旋转方向检测的状态表，用于查表法计算旋转方向。

4. 主要功能实现

4.1 主函数

int main(void)
{
  /* 系统初始化 */
  HAL_Init();
  SystemClock_Config();
  MX_GPIO_Init();
  MX_TIM10_Init();
  MX_FREERTOS_Init();

  /* 启动PWM输出 */
  if (HAL_TIM_PWM_Start(&htim10, TIM_CHANNEL_1) != HAL_OK)
  {
    Error_Handler();
  }

  /* 启动任务调度器 */
  osKernelStart();

  /* 永远不会执行到这里 */
  while (1)
  {
  }
}

主函数首先进行系统初始化，然后配置 GPIO、TIM10 定时器和 FreeRTOS，启动 PWM 输出和任务调度器。

4.2 任务初始化

void MX_FREERTOS_Init(void)
{
  /* 创建任务 */
  EncoderTaskHandle = osThreadNew(EncoderTask, NULL, &EncoderTask_attributes);
  KEYTaskHandle = osThreadNew(KEYTask, NULL, &KEYTask_attributes);
  LEDTaskHandle = osThreadNew(LEDTask, NULL, &LEDTask_attributes);
}

使用osThreadNew函数创建三个任务，并设置任务属性。

4.3 Encoder 任务

void EncoderTask(void *argument)
{
  static uint8_t enc_last = 0;
  uint8_t enc_current;
  int8_t enc_dir;

  for (;;)
  {
    /* 读取编码器状态 */
    enc_current = ((GPIOE->IDR & GPIO_PIN_12) >> 12) | ((GPIOE->IDR & GPIO_PIN_13) >> 12);
    
    /* 计算旋转方向 */
    enc_dir = enc_table[(enc_last << 2) | enc_current];
    enc_last = enc_current;
    
    /* 根据方向调整PWM占空比 */
    if (enc_dir > 0 && pwm_duty < pwm_arr)
    {
      pwm_duty += pwm_step;
      if (pwm_duty > pwm_arr) pwm_duty = pwm_arr;
    }
    else if (enc_dir < 0 && pwm_duty > 0)
    {
      pwm_duty -= pwm_step;
      if (pwm_duty > pwm_arr) pwm_duty = 0; // 防止溢出
    }
    
    osDelay(10);
  }
}

Encoder 任务使用查表法检测编码器旋转方向，并根据方向调整 PWM 占空比。

4.4 KEY 任务

void KEYTask(void *argument)
{
  static uint8_t key_state = 0;
  static uint32_t key_time = 0;

  for (;;)
  {
    /* 按键防抖处理 */
    if (HAL_GPIO_ReadPin(GPIOC, GPIO_PIN_13) == GPIO_PIN_RESET)
    {
      if (key_state == 0)
      {
        key_state = 1;
        key_time = osKernelGetTickCount();
      }
      else if (key_state == 1)
      {
        if (osKernelGetTickCount() - key_time > 50)
        {
          key_state = 2;
          /* 切换LED使能状态 */
          led_enabled = !led_enabled;
        }
      }
    }
    else
    {
      key_state = 0;
    }
    
    osDelay(10);
  }
}

KEY 任务实现了按键的防抖处理，当检测到按键按下时，切换 LED 的使能状态。

4.5 LED 任务

void LEDTask(void *argument)
{
  for (;;)
  {
    /* 根据PWM占空比和LED使能状态控制LED亮度 */
    uint16_t out = led_enabled ? (uint16_t)(pwm_arr - pwm_duty) : pwm_arr;
    __HAL_TIM_SET_COMPARE(&htim10, TIM_CHANNEL_1, out);
    
    osDelay(50);
  }
}

LED 任务通过 TIM10 的 PWM 输出控制 LED 亮度。由于 PB8 是低电平有效，所以需要将 PWM 占空比取反。

4.6 TIM10 定时器初始化

static void MX_TIM10_Init(void)
{
  TIM_OC_InitTypeDef sConfigOC = {0};

  htim10.Instance = TIM10;
  htim10.Init.Prescaler = 0;
  htim10.Init.CounterMode = TIM_COUNTERMODE_UP;
  htim10.Init.Period = 65535;
  htim10.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
  htim10.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE;
  if (HAL_TIM_Base_Init(&htim10) != HAL_OK)
  {
    Error_Handler();
  }
  if (HAL_TIM_PWM_Init(&htim10) != HAL_OK)
  {
    Error_Handler();
  }
  sConfigOC.OCMode = TIM_OCMODE_PWM1;
  sConfigOC.Pulse = 0;
  sConfigOC.OCPolarity = TIM_OCPOLARITY_HIGH;
  sConfigOC.OCFastMode = TIM_OCFAST_DISABLE;
  if (HAL_TIM_PWM_ConfigChannel(&htim10, &sConfigOC, TIM_CHANNEL_1) != HAL_OK)
  {
    Error_Handler();
  }
  HAL_TIM_MspPostInit(&htim10);
}

TIM10 定时器初始化函数配置了定时器的基本参数和 PWM 输出通道。

4.7 GPIO 初始化

static void MX_GPIO_Init(void)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};

  /* GPIO Ports Clock Enable */
  __HAL_RCC_GPIOC_CLK_ENABLE();
  __HAL_RCC_GPIOD_CLK_ENABLE();
  __HAL_RCC_GPIOB_CLK_ENABLE();

  /* 配置PC13为输入 */
  GPIO_InitStruct.Pin = GPIO_PIN_13;
  GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
  GPIO_InitStruct.Pull = GPIO_PULLUP;
  HAL_GPIO_Init(GPIOC, &GPIO_InitStruct);

  /* 配置PD12和PD13为输入 */
  GPIO_InitStruct.Pin = GPIO_PIN_12|GPIO_PIN_13;
  GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
  GPIO_InitStruct.Pull = GPIO_PULLUP;
  HAL_GPIO_Init(GPIOD, &GPIO_InitStruct);
}

GPIO 初始化函数配置了按键和编码器的输入引脚。

5. 技术细节

5.1 编码器工作原理

EC11 编码器是一种旋转式位置传感器，通过两个输出信号（A 相和 B 相）的相位差来检测旋转方向。当编码器顺时针旋转时，A 相领先 B 相；当编码器逆时针旋转时，B 相领先 A 相。

本项目使用查表法检测旋转方向，通过读取 A 相和 B 相的状态，计算出当前状态码，然后根据上一次的状态码和当前状态码查表得到旋转方向。

5.2 PWM 控制原理

PWM（脉冲宽度调制）是一种通过改变脉冲宽度来控制信号的技术。在 LED 控制中，PWM 的占空比（高电平时间与整个周期的比值）决定了 LED 的平均亮度。占空比越高，LED 越亮；占空比越低，LED 越暗。

本项目使用 TIM10 定时器生成 PWM 信号，定时器时钟为 84MHz（APB2 总线时钟），预分频器为 0，自动重装载值为 65535，因此 PWM 频率为：

PWM频率 = 定时器时钟 / (预分频器+1) / (自动重装载值+1) = 84MHz / 1 / 65536 ≈ 1281Hz

5.3 FreeRTOS 任务管理

FreeRTOS 是一个开源的实时操作系统，提供了任务管理、队列、信号量等功能。本项目使用 FreeRTOS 的任务管理功能，创建了三个任务：

Encoder 任务：优先级正常，负责读取编码器状态并计算旋转方向
KEY 任务：优先级低，负责检测按键状态
LED 任务：优先级低，负责控制 LED 亮度

任务调度器根据任务优先级和状态，决定哪个任务获得 CPU 控制权。

5.4 按键防抖处理

按键在按下和释放时会产生机械抖动，导致多次触发。本项目实现了软件防抖，通过检测按键状态的持续时间来判断按键是否真正被按下。当按键状态持续 50ms 以上时，才认为按键被按下。

5.5 任务间通信

当前项目使用全局变量进行任务间通信，Encoder 任务更新pwm_duty变量，KEY 任务更新led_enabled变量，LED 任务读取这些变量并控制 LED 亮度。

6. 工作流程

系统初始化：
- 配置系统时钟
- 初始化 GPIO
- 初始化 TIM10 定时器
- 初始化 FreeRTOS
任务创建：
- 创建 Encoder 任务
- 创建 KEY 任务
- 创建 LED 任务
任务执行：
- Encoder 任务：
  - 读取编码器状态
  - 计算旋转方向
  - 根据方向调整 PWM 占空比
- KEY 任务：
  - 检测按键状态（带防抖）
  - 当按键按下时，切换 LED 使能状态
- LED 任务：
  - 根据 PWM 占空比和 LED 使能状态控制 LED 亮度

7. 代码优化建议

7.1 使用队列替代全局变量

当前代码使用全局变量传递数据，建议使用 FreeRTOS 的队列进行任务间通信，提高代码的可靠性和可维护性。例如：

// 创建队列
osMessageQueueId_t pwmQueue = osMessageQueueNew(1, sizeof(uint16_t), NULL);

// 发送消息
osMessageQueuePut(pwmQueue, &pwm_duty, 0, 0);

// 接收消息
osMessageQueueGet(pwmQueue, &pwm_duty, NULL, 0);

7.2 增加参数配置

可以将 PWM 的步长、按键防抖时间等参数定义为可配置的宏，方便调整：

#define PWM_STEP        1000    // PWM变化步长
#define KEY_DEBOUNCE_MS 50      // 按键防抖时间
#define ENCODER_DELAY   10      // 编码器检测延迟
#define LED_UPDATE_DELAY 50     // LED更新延迟

7.3 增加错误处理

在关键操作处增加错误处理，提高系统的稳定性：

if (HAL_TIM_PWM_Start(&htim10, TIM_CHANNEL_1) != HAL_OK)
{
  Error_Handler();
}

7.4 优化任务优先级

根据实际需求调整任务优先级，确保关键任务能够及时响应：

Encoder 任务：优先级较高，确保及时响应编码器输入
KEY 任务：优先级中等
LED 任务：优先级较低，因为亮度更新不需要实时响应

7.5 增加状态指示

可以增加 LED 状态指示，例如当 LED 开启时，使用另一个 LED 指示状态：

if (led_enabled)
{
  HAL_GPIO_WritePin(GPIOB, GPIO_PIN_9, GPIO_PIN_SET);
}
else
{
  HAL_GPIO_WritePin(GPIOB, GPIO_PIN_9, GPIO_PIN_RESET);
}

8. 测试方法

基本功能测试：
- 旋转编码器，观察 LED 亮度变化
- 按下编码器的按键，观察 LED 的开关状态
性能测试：
- 快速旋转编码器，测试系统的响应速度
- 多次按下按键，测试防抖功能
边界测试：
- 旋转编码器到最小亮度，测试是否能正确停止
- 旋转编码器到最大亮度，测试是否能正确停止
稳定性测试：
- 长时间运行，测试系统的稳定性
- 重复操作，测试系统的可靠性

9. 项目结构

FreeRTOS\F02_Encoder_PWM_LED_1\
├── Core\
│   ├── Inc\
│   │   ├── main.h
│   │   └── stm32f4xx_hal_conf.h
│   └── Src\
│       ├── main.c
│       ├── stm32f4xx_hal_msp.c
│       ├── stm32f4xx_it.c
│       └── sysmem.c
├── Drivers\
│   ├── CMSIS\
│   │   ├── Device\
│   │   └── Include\
│   └── STM32F4xx_HAL_Driver\
│       ├── Inc\
│       └── Src\
├── FreeRTOS\
│   ├── CMSIS_RTOS_V2\
│   └── Source\
└── README.md

10. 技术要点

FreeRTOS 任务创建与管理：使用osThreadNew创建任务，设置任务优先级和栈大小。
编码器读取算法：使用查表法实现编码器旋转方向的检测，提高检测速度和准确性。
PWM 控制：使用 TIM10 的 PWM 模式控制 LED 亮度，实现平滑的亮度调节。
按键防抖：实现软件防抖，提高按键检测的可靠性。
任务间通信：当前使用全局变量，建议使用队列进行任务间通信。
STM32 HAL 库使用：使用 HAL 库函数配置 GPIO、定时器等外设。
代码规范：遵循 STM32 HAL 库的代码规范和注释风格。

11. 项目特点

模块化设计：将功能分为三个独立的任务，便于维护和扩展。
实时响应：使用 FreeRTOS 实现实时任务调度，确保编码器输入和按键操作能够及时响应。
平滑控制：通过 PWM 技术实现 LED 亮度的平滑调节，避免亮度突变。
可靠性：实现了按键防抖，提高了系统的可靠性。
可扩展性：代码结构清晰，便于添加新的功能或修改现有功能。

12. 应用场景

本项目实现的 EC11 编码器控制 LED 亮度技术可以应用于多种场景：

照明控制：调节室内灯光亮度
设备参数调节：调节设备的各种参数，如音量、速度等
仪表盘控制：控制仪表盘的显示亮度
智能家居：调节智能灯具的亮度
工业控制：调节设备的输出功率

13. 总结

本项目成功实现了使用 EC11 编码器控制 LED 亮度的功能，通过 FreeRTOS 的任务管理实现了无阻塞的操作。项目结构清晰，代码简洁，功能完整，可以作为学习 FreeRTOS 和 STM32 PWM 控制的参考示例。

通过本项目的学习，可以掌握以下技术：

STM32 微控制器的 GPIO 和定时器配置
FreeRTOS 任务创建和管理
编码器读取和旋转方向检测
PWM 控制技术
按键防抖处理
任务间通信方法

这些技术在嵌入式系统开发中非常实用，可以应用于各种需要用户输入和输出控制的场景。

JLC Foundation Board PWM LED Demo

Thu, 02 Apr 2026 14:38:52 GMT

PWM LED Control Project Documentation

1. Project Overview

This project is an LED brightness control example based on the STM32F407 microcontroller. It uses PWM (Pulse Width Modulation) technology to achieve dynamic LED brightness adjustment. The project is developed using the STM32 HAL library, uses the TIM10 timer to generate PWM signals, controls LED brightness by changing the duty cycle, and implements an LED breathing light effect.

2. Technical Framework

2.1 Hardware Platform

Microcontroller: STM32F407
Timer: TIM10
PWM Output Pin: TIM10_CH1

2.2 Software Architecture

Development Environment: STM32CubeMX + VScode
Library: STM32 HAL library
Code Structure: Standard STM32 HAL project structure

3. Code Structure Analysis

3.1 Header Files

#include "main.h"

Includes the main header file, which defines the basic configuration and function declarations of the STM32 HAL library.

3.2 Variable Definitions

TIM_HandleTypeDef htim10;

Defines the handle for the TIM10 timer, used for timer operations.

3.3 Constant Definitions

static const uint16_t LED_PWM_DUTY_MAX = 60000U;   // PWM maximum duty cycle value
static const uint16_t LED_PWM_DUTY_MIN = 0U;       // PWM minimum duty cycle value
static const uint16_t LED_FADE_STEPS = 70U;        // Breathing light fade steps
static const uint32_t LED_FADE_STEP_MS = 8U;        // Delay time per step (milliseconds)
static const uint32_t LED_PEAK_HOLD_MS = 160U;     // Maximum brightness hold time (milliseconds)
static const uint32_t LED_VALLEY_HOLD_MS = 120U;   // Minimum brightness hold time (milliseconds)

These constants define various parameters for the LED breathing light effect, including PWM duty cycle range, fade steps, and timing parameters.

3.4 Function Prototypes

void SystemClock_Config(void);              // System clock configuration
static void MX_GPIO_Init(void);             // GPIO initialization
static void MX_TIM10_Init(void);            // TIM10 timer initialization
static void LED_SetBrightness(uint16_t duty);      // Set LED brightness
static void LED_GentleFade(uint16_t start_duty, uint16_t end_duty);  // LED fade effect

4. Main Function Implementation

4.1 Main Function

int main(void)
{
  // System initialization
  HAL_Init();
  SystemClock_Config();

  // Peripheral initialization
  MX_GPIO_Init();
  MX_TIM10_Init();

  // Start PWM output
  if (HAL_TIM_PWM_Start(&htim10, TIM_CHANNEL_1) != HAL_OK)
  {
    Error_Handler();
  }
  LED_SetBrightness(LED_PWM_DUTY_MIN);

  // Main loop
  while (1)
  {
    LED_GentleFade(LED_PWM_DUTY_MIN, LED_PWM_DUTY_MAX);
    HAL_Delay(LED_PEAK_HOLD_MS);
    LED_GentleFade(LED_PWM_DUTY_MAX, LED_PWM_DUTY_MIN);
    HAL_Delay(LED_VALLEY_HOLD_MS);
  }
}

The main function first performs system initialization, then configures GPIO and TIM10 timer, and starts PWM output. In the main loop, the LED breathing light mode is achieved through the LED_GentleFade function to create smooth brightness transitions.

4.2 System Clock Configuration

void SystemClock_Config(void)
{
  RCC_OscInitTypeDef RCC_OscInitStruct = {0};
  RCC_ClkInitTypeDef RCC_ClkInitStruct = {0};

  // Configure main internal regulator output voltage
  __HAL_RCC_PWR_CLK_ENABLE();
  __HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE1);

  // Initialize RCC oscillator
  RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
  RCC_OscInitStruct.HSEState = RCC_HSE_ON;
  RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
  RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
  RCC_OscInitStruct.PLL.PLLM = 4;
  RCC_OscInitStruct.PLL.PLLN = 168;
  RCC_OscInitStruct.PLL.PLLP = RCC_PLLP_DIV2;
  RCC_OscInitStruct.PLL.PLLQ = 4;
  if (HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK)
  {
    Error_Handler();
  }

  // Initialize CPU, AHB, and APB bus clocks
  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_DIV4;
  RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV2;

  if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_5) != HAL_OK)
  {
    Error_Handler();
  }
}

The system clock configuration function uses HSE (external high-speed clock) as the PLL clock source and generates a 168MHz system clock through PLL multiplication. It configures clock dividers for CPU, AHB, and APB buses, achieving clock distribution for the entire system.

4.3 TIM10 Timer Initialization

static void MX_TIM10_Init(void)
{
  TIM_OC_InitTypeDef sConfigOC = {0};

  htim10.Instance = TIM10;
  htim10.Init.Prescaler = 0;
  htim10.Init.CounterMode = TIM_COUNTERMODE_UP;
  htim10.Init.Period = 65535;
  htim10.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
  htim10.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE;
  if (HAL_TIM_Base_Init(&htim10) != HAL_OK)
  {
    Error_Handler();
  }
  if (HAL_TIM_PWM_Init(&htim10) != HAL_OK)
  {
    Error_Handler();
  }
  sConfigOC.OCMode = TIM_OCMODE_PWM1;
  sConfigOC.Pulse = LED_PWM_DUTY_MAX;
  sConfigOC.OCPolarity = TIM_OCPOLARITY_HIGH;
  sConfigOC.OCFastMode = TIM_OCFAST_DISABLE;
  if (HAL_TIM_PWM_ConfigChannel(&htim10, &sConfigOC, TIM_CHANNEL_1) != HAL_OK)
  {
    Error_Handler();
  }
  HAL_TIM_MspPostInit(&htim10);
}

The TIM10 timer initialization function configures the timer’s basic parameters and PWM output channel. Key parameters include:

Prescaler: 0
Counter Mode: Up counting
Auto-reload Value (Period): 65535
PWM Mode: PWM1 mode
Output Polarity: Active high

4.4 GPIO Initialization

static void MX_GPIO_Init(void)
{
  /* GPIO Ports Clock Enable */
  __HAL_RCC_GPIOH_CLK_ENABLE();
  __HAL_RCC_GPIOA_CLK_ENABLE();
  __HAL_RCC_GPIOB_CLK_ENABLE();
}

The GPIO initialization function enables GPIO port clocks to provide clock support for the PWM output pin.

4.5 LED Brightness Setting Function

static void LED_SetBrightness(uint16_t duty)
{
  __HAL_TIM_SET_COMPARE(&htim10, TIM_CHANNEL_1, duty);
}

The LED_SetBrightness function changes the PWM duty cycle by setting the comparison register (CCR) value of TIM10 channel 1, thereby controlling LED brightness. Higher duty cycle means brighter LED; lower duty cycle means dimmer LED.

4.6 LED Fade Effect Function

static void LED_GentleFade(uint16_t start_duty, uint16_t end_duty)
{
  const int32_t delta = (int32_t)end_duty - start_duty;

  for (uint16_t step = 0; step <= LED_FADE_STEPS; ++step)
  {
    const uint16_t duty = (uint16_t)(start_duty + (delta * step) / LED_FADE_STEPS);
    LED_SetBrightness(duty);
    HAL_Delay(LED_FADE_STEP_MS);
  }
}

The LED_GentleFade function implements smooth LED brightness fading. It starts from the initial duty cycle value and gradually changes to the target duty cycle value, with brief delays between each step. By adjusting LED_FADE_STEPS and LED_FADE_STEP_MS parameters, the speed and smoothness of the fade can be changed.

4.7 Error Handler Function

void Error_Handler(void)
{
  /* User can add his own implementation to report the HAL error return state */
  __disable_irq();
  while (1)
  {
  }
}

The error handler function is called when an error occurs. It disables interrupts and enters an infinite loop to prevent the system from continuing to run.

5. Technical Details

5.1 PWM Principle

5.2 TIM10 Timer Configuration

TIM10 is a 16-bit timer on the STM32F407 with the following features:

16-bit auto-reload counter
Up to 4 independent channels (IC, OC, or PWM)
Programmable prescaler
Repetition counter

In this project, TIM10 is configured in PWM mode using channel 1 for PWM output. The timer clock is 84MHz (APB2 bus clock), prescaler is 0, and auto-reload value is 65535, so the PWM frequency is: PWM frequency = Timer clock / (Prescaler + 1) / (Auto-reload value + 1) = 84MHz / 1 / 65536 ≈ 1281Hz

5.3 Breathing Light Effect Implementation

The breathing light effect is achieved through the LED_GentleFade function, which fades LED brightness from minimum to maximum and back from maximum to minimum. The fade process is divided into multiple steps with brief delays between each step, creating a smooth brightness change effect.

The number of fade steps and the delay time per step determine the speed and smoothness of the breathing light. More steps and longer delay per step result in a smoother but slower breathing light effect; fewer steps and shorter delays result in a more pronounced but faster effect.

5.4 STM32 HAL Library Usage

This project is developed using the STM32 HAL library, which provides rich functions and structures that simplify peripheral configuration and usage. For example:

HAL_Init(): Initialize the HAL library
HAL_RCC_OscConfig(): Configure system clock source
HAL_RCC_ClockConfig(): Configure system clocks
HAL_TIM_Base_Init(): Initialize timer basic functions
HAL_TIM_PWM_Init(): Initialize timer PWM functions
HAL_TIM_PWM_Start(): Start PWM output
__HAL_TIM_SET_COMPARE(): Set timer comparison value

5.5 Code Structure and Comment Standards

This project follows the code structure generated by STM32CubeMX, using specific comment markers for user code areas, such as:

/* USER CODE BEGIN Header / and / USER CODE END Header */
/* USER CODE BEGIN Includes / and / USER CODE END Includes */
/* USER CODE BEGIN 2 / and / USER CODE END 2 */
/* USER CODE BEGIN 3 / and / USER CODE END 3 */
/* USER CODE BEGIN 4 / and / USER CODE END 4 */

This structure ensures that user code is not overwritten when regenerating code, improving code maintainability.

6. Project Features

Modular Design: LED control functionality is encapsulated in independent functions, making it easy to maintain and extend.
Parameterized Configuration: Constants are used to define breathing light effect parameters for easy adjustment.
Error Handling: Basic error handling mechanism is implemented.
Code Standards: Follows STM32 HAL library code standards and comment style.
Scalability: The code structure is clear, making it easy to add new features or modify existing ones.

7. Application Scenarios

The PWM LED control technology implemented in this project can be applied to various scenarios:

LED lighting control
Indicator brightness adjustment
Decorative lighting effects
Backlight brightness adjustment
Signal light control

8. Summary

This project demonstrates how to use the STM32F407 timer’s PWM function to achieve LED brightness control and breathing light effects. Through reasonable timer parameter configuration and writing control functions, smooth LED brightness adjustment is achieved. The code structure is clear, follows STM32 HAL library standards, and has good maintainability and scalability. This example can serve as a reference for learning STM32 timer PWM functions and LED control technology.

Integer Overflow

Thu, 02 Apr 2026 13:02:17 GMT

Integer Overflow Technical Notes

Core Concepts

Integer overflow occurs when the result of an arithmetic operation exceeds the representable range of the data type.

Unsigned integer overflow: In C/C++ standards, this is legal, and the result undergoes wrap-around — jumping from the maximum value to the minimum (or vice versa), causing logical errors.
Signed integer overflow: This is undefined behavior (UB), which may cause program crashes, calculation errors, or security vulnerabilities.

Example type ranges: The range of uint16_t (16-bit unsigned integer) is 0 ~ 65535 (216−12^{16} - 1216−1).

Typical Scenario Analysis: PWM Duty Cycle Gradient

In embedded development, calculating the difference between two unsigned integers (such as PWM duty cycle variation) is a common scenario. If handled improperly, overflow is highly likely to occur.

Incorrect Approach: Direct Subtraction

When end_duty < start_duty, unsigned subtraction causes underflow.

uint16_t start = 1000;
uint16_t end = 500;

// Incorrect approach
uint16_t delta1 = end - start; 
// 500 - 1000 = -500
// But uint16_t cannot store negative numbers, it wraps automatically: 65536 - 500 = 65036 (completely wrong)

This is a typical unsigned integer overflow.

// Correct approach
int32_t delta2 = (int32_t)end - start; 
// First cast end to 32-bit signed integer, the result is also signed
// Can now store negative numbers, result = -500 (correct)

Common Overflow Prevention Techniques

1. Type Promotion

// Addition overflow protection
uint16_t a = 60000, b = 60000;
uint32_t sum = (uint32_t)a + b;  // Promote to 32-bit before adding
if (sum > 65535) {
    // Handle overflow
}

// Multiplication overflow protection
uint16_t x = 1000, y = 1000;
uint32_t product = (uint32_t)x * y;  // 1,000,000 won't overflow 32-bit

2. Pre-check

uint16_t add_with_check(uint16_t a, uint16_t b) {
    if (a > UINT16_MAX - b) {
        // Will overflow, return max value or throw error
        return UINT16_MAX;
    }
    return a + b;
}

// Multiplication pre-check
uint16_t mul_with_check(uint16_t a, uint16_t b) {
    if (a != 0 && b > UINT16_MAX / a) {
        return UINT16_MAX;  // Overflow
    }
    return a * b;
}

3. Use Larger Intermediate Types

// Example from your code
const int32_t delta = (int32_t)end_duty - start_duty;

// Subsequent calculation
uint16_t duty = (uint16_t)(start_duty + (delta * step) / LED_FADE_STEPS);
//                   ^^^^^ Convert back to uint16_t in the end
//                   delta * step max approx 60000 * 70 = 4.2M< 2^31, safe

4. Saturation Arithmetic

uint16_t saturated_add(uint16_t a, uint16_t b) {
    uint32_t result = (uint32_t)a + b;
    return (result > UINT16_MAX) ? UINT16_MAX : (uint16_t)result;
}

// For PWM duty cycle limiting
uint16_t duty = saturated_add(current_duty, increment);

5. Compiler Built-in Overflow Checks (GCC/Clang)

#include <stdint.h>

int32_t multiply_with_overflow_check(int32_t a, int32_t b) {
    int32_t result;
    if (__builtin_mul_overflow(a, b, &result)) {
        // Overflow occurred
        return INT32_MAX;
    }
    return result;
}

// Check addition
int32_t add_with_overflow_check(int32_t a, int32_t b) {
    int32_t result;
    if (__builtin_add_overflow(a, b, &result)) {
        return INT32_MAX;
    }
    return result;
}

6. Special Techniques for Timer Scenarios

// Handling timer counter overflow (common in encoders, input capture)
static uint16_t last_count = 0;
static uint16_t overflow_count = 0;

void timer_irq_handler(void) {
    uint16_t current_count = TIM2->CNT;
    
    // Detect underflow (decrementing count)
    if (current_count > last_count) {
        overflow_count++;  // Handle overflow
    }
    
    // Calculate actual 32-bit count value
    uint32_t real_count = (overflow_count << 16) | current_count;
    
    last_count = current_count;
}

Complete Overflow Prevention Analysis of Your Code

static void LED_GentleFade(uint16_t start_duty, uint16_t end_duty)
{
    const int32_t delta = (int32_t)end_duty - start_duty;  // Prevent subtraction overflow
    
    for (uint16_t step = 0; step <= LED_FADE_STEPS; ++step)
    {
        // Dangerous calculation: (delta * step) / LED_FADE_STEPS
        // delta max 60000, step max 70 → product 4.2M
        // int32_t max 2.1B, so it's safe
        const uint16_t duty = (uint16_t)(start_duty + (delta * step) / LED_FADE_STEPS);
        //            ^^^^^ Final result range 0~60000, converting back to uint16_t is safe
        
        LED_SetBrightness(duty);
        HAL_Delay(LED_FADE_STEP_MS);
    }
}

Potential risks (already avoided):

If LED_FADE_STEPS is changed to 1000, delta * step max is 60M, still safe
If LED_PWM_DUTY_MAX is changed to 600000 (exceeding uint16_t), the code will have problems

Best Practices Summary

Scenario	Recommended Technique
Subtraction may result in negative	Promote to signed type `(int32_t)a - b`
Adding two small integers	Promote to larger type `(uint32_t)a + b`
Multiplication may overflow	Pre-check `if (a > MAX / b)`
Loop accumulation	Use larger type for accumulation, truncate at the end
Time difference calculation	Use unsigned subtraction (leveraging wrap-around) with overflow flag
PID/filter calculation	Use floating point or fixed point with saturation

Utility Macros

// Safe addition macro (saturation)
#define SAFE_ADD_U16(a, b) ((uint16_t)(((uint32_t)(a) + (b)) > UINT16_MAX ? UINT16_MAX : ((a) + (b))))

// Safe subtraction (with type promotion)
#define SAFE_SUB_U16(a, b) ((int32_t)(a) - (int32_t)(b))

// Check if addition overflows
#define ADD_OVERFLOW_U16(a, b) (((uint32_t)(a) + (b)) > UINT16_MAX)

// Usage example
uint16_t pwm = 60000;
uint16_t inc = 10000;

if (ADD_OVERFLOW_U16(pwm, inc)) {
    pwm = UINT16_MAX;  // Saturate to max value
} else {
    pwm += inc;
}

整形溢出_IntegerOverflow

Thu, 02 Apr 2026 13:02:17 GMT

整数溢出 (Integer Overflow) 技术笔记

核心概念

整数溢出是指算术运算的结果超出了数据类型所能表示的数值范围。

无符号整数溢出：在 C/C++ 标准中是合法的，结果会发生回绕 (Wrap-around)，即从最大值跳变到最小值（或反之），导致逻辑错误。
有符号整数溢出：属于未定义行为 (Undefined Behavior)，可能导致程序崩溃、计算错误或安全漏洞。

示例类型范围：uint16_t (16 位无符号整数) 的取值范围为 0 ~ 65535 (216−12^{16} - 1216−1)。

典型场景分析：PWM 占空比渐变

在嵌入式开发中，计算两个无符号整数的差值（如 PWM 占空比的变化量）是常见场景。若处理不当，极易引发溢出。

❌ 错误做法：直接相减

当 end_duty < start_duty 时，无符号减法会导致向下溢出。

uint16_t start = 1000;
uint16_t end = 500;

// 错误做法
uint16_t delta1 = end - start; 
// 500 - 1000 = -500
// 但 uint16_t 不能存负数，会自动回绕：65536 - 500 = 65036（完全错误）

这就是典型的无符号整数溢出。

// 正确做法
int32_t delta2 = (int32_t)end - start; 
// 先把 end 强转为 32位有符号整数，运算结果也是有符号数
// 可以正常存储负数，结果 = -500（正确）

️ 常见防溢出技巧

1. 类型提升（Type Promotion）

// 加法溢出防护
uint16_t a = 60000, b = 60000;
uint32_t sum = (uint32_t)a + b;  // 提升到32位再相加
if (sum > 65535) {
    // 处理溢出
}

// 乘法溢出防护
uint16_t x = 1000, y = 1000;
uint32_t product = (uint32_t)x * y;  // 1,000,000 不会溢出32位

2. 预检查（Pre-check）

uint16_t add_with_check(uint16_t a, uint16_t b) {
    if (a > UINT16_MAX - b) {
        // 会溢出，返回最大值或报错
        return UINT16_MAX;
    }
    return a + b;
}

// 乘法预检查
uint16_t mul_with_check(uint16_t a, uint16_t b) {
    if (a != 0 && b > UINT16_MAX / a) {
        return UINT16_MAX;  // 溢出
    }
    return a * b;
}

3. 使用更大的中间类型

// 你的代码中的例子
const int32_t delta = (int32_t)end_duty - start_duty;

// 后续计算
uint16_t duty = (uint16_t)(start_duty + (delta * step) / LED_FADE_STEPS);
//                   ^^^^^ 最终转回 uint16_t
//                   delta * step 最大约 60000 * 70 = 4.2M < 2^31，安全

4. 饱和运算（Saturation）

uint16_t saturated_add(uint16_t a, uint16_t b) {
    uint32_t result = (uint32_t)a + b;
    return (result > UINT16_MAX) ? UINT16_MAX : (uint16_t)result;
}

// 用于PWM占空比限制
uint16_t duty = saturated_add(current_duty, increment);

5. 使用编译器内置溢出检查（GCC/Clang）

#include <stdint.h>

int32_t multiply_with_overflow_check(int32_t a, int32_t b) {
    int32_t result;
    if (__builtin_mul_overflow(a, b, &result)) {
        // 溢出发生了
        return INT32_MAX;
    }
    return result;
}

// 检查加法
int32_t add_with_overflow_check(int32_t a, int32_t b) {
    int32_t result;
    if (__builtin_add_overflow(a, b, &result)) {
        return INT32_MAX;
    }
    return result;
}

6. 定时器场景的特殊技巧

// 处理定时器计数器溢出（常见于编码器、输入捕获）
static uint16_t last_count = 0;
static uint16_t overflow_count = 0;

void timer_irq_handler(void) {
    uint16_t current_count = TIM2->CNT;
    
    // 检测向下溢出（递减计数）
    if (current_count > last_count) {
        overflow_count++;  // 处理溢出
    }
    
    // 计算实际32位计数值
    uint32_t real_count = (overflow_count << 16) | current_count;
    
    last_count = current_count;
}

你的代码中的完整防溢出分析

static void LED_GentleFade(uint16_t start_duty, uint16_t end_duty)
{
    const int32_t delta = (int32_t)end_duty - start_duty;  // ✅ 防止减法溢出
    
    for (uint16_t step = 0; step <= LED_FADE_STEPS; ++step)
    {
        // 危险计算：(delta * step) / LED_FADE_STEPS
        // delta 最大 60000, step 最大 70 → 乘积 4.2M
        // int32_t 最大 2.1B，所以安全
        const uint16_t duty = (uint16_t)(start_duty + (delta * step) / LED_FADE_STEPS);
        //            ^^^^^ 最终结果范围 0~60000，转回 uint16_t 安全
        
        LED_SetBrightness(duty);
        HAL_Delay(LED_FADE_STEP_MS);
    }
}

潜在风险（已避免）：

如果 LED_FADE_STEPS 改成 1000，delta * step 最大 60M，仍然安全
如果 LED_PWM_DUTY_MAX 改成 600000（超过 uint16_t），代码会出问题

最佳实践总结

场景	推荐技巧
减法可能导致负数	提升到有符号类型 `(int32_t)a - b`
两个小整数相加	提升到更大类型 `(uint32_t)a + b`
乘法可能溢出	预检查 `if (a > MAX / b)`
循环累加	使用更大类型累加，最后再截断
时间差值计算	使用无符号减法（利用回绕特性）配合溢出标志
PID/滤波计算	使用浮点或定点数并做饱和处理

实用工具宏

// 安全加法宏（饱和）
#define SAFE_ADD_U16(a, b) ((uint16_t)(((uint32_t)(a) + (b)) > UINT16_MAX ? UINT16_MAX : ((a) + (b))))

// 安全减法（带符号提升）
#define SAFE_SUB_U16(a, b) ((int32_t)(a) - (int32_t)(b))

// 检查加法是否溢出
#define ADD_OVERFLOW_U16(a, b) (((uint32_t)(a) + (b)) > UINT16_MAX)

// 使用示例
uint16_t pwm = 60000;
uint16_t inc = 10000;

if (ADD_OVERFLOW_U16(pwm, inc)) {
    pwm = UINT16_MAX;  // 饱和到最大值
} else {
    pwm += inc;
}

JLC Foundation Board LED Demo

Thu, 02 Apr 2026 02:56:51 GMT

JLC Foundation Board LED Demo_1

FreeRTOS Basics and API Guide for STM32 Beginners

Tue, 31 Mar 2026 04:00:00 GMT

FreeRTOS Basics and API Guide for STM32 Beginners

Goal: After reading this guide, you can independently set up a minimal FreeRTOS project with “2 tasks + 1 queue + 1 semaphore”.

1. Establish overall understanding first
1. Task execution states (core)
1. Key concepts: scheduling, Tick, critical section, heap and stack
1. Core API quick reference (native FreeRTOS)
1. From 0 to 1: minimal project mental model
1. Common beginner pitfalls and troubleshooting
1. 5-day beginner practice checklist
1. Native API vs CMSIS-RTOS v2 comparison

1. Establish Overall Understanding First

FreeRTOS is essentially a kernel that does three things for you:

Manage multiple tasks.
Schedule tasks to run based on priority and timing.
Provide inter-task communication mechanisms (queues, semaphores, event groups, etc.).

You can think of it as “a micro operating system kernel on a microcontroller”:

main() does hardware initialization.
Create tasks.
Start the scheduler.
From then on, the kernel takes over CPU allocation.

2. Task Execution States (Core)

2.2 Task State Flow (Visualization)

stateDiagram-v2
    [*] --> Ready
    Ready --> Running:获得CPU
    Running --> Blocked: 等待事件
    Blocked --> Ready: 事件发生
    Running --> Ready: 时间片用尽
    Running --> Suspended: 挂起
    Suspended --> Ready: 恢复

2.3 Most Common Confusion for Beginners

Blocked is “passively waiting for a condition”, it automatically returns to Ready when the condition is met.
Suspended is “manual freezing”, it does not automatically recover.

3. Key Concepts: Scheduling, Tick, Critical Section, Heap and Stack

3.1 Priority and Preemption

FreeRTOS typically uses “highest priority runs first”.
When preemption is enabled (configUSE_PREEMPTION=1), a higher priority task becoming ready will preempt a lower priority task.
Whether same-priority time slicing occurs depends on configUSE_TIME_SLICING.

Recommendations:

Start by dividing task priorities into 2-3 levels, don’t spread them out initially.
Only put “short, urgent, critical” tasks in high priority.

3.2 Tick and Delay

Tick is the kernel’s periodic interrupt (e.g., 1ms once, depends on configTICK_RATE_HZ).
The parameter unit for vTaskDelay() is Tick, not ms.
It is recommended to use pdMS_TO_TICKS(ms) for conversion.

Example:

vTaskDelay(pdMS_TO_TICKS(500));

vTaskDelay() vs vTaskDelayUntil():

vTaskDelay(): Relative delay, will accumulate drift in loops.
vTaskDelayUntil(): Absolute periodicity, more suitable for periodic tasks.

3.3 Critical Section

Used to protect shared resources, preventing concurrent access from corrupting data.

Common in task context:

taskENTER_CRITICAL();
/* critical section */
taskEXIT_CRITICAL();

Principles:

Keep critical sections short.
Do not perform blocking operations (such as queue blocking wait) inside critical sections.

3.4 Idle Task and Tick Hook

Idle Task runs when “no task is runnable”.
You can use Idle Hook/Tick Hook for lightweight background work (must be very short).
It is not recommended to write complex logic in Hooks.

3.5 Heap and Stack (Must Be Distinguished)

Stack: Each task is independent, stores function local variables/call context.
Heap: System dynamic allocation area, task control blocks, queues, etc. are often allocated from heap.

Common problems:

Task stack too small → stack overflow.
Improper heap_x.c selection or heap too small → object creation failure.

4. Core API Quick Reference (Native FreeRTOS)

Note: The following focuses on native APIs; for CMSIS comparison, see Section 8.

4.1 Task Management

xTaskCreate(): Create a task.
vTaskDelete(): Delete a task.
vTaskDelay(): Relative delay.
vTaskDelayUntil(): Fixed period delay.
vTaskSuspend() / vTaskResume(): Suspend/resume tasks.

Minimal example:

xTaskCreate(TaskA, "A", 256, NULL, 2, NULL);
xTaskCreate(TaskB, "B", 256, NULL, 1, NULL);
vTaskStartScheduler();

4.2 Queue

Purpose: Pass data between tasks (most commonly used).

xQueueCreate(len, item_size)
xQueueSend() / xQueueReceive()

Example:

QueueHandle_t q = xQueueCreate(8, sizeof(uint32_t));
uint32_t v = 123;
xQueueSend(q, &v, pdMS_TO_TICKS(10));
xQueueReceive(q, &v, portMAX_DELAY);

Note:

item_size must match the send/receive data type.
The timeout parameter unit for send/receive is Tick.

4.3 Semaphore and Mutex

Binary semaphore: Event synchronization.
Counting semaphore: Resource counting.
Mutex: Shared resource mutual exclusion, with priority inheritance.

Common APIs:

xSemaphoreCreateBinary()
xSemaphoreCreateCounting()
xSemaphoreCreateMutex()
xSemaphoreTake() / xSemaphoreGive()

Recommendations:

Mutex is preferred for protecting shared peripherals (such as UART).
Binary semaphore or task notification is commonly used for ISR-to-task synchronization.

4.4 Event Group

Purpose: Combined judgment of multiple event bits (e.g., “network ready + sensor ready”).

xEventGroupCreate()
xEventGroupSetBits()
xEventGroupWaitBits()

4.5 Software Timer

Purpose: Execute lightweight callbacks periodically.

xTimerCreate()
xTimerStart()
Avoid time-consuming and blocking operations in callback functions.

4.6 Interrupt Cooperation (ISR and Task)

Rules:

Must use FromISR version API in ISR.
When a task switch may be triggered, call portYIELD_FROM_ISR().

Example:

BaseType_t hpw = pdFALSE;
xQueueSendFromISR(q, &data, &hpw);
portYIELD_FROM_ISR(hpw);

Interrupt priority note:

On Cortex-M, ensure the interrupt priority configuration allows FreeRTOS API calls.
Focus on configMAX_SYSCALL_INTERRUPT_PRIORITY.

5. From 0 to 1: Minimal Project Mental Model

5.1 Recommended `main()` Order

Clock/interrupt group initialization.
Peripheral initialization (GPIO/UART, etc.).
Create communication objects (Queue/Semaphore).
Create tasks.
vTaskStartScheduler() to start the scheduler.

5.2 Task Division Recommendations (Beginner Version)

Acquisition task: Read sensors, send to queue.
Processing task: Receive from queue, calculate.
Output task: UART/screen output.

Avoid:

One task doing everything.
Multiple tasks directly operating the same peripheral without mutual exclusion.

5.3 Typical Dual-Task Flow (LED + UART)

Task A (LED): Toggles every 500ms to prove scheduling is running.
Task B (UART): Prints count every 1s.
Set both tasks to the same priority initially, then optimize after confirming stability.

Success criteria:

LED blinks regularly.
UART prints stably, system does not freeze or produce garbled output.

6. Common Beginner Pitfalls and Troubleshooting

6.1 Stack Overflow

Symptoms: Unexplained HardFault, random freezes.

Troubleshooting:

Enable stack overflow detection (configCHECK_FOR_STACK_OVERFLOW).
Increase the stack of suspicious tasks.
Avoid putting large arrays on stack, use static or heap instead.

6.2 Wrong Blocking Time Unit

Treating Tick as ms will cause timing chaos.
Use pdMS_TO_TICKS() uniformly.

6.3 Using Wrong API in ISR

Using xQueueSend() instead of xQueueSendFromISR() in ISR.
The result may be assertion failure or abnormal behavior.

6.4 Queue Length or Element Size Mismatch

Mismatch between queue element definition and actual send/receive type will cause “seems to run but data garbled”.

6.5 Deadlock

Task A waits for Task B’s lock, Task B waits for Task A’s lock.
Keep lock ordering consistent, reduce nested locks.

6.6 Priority Inversion

Low priority holding mutex resource causes high priority to be indirectly blocked.
Use mutexes for shared resources (has priority inheritance).

6.7 `printf` Risks

Large stack usage, time-consuming, reentrancy risks.
Recommendations:
- Reduce print frequency.
- Avoid printing in ISR.
- Use lightweight logging on critical paths.

7. 5-Day Beginner Practice Checklist

Day 1: Get a Minimal Dual-Task Running

Goal: LED task + UART task running concurrently.
Verify: LED blinks steadily, UART outputs once per second.

Day 2: Queue Communication

Goal: TaskA sends count to queue, TaskB receives and prints.
Verify: Printed values are continuous with no loss.

Day 3: Semaphore Synchronization

Goal: Button interrupt releases semaphore, task is awakened to handle.
Verify: Task blocks without button press, responds immediately after press.

Day 4: Software Timer

Goal: Software timer periodically triggers status reporting.
Verify: Callback executes at fixed period.

Day 5: ISR to Task Notification

Goal: Interrupt uses FromISR API to awaken task.
Verify: Task runs quickly after interrupt response, system is stable.

8. Native API vs CMSIS-RTOS v2 Comparison

Only the most common mappings are listed for quick switching when reading different tutorials:

Task creation: xTaskCreate <-> osThreadNew
Delay: vTaskDelay <-> osDelay
Start scheduler: vTaskStartScheduler <-> osKernelStart
Queue send/receive: xQueueSend/xQueueReceive <-> osMessageQueuePut/osMessageQueueGet
Semaphore take/give: xSemaphoreTake/xSemaphoreGive <-> osSemaphoreAcquire/osSemaphoreRelease

Conclusion:

Beginners are recommended to master native FreeRTOS APIs first, then look at CMSIS wrappers.
The concepts are the same, main differences are in naming and wrapper layer.

Final Checklist (Review Before Writing Code)

Have you used pdMS_TO_TICKS() uniformly for Tick and ms?
Are all ISRs using FromISR API?
Are shared peripherals protected with mutual exclusion?
Do task stack sizes have margin?
Are blocking waits all set with reasonable timeouts?

9. Directly Runnable Minimal Project Template (Can Be Copied to STM32 Project)

The following example is a minimal FreeRTOS skeleton that can be directly copied to your project: two tasks (LED, UART), one queue and one mutex. Note: Peripheral initialization (UART/GPIO) should be replaced according to your HAL/LL implementation.

/* Global objects */
QueueHandle_t g_queue;
SemaphoreHandle_t g_uartMutex;

void LedTask(void *pvParameters)
{
    (void) pvParameters;
    for (;;)
    {
        HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
        vTaskDelay(pdMS_TO_TICKS(500)); // Blocked state
    }
}

void UartTask(void *pvParameters)
{
    (void) pvParameters;
    uint32_t cnt = 0;
    char buf[64];

    for (;;)
    {
        if (xSemaphoreTake(g_uartMutex, pdMS_TO_TICKS(50)) == pdPASS)
        {
            int n = snprintf(buf, sizeof(buf), "cnt=%lu\r\n", (unsigned long)cnt++);
            HAL_UART_Transmit(&huart1, (uint8_t*)buf, n, HAL_MAX_DELAY);
            xSemaphoreGive(g_uartMutex);
        }
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART1_UART_Init();

    g_queue = xQueueCreate(8, sizeof(uint32_t));
    g_uartMutex = xSemaphoreCreateMutex();

    if (g_queue == NULL || g_uartMutex == NULL)
    {
        Error_Handler();
    }

    xTaskCreate(LedTask, "LED", 128, NULL, 1, NULL);
    xTaskCreate(UartTask, "UART", 256, NULL, 1, NULL);

    vTaskStartScheduler(); // Will not return, FreeRTOS takes over

    for (;;);
}

10. Common FreeRTOSConfig Macros and Behavior Mapping (Quick Reference)

configUSE_PREEMPTION = 1: Enable preemption, higher priority task becoming ready will immediately switch to CPU.
configUSE_TIME_SLICING = 1: Enable time slicing between same priority tasks (if 0, same priority may not slice).
configTICK_RATE_HZ: Tick frequency (e.g., 1000 -> 1 tick = 1 ms), affects vTaskDelay, etc.
configMINIMAL_STACK_SIZE: Default minimal task stack size, estimate reasonably when creating tasks.
configMAX_PRIORITIES: Maximum number of priority levels allowed.
configCHECK_FOR_STACK_OVERFLOW: Enable stack overflow detection (recommend setting to 1 or 2 and implement vApplicationStackOverflowHook).
configUSE_MUTEXES: Enable mutexes (priority inheritance), recommended for shared peripheral protection.
configMAX_SYSCALL_INTERRUPT_PRIORITY / Cortex-M interrupt priority configuration: Ensure interrupt priority using FreeRTOS API is not higher than this threshold.

Documentation should explain that these macros are typically modified in FreeRTOSConfig.h, and provide recommended values or ranges for common projects.

11. Common Incorrect vs Correct 写法对照 (Training Style Examples)

Incorrect: Calling xQueueSend() in ISR (will cause unpredictable behavior or assertion) Correct: Call xQueueSendFromISR() in ISR and call portYIELD_FROM_ISR() when needed.
Incorrect: Multiple tasks directly calling HAL_UART_Transmit() (not thread-safe, data may be interleaved) Correct: Create a mutex for UART, all tasks xSemaphoreTake() before sending, xSemaphoreGive() after.
Incorrect: Queue creation item_size does not match passed type (e.g., sizeof(uint32_t) but passing struct pointer) Correct: Queue element size should exactly match the actual passed data type, or send pointer and ensure lifecycle.
Incorrect: Making blocking calls in critical section (e.g., calling xQueueReceive(portMAX_DELAY) after taskENTER_CRITICAL()) Correct: Only perform short, small, and non-blocking operations in critical sections, blocking operations should be outside critical sections.

12. Debugging and Observation: How to Diagnose Stack/Queue/Scheduling Problems

View task stack high water mark: uxTaskGetStackHighWaterMark() returns the minimum remaining stack value used by a task (unit platform dependent), used to evaluate whether stack needs to be increased.
Implement hooks: Implement vApplicationStackOverflowHook() and vApplicationMallocFailedHook(), record information when problems occur and safely restart or enter safe state.
Use assertions: Enable configASSERT(), and output key information in assertion callback (such as current task name, register snapshot) for troubleshooting.
Statistics and events: Use vTaskList() / vTaskGetRunTimeStats() (if runtime stats are enabled) to observe task running conditions and CPU usage.
Fault injection: As an exercise, intentionally shrink queue length or set a task’s stack too small, observe system behavior and use above tools to locate problems.

Quick Reference Checklist (Newly Added)

Runnable minimal project template see Section 9.
Common errors and correct approaches see Section 11, debugging methods see Section 12.

FreeRTOS 基础概念与 API 入门（STM32 新手向）

Tue, 31 Mar 2026 04:00:00 GMT

FreeRTOS 基础概念与 API 入门（STM32 新手向）

目标：看完这份笔记，你可以独立搭出一个“2 任务 + 1 队列 + 1 信号量”的最小 FreeRTOS 工程。

1. 先建立整体认知

FreeRTOS 本质是一个内核，它帮你做三件事：

管理多个任务（Task）。
按优先级和时机调度任务运行。
提供任务间通信手段（队列、信号量、事件组等）。

你可以把它理解为“单片机上的微型操作系统内核”：

main() 里做硬件初始化。
创建任务。
启动调度器。
从此由内核接管 CPU 分配。

2. 任务运行状态（核心）

2.2 任务状态流（可视化）

stateDiagram-v2
    [*] --> Ready
    Ready --> Running: 获得CPU
    Running --> Blocked: 等待事件
    Blocked --> Ready: 事件发生
    Running --> Ready: 时间片用尽
    Running --> Suspended: 挂起
    Suspended --> Ready: 恢复

2.3 新手最容易混淆

Blocked 是“被动等待条件”，条件满足会自动回到 Ready。
Suspended 是“人为冻结”，不会自动恢复。

3. 关键概念：调度、Tick、临界区、堆与栈

3.1 优先级与抢占

FreeRTOS 通常是“高优先级优先运行”。
抢占开启时（configUSE_PREEMPTION=1），更高优先级就绪会打断低优先级任务。
同优先级是否时间片轮转取决于 configUSE_TIME_SLICING。

建议：

先把任务优先级分成 2~3 档，不要一开始全拉开。
高优先级只放“短、急、关键”任务。

3.2 Tick 与延时

Tick 是内核时基中断（例如 1ms 一次，取决于 configTICK_RATE_HZ）。
vTaskDelay() 的参数单位是 Tick，不是 ms。
推荐用 pdMS_TO_TICKS(ms) 做转换。

示例：

vTaskDelay(pdMS_TO_TICKS(500));

vTaskDelay() vs vTaskDelayUntil()：

vTaskDelay()：相对延时，循环中会累积漂移。
vTaskDelayUntil()：绝对周期，更适合周期任务。

3.3 临界区

用于保护共享资源，防止并发访问破坏数据。

任务上下文常用：

taskENTER_CRITICAL();
/* critical section */
taskEXIT_CRITICAL();

原则：

临界区要短。
临界区内不要做阻塞操作（如队列阻塞等待）。

3.4 空闲任务与 Tick Hook

空闲任务（Idle Task）在“无任务可运行”时执行。
可用 Idle Hook/Tick Hook 做轻量背景工作（必须非常短）。
不建议在 Hook 里写复杂逻辑。

3.5 堆与栈（必须分清）

栈（Stack）：每个任务独立，存函数局部变量/调用现场。
堆（Heap）：系统动态分配区，任务控制块、队列等常从堆申请。

常见问题：

任务栈太小 -> 栈溢出。
heap_x.c 选型不当或堆太小 -> 创建对象失败。

4. 核心 API 速查（原生 FreeRTOS）

说明：以下以原生 API 为主，CMSIS 对照见第 8 节。

4.1 任务管理

xTaskCreate()：创建任务。
vTaskDelete()：删除任务。
vTaskDelay()：相对延时。
vTaskDelayUntil()：固定周期延时。
vTaskSuspend() / vTaskResume()：挂起/恢复任务。

最小示例：

xTaskCreate(TaskA, "A", 256, NULL, 2, NULL);
xTaskCreate(TaskB, "B", 256, NULL, 1, NULL);
vTaskStartScheduler();

4.2 队列（Queue）

用途：任务间传数据（最常用）。

xQueueCreate(len, item_size)
xQueueSend() / xQueueReceive()

示例：

QueueHandle_t q = xQueueCreate(8, sizeof(uint32_t));
uint32_t v = 123;
xQueueSend(q, &v, pdMS_TO_TICKS(10));
xQueueReceive(q, &v, portMAX_DELAY);

注意：

item_size 要和收发数据类型一致。
发送接收的超时参数单位是 Tick。

4.3 信号量与互斥量

二值信号量：事件同步。
计数信号量：资源计数。
互斥量：共享资源互斥，带优先级继承。

常用 API：

xSemaphoreCreateBinary()
xSemaphoreCreateCounting()
xSemaphoreCreateMutex()
xSemaphoreTake() / xSemaphoreGive()

建议：

保护共享外设（如串口）优先用互斥量。
ISR 到任务同步常用二值信号量或任务通知。

4.4 事件组（Event Group）

用途：多个事件位组合判断（如“网络就绪 + 传感器就绪”）。

xEventGroupCreate()
xEventGroupSetBits()
xEventGroupWaitBits()

4.5 软件定时器（Software Timer）

用途：定时执行轻量回调。

xTimerCreate()
xTimerStart()
回调函数中避免耗时和阻塞。

4.6 中断协作（ISR 与任务）

规则：

ISR 里必须用 FromISR 版本 API。
可能触发任务切换时，调用 portYIELD_FROM_ISR()。

示例：

BaseType_t hpw = pdFALSE;
xQueueSendFromISR(q, &data, &hpw);
portYIELD_FROM_ISR(hpw);

中断优先级注意：

Cortex-M 下要确保可调用 FreeRTOS API 的中断优先级配置正确。
重点关注 configMAX_SYSCALL_INTERRUPT_PRIORITY。

5. 从 0 到 1 最小工程心智模型

5.1 `main()` 推荐顺序

时钟/中断分组初始化。
外设初始化（GPIO/UART 等）。
创建通信对象（Queue/Semaphore）。
创建任务。
vTaskStartScheduler() 启动调度器。

5.2 任务划分建议（新手版）

采集任务：读传感器，发队列。
处理任务：收队列，计算。
输出任务：串口/屏幕输出。

避免：

一个任务里什么都干。
多个任务同时直接操作同一外设且无互斥。

5.3 典型双任务流程（LED + 串口）

任务 A（LED）：500ms 翻转一次，证明调度在跑。
任务 B（UART）：每 1s 打印计数。
两任务优先级先设相同，确认稳定后再调优。

达标标准：

LED 按周期闪烁。
串口稳定打印，系统不死机、不乱序。

6. 新手高频坑与排查

6.1 栈溢出

现象：莫名 HardFault、随机死机。

排查：

开启栈溢出检测（configCHECK_FOR_STACK_OVERFLOW）。
增大可疑任务栈。
避免大数组放栈上，改静态或堆。

6.2 阻塞时间单位写错

把 Tick 当 ms 会导致节奏错乱。
统一使用 pdMS_TO_TICKS()。

6.3 ISR 调错 API

ISR 中误用 xQueueSend() 而不是 xQueueSendFromISR()。
结果可能是断言失败或异常行为。

6.4 队列长度或元素大小不匹配

队列元素定义和实际收发类型不一致会导致“看似能跑但数据错乱”。

6.5 死锁

任务 A 等 B 的锁，B 又等 A 的锁。
保持锁顺序一致，减少嵌套锁。

6.6 优先级反转

低优先级占互斥资源导致高优先级被间接阻塞。
共享资源优先用互斥量（有优先级继承）。

6.7 `printf` 风险

栈占用大、耗时长、重入性风险。
建议：
- 降低打印频率。
- 避免在 ISR 内打印。
- 关键路径用轻量日志。

7. 5 天入门练习清单

Day 1：跑通最小双任务

目标：LED 任务 + UART 任务并发运行。
验证：LED 稳定闪烁，串口 1s 输出一次。

Day 2：队列通信

目标：TaskA 发送计数到队列，TaskB 接收并打印。
验证：打印值连续且无丢失。

Day 3：信号量同步

目标：按键中断释放信号量，任务被唤醒处理。
验证：无按键时任务阻塞，按下后立即响应。

Day 4：软件定时器

目标：用软件定时器周期触发状态上报。
验证：回调按固定周期执行。

Day 5：ISR 到任务通知

目标：中断使用 FromISR API 唤醒任务。
验证：中断响应后任务快速运行，系统稳定。

8. 原生 API 与 CMSIS-RTOS v2 对照

仅列最常用映射，便于读不同教程时快速切换：

任务创建：xTaskCreate <-> osThreadNew
延时：vTaskDelay <-> osDelay
启动调度：vTaskStartScheduler <-> osKernelStart
队列发送/接收：xQueueSend/xQueueReceive <-> osMessageQueuePut/osMessageQueueGet
信号量获取/释放：xSemaphoreTake/xSemaphoreGive <-> osSemaphoreAcquire/osSemaphoreRelease

结论：

新手建议先掌握原生 FreeRTOS API，再看 CMSIS 封装。
两者思路一致，主要差在命名和包装层。

最后检查清单（写代码前看一遍）

Tick 与 ms 是否都用 pdMS_TO_TICKS() 统一转换？
ISR 是否全部使用 FromISR API？
共享外设是否有互斥保护？
各任务栈大小是否留有余量？
阻塞等待是否都设置了合理超时？

9. 可直接运行的最小工程模板（可复制到 STM32 工程）

下面示例是一个可直接拷贝到用户工程的最小 FreeRTOS 骨架：两个任务（LED、UART），一个队列和一个互斥量。注：外设初始化（UART/GPIO）请按你的 HAL/LL 实现替换。

/* 全局对象 */
QueueHandle_t g_queue;
SemaphoreHandle_t g_uartMutex;

void LedTask(void *pvParameters)
{
    (void) pvParameters;
    for (;;)
    {
        HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
        vTaskDelay(pdMS_TO_TICKS(500)); // Blocked 状态
    }
}

void UartTask(void *pvParameters)
{
    (void) pvParameters;
    uint32_t cnt = 0;
    char buf[64];

    for (;;)
    {
        if (xSemaphoreTake(g_uartMutex, pdMS_TO_TICKS(50)) == pdPASS)
        {
            int n = snprintf(buf, sizeof(buf), "cnt=%lu\r\n", (unsigned long)cnt++);
            HAL_UART_Transmit(&huart1, (uint8_t*)buf, n, HAL_MAX_DELAY);
            xSemaphoreGive(g_uartMutex);
        }
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART1_UART_Init();

    g_queue = xQueueCreate(8, sizeof(uint32_t));
    g_uartMutex = xSemaphoreCreateMutex();

    if (g_queue == NULL || g_uartMutex == NULL)
    {
        Error_Handler();
    }

    xTaskCreate(LedTask, "LED", 128, NULL, 1, NULL);
    xTaskCreate(UartTask, "UART", 256, NULL, 1, NULL);

    vTaskStartScheduler(); // 不会返回，FreeRTOS 接管

    for (;;);
}

10. 常用 FreeRTOSConfig 宏与行为映射（快速参考）

configUSE_PREEMPTION = 1 : 启用抢占，优先级高的任务就绪会立即切换上 CPU。
configUSE_TIME_SLICING = 1 : 同优先级任务之间启用时间片轮转（若为 0 则同优先级可能不轮转）。
configTICK_RATE_HZ : tick 频率（例如 1000 -> 1 tick = 1 ms），影响 vTaskDelay 等。
configMINIMAL_STACK_SIZE : 默认任务最小栈大小，创建任务时要基于此合理估算。
configMAX_PRIORITIES : 允许的最大优先级数量。
configCHECK_FOR_STACK_OVERFLOW : 启用栈溢出检测（建议设 1 或 2 并实现 vApplicationStackOverflowHook）。
configUSE_MUTEXES : 使能互斥量（优先级继承），建议用于共享外设保护。
configMAX_SYSCALL_INTERRUPT_PRIORITY / Cortex-M 中断优先级配置：确保使用 FreeRTOS API 的中断优先级不高于此阈值。

在文档中应说明这些宏通常在 FreeRTOSConfig.h 中修改，并给出常见工程的推荐值或范围。

11. 常见错误写法与正确写法对照（训练式示例）

错误：在 ISR 中调用 xQueueSend()（会导致不可预测行为或断言）正确：在 ISR 中调用 xQueueSendFromISR() 并在需要时调用 portYIELD_FROM_ISR()。
错误：多个任务直接调用 HAL_UART_Transmit()（非线程安全，可能数据交错）正确：为串口创建一个互斥量，所有任务在发送前 xSemaphoreTake()，发送后 xSemaphoreGive()。
错误：队列创建时 item_size 与传入类型不匹配（例如 sizeof(uint32_t) 但传入结构体指针）正确：队列元素大小应与实际传入的数据类型完全一致，或发送指针并确保生命周期。
错误：在临界区中做阻塞调用（例如在 taskENTER_CRITICAL() 后调用 xQueueReceive(portMAX_DELAY)）正确：临界区内仅做短、小且非阻塞的操作，阻塞操作应在临界区外执行。

12. 调试与观测：如何判断栈/队列/调度问题

查看任务栈水位：uxTaskGetStackHighWaterMark() 可以返回任务已使用栈的最小剩余值（单位平台相关），用于评估是否需要增大栈。
实现钩子：实现 vApplicationStackOverflowHook() 与 vApplicationMallocFailedHook()，在发生问题时记录信息并安全重启或进入安全状态。
使用断言：启用 configASSERT()，并在断言回调中输出关键信息（例如当前任务名、寄存器快照）以便排查。
统计与事件：使用 vTaskList() / vTaskGetRunTimeStats()（如果配置启用 run-time stats）来观察任务运行情况与 CPU 占用。
故障注入：作为练习，有意识地缩小队列长度或把某任务栈设置偏小，观察系统表现并用以上工具定位问题。

参考快速清单（新增后）

可复制的最小工程模板见本节第 9 节。
常见错误与正确写法见第 11 节，调试方法见第 12 节。

STM32 GPIO Notes

Wed, 25 Mar 2026 07:00:00 GMT

STM32 GPIO Notes

GPIO Configuration Options in CubeMX

When configuring GPIO in STM32CubeMX, the main options include:

Pin Mode: Select the pin’s function, such as Input, Output, Analog, or Alternate Function.
GPIO output level: Set the initial output level, High or Low.
GPIO mode: Select the output type, Push-Pull or Open-Drain.
GPIO Pull-up/Pull-down: No pull-up and no pull-down, Pull-up, or Pull-down.
Maximum output speed: Low, Medium, High, or Very High.
User Label: Add a custom name to the pin for easy reference in code.

GPIO Modes

GPIO has multiple modes:

Input Floating: Pin floating input without internal pull-up or pull-down.
Input Pull-up: Pin input pulled up to VCC.
Input Pull-down: Pin input pulled down to GND.
Output Push-Pull: Output mode that can drive both high and low levels.
Output Open-Drain: Output mode that can only pull low; requires external pull-up.
Alternate Function Push-Pull: Alternate function such as UART, SPI, etc., push-pull output.
Alternate Function Open-Drain: Alternate function, open-drain output.
Analog: Used for ADC/DAC with no digital functionality.

HAL Library Function Usage

The STM32 HAL library provides simplified GPIO operation functions:

HAL_GPIO_ReadPin(GPIOx, GPIO_PIN_x): Reads the specified GPIO pin state, returns GPIO_PIN_SET or GPIO_PIN_RESET.
- Example: if (HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0) == GPIO_PIN_SET)
HAL_GPIO_WritePin(GPIOx, GPIO_PIN_x, GPIO_PIN_SET/RESET): Sets the output level of a GPIO pin.
- Example: HAL_GPIO_WritePin(GPIOA, GPIO_PIN_1, GPIO_PIN_SET);
HAL_GPIO_TogglePin(GPIOx, GPIO_PIN_x): Toggles the output level of a GPIO pin.
- Example: HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_2);

Comparison with Standard Peripheral Library

The HAL library is an abstraction of the Standard Peripheral Library, providing a more user-friendly interface. Here is the comparison:

HAL_GPIO_ReadPin corresponds to Standard Library’s GPIO_ReadInputDataBit or GPIO_ReadOutputDataBit.
- Standard Library: uint8_t GPIO_ReadInputDataBit(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin);
HAL_GPIO_WritePin corresponds to Standard Library’s GPIO_SetBits and GPIO_ResetBits.
- Standard Library: void GPIO_SetBits(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin);
- void GPIO_ResetBits(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin);
HAL_GPIO_TogglePin requires manual implementation in the Standard Library, or use bit manipulation.
- No direct equivalent in Standard Library; commonly used: GPIOx->ODR ^= GPIO_Pin;

The HAL library is more abstract and more compatible, while the Standard Library is more low-level and more efficient but more complex.

Detailed GPIO Mode Functions

Analog Mode: Used to connect analog peripherals such as ADC (Analog-to-Digital Converter) or DAC (Digital-to-Analog Converter). In this mode, the pin does not perform digital input/output but directly passes analog signals to the internal ADC/DAC module for voltage measurement or analog voltage output. Commonly used for sensor input or audio output.
Alternate Function Mode: Allows GPIO pins to be multiplexed by other peripherals such as UART, SPI, I2C, PWM, and other communication or timer functions. At this time, the pin is no longer used as a general GPIO but is controlled by the corresponding peripheral for data transmission, clock signals, etc. Whether to choose Push-Pull or Open-Drain depends on the peripheral requirements; for example, I2C often uses Open-Drain.

GPIO Power Saving

If an IO is not in use, it can be configured to analog mode, so the pin will not consume current, thereby reducing power consumption.

JTAG/SWD Pin Considerations

Early in the power-on/reset phase, the SWJ (SWD+JTAG) interface is enabled by default, and related pins may exhibit brief transients. These pins should not directly drive sensitive loads before system initialization.

When using only SWD: The JTAG can be disabled early in initialization to release additional pins (such as JTDI/TDI, JTDO/TDO, JTMS/TMS, NJTRST). After release, these pins can be configured as regular GPIO input, output, or alternate function.
Practical advice: Before disabling/remapping, configure these pins as input with appropriate pull-up/pull-down; only set the target mode and initial output level after release is complete to avoid misoperation at power-on.
Trace/ITM: If serial debug output (SWO/JTDO) is not used, it is recommended to keep it disabled or configure it as input to avoid external triggering.

Examples (F1 series):

HAL: Keep SWD, disable JTAG: __HAL_AFIO_REMAP_SWJ_NOJTAG();; Fully disable SWJ: __HAL_AFIO_REMAP_SWJ_DISABLE();
Standard Library: Keep SWD, disable JTAG: GPIO_PinRemapConfig(GPIO_Remap_SWJ_JTAGDisable, ENABLE);; Fully disable SWJ: GPIO_PinRemapConfig(GPIO_Remap_SWJ_Disable, ENABLE);

The specific disable/remap methods may differ for different series chips. Please refer to the series reference manual and HAL/LL macro documentation.

Series Differences Summary

F1 (STM32F1)
- Configuration location: AFIO remap.
- Keep SWD, disable JTAG: __HAL_AFIO_REMAP_SWJ_NOJTAG();
  - Standard Library: GPIO_PinRemapConfig(GPIO_Remap_SWJ_JTAGDisable, ENABLE);
- Fully disable SWJ: __HAL_AFIO_REMAP_SWJ_DISABLE();
  - Standard Library: GPIO_PinRemapConfig(GPIO_Remap_SWJ_Disable, ENABLE);
- After release: Configure PA15/PB3/PB4 as GPIO input/output/alternate function as needed.
F4 (STM32F4)
- Configuration location: In CubeMX System Core -> SYS -> Debug selection; no AFIO macros at code level.
- Recommended: Select Serial Wire (keep SWD, release JTAG-only pins); No Debug releases all debug pins including PA13/PA14. Use with caution.
- Common pins: SWDIO PA13, SWCLK PA14; JTAG-only: PA15 (JTDI), PB3 (JTDO/SWO), PB4 (NJTRST).
- After release example (applicable to F4/L4/H7, for reference only):

// In early initialization phase, set JTAG-only pins to safe mode (input) or target mode
GPIO_InitTypeDef GPIO_InitStruct = {0};
__HAL_RCC_GPIOA_CLK_ENABLE();
__HAL_RCC_GPIOB_CLK_ENABLE();

GPIO_InitStruct.Mode = GPIO_MODE_INPUT;   // or GPIO_MODE_OUTPUT_PP, etc.
GPIO_InitStruct.Pull = GPIO_NOPULL;       // choose PULLUP/PULLDOWN based on external circuit

GPIO_InitStruct.Pin = GPIO_PIN_15;        // PA15: JTDI (can be used as regular GPIO in SWD mode)
HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

GPIO_InitStruct.Pin = GPIO_PIN_3 | GPIO_PIN_4; // PB3: JTDO/SWO, PB4: NJTRST
HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);

L4 (STM32L4)
- Configuration location similar to F4: Via CubeMX SYS -> Debug select SWD/JTAG/disable.
- Pin assignment basically consistent with F4 (specific models may vary slightly), SWD: PA13/PA14; JTAG-only: PA15/PB3/PB4.
- If Trace/ITM is enabled, PB3 (SWO) will be occupied; when not in use, set to input or disable.
H7 (STM32H7)
- Configuration location similar to F4/L4: CubeMX SYS -> Debug; some dual-core devices (M7+M4) have independent debug ports. Confirm according to device manual.
- Pins: SWD keeps PA13/PA14; JTAG-only common PA15/PB3/PB4; Trace/SWO uses PB3.
- Disable or release strategy same as F4/L4: When Trace is not used, keep PB3 disabled or input to avoid accidental triggering.

Note: The above pins are common mappings. For specific pin assignments, refer to the device datasheet/CubeMX pin view. Releasing debug pins will affect online debugging capability. Please handle with caution when in mass production or having strict pin requirements.