🏎 巡线小车虚拟仿真系统 V3.3 — 使用说明

1. 编程页面

1. 左侧积木区与 Mixly 的 V2.6 库完全一致：「🏗 程序结构」里有初始化（setup）和主循环（loop），动力输出、双轮驱动、精准巡线、搜线定位、巡线大师、麦轮、FreeRTOS 多任务、TFT 彩屏等 16 大类齐全。
2. 「📦 变量」类别里有「📌 声明变量」积木；「🧩 函数」类别可定义自己的函数。
3. 「💾 保存程序」把当前程序存进本机浏览器（首次保存需起名，之后再点直接覆盖保存）；「📄 程序另存为」把程序保存为 .xml 文件到电脑硬盘（自己选择文件夹）；「📁 打开程序」可打开浏览器保存的程序，或点「📂 从电脑文件打开」载入 .xml 文件。
4. 编辑中的程序会自动保存：不小心关掉或刷新页面，重新打开后自动恢复，不用担心丢程序。
5. 「🖥 查看代码」把当前积木程序转换成 Arduino C++ 代码（与 Mixly 生成格式一致），可复制、可下载 .ino 文件直接用 Arduino IDE 打开。
6. 「⚙ 编译」像 Mixly 一样做程序检查：函数是否定义、参数个数是否匹配、游离积木、缺少初始化等，错误和警告一目了然。
7. 「⭐ 巡线大师」「🛣️ 精准巡线」的 PID 参数与真车同名同义，调好的参数可直接上车。
8. 部分外设积木（ESP-NOW、菊链、小智AI、遥控手柄、步进电机等）在仿真中会提示"不产生实际动作"，不影响程序流程执行。

2. 地图页面 — 选择地图

1. 第一次进入「地图页面」会显示选择地图界面：内置 3 张比赛地图（城市治理、无人控制系统·陆地人员救助、航天创新）+ 演示赛道。
2. 点选一张地图卡片，点「✔ 确定」，系统自动读取地图实际尺寸（PDF 按页面物理尺寸，图片按 DPI）。
3. 选过的地图和摆放好的小车位置会自动记住：下次再进入「地图页面」直接全屏显示当前地图和小车状态。
4. 点「🔄 更换地图」可重新选择；点「📄 上传地图」可加载自己电脑里的 PDF / PNG / JPG 地图。

3. 地图页面 — 摆放小车与运行

1. 在地图上按住小车拖动到起点位置；拖动空白处平移视角。
2. 键盘 ← / → 方向键旋转车身（每按一次 5°）；鼠标滚轮缩放画面；「⛶ 适应」按钮让地图完整显示在窗口里。
3. 想让地图更大：点「⛶ 全屏」进入沉浸全屏（隐藏浏览器和串口，地图铺满整个物理屏幕，按 Esc 退出）；或点「⤢ 填满」把地图放大到与窗口同宽（上下超出部分拖动画布查看）。注意：地图按真实比例绘制，宽高比和屏幕不同时（如 220×180 的地图在宽屏上），完整显示必有留白，这是比例决定的。
4. 地图默认铺满几乎整个屏幕：底部的「串口监视器」默认收起成一条细线（仍显示最新一条输出），需要看完整输出时点「⌄ 展开」，地图会自动腾出空间；收起/展开状态会记住。
5. 摆好后点「▶ 开始仿真」，小车开始执行编程页面里编好的程序（初始化 → 主循环）。
6. 可调仿真速度 0.5×~8× 慢放或快放；「↺ 重置」让小车回到起点重新跑。
7. 底部「串口监视器」显示打印积木输出；传感器圆点绿色=白色地面，红色=压到黑线；TFT 彩屏积木会点亮画面左上角的虚拟彩屏窗口。

4. 仿真精度说明

1. 物理模型含死区、速度非线性、编码器标定、轮距误差（按实测标定拟合），比理想模型更接近真车。
2. 适合验证程序逻辑、循迹策略、路口判断、PID 参数方向；上车后参数需按实际情况微调。

常见问题

1. 页面空白/积木出不来：首次打开需联网加载 Blockly 组件（CDN），稍等几秒或刷新页面。
2. 内置地图加载失败：内置地图需要通过本地服务器访问（不要直接双击 HTML 文件）。推荐在系统目录运行 python -m http.server 8734 后用 http://127.0.0.1:8734/巡线小车虚拟仿真系统V3.0.html 打开。
3. PDF 加载成功但看不见地图：多为 PDF 第 1 页是空白封面，系统会自动跳过空白页找地图页；若整页仍是白的，说明线条太细（CAD 图），请加粗线条或转成 PNG/JPG 再上传。
4. 小车原地打转：检查单灰度巡线的"线的左侧/右侧"是否选反、Kp 是否过大。
5. 巡线丢失：调大 Kp、核对灰度传感器间距/前瞻距离是否与实车一致。