雅特力 AT32 开发指南

编制日期 2026-10-14 ｜ 版本号 Rev 1.0

从 Work Bench 装不起来、AT-Link 连不上、STM32 代码搬不过来，一路到量产烧录与 USB 免晶振设计 —— 一份把「第一次上手会踩的坑」全部前置的工程手册

结论：AT32 是国产 Cortex-M4 里对 STM32 兼容性最好、替换成本最低的一支，雅特力官方宣称代码兼容度 90% 以上、多数型号 Pin-to-Pin 可换。 但「兼容」不等于「二进制兼容」—— 真正卡人的三件事是：① 把 STM32 的 RCC 时钟代码原样搬过来 PLL 配不出正确频率（AT32 叫 CRM，且 >72MHz 要置 PLLRANGE）； ② 直接复用 .axf 与 STM32 启动文件，向量表与时钟初始化全错；③ 读保护一旦使能就触发整片擦除，救砖只能靠 AT-Link 救回。 本文按「装环境 → 建工程 → 编译 → 下载 → 调试 → 量产 → 移植」的真实顺序组织，每一段都给出可复制的命令、可对照的表格、以及该段最常踩的坑。

报告总结

雅特力官网把 AT32 的资料拆得非常细：数据手册（DS）讲电气与引脚、参考手册（RM）讲寄存器、 Firmware Library（BSP）含驱动库与几十个例程，而 Work Bench 用法又在另一个工具里。网上的中文教程绝大多数停留在「新建工程 → 点编译 → 点下载」这一步，一旦遇到 AT-Link 连不上、读保护、USB 枚举不上、STM32 代码搬不过来就无解。本文档做了三件官方分散文档没有做的事：

• 把接力棒画清楚：明确指出「装 IDE」到「能断点调试」之间实际要经过哪几步，以及每一步做完了用什么现象验收。
• 把坑写在坑发生的地方：不单独罗列「常见问题」，而是在讲每个环节时就把该环节的失效现象、原因、处置一起给出。
• 标注来源与版本：所有数值型信息（引脚、电压、容量、寄存器地址、等待周期配置）都追溯到官方 DS/RM 的版本号。

读者路径

本文档共 20 章 + 5 个附录，按「先跑通、再理解」的顺序组织：

• 只想尽快跑通第一个程序：第 4 章（装 Work Bench）→ 第 5 章（建工程点灯）→ 第 7 章（下载）→ 第 20 章（核查清单），四章足够。
• 要做产品开发 / 选型：第 2 章家族选型 → 第 3 章架构差异 → 第 6 章工程结构 → 第 17 章硬件设计。
• 调不通、报错：直接翻第 20 章故障排查速查表，按现象分层定位。
• 要写驱动：第 9 章 GPIO → 第 10 章 NVIC → 第 11 章时钟 → 第 12~13 章外设。
• 从 STM32 切过来：第 18 章是专门的移植对照，先看这一章能省两三天。
• 做 USB 产品：第 14 章（含 crystal-less 免晶振方案）。
• 做低功耗 / 电池产品：第 16 章低功耗，注意「待机唤醒等于一次复位」这件事。

1 · 文档导读与阅读路径

这一章说明本文档的边界：覆盖什么、不覆盖什么，以及为什么把内容按「流水线」而不是按「功能模块」组织。

1.1 覆盖范围

本文档覆盖从拿到一块 AT32 最小系统板，到固件跑起来、能在断点处停下来、并能量产烧录的完整链路：

• 家族与选型：AT32F403A/F407/F413/F415/F421/F423/F425/F435/F437/WB415/A 系列等规格对照，以及按「成本 / 主频 / 外设 / 封装」的选型号思路。
• 架构差异：Cortex-M4 内核、CRM 时钟复位管理、SRAM 扩展（ZW/NZW 与 EOPB0）、sLib 安全库区。
• 开发环境：AT32 Work Bench 图形化配置、AT32 VSCode IDE、AT32 IDE、Keil/IAR Pack 的安装与首次配置。
• 工程与构建：Firmware Library 目录结构、启动文件、链接脚本、器件宏、命令行编译、体积优化。
• 下载与量产：ICP/ISP/IAP 三种模式、AT-Link 硬件形态与接线、BOOT 启动模式、命令行烧录。
• 外设：GPIO/AFIO、NVIC、CRM 时钟、USART/SPI/I2C/ADC/DMA、定时器/PWM/RTC/看门狗、USB、Flash/USD。
• 硬件与迁移：最小系统电路设计要点、从 STM32 移植的改动清单、批量排障。

