数字模拟 / g2-v1建议耗时 20 分钟

G2-V1｜Wokwi 数字模拟：UNO + 按钮 + 4 颗 WS2812

✅ 2026-11-07 正式验收通过（主机逻辑 + Wokwi 编译/启动/交互三层证据齐备；真实硬件层独立待板型确认，不影响本关关闭）。Wokwi 不再继续投入优化。 证据分层：本页区分【主机逻辑测试】= Mac 上直接编译运行的 C++ 测试；【Wokwi 运行】= wokwi.com 浏览器仿真；【真实硬件验证】= 尚未执行。 日期：2026-11-07（v2，按验收意见收尾）。被测代码 controller.h 原样复用（md5 063985036d6a00dae6f98e0b0715dc54），一行未改。 ⚠️ 当前家中 Arduino 实物型号未知。Wokwi 基线 = UNO R3（教程既定基线），本页所有内容不构成实物接线结论。

目标

在采购任何电子件之前，验证 V3 星星灯控制逻辑（短按循环 / 长按关闭 / 去抖 / 上电抑制 / 10 分钟超时）在数字环境中成立，并产出可在 Wokwi 一键复现的项目文件。G2-V2（PIR、音频）不在本关范围。

交付物（source-data/christmas-magic-tent/g2/）

文件 说明
firmware/ChristmasStar.ino + controller.h 生产固件，从 christmas_maker_tutorial_v3.zip 原样复制（md5 校验一致）
firmware/controller_idle10s.h 仅 Wokwi 演示用派生头文件：与生产版唯一 diff 为 IdleMs 600000→10000（diff 已验证）；去抖 30ms、长按 1200ms 与生产一致
host-tests/test_g2.cpp 主机逻辑测试（11 场景，纯 C++，不依赖 Arduino）
host-tests/RESULTS.txt 测试运行输出
wokwi/diagram.json 接线图：UNO R3 + 瞬时按钮(D2，键盘快捷键 Q) + 4× WS2812(D6)
wokwi/SimTimeoutTest.ino 仅 Wokwi 用的自动熄灯演示草图（引 controller_idle10s.h，传原始 millis()，无时间缩放）
wokwi/libraries.txt 库配置：Adafruit NeoPixel

v2 修正记录（按验收意见）：

  1. 旧版 SimTimeoutTest 用 millis()*60 全局加速——会同时把去抖压到 0.5ms、长按压到 20ms（按下几十毫秒即被误判长按，无法先点亮）。已废弃该方案，改为 controller_idle10s.h（只缩短空闲超时）。10 分钟阈值的行为验证仍以主机测试 S6 为准。
  2. test_g2.cpp S4 补足 31ms 断言（29 拒绝 / 30 生效 / 31 生效），场景说明与实际覆盖一致。
  3. diagram.json 按钮增加 "key": "Q" 键盘快捷键（Wokwi 原生支持；交互不再依赖 canvas 鼠标事件）。
  4. 按钮触点表述修正：1.l 与 2.l 是两个独立触点，按下时才连通（原"同侧引脚内部连通"说法有误）。

主机逻辑测试（第一层证据）——全部通过

编译运行：cd source-data/christmas-magic-tent/g2/host-tests && c++ -std=c++11 -Wall -o test_g2 test_g2.cpp && ./test_g2

S1  上电关闭: PASS
S2  短按循环: PASS
S3  长按关闭+边界(1199/1200): PASS
S4  去抖+边界(29拒绝/30生效/31生效,毛刺): PASS
S5  上电按住抑制: PASS
S6  10分钟空闲超时+边界: PASS
S7  快速连续按压+长按后恢复: PASS
S8  millis 回绕: PASS
ALL PASS: 8 类行为 / 11 个场景全部通过

原版回归测试（教程自带 qa/test_controller.cpp，7 场景）亦 PASS。测试开发中修过 3 处测试脚本自身的时序笔误（pressStarted 从去抖稳定点起算、时间倒退、lastAction 边界差 10ms）——控制器代码零改动。

