Nunchaku-flux-1-dev实战：STM32项目文档自动生成示意图

Nunchaku-flux-1-dev实战：STM32项目文档自动生成示意图

每次接手一个新项目，或者回头维护自己半年前写的代码，你是不是也经常对着密密麻麻的代码和配置文件发懵？特别是用STM32做开发，各种外设初始化、引脚配置、中断处理交织在一起，想画个清晰的系统框图给同事或客户看，都得花上大半天时间手动整理。

更头疼的是，项目中途改了个配置，比如把UART1从PA9/PA10换到了PB6/PB7，你记得更新代码，但很可能忘了去更新那份已经躺在文档里的示意图。结果就是，文档慢慢和实际项目脱节，最后谁也不敢信那份文档了。

最近我在尝试用Nunchaku-flux-1-dev来解决这个痛点。它不是一个画图软件，而是一个能“理解”代码和配置，然后自动生成示意图的智能工具。今天，我就结合一个实际的STM32项目，带你看看怎么把它融入到开发流程里，让项目文档自己“长”出来，既省时又保证准确。

1. 为什么我们需要自动化的项目示意图？

在深入具体操作之前，我们先聊聊这件事的价值。给STM32项目画示意图，传统流程无非是：先读代码，再打开Visio、Draw.io或PPT，然后一个框一个框、一条线一条线地手动绘制。这个过程至少有三个明显的弊端：

第一，极其耗时耗力。一个中等复杂度的项目，涉及USART、SPI、I2C、ADC、定时器等几个外设，把它们之间的数据流和依赖关系理清并画出来，没个小半天搞不定。

第二，难以维护，容易过时。这是最致命的一点。开发是动态的，今天改个时钟源，明天换个DMA通道，但文档的更新永远是滞后的。很快，文档就成了“历史文物”，而非开发参考。

第三，依赖个人能力，不易标准化。不同工程师画的框图风格各异，详略不一。新成员阅读时需要额外的时间去适应和理解，降低了团队协作的效率。

而自动生成示意图的核心思路是“源头唯一”。我们不再维护一份独立的图示文档，而是维护好唯一的真相源——也就是项目代码和CubeMX的.ioc配置文件。示意图只是这个真相源的一个“视图”，由工具自动、实时地生成。代码变，图就变，从根本上解决了维护一致性的难题。

2. 搭建你的自动化文档工具链

想法很好，但要落地，我们需要一套具体的工具和方法。这里我分享一个我目前在使用的工作流，核心就是Nunchaku-flux-1-dev，它在这里扮演了“翻译官”和“绘图师”的角色。

2.1 工具链核心：Nunchaku-flux-1-dev能做什么？

简单来说，Nunchaku-flux-1-dev是一个多模态大模型，特别擅长理解和生成结构化的图形信息。在我们的场景里，我们利用它的两种核心能力：

1. 代码与配置理解：它能解析STM32的C语言源码、头文件，特别是CubeMX生成的main.c、gpio.c等初始化文件，以及关键的.ioc配置文件。它能从中提取出“哪个外设（如USART2）”、“配置了什么参数（波特率115200）”、“连接到了哪个引脚（PA2/PA3）”、“和哪个其他模块有数据交互（通过DMA1_Channel6）”等信息。
2. 图形化表达生成：根据提取出的结构化信息，它能生成详细的文本描述，指导图形渲染引擎（比如Mermaid、Graphviz，或者它自身的图像生成能力）绘制出系统框图、外设连接图或数据流图。

它不是一个开箱即用的桌面软件，通常需要通过API调用的方式，集成到你的脚本或自动化流程中。

2.2 准备工作：让模型认识STM32

直接给模型扔一段STM32的HAL_UART_Init()代码，它可能知道这是串口初始化，但未必能深刻理解STM32外设体系的特殊性。因此，我们需要给它一些“背景知识”，也就是微调（Fine-tuning）或提供高质量的上下文（Context）。

准备“教材”：我通常会准备这样几个示例文件：

• 一个典型的.ioc文件：包含GPIO、USART、SPI、I2C、ADC等常见外设配置。
• 对应的生成代码：尤其是main.c中的SystemClock_Config、外设初始化函数MX_GPIO_Init，MX_USART2_UART_Init等。
• 人工绘制的标准示意图：与上述配置对应的、你认为清晰理想的系统框图和数据流图。