1.2 不覆盖什么

以下内容超出本文档范围，需要时请查阅对应官方资料：

• BLE 协议栈细节：AT32WB415 的蓝牙 5.0 协议栈 API、GATT 配置、射频认证属于独立的无线文档。
• 以太网协议栈深度用法：F437 的 EMAC + LWIP 移植细节属于例程包中的独立示例。
• 每一款封装的完整管脚定义：本文档只给最常用封装的关键引脚（调试、自举、电源、USB），完整管脚表请查对应 DS。
• 寄存器位域全集：RM 有数百页寄存器描述，本文档只给关键模块的常用位域，写代码时仍需对着 RM 核一遍。
• 电机算法本身：FOC / 无感观测器属于电机控制理论，本文档只覆盖相关外设资源与调试接口。

1.3 版本与命名约定

本文档通篇使用如下约定，避免歧义：

• AT32 指雅特力（Artery Technology）的整个 Cortex-M 系列 MCU。
• F1-class 指 F413 / F415 这类单 PLL、SYSCLK≤150MHz 的架构；F4-class 指 F403A/F407/F435/F437 这类含 PLL1/2/3、SYSCLK 240~288MHz 的架构。
• 寄存器名优先用 AT32 官方命名（如 CRM、TMR、GPIOx_BSRE），对照 STM32 时再标 ST 名称。
• 代码块以 AT32F415 为默认示例型号，跨系列差异处均单独说明。

1.4 事实来源与免责

本文档数值型信息主要来自雅特力官网公开资料（数据手册 DS、参考手册 RM、应用笔记 AN、BSP），基准版本如下：

芯片寄存器细节以用户手上对应型号的 RM 为准；本文档示例代码以说明原理为主，量产前请对照官方 BSP 的例程逐项核对。雅特力官网资源中心：arterychip.com/cn/product/AT32<系列>.jsp。

2 · AT32 家族全景与选型

这一章把 AT32 几十个型号收敛成「按场景选」的几条路径，并给出料号读法。选型错了后面全是返工，所以先花篇幅把家族讲透。

2.1 一句话认识 AT32

雅特力科技（Artery Technology）成立于 2016 年，总部与研发中心分布在重庆、深圳、苏州、上海、台湾，2018 年起正式对外销售，是专注于 ARM® Cortex®-M4 / M0+ 的国产 MCU 设计公司，已通过 ISO 9001、AEC-Q100、ISO 26262 等认证。AT32 的市场定位非常清晰：用 Pin-to-Pin 引脚兼容 + 寄存器近似兼容，做 STM32 的高性价比国产替代。

2.2 两大架构世代：F1-class 与 F4-class

理解 AT32 最关键的一件事：它内部按架构分两代，寄存器命名、时钟树、Flash 结构都不同，选型和写驱动前必须先判断手上的型号属于哪一代：

2.3 全家族规格速查

下表是常用型号的公开摘要（SRAM 区间含 EOPB0 扩展后的最大值）。封装、温度等以各系列 DS 为准。

2.4 高性能主流：F403A / F407

这两颗是 AT32 的「旗舰替代」定位，Cortex-M4F 带 FPU、240MHz，256KB~1MB Flash，SRAM 经 EOPB0 扩到 224KB。F407 额外集成 EMAC 以太网 MAC（部分方案外置 PHY），均含 USB、XMC（外部存储器控制器，可接 SRAM/NOR/NAND/8080 屏）、双 CAN。直接对标 STM32F103/F205/F407，适合工业控制、PLC、伺服驱动、带屏显的网关。

2.5 性价比主流：F413 / F415