覆盖对照：上电关闭✓ 短按循环✓ 长按关闭✓ 去抖✓ 上电按住✓ 10 分钟超时✓（599999/600000 边界）快速连续按压✓（20 次 + 长按后恢复）计时边界✓（去抖 29/30/31、长按 1199/1200、超时 599999/600000、millis 回绕）。

Wokwi 运行（第二层证据）

已自动化验证

项目按 wokwi/diagram.json + firmware/ 在 wokwi.com 编辑器搭建（含 key:"Q" 与 controller_idle10s.h）：编译通过、仿真启动、串口输出正确、上电 4 灯全灭、D2 引脚 Pullup 生效：

Wokwi 仿真运行：串口输出固件提示语，上电 LED 全灭

部件全景：MODE 按钮 + 4 颗 LED 熄灭

库缺失时的构建失败与一键安装均截图留档（wokwi_build_failed_before_library.png / wokwi_library_installed.png）；安装后 libraries.txt 自动生成。

交互验证：待人工执行（自动化受阻于环境，如实记录）

自动化尝试与受阻原因：鼠标合成点击（cua.click/drag）与合成键盘事件均未触发模式切换；截图测量确认 Wokwi 仿真时钟在本环境停滞（速度指示 0%、CPU 0%、rAF 驱动停摆）——任何 down→up 间隔在停滞的仿真时间里都是 0ms，被 30ms 去抖吞掉。这是浏览器无头化环境的限制，不是固件或接线问题。已把按钮配置为键盘快捷键 Q，在正常前台浏览器里即可验证。

人工复现步骤（预计 5 分钟）：

  1. 打开 https://wokwi.com/projects/new/arduino-uno
  2. tab 栏 ▾ → New file… ×2：创建 controller.h（粘贴 g2/firmware/controller.h 全文）与 controller_idle10s.h（粘贴 g2/firmware/controller_idle10s.h 全文）
  3. sketch.ino 替换为 g2/firmware/ChristmasStar.ino；diagram.json 替换为 g2/wokwi/diagram.json（已含 "key":"Q"）
  4. 运行 → 首次弹 "Build failed" → 点 INSTALL "ADAFRUIT NEOPIXEL" LIBRARY → 再次运行
  5. 点击电路图区域聚焦，然后敲键盘 Q（每按一次 = 一次完整短按）：
    • 灭 → 单击 Q → 4 颗暖橙（串口 Mode: 1）
    • → 再击 Q → 彩色循环（Mode: 2）
    • → 再击 Q → 全灭（Mode: 0）
    • 点亮后按住 Q ≥1.2s 再松开 → 直接回灭，且松手不再切换
    • 上电瞬间按住 Q → 不得点亮
  6. 超时可视化（可选）：sketch 换成 wokwi/SimTimeoutTest.ino（引 controller_idle10s.h），点亮后静置约 10 秒自动回 Mode: 0 —— 仅演示用；10 分钟阈值的边界验证以主机测试 S6 为准
  7. 保存截图/项目：Wokwi 保存项目需登录 GitHub/Google 账号（匿名项目无法获得直链）；登录后 SAVE 即得可分享直链

真实硬件验证（第三层）——未执行

家中 Arduino 实物型号未知。型号确认（正反面照片）前：不采购、不接线、不下单。ChristmasStar.ino 内置 #if !defined(ARDUINO_AVR_UNO) #error 守卫，防止在未确认的板子上直接编译通过。

验收状态（三层证据）