这些文件构成了一个“配对数据集”。核心目的是教会模型：“当看到这样的.ioc配置和代码时，应该生成那样结构的示意图。”

2.3 设计你的提示词（Prompt）

这是与模型沟通的关键。一个好的提示词要清晰、具体、有约束。以下是一个我常用的提示词框架，你可以根据自己的需求调整：

你是一个STM32嵌入式系统设计专家，擅长将代码转换为技术图表。 请分析以下提供的STM32项目代码和CubeMX配置信息： 【这里粘贴或引用你的代码/配置关键部分】 请根据以上信息，生成一份详细的系统设计示意图描述，用于自动绘图。你的描述需要包含以下层次： 1. **系统核心框图**： - 以MCU（STM32Fxxx）为中心。 - 列出所有已启用的外设模块（如USART1, SPI2, I2C1, ADC1, TIM2等）。 - 标明各外设与MCU内核、总线（AHB, APB1, APB2）的连接关系。 2. **外设引脚连接示意图**： - 针对每个外设，列出其使用的具体GPIO引脚（如USART1_TX: PA9, USART1_RX: PA10）。 - 如果外设连接到外部器件（如SPI Flash， I2C传感器），请用虚线框标明外部器件，并连接对应引脚。 3. **关键数据流图**： - 描述主要的数据流动路径。例如：“ADC1通过DMA1_Channel1将数据搬运至内存数组`adc_buffer`，主循环中处理数据后，再通过USART2发送至上位机”。 - 用箭头明确指示数据流向，并标注触发方式（中断、DMA、轮询）。 请使用清晰、分层级的文本描述，避免使用Markdown图表代码（如Mermaid），因为我需要将你的描述输入到另一个专门的绘图生成工具中。重点在于关系的准确性和完整性。

这个提示词明确了角色、任务、输入和输出的具体格式，能极大地提高模型输出结果的可用性。

3. 实战：从代码到示意图的完整流程

光说不练假把式。我们假设一个简单的项目：STM32通过ADC采集传感器电压，通过USART打印到串口助手，同时通过SPI连接一个OLED屏幕显示实时值。

3.1 第一步：准备“原料”

我们在CubeMX里配置好：

• ADC1， Channel1， 对应引脚PA1， 使用DMA（连续传输）。
• USART2， 异步模式， 引脚PA2/PA3， 波特率115200。
• SPI1， 全双工主模式， 引脚PA5(SCK)， PA6(MISO)， PA7(MOSI)， 软件控制片选（PA4）。
• 生成代码。

然后，我们提取关键配置信息，整理成一份简洁的文本，作为给模型的输入：

【项目配置摘要】 MCU: STM32F103C8T6 时钟: HSE 8MHz -> PLL -> 系统时钟72MHz 外设配置： 1. ADC1: - 规则通道: Channel1 (PA1) - DMA: DMA1_Channel1 - 连续转换模式， 数据右对齐 2. USART2: - 引脚: PA2 (TX), PA3 (RX) - 波特率: 115200 - 字长: 8位， 停止位1， 无校验 3. SPI1 (主模式): - 引脚: PA5(SCK), PA6(MISO), PA7(MOSI) - 软件NSS: PA4 - 预分频: FPCLK/256 - 数据大小: 8位 数据流设计： - ADC1持续采样，通过DMA1_Channel1循环写入数组`adc_raw_data[100]`。 - 主程序中计算电压值，格式化字符串。 - 电压字符串通过USART2发送至PC端串口助手。 - 同时，电压值通过SPI1发送至OLED显示屏（SSD1306驱动）进行显示。

3.2 第二步：调用模型生成描述

将上面的配置摘要和我们设计好的提示词，一起发送给Nunchaku-flux-1-dev的API。你会得到一段结构化的文本描述。下面是我得到的一个简化版示例输出：

系统核心框图： 中央为STM32F103C8T6内核与总线矩阵。APB2总线连接ADC1（时钟使能）。APB1总线连接USART2。APB2总线连接SPI1。DMA1拥有独立总线，其Channel1服务于ADC1。

外设引脚连接示意图：