F413 是带 FPU 的 200MHz 通用型（64~256KB）；F415 是本文默认示例型号：Cortex-M4（无 FPU）、150MHz、最高 256KB Flash / 32KB SRAM，亮点是 USB OTG FS 支持 crystal-less 免晶振 Device 模式、CAN、两路比较器。对标 STM32F103/F072，是消费电子、USB 外设、小网关的主力料。

2.6 超值小封装：F421 / F423 / F425

这三颗主打低成本小封装（LQFP32/QFN32），96~150MHz：

• F421：M4 无 FPU，16~64KB，带 ADC 与比较器，对标 STM32F030。
• F423：M4F，256KB，5.33Msps ADC + 2×DAC + USB OTG + XMC，小封装里外设最全。
• F425：M4 无 FPU，96MHz，带 CAN + 4×UART + OTG，性价比高。

2.7 超高性能大容量：F435 / F437

AT32 的「性能天花板」：Cortex-M4F、288MHz（55nm 工艺，M4 业界最高之一），256KB~4032KB Flash，SRAM 384→512KB。F437 集成 EMAC 以太网（含部分 PHY 特性）、双 USB OTG（HS+FS，Device 模式 crystal-less）、双 QSPI、SDRAM 接口、双 CAN、3×5.33Msps ADC，对标 STM32F405/F407/F427/F429。

2.8 无线与车载：WB415 / A 系列

• AT32WB415：Cortex-M4、150MHz、256KB/32KB，内置 Bluetooth LE 5.0（BQB 认证），面向 IoT 无线终端、电池设备。
• AT32A403A / A423：车规级（AEC-Q100）版本，参数与 F403A/F423 一致，面向车载与高可靠场景。

2.9 料号怎么读

以 AT32F415RCT7 为例，逐段拆解：

2.10 选型决策路径

把上面这些收敛成五个问题的决策树，从上往下问，命中即停：

• 第一次接触就买 AT-START-F415 或 AT-START-F403A 官方板，板载 AT-Link 电路与排针，能省掉一半接线类故障。
• 同一产品线内优先选大 Flash 那一档。AT32 各档差价极小，后期发现 Flash 不够的成本远高于差价。
• 需要量产烧录先确认 AT-Link 命令行（AT-Link Console），别等到产线上才发现只有 GUI 版本。
• 要免晶振 USB 优先 F415/F435/F437，能省一颗 48MHz 晶振与两颗负载电容，BOM 与面积都降。

3 · 内核与架构：Cortex-M4 与 Artery 的差异点

AT32 不是简单贴牌 STM32。它在标准 Cortex-M4 之上加了一批 Artery 自研模块（CRM、PWC、sLib、ACC），这些正是「90% 兼容但 10% 要改」的那 10%。这一章把它们讲清楚。

3.1 Cortex-M4F 内核

AT32 主力是 ARM Cortex-M4，F403A/F407/F413/F423/F435/F437 带 FPU（浮点单元），F415/F421/F425 不带 FPU。内核自带 24 位 SysTick 自减计数器、NVIC 嵌套向量中断控制器、可选的 MPU、以及 DWT/ITM/SWO 调试追踪单元。指令集与 STM32 同代完全一致，应用层算法（PID、滤波、FOC 数学）基本可直接搬。

3.2 Artery 自研模块总览

除了标准 M4 内核，AT32 的差异点集中在下面几个 Artery 自研 IP：

3.3 CRM 时钟复位管理（对照 STM32 RCC）

这是移植时改动量最大的一块。STM32 的 RCC 在 AT32 里叫 CRM（Clock & Reset Management），寄存器名与配置流程都不同：

F415（F1-class）是单 PLL：输入 HICK(4MHz)/HEXT/HEXT÷2，经 PLLMULT x2~x64 倍频，SYSCLK 上限 150MHz，AHB/APB1/APB2 上限 150/75/75MHz。F435/F437（F4-class）则是 PLL1/PLL2/PLL3 分数式结构，PLL1 主系统时钟可到 288MHz，PLL2/PLL3 给 I2S/USB 等外设。

3.4 SRAM 扩展（ZW/NZW 与 EOPB0）

