# 朋友制作器快速上手

[English](en/user-trial-guide.md)

这份文档只服务一件事：让你按当前项目真实可用的方式，完成一次从安装启动到开始绘制的主流程。

当前统一入口是四页工作流：

`刷入固件 -> 手柄测试 -> 调试测速 -> 脚本生成`

开始前先提醒一句：

- 这不是 `零门槛`、`即装即用` 的纯消费级工具
- 首次使用通常仍需要完成 `ESP32` 刷写、串口或驱动识别、`Switch` 手柄配对和 `timing` 调整
- 如果你之前没有接触过 `ESP32`、`PlatformIO` 或类似链路，建议严格按顺序逐步验证；首次环境准备通常需要稳定外网，并预留一定的准备与调试时间

如果你还没了解项目定位，先看仓库首页：[README](../README.md#zh-cn)。
如果中途遇到串口、联网、固件、连接或漂移问题，直接跳到：[排障说明](troubleshooting.md)。

## 1. 先理解项目

### 1.1 它是什么

`朋友制作器` 是一个面向 `Nintendo Switch《朋友收集：梦想生活》 / Tomodachi Life` 的自动绘制工作台。

它会把图片转换成像素预览和动作脚本，再通过 `ESP32-WROOM-32 / ESP-32S` 模拟 `Switch Pro Controller` 输入，在游戏画板里完成自动绘制。

### 1.2 当前主线能力

当前版本已经把下面这些能力接到同一套工作流里：

- `刷入固件`
- `手柄测试`
- `调试测速`
- `脚本生成`
- `PNG / JPG / WEBP / SVG` 图片导入、像素预览、模板裁切、自动扣背景
- `单色绘制`
- `官方色绘制`
- `自定义多色`
- 方块像素笔刷 `1 / 3 / 7 / 13 / 19 / 27` 六档
- 暂停、继续、中断并保存恢复点

### 1.3 当前使用建议

- 当前已经正式支持 `单色绘制`、`官方色绘制` 和 `自定义多色`
- 第一次试用时，仍建议先用 `单色绘制` 或更简单的图片把整条链路跑通
- 当前公开界面只开放方块像素笔刷；圆形像素笔刷仍是预留入口
- 当前第一优先级是 `输入稳定性`，不是 `绘制速度`
- 当前系统固定按 `256x256` 和 `画布中心起步` 建模
- 已知部分 `ESP32` 兼容板在连接阶段存在个体差异

### 1.4 开始前必须知道

开始正式绘制前，请先确认这 3 件事：

1. `脚本生成` 页里已经选好你要使用的像素画笔；开始或恢复绘制时，应用会自动切到这一档
2. 进入绘图页后，画笔和光标停在 `画布中心`
3. 如果使用 `官方色绘制`，保持游戏默认的 `9` 个色盘槽位颜色

补充提醒：

- 当前恢复流程也按“重新进入绘图页后，从画布中心继续”建模；恢复时也会自动重新切回保存时的画笔
- 开始绘制后，不要再操作手柄，也不要触碰屏幕，否则容易错位
- 当前建议使用 `方块笔刷`；圆形笔刷不要作为首次试用入口

## 2. 准备硬件与环境

你至少需要准备：

- 一台 `macOS` 电脑或 `Windows x64` 电脑
- 一块 `ESP32-WROOM-32 / ESP-32S` 开发板
- 一台 `Nintendo Switch`
- 一根可传输数据的 USB 线
- 一个 `稳定联网` 的环境

补充说明：

- 常见兼容板如 `ESP32 DevKitC`、`NodeMCU-32S` 通常也可以
- 当前不建议把 `ESP32-C3 / ESP32-S3 / ESP32-C6` 当作主线板型
- 首次准备 `PlatformIO`、下载工具链与部分依赖时需要稳定联网；如果网络波动，准备流程可能失败或明显变慢
- `Windows ARM64` 当前不在支持范围内

硬件连接方式见：[硬件连接说明](wiring.md)。

## 3. 选择进入方式

项目当前支持两条并列入口：`桌面端安装包` 和 `仓库源码路线`。
它们的安装方式不同，但进入应用后都汇合到同一套四页工作流。

### 3.1 路线 A：桌面端安装包

#### macOS

- 打开 `.dmg`
- 把 `Friend Maker.app` 拖到 `Applications`
- 直接启动 `Friend Maker`

#### Windows x64

- 运行 `.exe` 安装包
- 按向导完成安装
- 从桌面快捷方式或开始菜单启动 `Friend Maker`

首次使用请注意：

- 不要安装在中文目录下
- 首次进入 `刷入固件` 页时，如果提示缺少 `PlatformIO`，点击 `准备 PlatformIO`
- 如果应用提示缺少 `Python`，允许它下载一个仅供 `Friend Maker` 使用的本地运行环境即可
- `Windows` 下如果 `PlatformIO` 已就绪但没有串口，可先在应用内安装 `CP210x` 驱动，再尝试 `CH340/CH341`

平台细节见：

- [Windows 平台补充](setup-windows.md)
- [macOS 平台补充](setup-mac.md)

### 3.2 路线 B：仓库源码路线

如果你想直接从仓库源码运行，请先准备：

- `Node.js 20+`
- `npm 10+`
- `PlatformIO Core 6+`
- `Windows` 手动安装 `PlatformIO` 时还需要可用的 `Python 3`

常见启动方式如下。

#### 直接手动启动

```bash
cd /path/to/friendmaker
npm install
npm run check
npm run ui:dev
```

启动后打开：

```text
http://127.0.0.1:4307
```

#### macOS 一键启动脚本

你也可以双击：

- `Start Friend Maker.command`

这个脚本会转到仓库里的 `scripts/macos-launch.sh`，自动检查依赖并启动本地界面。

#### Windows 一键安装脚本

你也可以双击：

- `Install Friend Maker.cmd`

这个脚本会自动检查 `Node.js`、`npm`、`Python 3` 和 `PlatformIO`，并执行：

- `npm install`
- `npm run check`

注意：

- 它负责 `安装和检查`
- 安装完成后，仍然需要你手动运行 `npm run ui:dev`

## 4. 刷入 ESP32 固件

### 4.1 推荐方式：在应用里刷固件

进入 `刷入固件` 页后，按这个顺序：

1. 选择 `Switch 型号`
2. 选择目标环境
3. 确认串口设备
4. 点击 `编译并刷入固件`

当前 `Switch 型号` 分成 2 个：

- `Switch1 和 Lite 固件`：适用于 Switch1 和 Switch Lite，使用启用 `SWITCH_LITE` 的稳定构建，重点提升配对和按键稳定性
- `Switch 2`：使用更保守的蓝牙 HID 时序，并在认证成功后主动补发 `virtual cable` 请求

当前主线推荐环境：

- `esp32dev_wireless`：默认推荐，适合常见 `ESP32-WROOM-32 / ESP-32S`
- `nodemcu_32s_wireless`：如果你的板子明确标注 `NodeMCU-32S`，可以改用它

补充说明：

- 如果你选择的是 `Switch1 和 Lite 固件` 或 `Switch 2`，当前目标环境需要保持在主线 `ESP32-WROOM-32 / ESP-32S`
- 旧标准 `Switch` 固件已在界面隐藏，仅作为命令行兼容兜底保留

页面里还可以直接完成：

- `刷新串口`
- `准备 PlatformIO`
- `Windows` 串口驱动辅助安装
- 查看完整刷写日志

如果刷写失败，先检查：

- 数据线是否可传输数据
- 串口是否被别的程序占用
- 是否选错了目标环境

如果开发板进不去下载模式，可以尝试按住实体板上的 `BOOT` 键，再重新刷入。

### 4.2 命令行兜底方式

如果你正在使用源码路线，或想单独验证 `PlatformIO`，可以直接执行：

```bash
cd /path/to/friendmaker/firmware/esp32

# 旧标准 Switch 固件（界面已隐藏，仅命令行兜底）
pio run -e esp32dev_wireless -t upload

# Switch 2（仅限 ESP32-WROOM-32 / ESP-32S）
pio run -e esp32dev_wireless_switch2 -t upload

# Switch1 和 Lite 固件（仅限 ESP32-WROOM-32 / ESP-32S）
pio run -e esp32dev_wireless_switch_lite -t upload
```

如果 `pio` 不在 `PATH` 里，请改用完整路径：

- `macOS`：`~/.platformio/penv/bin/pio`
- `Windows`：`%USERPROFILE%\.platformio\penv\Scripts\pio.exe`

`Windows` 示例：

```powershell
cd C:\path\to\friendmaker\firmware\esp32

# 旧标准 Switch 固件（界面已隐藏，仅命令行兜底）
$env:USERPROFILE\.platformio\penv\Scripts\pio.exe run -e esp32dev_wireless -t upload --upload-port COM3

# Switch 2（仅限 ESP32-WROOM-32 / ESP-32S）
$env:USERPROFILE\.platformio\penv\Scripts\pio.exe run -e esp32dev_wireless_switch2 -t upload --upload-port COM3

# Switch1 和 Lite 固件（仅限 ESP32-WROOM-32 / ESP-32S）
$env:USERPROFILE\.platformio\penv\Scripts\pio.exe run -e esp32dev_wireless_switch_lite -t upload --upload-port COM3
```

## 5. 手柄测试

刷入固件成功后，进入 `手柄测试` 页。

按这个顺序操作：

1. 点击 `连接手柄`
2. 在 `Switch` 上进入 `控制器 -> 更改握法/顺序`
3. 等待状态进入“已连接 / 可发送”
4. 继续做按钮、方向键和摇杆单步测试

如果一开始就连不上，按这个顺序处理：

1. 点击 `重置手柄蓝牙`
2. 等待完成
3. 再点 `连接手柄`
4. 在 `Switch` 上重新进入 `更改握法/顺序`
5. 如果还是连不上，按一下开发板上的 `EN` 键重启，再重新连接
6. 如果还是不稳定，回到 `刷入固件` 页重新刷一次固件

已知情况：

- 部分 `ESP32` 兼容板在连接阶段可能更容易掉线
- 如果连接建立后仍反复断开，除了继续重试软件流程，也建议一起排查数据线、供电和开发板个体差异
- 试用时尽量保持蓝牙环境干净，减少附近同时活跃的蓝牙设备

## 6. 调试测速

连接能稳定建立后，进入 `调试测速` 页。

这页的作用不是先追求最快，而是先把 `当前设备 + 当前板子 + 当前线材` 组合跑稳。

建议顺序：

1. 先用推荐默认值 `45 / 65`
2. 优先调 `inputDelay`
3. 只有在连接和动作都基本稳定后，再微调 `buttonPressDuration`

经验口径：

- `inputDelay` 更像稳定性旋钮
- `buttonPressDuration` 更像按键力度旋钮

如果你看到下面这些情况，先动 `inputDelay`：

- 连续动作吃不稳
- 偶发漂移
- 长流程里越来越容易错位

补充建议：

- 如果开发板已经明显发热，适当降温后再继续测试，某些板子的稳定性会更好
- 如果当前环境里蓝牙设备很多，先减少附近同时活跃的蓝牙连接，再继续调 timing

## 7. 开始绘制

前面三页都正常后，再回到 `脚本生成` 页。

### 7.1 当前推荐试用方式

第一次试用建议：

- 绘制模式：`单色绘制`
- 画笔大小：`3`
- 笔刷：`方块笔刷`
- 图片：结构简单、对比清晰的图

如果这条链路稳定，再尝试：

- `官方色绘制`
- `自定义多色`
- 更复杂的图片
- 更细的画笔

### 7.2 基本步骤

1. 导入图片
2. 选择方块像素画笔大小
3. 选择 `单色绘制`、`官方色绘制` 或 `自定义多色`
4. 需要时调整模板、缩放、位置和自动扣背景
5. 先点 `仅生成命令` 看预览和统计信息
6. 确认无误后，再点 `一键开始绘制`

### 7.3 关于恢复任务

如果你执行了：

- `暂停绘制`
- `中断并保存恢复点`
- 异常退出后重新启动应用

应用会在本地保留恢复任务。

继续前请先：

1. 在 `Switch` 里保存当前画作
2. 手动重新进入绘图页
3. 确认光标重新回到 `画布中心`
4. 再从恢复任务里继续；恢复时会自动重新切到上次保存的画笔

## 8. 使用中的注意事项

- 绘制过程中不要拔掉开发板
- 绘制过程中不要关闭 `Friend Maker`，也不要关闭源码路线里启动的本地服务进程
- 绘制过程中不要再操作手柄，也不要触碰 `Switch` 屏幕
- `暂停绘制` 和 `中断并保存恢复点` 都会等当前命令执行完再生效
- 如果 `正在中断绘制` 长时间不结束，再使用页面里的应急按钮强制清除卡住状态
- 如果单步测试里出现 `串键`、粘连或异常连发，优先按一下开发板上的 `EN` 键重启，再重新连接手柄
- 如果按 `EN` 重启后串键立刻消失，先重新做一轮手柄验证，再判断绘制或颜色问题

## 9. 继续排障与平台补充

公开文档建议这样分工使用：

- [排障说明](troubleshooting.md)：遇到问题时先看这里
- [硬件连接说明](wiring.md)：确认支持板型、连接方式、线材和供电
- [Windows 平台补充](setup-windows.md)：看 `winget`、驱动、`COM` 口相关问题
- [macOS 平台补充](setup-mac.md)：看串口、驱动和源码启动相关问题