• ADC1: 模拟输入引脚A1 (对应GPIO PA1)。
• USART2: 发送引脚TX -> GPIO PA2； 接收引脚RX -> GPIO PA3。
• SPI1: 时钟SCK -> GPIO PA5； 主机输入MISO -> GPIO PA6； 主机输出MOSI -> GPIO PA7； 片选NSS (软件控制) -> GPIO PA4。
• 外部器件1: PC串口助手，连接至USART2的TX/RX线。
• 外部器件2: OLED显示屏(SSD1306)，其DIN接MOSI(PA7)， CLK接SCK(PA5)， CS接PA4， DC和RESET接其他GPIO（假设为PB0， PB1）。

关键数据流图：

1. 模拟信号流：外部传感器 -> PA1引脚 -> ADC1输入通道。
2. 数字数据流：ADC1转换完成 -> 触发DMA1_Channel1 -> 自动搬运至内存adc_raw_data数组。
3. 处理流：主程序从adc_raw_data读取 -> 计算实际电压值 -> 格式化字符串voltage_str。
4. 输出流A（串口）：voltage_str-> 调用HAL_UART_Transmit -> 通过USART2 (PA2) 发送至PC。
5. 输出流B（显示）：电压数值 -> SPI1发送函数 -> 通过MOSI(PA7) 发送至OLED显示屏刷新显示。

3.3 第三步：将描述转换为示意图

现在，我们有了机器可读的、极其精确的系统描述。最后一步就是把它变成图。这里有几种路径：

• 路径A：使用图表生成库。将上述描述中的“外设引脚连接”部分，稍作格式调整，输入给Mermaid或Graphviz。例如，可以快速生成一个引脚分配图。
• 路径B：使用图像生成模型。将整个结构化描述，作为另一个图像生成模型（比如SDXL）的提示词，直接生成一张美观的系统架构图。Nunchaku-flux-1-dev本身也可能具备直接生成图像的能力。
• 路径C：导入专业工具。将描述整理成表格或列表，导入到Draw.io等工具的批量创建功能中，快速搭建框图骨架，再进行微调。

无论哪种路径，最关键、最耗脑力的“信息提取与关系梳理”工作，已经由模型完成了。我们只需要进行最后的“渲染”即可，效率提升不是一点半点。

4. 如何融入你的开发流程？

让这个工具发挥最大价值，关键在于把它“管道化”，而不是手动执行。我建议的集成点有两个：

1. 在CubeMX生成代码后自动触发： 写一个简单的本地脚本（Python/Bash均可），监视你的项目目录。当检测到.ioc文件保存或main.c等关键文件更新时，自动执行以下流程：

1. 解析.ioc文件（本质是XML）和关键代码。
2. 调用Nunchaku-flux-1-dev API，生成示意图描述。
3. 调用绘图引擎（如Mermaid CLI），生成SVG或PNG图片。
4. 将图片自动保存到项目/docs目录下，并更新README中的图片链接。

2. 在CI/CD流水线中集成： 在GitHub Actions或GitLab CI中增加一个文档生成环节。每次有新的代码合并到主分支时，自动运行上述流程，将生成的示意图作为构件（Artifact）保存，或直接提交回仓库的docs目录。这样，你的项目文档永远与主分支代码同步。

5. 总结与展望

试用了这段时间，我的感受是，用Nunchaku-flux-1-dev这类工具来生成STM32项目示意图，最大的优势不是图画得有多漂亮，而是建立了从代码到文档的“单向可信链路”。文档成了开发的自然副产品，而不是额外负担。对于团队协作和项目维护来说，这种一致性带来的价值，远超过画图本身节省的时间。

当然，它目前还不是全自动的魔法。你需要设计清晰的提示词，可能需要对一些复杂的、非标准的数据流进行人工修正。但即便是生成一个80%准确的草图，也能为你节省大量重复劳动，让你把精力集中在真正的设计思考和代码优化上。

未来，我期待这类工具能更深度地集成，比如直接解析ELF文件，结合调用关系图，生成更运行时态的系统视图。但对于当下大多数STM32项目来说，从静态配置和代码结构入手，实现示意图的自动生成，已经是一个触手可及、能显著提升幸福感的实践了。你不妨也从下一个项目开始试试看。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。