层 状态 证据
主机逻辑测试 通过（8 类行为/11 场景 + 原版 7 场景回归） host-tests/RESULTS.txt
Wokwi 编译/启动/上电初态/串口 通过 public/media/.../g2/
Wokwi 按钮与灯光交互 通过（2026-11-07，Brave 真实浏览器补验：CDP 原生鼠标 press-hold-release；串口完整链 Mode: 1→2→0→1→0；4×WS2812 全亮暖橙；长按 1.6s 关闭且松手不切换） wokwi_brave_mode1_serial.png、wokwi_brave_leds_on.png
真实 Arduino 接线与使用 未验证（板型已确认为 UNO R3 ✅ 2026-11-09；实物接线按本页 UNO 基线方案执行，到货组装时验证） —

补验记录：IAB 无头环境仿真时钟停滞（速度 0%）导致自动化失败；改在 Brave（CDP 9222）中以 99~100% 全速运行，smart_interact 原生鼠标 --delay 150 按压（越过 30ms 去抖、低于 1.2s 长按阈值）完成全部交互。诊断要点：按钮为 wokwi-pushbutton 自定义元素（shadowRoot 内含真实 button），初始位置超出视口需先 Fit；LED 链数据正常，BRIGHTNESS=48（19%）在小部件上视觉难辨，曾以 255 做对照实验确认后已还原 48。

  • controller.h 原样复用（md5 一致），控制器零重写
  • 主机逻辑测试 8 类行为 / 11 场景全 PASS（含全部计时边界、31ms 断言、millis 回绕）
  • 原版 7 场景回归 PASS
  • Wokwi 项目文件齐备（diagram.json 含 key:Q / 固件 / controller_idle10s.h / SimTimeoutTest / libraries.txt）
  • Wokwi 编译通过 + 仿真运行 + 串口输出正确
  • SimTimeoutTest 全局 ×60 时钟问题修正：仅缩短空闲超时，去抖/长按阈值与生产一致
  • Wokwi 交互验证（Brave 补验）：短按循环 / 长按关闭 / LED 点亮 / 串口日志全通过
  • 真实硬件验证——板型已确认 UNO R3（用户确认 2026-11-09）；实物接线待帐篷/元件到货组装时执行
  • 全程未采购、未下单；G2-V2（PIR/音频）未提前展开

出问题怎么办

  • Wokwi 编译报 Adafruit_NeoPixel.h not found：Build failed 弹窗点蓝色 INSTALL 按钮，或 Library Manager → + → 搜 "Adafruit NeoPixel" 安装。
  • 敲 Q 没反应：先单击电路图区域确保焦点在仿真面板；确认仿真在运行（右上角计时器在走）；确认 diagram.json 里按钮 attrs 有 "key":"Q"。也可直接鼠标点击按钮（正常前台浏览器中鼠标可用）。
  • 按一下 Q 模式跳了两档：键盘自动重复（长按 OS 重复触发）——敲击要干脆，或改用鼠标点击。
  • host 测试编译失败：需要 C++11 以上（macOS 自带 clang 即可）；test_controller.cpp 原版测试的 include 是相对教程目录结构，放回 qa/ 同级 03_Arduino/ 再编译。
  • SimTimeoutTest 里 10 秒就自动灭：预期行为（IdleMs=10000 演示版）；生产固件是 600000ms。
  • 实物板不是 UNO：停。先拍照确认型号，再由下一关决定移植或换基线；勿直接套用接线。

局限性声明

主机测试验证的是 StarController 状态机逻辑；Wokwi 验证的是 UNO+NeoPixel 的数字环境可编译可运行；两者都不验证：真实 WS2812 电气特性、供电余量（1000µF/330Ω 是否必要）、实物按钮手感与去抖实测参数、以及任何物理安全。这些属于 G4 实物验证阶段。

本章操作已通过？

完成所有勾选项后可标记本章完成。个人进度只存储在浏览器。

← 上一关G0 数字模拟评审：Blender 参数化 A/B 对比
Maker Lab · 用真实动手验证每一步。本站为独立学习记录，与上游项目无官方合作关系。
制作日期 2026-11-06 · 许可与来源 · 新增项目