AT32 的 Flash 分为零等待区（ZW）与非零等待区（NZW）。出厂默认把一部分容量配成 SRAM（零等待、运行快），其余是 Flash。通过用户选项字节 EOPB0 可以重新划分 ZW/ NZW/SRAM 的边界：

• F403A：默认 SRAM 96KB，经 EOPB0 可扩到 224KB（代价是减少 ZW Flash）。
• F435/F437：默认 384KB，可扩到 512KB。
• F415 不做分档，SRAM 固定 32KB。

3.5 sLib 安全库区

sLib（Security Library）是 AT32 独有的代码保护机制：可以把某段 Flash 设为「可执行但不可读」的安全库区，用于交付给第三方的算法（比如电机库、加密库）防止被逆向。解锁键 0xA35F6D24，区域由 SLIB 起始/结束地址定义。AT32F415 的 sLib 可覆盖 Sector 4~63（xB）/ 2~127（xC）。

3.6 与 STM32 的兼容边界

把第 2 章图 2 的结论落到可执行的清单：硬件 Pin-to-Pin 可换，软件 90% 可复用但要改这一批。具体清单见附录 B（AT32 与 STM32 寄存器/宏对照表）与第 18 章（移植）。移植前务必把下面这些当成「必改项」：

• 启动文件换成 startup_at32f4xx.s，向量表偏移、向量名不同（如 TMR1 vs TIM1）。
• 时钟换 system_at32f4xx.c，CRM 重算 PLL，>72MHz 置 PLLRANGE。
• 外设库换成 at32f4xx_*.c/.h，类型名 GPIO_Type（无 Def 后缀）、引脚宏 GPIO_Pins_1。
• Flash/选项字节改用 AT32 库与 ICP/ISP 工具，页大小与 STM32 不同。

4 · 开发环境：Work Bench / AT32 IDE / VSCode IDE

雅特力的工具生态比多数国产 MCU 完整：既有官方图形化配置工具，也有免费跨平台的 VSCode IDE。这一章把四条路线讲清楚，并给出安装期最常见的坑。

4.1 官方工具矩阵

雅特力对外提供四类 IDE 路线 + 三类调试器驱动包（Pack）。下表是 2026 年官网公开的版本摘要：

⚠ 版本号以官网下载页实时值为准（中国站 arterytek.com 通常比台湾站 arterychip.com 更新快一两版）。

4.2 AT32 Work Bench 图形化配置

AT32 Work Bench（不是 "AT32Cube"，网上流传的 AT32CubeMX 是社区叫法，官方不存在）是雅特力官方的图形化配置工具，功能对标 STM32CubeMX：

• 外设初始化配置、PIN MUX 与自定义引脚标签、系统时钟自动化配置。
• 内置 FreeRTOS、USB_DEVICE、USB_HOST 中间件，可在线代码预览。
• 支持 add user code 保护区（/* add user code begin ... */ 之间代码重生成不丢）。
• 可生成 Keil / IAR / AT32 IDE 工程（不生成 HAL、不生成 .ioc）。

4.3 AT32 VSCode IDE（推荐）

这是目前最推荐的入门路线——免费、跨平台、自带工具链。在 VSCode 扩展市场搜 arterytek.at32-vscode-ide 安装，扩展会自动提示安装 5 项依赖：GCC ARM toolchain → CMake → Ninja → OpenOCD → Templates。

常用命令（命令面板 Ctrl+Shift+P）：AT32: New Project、AT32: Open AT32 Project、Import AT32 WK CMake Project、Import Keil MDK Project。侧边栏的 Actions 区提供 Build / Rebuild / Erase / Download / Debug / Clean All。

4.4 AT32 IDE 与 Keil / IAR

AT32 IDE 是基于 Eclipse 的跨平台 IDE，内置 GNU ARM（arm-none-eabi）工具链 + GCC Make + GDB，模板工程在 BSP 的 project/at_start_xxx/templates/at32_ide/。

