简介：本资源为2024年全国大学生嵌入式芯片与系统设计竞赛应用赛道国家一等奖获奖作品“Ultra-Lamp”的完整工程源码包，面向嵌入式开发初学者、竞赛备赛学生及STM32/LVGL项目实践者，聚焦智能照明类嵌入式系统的设计落地与性能优化。压缩包共2000个文件，主体为1184个C源文件与620个H头文件（构成LVGL图形界面、音频可视化、灯光控制核心逻辑），辅以138个说明文本、30个配置JSON及22个Markdown文档，完整覆盖硬件驱动、GUI资源管理、音乐频谱渲染（如img_lv_demo_music_wave_top_large.c等）与低功耗系统调度；包体大小166.41MB。已有1431人学习下载。读者可直接复现国家级竞赛级项目：获得结构清晰的多层目录工程（含main、drivers、lvgl、assets等模块）、经实测的LVGL 8.x定制化移植方案、音频FFT+LED灯效联动代码、以及面向MCU资源约束的内存与帧率优化实践，是深入理解嵌入式GUI开发与软硬协同设计的优质参考范例。 2024年全国大学生嵌入式芯片与系统设计竞赛，我们带着一个看起来不起眼、实际上五脏俱全的嵌入式系统作品，从分赛区一路打到全国总决赛，最后拿了应用赛道的国家一等奖。作品名字叫Ultra-Lamp。说它是盏灯，它又不止是盏灯——除了基础的LED照明，它还集成了环境光感知、人体感应、温湿度监测、Wi-Fi联网和低功耗策略，整套东西就是用嵌入式芯片和系统设计把“智能照明”这个场景从头到尾做透。这篇复盘我就把Ultra-Lamp的完整设计思路、关键实现、踩坑记录和作品打包交付的经验全部整理出来，给以后想打这个竞赛、或者想做智能照明类项目的同学一个可以直接参考的样本。
1. 为什么做一盏“灯”：项目定位与创意原点
1.1 赛题选择：为什么是照明场景
每年嵌入式芯片与系统设计竞赛应用赛道，参赛作品五花八门：智能小车、医疗设备、工业检测、农业监控……我们一开始也列了好几个方向。但经过认真调研和评估，最后把目标锁定在“照明”这个场景上。原因有三点：
第一，照明是刚需。世界上任何角落、任何场景都需要光，这保证了作品的应用价值不用向评委多解释。智能照明不是“为了智能而智能”，它是真正能解决实际问题的：自动调节亮度、人来灯亮人走灯灭、根据环境变化调整色温，这些功能对用户有直接、可感知的价值。
第二，技术纵深足够。别觉得“做个灯”太简单，实际上一个优秀的智能照明系统要覆盖传感器采集、信号调理、嵌入式控制、PWM调光、无线通信、低功耗设计、电源管理等多个嵌入式核心技术点，这正好是竞赛评审最看重的东西——不是你会用某一块板子，而是你能不能把一套完整系统设计出来并可靠运行。
第三，可迭代空间大。照明系统可以从单灯扩展到多灯联动，可以接入智能家居平台，可以做健康节律照明，后续拓展方向非常多，这也让我们的作品在展示时有更多聊头，而不是一个“做完就结束”的一次性demo。
1.2 竞品与同类方案分析
动手之前，我们花了不少时间拆解市面上的竞品和往届类似作品，找出它们的短板，然后针对性地做差异化。
市售的智能灯泡和智能台灯，绝大多数走的是“App控制”路线：手机连上Wi-Fi，通过厂商App或智能音箱控制开关、亮度、色温。这类产品有几个通病：一是高度依赖网络和云平台，一旦家里断网，灯具可能直接失控；二是交互逻辑繁琐，想调个亮度要打开App、找到设备、滑动进度条，实际体验反而比传统开关差；三是大部分产品只有“遥控”功能，缺少基于真实环境状态的自动决策能力。
一些高校竞赛作品里的智能照明，则容易走向另一个极端：堆功能。一个作品里塞了语音识别、手势识别、人脸识别、温度显示、空气质量检测，结果每个功能都是浅尝辄止，现场演示时一个环节卡住就翻车。
所以Ultra-Lamp的定位从一开始就很明确：不做功能数量上的堆砌，而是围绕“本地自主决策”这个核心，把环境感知、智能调光、低功耗运行这三大块做深做扎实。Wi-Fi联网只做远程状态查看和配置下发，就算断网，灯具也能完完全全按本地逻辑正常工作。这个“断网可用”的设计，后来在答辩时成了我们和市售产品拉开差距的重要论据。
1.3 设计目标与功能清单
我们还特意写了一份设计目标清单，相当于整个项目的“北极星”，后面所有开发工作都围绕它展开：
- 核心定位：一盏能感知环境并自主调节的智能照明设备，不依赖云端也能正常工作。
- 自动调光：根据环境光传感器读数，自动调节LED亮度，让工作面照度始终维持在舒适区间。
- 人来灯亮：结合人体感应模块，检测到有人进入范围时自动亮灯，离开后延时熄灭，避免费电。
- 视觉舒适：调光过程必须平滑无频闪，亮度变化符合人眼感知曲线，不能出现肉眼可见的阶梯感。
- 低功耗：在电池供电的应急使用场景下，整机待机电流控制在毫安级，续航至少到达标水平。
- 联网可配置：通过Wi-Fi接入本地网络，支持手机端查看设备状态、远程修改亮度上限和延时参数。
- 可靠性：连续运行72小时不死机、不误触发、不频闪，电源波动时不影响工作状态。
这个清单看起来简单，但每一条深入下去都是一个技术点。接下来我从系统设计开始，把每个决策背后的思考讲清楚。
2. 系统总体设计：软硬件方案选型与架构
2.1 主控芯片选型与计算依据
主控是整个系统的脑子。Ultra-Lamp选型时，我们充分考虑了“资源够用、成本可控、开发效率高”三个因素。
最终选定的主控是STM32F407VET6，Cortex-M4内核，主频168MHz，Flash 512KB，RAM 128KB。这个选型是基于需求倒推出来的：
- 调光需要定时器输出PWM，F407的高级定时器和通用定时器数量充足，可以分配独立通道驱动多路LED，互不干扰。
- 多传感器数据采集需要ADC和I2C接口，F407的I2C外设经过配置可以稳定跑在400kHz快速模式，同时有3个ADC，可以并行采集不同模拟信号。
- 后续要跑FreeRTOS，还要预留一定的协议栈缓冲，128KB的RAM完全够用，不至于像小容量芯片那样捉襟见肘。
这里我想提一下为什么没有直接上更高端的平台。有些队伍喜欢用带Linux的MPU，或者性能更强的双核芯片，但竞赛作品的开发周期通常只有几个月，团队精力有限，用Linux系统意味着要处理驱动适配、系统移植、启动优化等一堆问题，反而挤占了应用逻辑的开发时间。F407这类MCU虽然没有操作系统加持，但用裸机状态机或者FreeRTOS完全能搞定我们的需求，开发调试也直接、可控，这是典型的“够用就好”选型思路。
另外，我们采用的是贴片LQFP100封装，手工焊接和PCB设计都比较友好。如果你也想走这条路，建议买几片备用芯片，焊接时用拖焊法配合助焊剂，成功率会高很多。
2.2 传感器与执行器选型
Ultra-Lamp的感知层一共有三类传感器，每类都针对不同的环境状态：
- 环境光传感器：选用BH1750，I2C接口，量程1到65535勒克斯。这颗芯片是数字输出，内部自带16位ADC和照度计算逻辑，MCU直接读寄存器就能拿到勒克斯值，不需要额外做标定。它还有个优势是支持多种测量精度模式，低精度模式测量时间只要16毫秒，适合快速响应的场景。
- 人体感应模块：选用基于热释电效应的红外传感器模块（PIR），检测范围约7米，感应角度120度。这类模块输出的是数字电平信号，有人进入时输出高电平，离开后延时输出低电平，硬件上自带信号调理，MCU只需要读取GPIO状态。
- 温湿度传感器：选用SHT30，同样是I2C接口。它主要用来监测灯具工作环境，防止LED长时间工作导致局部温度过高，同时为后续扩展“根据温度调整散热策略”预留数据基础。
执行器方面，LED灯板选用了12V输入的暖白+冷白双色温灯板，两种色温通过独立PWM通道控制，可以混合出从2700K到6500K的连续色温调节范围。灯板额定功率5W，在桌面照明场景下亮度充裕。
选型时的对比表我整理如下，供参考：
| 模块 | 型号 | 接口 | 关键参数 | 选型理由 |
|---|---|---|---|---|
| 主控 | STM32F407VET6 | - | 168MHz / 512KB Flash | 资源充裕，外设丰富，生态成熟 |
| 环境光 | BH1750 | I2C | 1-65535 lx，16位精度 | 数字输出，无需标定，响应快 |
| 人体感应 | PIR热释电模块 | GPIO | 7米 / 120° | 成本低，检测范围覆盖桌面场景 |
| 温湿度 | SHT30 | I2C | ±0.3°C / ±2%RH | 精度高，长期稳定性好 |
| LED驱动 | PT4115 | PWM调光 | 最大1.2A恒流输出 | 外围简单，调光线性度好 |
| Wi-Fi | ESP8266 | UART | 802.11 b/g/n | 成本低，AT指令开发快 |
2.3 系统架构与数据流设计
Ultra-Lamp的整体架构可以抽象成“感知-决策-执行-交互”四层。感知层由BH1750、PIR和SHT30组成，负责采集环境光强度、人员存在状态和温湿度；决策层在STM32内实现，核心是一个基于状态机的控制逻辑，把所有传感器数据融合起来，判断当前应该处于什么照明状态；执行层通过PT4115驱动LED灯板，输出对应亮度和色温；交互层通过ESP8266连接Wi-Fi，定时上报设备状态，并接收手机端下发的配置参数。
数据流是这样的：传感器数据先经过MCU内部的滤波处理，然后进入状态机做综合判断，状态机输出目标亮度和色温值，再经Gamma校正换算成PWM占空比，最终驱动LED。同时，状态机的运行参数和当前状态通过串口发送给ESP8266，由其打包上报到MQTT服务器。
这里最关键的设计决策是：状态机运行完全在本地。Wi-Fi或者服务器挂了，整个决策链路不受任何影响。联网只是一个“附加功能”，而不是“必要前提”。这种设计思路在工程上叫“本地优先”，它保证了系统在真实环境中不会因为外部依赖而失效。
3. 核心模块实现与关键技术细节
3.1 LED恒流驱动与PWM调光设计
LED灯珠的亮度和电流直接相关，所以驱动方案选择的是恒流驱动芯片PT4115。它的外围电路非常简洁：一颗芯片、一个电感、一个采样电阻、一个续流二极管就能组成Buck恒流电路。通过PWM信号控制DIM引脚，就可以实现LED亮度的调节。
PWM调光有两个关键参数需要认真设计：频率和分辨率。
首先是频率。人眼对低频PWM调光非常敏感，频率低于约100Hz时能明显感受到闪烁，长时间在这种光线下工作容易眼疲劳。更麻烦的是，手机摄像头和摄像机会捕捉到低频频闪，表现为画面中肉眼不可见的滚动条纹。根据工程经验，高品质照明的PWM调光频率至少要在16kHz以上。我们把频率定在了20kHz，正好在听觉范围上限之上，不会产生电感啸叫，同时PT4115的开关速度完全能跟上。
其次是分辨率。我们选用定时器的8位PWM模式，即256级亮度调节。为什么不用更高分辨率？因为PT4115的调光端响应速度和实际LED亮度变化限制了有效分辨率的发挥，8位256级已经足够实现平滑的亮度变化，而且高分辨率PWM在MCU上的中断开销更大，反而得不偿失。
这里还要提一个很多人容易忽略的细节：人眼对亮度的感知不是线性的。在低亮度区域，人眼对亮度变化非常敏感；在高亮度区域，即使实际亮度变化很大，人眼也感觉不明显。如果直接用线性占空比去控制LED，调光过程会出现“低亮度时变化剧烈、高亮度时几乎看不出变化”的问题。
解决方法是做Gamma校正。具体做法是设定一个输出曲线：目标PWM占空比等于亮度等级的2.2次幂。举个例子，亮度等级取160（满量程255），线性法的占空比是62.7%，Gamma校正后实际输出的占空比是(160/255)^2.2，算下来约36.5%。这样一来，人眼感知到的亮度变化就近似线性的了。这个细节我们花了整整一个晚上调试，但最终调光效果的细腻程度，评委现场体验后给了一致好评。
3.2 多传感器数据采集与状态判断
主控通过I2C总线挂载了BH1750和SHT30两个传感器，加上一个PIR数字输入，系统每100毫秒做一次状态采集，然后进入滤波和判断逻辑。
BH1750的采集需要注意测量模式的选择。它支持一次测量和连续测量两种模式，每种模式下又有高分辨率、高分辨率2和低分辨率三个档位。我们在实际开发中发现，高分辨率模式的测量时间约为120毫秒，如果每次采集都等它转换完，状态机会被卡住。后来我们改用了低分辨率模式配合软件滑动滤波：16毫秒完成一次采样，连续采5次去掉最大值和最小值后取平均。这样既保证了响应速度，又有效抑制了环境光的瞬时波动。
PIR传感器的处理则要更谨慎一些。热释电红外传感器有一个物理特性：它检测的是红外辐射的变化量，不是绝对量。所以如果一个人坐在那里长时间不动，PIR输出会从高电平恢复为低电平，造成“人还在灯却灭了”的尴尬局面。我们设计了一个状态机的重触发机制：每次PIR从低电平跳变到高电平，系统就刷新一次“最后有人时间”标记；定时器每10秒检查一次，如果超过设定延时（默认5分钟）没有任何新的触发，才判定为无人并熄灭LED。这个机制有效解决了PIR传感器静态检测能力弱的问题。
还有一个抗误触发策略值得分享：我们的PIR安装角度是朝前下方倾斜30度的，这样可以避免它直接面对窗户或热源。因为阳光直射区域和空调出风口的热气流都会让PIR产生误触发，这个部署角度加上软件上的两次连续确认（连续两次采样都为高才判定有人），把误触发率降到了一个可以接受的水平。
3.3 通信与低功耗策略
ESP8266在这里的工作模式是通过UART串口和主控通信，使用AT指令集。主控定时把设备状态打包成JSON格式的字符串，通过串口发送给ESP8266，ESP8266再以MQTT协议上报到本地服务器。反过来，服务器下发的配置参数也通过MQTT推送到ESP8266，再透传给主控解析。
通信这块核心要处理好的是“断线重连”和“数据同步”两个问题。ESP8266的稳定性不算特别强，运行时间长了偶尔会出现模块挂死或Wi-Fi断连的情况。我们的做法是：主控每30秒检查一次ESP8266的状态引脚，如果发现异常，会给模块发送硬件复位信号，强制重启后再重新建立MQTT连接。同时在MCU内部维护一份配置参数副本，即使通信模块一直不可用，也能保证本地控制逻辑正常运行。这个机制后来在现场演示时立了大功——楼下展厅Wi-Fi信号很差，ESP8266频繁掉线，但Ultra-Lamp的照明控制完全不受影响。
低功耗设计方面，我们针对不同工作模式做了功耗管理。正常照明模式下，MCU运行在168MHz全速，传感器按时序工作，整机功耗大约在1.5W左右。待机模式下，MCU进入Stop模式，BH1750和SHT30进入掉电状态，PIR模块保持低功耗侦听，整机功耗可以压到约30mW。
给大家算一笔具体的账：假设用一块5000mAh的12V锂电池组给Ultra-Lamp供电（电池组能量约60Wh），每天以150mA的平均电流工作8小时，待机16小时（待机电流约2.5mA），一天的耗电量大约是150mA×8h + 2.5mA×16h = 1.24Ah。理论上这块电池可以支撑4天左右。如果不算LED驱动，纯控制电路的主控部分，用两个5号电池串联再经过LDO降压到3.3V，也能跑很久。这就是低功耗设计带来的实际价值。
4. 从原型到国赛作品的迭代过程
4.1 第一版原型：功能跑通
我们的开发过程分了三个阶段，第一阶段的目标只有一个：把所有功能点亮，跑出一个能用的原型。
第一版原型完全是在面包板上搭出来的。STM32最小系统板插在面包板一端，传感器模块和ESP8266模块用杜邦线连过去，LED驱动部分则用一块独立的恒流驱动小板。代码方面，我们先用CubeMX生成了外设初始化工程，然后在上面逐个模块验证：先点亮LED、做个呼吸灯效果确认PWM正常，再读BH1750，串口打印光照值，再测PIR触发，最后再接上ESP8266做MQTT通信。
这个阶段最大的收获是快速验证了方案的可行性，但问题也暴露了一大堆：面包板接触不良导致传感器数据时不时跳变、杜邦线太乱容易拉扯脱落、ESP8266的天线贴着其他线缆导致Wi-Fi信号时断时续。当时我们就意识到，真正能拿出去比赛的成品，绝不能是这个状态。
4.2 第二版优化：可靠性打磨
第二阶段，我们重新画了PCB，把整个系统集成到一块板子上。这个阶段用了大约两周，主要做三件事。
第一是电源走线重新设计。LED驱动部分是典型的开关电源电路，如果它和主控部分的电源规划不当，LED开启时会拉低电压导致MCU复位。我们在PCB上把LED驱动电路的输入电源单独走线，在输入端并联了一个470uF的电解电容和一个0.1uF的陶瓷电容，同时把MCU的供电走线和驱动电路隔开，中间用地线隔离。这样改动之后，LED全亮瞬间MCU电源电压的跌落从以前的0.5V降到了0.1V以内，系统再也没出现过复位。
第二是传感器接口统一改成XH2.54端子，方便现场快速插拔和更换。同时给PIR模块预留了调节电位器的开孔位置，方便根据安装环境调整灵敏度和延时时间。
第三是3D打印了外壳。Ultra-Lamp的外壳我们设计了两个版本：第一版是全封闭的，装上后Wi-Fi信号衰减特别严重，手机端经常连不上设备。后来在外壳侧面开了一个缺口，把ESP8266的PCB天线部分暴露出来，信号强度立刻恢复。这个细节提醒我们：任何带无线功能的嵌入式设备，外壳设计时必须考虑天线净空区。
4.3 国赛现场演示与答辩准备
到了全国总决赛阶段，技术方案基本定型，工作重心转向了展示效果和答辩。
我们提前两周开始录制演示视频和设计展示展板。演示视频的脚本反复改了五遍，核心逻辑是：“先让评委看到痛点（普通台灯无法自动调节），再展示Ultra-Lamp的解决方案（自动感知、自动调光），最后展示联网配置和低功耗数据”。整个视频控制在3分钟以内，节奏紧凑。
答辩环节，我们准备了一份12页的PPT，重点不是堆技术名词，而是回答了三个问题：这个作品解决什么问题？怎么解决的？和竞品相比优势在哪？评委现场问得最多的果然是我们在设计时反复思考的几个点：“断网了还能用吗？”“待机功耗具体多少？”“调光为什么不用线性PWM？”——因为我们真的做过、验证过，所以答起来很踏实。
这里想特别提醒以后的参赛队伍：演示设备一定要带备用方案。我们那次答辩带了两个电源适配器、一套备用电池、两根备用数据线，甚至把整个项目的固件烧录步骤都打印出来带在身边，以便现场出问题时能快速恢复。幸好最后没用到，但准备充分带来的底气是完全不一样的。
5. 开发过程中踩过的坑与排查实录
5.1 LED频闪与调光曲线问题
第一次报告频闪问题，是在第一版原型调试时，我们用手机摄像头录了一段调光视频，回放时看到LED灯珠表面有非常明显的滚动条纹。当时PWM频率设置的其实是1kHz，这个频率下人眼基本感知不到闪烁，但手机摄像头的采样率和LED的PWM频率产生混叠，视频里就出现了条纹。
这个问题有三个解决方案：把PWM频率提高到20kHz以上，保证和摄像头采样率错开；或者用手机的专业模式手动调节快门速度，避开频闪；再或者干脆改用线性恒流调光方案，不做PWM。我们最终选了第一条，也是最通用的工程做法。修改之后再用手机拍摄，画面完全干净。
另外一个和调光相关的问题是Gamma校正初期没做，亮度调节确实有“低亮区太敏感、高亮区不敏感”的体验问题。这个我在前面已经详细讲过，这里再强调一次：线性占空比不等于线性感知亮度，Gamma校正是智能照明里一个不太起眼但体验差异巨大的细节，一定要做。
5.2 传感器误触发与数据跳变
PIR模块在测试阶段出现过比较严重的误触发问题。一开始我们以为是模块坏了，换了三块新的，问题依旧。后来排查发现是办公桌上的一个暖光台灯在PIR的检测范围内，台灯点亮后发出的红外辐射会被PIR捕捉到，导致它一直输出高电平。
解决方法是两层：硬件上调整PIR模块的安装位置和角度，让检测区域避开热源；软件上增加连续确认机制，只有连续两次检测到高电平才判定为有人，避免瞬时干扰造成的误触发。同时对外壳和PIR透镜之间增加了遮光隔离，减少了透镜表面反射带来的干扰。经过这几项调整后，连续运行一周的误触发次数几乎降为零。
BH1750数据跳变的问题则主要源于供电纹波。在LED全亮时，I2C总线上的数据偶尔会出现错乱，读出的光照值偏离真实值很大。我们用示波器测量后发现是电源线上的纹波耦合到了I2C信号线上。解决办法是在BH1750的VCC引脚就近加了一个10uF的陶瓷电容，同时把I2C总线上拉电阻从10k欧调整到4.7k欧，提升了信号抗干扰能力。这两步操作之后，数据再也没有跳变过。
5.3 Wi-Fi断连与供电不稳问题
ESP8266在正常工作时，峰值发射电流可以达到170mA甚至更高。如果供电电路的裕量不足，模块一发射数据就会把电压拉低，导致MCU或者其他传感器工作异常。
我们的第一版供电方案是用一颗AMS1117-3.3从5V降压给所有3.3V设备供电，结果ESP8266一启动，3.3V电压直接从3.32V跌到3.1V，主控虽然还能跑，但I2C传感器偶尔会报错。排查后我们做了一件事：把ESP8266的供电从主3.3V电源轨上分离出来，单独用一颗LDO给它供电，并且在它旁边并联了一个470uF的钽电容作为能量缓冲。这样ESP8266发射瞬间主要靠电容放电补充能量，对其他电路的影响大幅降低。
Wi-Fi断连问题主要还是环境因素。比赛现场的无线信号干扰极其严重，评委席、参观区到处都是手机和路由器。我们最后加了一个看门狗逻辑：主控每30秒通过串口查询一次ESP8266的AT状态，如果连续3次没有响应，就切断模块电源等待2秒后再重启，让模块重新连接。这个自动恢复机制让设备在现场连续运行了一天半，中途只出现过一次断连且自动恢复成功，没有需要人工干预的情况。
我把排查过程中遇到的问题整理成了一个速查表，方便以后做类似系统时对照：
| 问题现象 | 可能原因 | 排查思路 | 解决方案 |
|---|---|---|---|
| 视频中有滚动条纹 | PWM频率过低 | 手机摄像回放观察 | PWM频率提高到20kHz以上 |
| 调光低亮区变化突兀 | 缺少Gamma校正 | 对比线性占空比和感知亮度 | 输出占空比按2.2次幂曲线校正 |
| PIR误触发频繁 | 检测区域有热源 | 调整安装角度或遮挡 | 改动部署角度，软件双重确认 |
| I2C数据偶尔错乱 | 电源纹波干扰 | 示波器测VCC和SDA波形 | 就近加去耦电容，调整上拉电阻 |
| ESP8266启动后系统复位 | 供电裕量不足 | 测模块启动瞬间电源电压 | 独立LDO供电，加钽电容缓冲 |
| Wi-Fi频繁掉线 | 天线被遮挡或干扰强 | 检查天线净空区 | 外壳开槽露出天线，加自动重启机制 |
6. 项目归档与交付：Ultra-Lamp.zip 的整理规范
6.1 交付包目录结构与内容说明
竞赛要求提交的最终成果包含作品文档、源码、硬件设计文件、演示视频和图片。这些东西最终会打包成一个压缩包，也就是Ultra-Lamp.zip。很多队伍在技术实现上花了很多功夫，但交付包做得乱七八糟，这其实非常影响评审体验。我们当时花了整整两天来整理交付包结构，最终目录是这样设计的：
Ultra-Lamp/ ├── README.md ├── docs/ │ ├── 设计文档.md │ ├── 硬件设计说明.md │ ├── 软件设计说明.md │ └── 测试报告.md ├── firmware/ │ ├── UltraLamp_Core/ # STM32 主控固件工程 │ ├── UltraLamp_WiFi/ # ESP8266 透传固件 │ └── README.md # 固件编译、烧录说明 ├── hardware/ │ ├── schematic/ │ ├── pcb/ │ └── bom.csv # 物料清单 ├── demo/ │ ├── 演示视频.mp4 │ ├── 展示图片/ │ └── 答辩PPT.pdf └── license.txt这样的目录结构，让评委能一眼看清作品交付物的全貌：文档在哪、固件在哪、硬件设计在哪、演示材料在哪。信息组织清晰，本身就是在给作品加分。
6.2 文档撰写与README规范
README是整个交付包的门面，也是评委最先打开的文件。我们写README时遵循了一个原则：让一个手里只有这颗芯片、没有任何背景信息的人，也能按部就班地编译、烧录并跑起来。
所以README里除了项目简介和技术亮点，还有三块内容必不可少。第一是硬件环境说明：列出了需要准备的开发板、传感器模块、供电规格，并附了一张完整的接线表。第二是软件环境说明：详细列出了用的IDE版本、HAL库版本、编译工具链，以及每个固件工程的打开方式和编译步骤。第三是烧录步骤：包括Boot引脚如何设置、ST-Link怎么接、烧录完成后如何验证系统正常工作。可以这么说，README写得好不好，直接反映了一个队伍对作品能否完整复现的重视程度。
设计文档方面，我们没有追求每篇都长篇大论，而是按照“需求分析→方案设计→详细设计→测试结果”这条标准链路来写。每一篇的开头都写清楚“这份文档解决什么问题”，结尾附上“测试数据和结论”。文档里配了系统框图、状态机图、PCB截图和测试照片，图文结合，评审阅读效率高，也给我们答辩提供了完整的素材库。
6.3 开源发布与作品复现
竞赛结束后，我们把Ultra-Lamp的部分核心代码和硬件设计文件做了脱敏处理后开源发布。开源这件事在实战中会逼你重新审视自己的代码质量：变量命名是否清晰、关键算法有没有注释、工程文件能不能在不同电脑上顺利编译。这些习惯在竞赛期间是“锦上添花”，但到了开源阶段就变成“基本要求”。
对于代码注释，我的建议是：不要写“这是加法”这种废话注释，而要写“为什么这么做”。比如Gamma校正的实现代码，注释就写清楚这个曲线的来源是ITU-R BT.709标准，以及它如何改善人眼感知的线性度。这种注释对后来接手项目的人价值巨大，对你自己三个星期后回来看代码也同样有用。
开源发布的技术细节里，有一个小问题特别值得提醒：工程文件打包前，一定要清理编译中间文件。我们第一次打包时没注意，固件目录里混进去了几个MB的编译缓存和临时文件，压缩包体积大了一倍还不止，而且评审解压后还会产生很多噪音。后来我们在工程里加了.gitignore文件，把build、Debug、Release、.o、.d文件全部排除在外，再重新打包，整个压缩包体积减少了约60%，结构清爽了很多。
还有一点是关于素材文件的格式和命名。演示视频我们用的是H.264编码的MP4格式，分辨率1920x1080，时长控制在3分钟以内。图片文件统一用PNG格式，命名规则是“序号_内容描述”，比如“01_系统整体外观.png”“02_自动调光效果对比.png”。这种细节看似不起眼，但在评委快速翻阅大量作品材料时，规范和一致性会留下非常好的专业印象。
关于Ultra-Lamp这个项目，其实还有一个细节我没说。我们的Wi-Fi模块在比赛现场演示时确实掉过线，但因为所有核心决策都在本地完成，评委看到的是灯具依然正常工作，手机端只是少了一个远程状态刷新而已。那一刻我就想，嵌入式系统设计里，“可靠性”三个字的分量，真的只有在现场环境下才能感受到。如果你也要做类似的嵌入式项目，记得在方案设计阶段就把“主功能不依赖外部网络”这条原则刻进脑子，它能帮你在很多关键场景下保住下限。
另外再分享一个小技巧：给代码工程和硬件文件做版本管理时，不要用“最终版”“最终版2”这种命名方式，直接用日期加版本号，比如UltraLamp_v1.3_20240915。配合一份CHANGELOG文档记录每次改了什么、为什么改，后期排查问题会省下大量时间。这个习惯我从Ultra-Lamp之后一直保持到现在，适用性极强。
本文还有配套的精品资源，点击获取