用 Keil / IAR 的老项目迁移路线：装对应的 ArteryTek.AT32F4xx_DFP Pack，新建工程时选厂商 ArteryTek → 系列 AT32F415 → 具体型号；Target 里 IROM1=0x08000000，IRAM1=0x20000000；C/C++ → Define 填完整型号宏如 AT32F415RCT7。J-Link 需 ≥ 6.20C。

4.5 安装阶段最常见的五个坑

补充：雅特力没有官方 "AT32-CubeProgrammer"（那是 ST 的工具），烧录工具统一叫 ICP Programmer / ISP Programmer / AT-Link Console（详见第 7 章）。

5 · 第一个工程：从新建到点亮 LED

这一章走通最小闭环：新建工程 → 配置时钟与引脚 → 编译 → 下载 → LED 翻转。所有「新手第一大坑」都前置在这里。

5.1 官方 BSP 与例程包结构

雅特力把驱动库、例程、模板都打包在 Firmware Library 里（GitHub ArteryTek/AT32F415_Firmware_Library 或 Gitee arterytek/AT32F415_Firmware_Library，V2.1.8）。目录结构见下图：

最省力的方法是用 project/at_start_f415/templates/ 下的模板工程（选 mdk_v5 / at32_ide / eclipse_gcc），它已包含启动文件、时钟配置、中断文件与 main.c，改改就能编译。

5.2 用 Work Bench 新建工程

如果用 AT32 Work Bench（或 VSCode IDE 的 New Project 向导），流程如下：

• 选器件：搜 AT32F415 → 选具体型号（UI 会显示 Core Frequency/Flash/SRAM/GPIOs）。
• 配 GPIO：把 PA0（接 LED 的引脚）设为 GPIO_Output。
• 配时钟：选 HEXT 8MHz → PLL → 150MHz（或默认）。
• Generate Code：Toolchain 选 MDK_V5，Heap 0x200 / Stack 0x400，勾 Keep User Code。
• 在生成的 main.c 里写翻转逻辑，Keil 打开编译下载。

5.3 工程目录与关键文件

5.4 编译与产物

编译后关键产物：

• text / data / bss 三行数字（Keil Build Output 或 GCC arm-none-eabi-size）—— 用来核对 Flash/SRAM 占用。
• .elf：含调试信息，下载与调试用。
• .hex / .bin：量产烧录用（bin 需指定起始地址 0x08000000）。

5.5 点亮 LED 的完整代码

以 PA0 接 LED（低电平点亮）为例，下面是可直接编译的最小代码。注意三处新手必坑已在注释里标红：

#include "at32f415.h"
#include "at32f415_clock.h"     /* 系统时钟配置，来自模板 */

int main(void)
{
    system_clock_config();        /* 配置 PLL → 150MHz，漏这行时钟不对 */

    /* ① 开 GPIOA 时钟（在 CRM 上）—— 漏这行 LED 永远不亮，编译器不报错 */
    crm_periph_clock_enable(CRM_GPIOA_PERIPH_CLOCK, TRUE);

    /* ② 配置 PA0 为推挽输出 */
    gpio_init_type gpio_init_struct;
    gpio_default_para_init(&gpio_init_struct);
    gpio_init_struct.gpio_pins        = GPIO_Pins_0;
    gpio_init_struct.gpio_mode        = GPIO_Mode_OUT_PP;   /* 通用推挽 */
    gpio_init_struct.gpio_out_type    = GPIO_Output_PushPull;
    gpio_init_struct.gpio_pull        = GPIO_Pull_None;
    gpio_init_struct.gpio_drive_strength = GPIO_Drive_Strength_Stronger;
    gpio_init(GPIOA, &gpio_init_struct);

    while (1)
    {
        gpio_bits_set(GPIOA, GPIO_Pins_0);      /* 置 1，LED 灭（低电平亮） */
        delay_ms(300);
        gpio_bits_reset(GPIOA, GPIO_Pins_0);    /* 清 0，LED 亮 */
        delay_ms(300);
    }
}

验收标准：编译输出有 text/data/bss 三行；obj/ 同存 .elf 与 .hex；下载成功且 LED 按 300ms 节奏翻转。三条全中说明「工具链 + 下载链路 + 最小系统」全部正常，可以进入第 7 章正式研究下载原理。