[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1228":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":34,"discoverSource":35},1228,"friendmaker","zhouxiyu1997\u002Ffriendmaker","zhouxiyu1997","Friend Maker is a macOS\u002FWindows toolkit for turning images into pixel grids and ESP32 controller scripts, enabling automatic drawing on Nintendo Switch in Tomodachi Life and related workflows.","",null,"TypeScript",1075,37,1,2,0,40,89,554,120,17.74,"GNU General Public License v3.0",false,"main",true,[27,28,29,30],"esp32","nintendo-switch","pro-controller-emulator","tomodachi-life","2026-06-12 02:00:25","# Friend Maker\n\n[中文说明](#中文说明) | [English](#english)\n\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-GPL--3.0--or--later-blue.svg)\n![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS%20%7C%20Windows-black.svg)\n![Hardware](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fhardware-ESP32--WROOM--32-orange.svg)\n![Status](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-alpha-yellow.svg)\n\n\u003Cp>\n  \u003Ca href=\"docs\u002Fmedia\u002Fdemo-video.mp4\">\n    \u003Cimg src=\"docs\u002Fmedia\u002Fdemo-real-device.jpeg\" alt=\"Friend Maker real device demo on Nintendo Switch\" width=\"760\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp>\n  \u003Cimg src=\"docs\u002Fmedia\u002Fui-studio-page.png\" alt=\"Friend Maker studio page for image import, preview, brush size, color modes, and serial execution\" width=\"32%\" \u002F>\n  \u003Cimg src=\"docs\u002Fmedia\u002Fui-firmware-page.png\" alt=\"Friend Maker firmware flashing page with PlatformIO integration\" width=\"32%\" \u002F>\n  \u003Cimg src=\"docs\u002Fmedia\u002Fui-controller-page.png\" alt=\"Friend Maker controller test page with connection status and button testing\" width=\"32%\" \u002F>\n\u003C\u002Fp>\n\n## 中文说明\n\n`朋友制作器` 是一个面向 `macOS \u002F Windows + ESP32-WROOM-32 \u002F ESP-32S` 的自动绘制工具。  \n它会将图片转换成像素网格和手柄动作脚本，再通过 ESP32 模拟 Switch Pro Controller 输入，在游戏画板中自动完成绘制。当前版本主要面向《朋友收集：梦想生活》与 `Tomodachi Life` 的绘图场景。\n\n这个项目已经历过多轮迭代，当前 README 以最新的 `桌面端四页工作流` 为准：\n\n- `刷入固件`\n- `手柄测试`\n- `调试测速`\n- `脚本生成 \u002F 恢复绘制`\n\n当前最推荐的体验路线仍然是 `单色绘制` 和 `官方色绘制`。  \n`自定义多色` 已经开放测试入口，但稳定性仍弱于前两条主线，当前仍属于 `测试阶段 \u002F 实验能力`。\n\n关键词：`Friend Maker`、`朋友制作器`、`Tomodachi Life`、`朋友收集：梦想生活`、`Nintendo Switch auto draw`、`ESP32 Pro Controller emulator`、`pixel art drawing automation`、`Bluetooth Classic HID`。\n\n### 平台支持\n\n- 支持桌面端一键安装启动：`macOS`\n- 支持桌面端一键安装启动：`Windows x64`\n- 暂不支持：`Windows ARM64`\n- 暂未正式支持：`Linux`\n\n当前版本已经提供：\n\n- `macOS \u002F Windows x64` 的桌面端安装包，安装后可直接启动\n- `macOS` 的 `Start Friend Maker.command` 一键启动脚本，作为仓库版备用方式\n- `Windows` 的 `Install Friend Maker.cmd` 一键安装脚本与手动启动流程，作为仓库版备用方式\n\n参考文档：\n\n- [macOS \u002F Windows 试用说明](docs\u002Fuser-trial-guide.md)\n- [Windows 安装说明](docs\u002Fsetup-windows.md)\n\n### 演示\n\n- [查看演示视频](docs\u002Fmedia\u002Fdemo-video.mp4)\n\n### 项目功能\n\n- 导入 `PNG \u002F JPG \u002F SVG` 图片，并生成绘制预览\n- 支持 `1 \u002F 3 \u002F 7 \u002F 13 \u002F 19 \u002F 27` 六种画笔大小\n- 支持 `单色绘制`、`官方色绘制`，以及 `自定义多色（测试中）`\n- 支持 `256x256` 脚本坐标画布工作流\n- 支持异形图纸模板裁切与模板预览\n- 支持 `自动扣背景`，适合白底、浅灰底、棋盘格假透明图\n- 通过带 `SEQ \u003Csession> \u003Cseq>` 去重帧的串口协议将绘制脚本逐条发送给 ESP32，并等待 `ACK`\n- 在界面中完成脚本生成、固件刷写、手柄连接、按钮测试与调试测速，以及暂停、继续和中断绘制\n- 支持本地恢复任务：暂停、中断、异常或应用重启后，仍可从恢复点继续\n\n### 整体架构\n\n```text\n图片输入\n  -> 像素化 \u002F 量化 \u002F 路径规划\n  -> 指令脚本\n  -> 串口 ACK 发送\n  -> ESP32-WROOM-32\n  -> Bluetooth Classic HID\n  -> Nintendo Switch\n  -> 游戏内画布绘制\n```\n\n### 当前主流程\n\n当前最稳定、也是文档默认采用的使用顺序：\n\n1. `刷入固件`\n2. `手柄测试`\n3. `调试测速`\n4. `脚本生成`\n\n对应的实际动作是：\n\n1. 在 `刷入固件` 页更新推荐固件并确认串口正常\n2. 在 `手柄测试` 页完成蓝牙连接、按钮和方向测试\n3. 在 `调试测速` 页优先调 `inputDelay`，再微调 `buttonPressDuration`，先把稳定性跑出来\n4. 回到 `脚本生成` 页导入图片、检查预览并正式开始绘制\n\n### 当前版本定位\n\n- 当前主线已经从早期的“手工脚本 + 命令行试验”迭代到“桌面端闭环工作流”\n- README 默认描述 `桌面端安装包 \u002F 桌面端页面` 的最新行为\n- 与绘图质量和成功率直接相关的能力，会优先以 `输入稳定性` 和 `恢复能力` 为准\n- `inputDelay` 更像稳定性旋钮，`buttonPressDuration` 更像力度旋钮；建议先调稳定，再看速度\n- `自定义多色` 虽然可见、可测试，但暂时不建议作为首次试用路线\n\n### 绘制模式\n\n#### 单色绘制\n\n- 深色像素会被绘制\n- 浅色像素会保留为空白\n- 适合黑白图、轮廓图与简单像素素材\n\n#### 官方色绘制\n\n- 会量化到游戏内置的 `7 x 12` 官方色盘\n- 当前支持 `8 \u002F 16 \u002F 32 \u002F 64 \u002F 84` 色量化档位\n- 当前按游戏原始 `9` 个色盘槽位的默认颜色起步\n\n#### 自定义多色（测试中）\n\n- 会先把图片自动量化成多种颜色，再按批次写入右侧 `9` 个自定义色槽\n- 当前更适合颜色数量较少、结构较简单的图片\n- 这是仍在继续打磨的实验路线，稳定性与容错性暂时弱于 `单色绘制` 和 `官方色绘制`\n- 首次试用时，更推荐先用 `单色绘制` 或 `官方色绘制` 验证整体链路\n\n### 运行要求\n\n#### 硬件\n\n- Mac 或 Windows 电脑\n- `ESP32-WROOM-32 \u002F ESP-32S` 开发板\n  常见写法如 `ESP32 DevKitC` 或 `NodeMCU-32S` 兼容板通常也可以；建议选择带 `USB` 串口、可直接刷机的版本，并尽量避开 `ESP32-C3 \u002F ESP32-S3 \u002F ESP32-C6` 这类只有 `BLE` 或当前不属于本项目主线支持范围的型号\n- Nintendo Switch\n- 可传输数据的 USB 线\n\n#### 软件\n\n- 如果你使用 `桌面端安装包`，不需要预先手动安装 `Node.js`、`npm` 或 `PlatformIO`，但首次准备 `PlatformIO` 需要联网\n- 如果你使用 `仓库版备用流程`，建议准备 `Node.js 20+`、`npm 10+`、`PlatformIO Core 6+`\n\n### 快速开始\n\n#### 桌面端一键安装启动（推荐）\n\n当前推荐优先使用桌面端安装包：\n\n- `macOS`：安装 `.dmg` 后直接启动 `Friend Maker`\n- `Windows x64`：运行安装包 `.exe` 后直接启动 `Friend Maker`\n\n首次使用请注意：\n\n- 如果 `刷入固件` 页提示没有 `PlatformIO`，点击 `准备 PlatformIO`\n- 这一步需要联网；如果应用提示缺少 `Python`，允许下载仅供 `Friend Maker` 使用的本地 Python 运行环境即可\n- 初次刷入固件可能需要 `5 分钟左右`，请耐心等待\n- 不要安装在中文目录下\n- 如果你是 `Windows` 用户，且串口设备列表为空、检查不到 `ESP32`，在 `PlatformIO` 就绪后先尝试 `安装 CP210x 驱动（优先）`，仍无效果再尝试 `安装 CH340\u002FCH341 驱动（备选）`\n- `Windows ARM64` 当前不在支持范围内；这类设备市场占有率约 `1%`，我们手头也没有设备可测，欢迎有能力的朋友提交 PR 补充支持\n\n#### 仓库版备用流程\n\n路径说明：\n\n- 将 `\u002Fpath\u002Fto\u002Ffriendmaker` 替换为你自己的本地项目目录\n- 将 `\u003Cyour-serial-port>` 替换为你自己的串口设备，例如 macOS 上的 `\u002Fdev\u002Fcu.usbserial-0001` 或 Windows 上的 `COM3`\n- 如果 `pio` 已经在 shell 的 `PATH` 中，可以直接使用 `pio ...`\n- 如果没有，请使用完整的 PlatformIO 路径\n- macOS 路径：`~\u002F.platformio\u002Fpenv\u002Fbin\u002Fpio`\n- Windows 路径：`%USERPROFILE%\\\\.platformio\\\\penv\\\\Scripts\\\\pio.exe`\n\n#### macOS 仓库版一键启动（备用）\n\n你现在可以通过下面两种方式启动应用：\n\n- 双击 [`Start Friend Maker.command`](.\u002FStart%20Friend%20Maker.command)\n- 或运行下面的命令：\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\n.\u002FStart\\ Friend\\ Maker.command\n```\n\n这个启动器会：\n\n- 检测 `Node.js`、`npm`、`Python 3` 和 `PlatformIO`\n- 在缺失时尝试自动安装所需软件\n- 在需要时自动安装项目依赖\n- 启动本地 Web UI\n- 自动打开 `http:\u002F\u002F127.0.0.1:4307`\n\n补充说明：\n\n- 如果缺少 `Homebrew`，启动器会询问是否安装\n- 第一次安装软件时，终端可能会请求输入系统密码\n- 使用过程中请保持终端窗口开启\n\n#### Windows 仓库版一键安装（备用）\n\n你现在可以通过下面两种方式完成安装：\n\n- 双击 [`Install Friend Maker.cmd`](.\u002FInstall%20Friend%20Maker.cmd)\n- 或在 `CMD` \u002F `PowerShell` 中运行：\n\n```bat\ncd C:\\path\\to\\friendmaker\nInstall Friend Maker.cmd\n```\n\n这个安装脚本会：\n\n- 检测 `Node.js`、`npm`、`Python 3` 和 `PlatformIO`\n- 在检测到 `winget` 时尝试自动安装缺失的软件\n- 自动执行 `npm install`\n- 自动执行 `npm run check`\n- 如果安装失败，用中文提示当前问题\n\n补充说明：\n\n- 如果系统里没有 `winget`，请先安装或更新 `App Installer`\n- 如果自动安装失败，可以直接参考 [Windows 安装说明](docs\u002Fsetup-windows.md) 走原本的手动安装流程\n- 这个脚本负责安装，当前 Windows 仍然需要手动运行 `npm run ui:dev` 启动网页\n\n#### 1. 安装依赖\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\nnpm install\n```\n\n#### 2. 检查项目\n\n```bash\nnpm run check\n```\n\n#### 3. 刷入固件\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\u002Ffirmware\u002Fesp32\n~\u002F.platformio\u002Fpenv\u002Fbin\u002Fpio run -e esp32dev_wireless -t upload\n```\n\nWindows 示例：\n\n```powershell\ncd C:\\path\\to\\friendmaker\\firmware\\esp32\n$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe run -e esp32dev_wireless -t upload --upload-port COM3\n```\n\n如果刷固件时开发板一直进不去下载模式，可以尝试按住实体板上的 `BOOT` 键，再重新刷入。\n\n#### 4. 启动网页界面\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\nnpm run ui:dev\n```\n\n打开：\n\n```text\nhttp:\u002F\u002F127.0.0.1:4307\n```\n\n### 开始绘制前必须确认\n\n这 3 条是试用时最容易漏掉的前提：\n\n1. Switch 中的画笔大小要和网页当前选择一致\n2. 开始绘制前，画笔和光标必须停在画布中心\n3. 如果使用官方色绘制，保持游戏默认的 `9` 个色盘槽位颜色即可\n\n补充约束：\n\n- 当前绘图与恢复流程都只支持“重新进入绘图页后，从画布中心继续”这一个起点假设\n- 不要把画布理解成可以稳定“撞到左上角再归零”的有边界平面；游戏主画布当前没有可依赖的左上角复位语义\n- 如果文档里提到“归左上”或“左上角起点”，那只适用于色盘或颜色编辑页内部的导航建模，不适用于绘图画布光标恢复\n\n### 自动扣背景\n\n如果素材是下面这些类型：\n\n- 白底 PNG\n- 浅灰底 PNG\n- 棋盘格“假透明”图片\n\n可以在脚本生成页的预览模块中启用 `自动扣背景`。\n\n补充说明：\n\n- 真正带透明通道的 PNG 不需要开启\n- `自动扣背景` 是边缘背景识别，不是 AI 抠图\n- 对角色、物品与像素素材通常已经够用\n\n### 网页模块\n\n#### 脚本生成\n\n- 导入图片\n- 选择画笔大小\n- 选择单色、官方色或自定义多色（测试中）\n- 选择模板、缩放和位置，并检查预览\n- 生成预览与命令\n- 查看官方色盘预览、统计信息与执行状态\n- 一键开始绘制\n- 暂停、中断或异常后会在本地保留恢复任务；如果应用在暂停期间被关闭，下次启动后该任务也会自动转成可恢复状态\n- 可以从恢复点继续，也可以手动放弃已经不需要的恢复记录\n- 如果“正在中断绘制”长时间卡住，页面会出现应急按钮，用于强制清除当前卡住状态\n\n#### 刷入固件\n\n- 枚举串口\n- 当前主线支持的固件目标环境为：`ESP32-WROOM-32 \u002F ESP-32S` 与 `NodeMCU-32S`\n- 调用本机 PlatformIO\n- 编译并刷入 ESP32 固件\n- Windows 下可在页面内直接安装 `CP210x` 或 `CH340\u002FCH341` 串口驱动\n- 返回刷写结果与滚动日志\n\n#### 手柄测试\n\n- 连接手柄\n- 重置手柄蓝牙\n- 如果连接手柄连不上，先点击 `重置手柄蓝牙`，再点击 `连接手柄`\n- 如果还是连不上，可以按一下实体板上的 `EN` 键重启开发板，再重新点击 `连接手柄`\n- 如果还是连不上，回到 `刷入固件` 页重新刷一次固件后再试\n- 单步测试按钮、方向键与摇杆，并可选择摇杆步数\n- 支持 `Home`、`Capture`、`LS`、`RS` 和 `L+R 配对` 等单独动作测试\n- 查看 HID 连接状态\n- 支持手动断开串口\n- 发送自定义测试命令并查看滚动日志\n\n### 仓库结构\n\n```text\napps\u002Fdesktop\u002Fsrc\n  app\u002F               绘制计划生成\n  cli\u002F               CLI 参数解析\n  config\u002F            默认配置与官方色表\n  image\u002F             图片缩放、量化、预览与扣背景\n  path\u002F              路径生成与轻量优化\n  protocol\u002F          指令对象与序列化\n  serial\u002F            串口枚举与 ACK 发送\n  web\u002F               本地网页工作台\n\nfirmware\u002Fesp32\n  src\u002F               ESP32 固件与蓝牙控制器实现\n\nprofiles\u002F            示例 profile\nexamples\u002F            演示图片与示例命令\ndocs\u002F                开发与试用文档\ndocs\u002Fmedia\u002F          README 展示图片与视频\n```\n\n### 文档\n\n- [docs\u002Fuser-trial-guide.md](docs\u002Fuser-trial-guide.md)：给试用者的启动与使用说明\n- [docs\u002Fdevelopment-manual.md](docs\u002Fdevelopment-manual.md)：当前开发手册与已知规则\n- [docs\u002Fsetup-mac.md](docs\u002Fsetup-mac.md)\n- [docs\u002Farrival-checklist.md](docs\u002Farrival-checklist.md)\n- [docs\u002Fwiring.md](docs\u002Fwiring.md)\n\n### 当前限制\n\n- Switch 连接和绘图流程仍然依赖固定场景假设\n- `自定义多色` 仍在测试阶段，当前整体稳定性明显弱于 `单色绘制` 和 `官方色绘制`\n- 自定义颜色自动调色和长流程容错还不稳定，当前更推荐 `官方色绘制`\n- 第一优先级仍然是输入稳定性，而不是绘制速度\n\n### 当前状态\n\n当前仓库已经具备可试用的闭环：\n\n```text\n网页刷入固件\n  -> 测试手柄连接\n  -> 导入图片\n  -> 像素化 \u002F 量化 \u002F 扣背景\n  -> 生成命令脚本\n  -> 串口 ACK 发送\n  -> ESP32 协议解析\n  -> Bluetooth Classic Switch 控制器输出\n  -> 游戏内绘制\n```\n\n### 许可证\n\n本仓库采用 **GPL-3.0-or-later** 开源协议。  \n完整协议内容请查看 [LICENSE](LICENSE)。\n\n当前 `firmware\u002Fesp32` 中的 Switch 蓝牙兼容实现，引入并改写自 [UARTSwitchCon](https:\u002F\u002Fgithub.com\u002Fnullstalgia\u002FUARTSwitchCon) 的思路与代码路径，因此当前仓库采用 GPL 以保持许可证一致。\n\n### 作者与来源\n\n- 来源作者：小红书作者 `惜羽拓麻镇`\n- 如果你公开转发、转载或分享这个项目，建议注明作者名称 `惜羽拓麻镇`\n- 建议同时附上原始发布地址\n\n## English\n\n`Friend Maker` is an automatic drawing toolkit for `macOS \u002F Windows + ESP32-WROOM-32 \u002F ESP-32S`.  \nIt converts images into pixel grids and controller action scripts, then uses an ESP32 to emulate Switch Pro Controller input and draw automatically on the in-game canvas. The current version is primarily tailored for drawing workflows in `Tomodachi Life` and 《朋友收集：梦想生活》.\n\nThe project has already gone through many iterations, and this README now follows the latest `desktop four-page workflow`:\n\n- `Firmware Flash`\n- `Controller Test`\n- `Timing Tune \u002F Benchmark`\n- `Script Studio \u002F Recovery`\n\nThe recommended paths are still `mono drawing` and `official palette drawing`.  \n`Custom multicolor` is now exposed for testing, but it is still less stable than those two main paths and should be treated as an `experimental \u002F testing-stage` feature.\n\nKeywords: `Friend Maker`, `Tomodachi Life`, `Nintendo Switch auto draw`, `ESP32 Pro Controller emulator`, `pixel art drawing automation`, `Bluetooth Classic HID`.\n\n### Compatibility\n\n- Desktop app one-click install and launch supported: `macOS`\n- Desktop app one-click install and launch supported: `Windows x64`\n- Not supported yet: `Windows ARM64`\n- Not officially supported yet: `Linux`\n\nThe current version already provides:\n\n- desktop installers for `macOS \u002F Windows x64`, with direct app launch after install\n- the `Start Friend Maker.command` launcher for the repo-based macOS fallback flow\n- the `Install Friend Maker.cmd` installer and manual startup flow for the repo-based Windows fallback path\n\nReference documents:\n\n- [macOS \u002F Windows Trial Guide](docs\u002Fuser-trial-guide.md)\n- [Windows Setup Guide](docs\u002Fsetup-windows.md)\n\n### Showcase\n\n- [Watch demo video](docs\u002Fmedia\u002Fdemo-video.mp4)\n\n### What It Does\n\n- Import `PNG \u002F JPG \u002F SVG` images and generate drawing previews\n- Support six brush sizes: `1 \u002F 3 \u002F 7 \u002F 13 \u002F 19 \u002F 27`\n- Support `mono drawing`, `official palette drawing`, and `custom multicolor (testing)`\n- Use a `256x256` script-coordinate canvas workflow\n- Support irregular drawing templates and template-aware preview cropping\n- Support `automatic background removal` for white, light gray, and fake transparency checkerboard backgrounds\n- Send drawing commands to the ESP32 over a `SEQ \u003Csession> \u003Cseq>` deduplicating serial protocol and wait for `ACK`\n- Handle script generation, firmware flashing, controller connection, button testing, timing tuning, and benchmark actions from the shared app interface\n- Preserve local recovery jobs so paused, interrupted, failed, or restarted sessions can still be resumed from a recovery point\n\n### Architecture\n\n```text\nImage input\n  -> Pixelization \u002F Quantization \u002F Path planning\n  -> Command script\n  -> Serial ACK sender\n  -> ESP32-WROOM-32\n  -> Bluetooth Classic HID\n  -> Nintendo Switch\n  -> In-game canvas drawing\n```\n\n### Current Workflow\n\nThe most stable workflow, and the one used by the documentation by default, is:\n\n1. `Flash firmware`\n2. `Test controller`\n3. `Tune timing`\n4. `Generate script`\n\nThe practical actions are:\n\n1. Update the recommended firmware in the `Firmware Flash` page and confirm the serial port works\n2. Complete Bluetooth connection, button tests, and direction tests in the `Controller Test` page\n3. In the `Timing Tune \u002F Benchmark` page, increase `inputDelay` first, then fine-tune `buttonPressDuration` until the link feels stable\n4. Return to the `Script Studio` page, import an image, review the preview, and start drawing\n\n### Current Product Focus\n\n- The main path has evolved from early command-line experiments into a desktop-app-centered closed loop\n- This README describes the latest packaged desktop app and page flow by default\n- Features that affect success rate are prioritized around `input stability` and `recovery`\n- `inputDelay` behaves more like a stability knob, while `buttonPressDuration` behaves more like a press-strength knob; tune for stability first, speed second\n- `Custom multicolor` is available for testing, but it is still not the recommended first-run path\n\n### Drawing Modes\n\n#### Mono Drawing\n\n- Dark pixels are drawn\n- Light pixels are left blank\n- Suitable for black-and-white images, outline art, and simple pixel assets\n\n#### Official Palette Drawing\n\n- Quantizes colors into the built-in `7 x 12` official palette\n- Currently supports `8 \u002F 16 \u002F 32 \u002F 64 \u002F 84` quantization levels\n- Starts from the game's default colors for the `9` palette slots\n\n#### Custom Multicolor (Testing)\n\n- Automatically quantizes the image into multiple colors, then writes them into the right-side `9` custom palette slots in batches\n- Currently works best on images with fewer colors and simpler structure\n- This path is still experimental, and its stability and tolerance are weaker than `mono drawing` and `official palette drawing`\n- For a first successful run, `mono drawing` or `official palette drawing` is still the safer recommendation\n\n### Requirements\n\n#### Hardware\n\n- A Mac or Windows computer\n- An `ESP32-WROOM-32 \u002F ESP-32S` development board\n  Common labels such as `ESP32 DevKitC` or `NodeMCU-32S` compatible boards are usually fine; prefer versions with a built-in `USB` serial interface that can be flashed directly, and avoid `ESP32-C3 \u002F ESP32-S3 \u002F ESP32-C6` variants because they are BLE-only or not part of the current main supported path for this project\n- Nintendo Switch\n- A USB cable that supports data transfer\n\n#### Software\n\n- If you use the packaged desktop app, you do not need to preinstall `Node.js`, `npm`, or `PlatformIO`, but the first `PlatformIO` setup requires network access\n- If you use the repo-based fallback flow, prepare `Node.js 20+`, `npm 10+`, and `PlatformIO Core 6+`\n\n### Quick Start\n\n#### Desktop app one-click install and launch (recommended)\n\nThe preferred path is now the packaged desktop app:\n\n- `macOS`: install the `.dmg`, then launch `Friend Maker`\n- `Windows x64`: run the installer `.exe`, then launch `Friend Maker`\n\nFirst-use notes:\n\n- if the `Firmware Flash` page says `PlatformIO` is missing, click `Prepare PlatformIO`\n- this step needs network access; if the app says `Python` is missing, allow it to download an app-local Python runtime for Friend Maker\n- the first firmware flash may take around `5 minutes`, so please wait patiently\n- do not install under a non-English path\n- if you are on `Windows` and no serial port appears for the `ESP32`, prepare `PlatformIO` first, then try `Install CP210x Driver` before `Install CH340\u002FCH341 Driver`\n- `Windows ARM64` is not in the current support scope; its market share is only about `1%`, we do not have hardware to validate it, and PRs are welcome if you want to add support\n\n#### Repo-based fallback flow\n\nPath notes:\n\n- Replace `\u002Fpath\u002Fto\u002Ffriendmaker` with your own local project directory\n- Replace `\u003Cyour-serial-port>` with your own serial device, such as `\u002Fdev\u002Fcu.usbserial-0001` on macOS or `COM3` on Windows\n- If `pio` is already in your shell `PATH`, you can use `pio ...` directly\n- Otherwise, use the full PlatformIO path\n- macOS path: `~\u002F.platformio\u002Fpenv\u002Fbin\u002Fpio`\n- Windows path: `%USERPROFILE%\\\\.platformio\\\\penv\\\\Scripts\\\\pio.exe`\n\n#### Repo-based one-click launch on macOS\n\nYou can now start the app in either of these ways:\n\n- double-click [`Start Friend Maker.command`](.\u002FStart%20Friend%20Maker.command)\n- or run:\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\n.\u002FStart\\ Friend\\ Maker.command\n```\n\nThis launcher will:\n\n- detect `Node.js`, `npm`, `Python 3`, and `PlatformIO`\n- try to install missing software automatically\n- install project dependencies automatically when needed\n- start the local web UI\n- open `http:\u002F\u002F127.0.0.1:4307` automatically\n\nNotes:\n\n- if `Homebrew` is missing, the launcher will ask whether it should be installed\n- the Terminal may ask for your password during first-time software installation\n- keep the Terminal window open while using the app\n\n#### Repo-based one-click install on Windows\n\nYou can now install the project in either of these ways:\n\n- double-click [`Install Friend Maker.cmd`](.\u002FInstall%20Friend%20Maker.cmd)\n- or run in `CMD` \u002F `PowerShell`:\n\n```bat\ncd C:\\path\\to\\friendmaker\nInstall Friend Maker.cmd\n```\n\nThis installer will:\n\n- detect `Node.js`, `npm`, `Python 3`, and `PlatformIO`\n- try to install missing software automatically when `winget` is available\n- run `npm install`\n- run `npm run check`\n- show Chinese error messages if installation fails\n\nNotes:\n\n- if `winget` is missing, install or update `App Installer` first\n- if the automatic install fails, switch to the original manual flow in [Windows Setup Guide](docs\u002Fsetup-windows.md)\n- this script handles installation only; on Windows you still start the web UI manually with `npm run ui:dev`\n\n#### 1. Install dependencies\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\nnpm install\n```\n\n#### 2. Type check\n\n```bash\nnpm run check\n```\n\n#### 3. Flash firmware\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\u002Ffirmware\u002Fesp32\n~\u002F.platformio\u002Fpenv\u002Fbin\u002Fpio run -e esp32dev_wireless -t upload\n```\n\nWindows example:\n\n```powershell\ncd C:\\path\\to\\friendmaker\\firmware\\esp32\n$env:USERPROFILE\\.platformio\\penv\\Scripts\\pio.exe run -e esp32dev_wireless -t upload --upload-port COM3\n```\n\n#### 4. Start the web UI\n\n```bash\ncd \u002Fpath\u002Fto\u002Ffriendmaker\nnpm run ui:dev\n```\n\nOpen:\n\n```text\nhttp:\u002F\u002F127.0.0.1:4307\n```\n\n### Before Drawing\n\nThese are the three most commonly missed prerequisites:\n\n1. The brush size in Switch must match the current selection in the web UI\n2. Before drawing starts, the brush and cursor must be positioned at the canvas center\n3. If you use official palette drawing, keep the game's default colors for the `9` palette slots\n\nAdditional constraint:\n\n- The current drawing and recovery flow supports only one restart assumption: after re-entering the drawing page, resume from the canvas center\n- Do not model the drawing canvas as a bounded plane that can reliably reset by pushing into the top-left corner; the in-game canvas does not currently expose a dependable top-left reset semantic\n- If any document mentions \"top-left reset\" or a \"top-left starting point\", that applies only to palette or color-editor navigation models, not to drawing-cursor recovery on the canvas\n\n### Automatic Background Removal\n\nIf your source image is one of the following:\n\n- a white-background PNG\n- a light-gray-background PNG\n- a checkerboard fake-transparency image\n\nyou can enable `automatic background removal` in the preview module of the script generation page.\n\nNotes:\n\n- Real transparent PNG files do not need this option\n- `Automatic background removal` uses edge-background detection, not AI cutout\n- It is usually sufficient for characters, props, and pixel-art materials\n\n### Web UI Pages\n\n#### Script Studio\n\n- Import images\n- Choose brush size\n- Choose mono drawing, official palette drawing, or custom multicolor (testing)\n- Choose template, scale, and position, then review the preview\n- Generate previews and command scripts\n- Review official palette previews, statistics, and execution status\n- Start drawing with one click\n- Preserve local recovery jobs after pause, stop, or failure; if the app closes while paused, the next launch will still surface that job as recoverable\n- Resume from a saved recovery point, or discard recovery records you no longer need\n- If the stop flow stays stuck for too long, the page exposes an emergency action to forcibly clear the stuck execution state\n\n#### Firmware Flash\n\n- Enumerate serial ports\n- The current main supported firmware targets are `ESP32-WROOM-32 \u002F ESP-32S` and `NodeMCU-32S`\n- Call the local PlatformIO installation\n- Build and flash the ESP32 firmware\n- Install `CP210x` or `CH340\u002FCH341` serial drivers directly from the page on Windows\n- Return flash results and scrollable logs\n\n#### Controller Test\n\n- Connect the controller\n- Reset Controller Bluetooth\n- If the controller does not connect, click `Reset Controller Bluetooth` first and then `Connect the controller`\n- If it still does not connect, reflash the firmware and try again\n- Test buttons, D-pad, and stick movement step by step, with selectable stick step sizes\n- Test standalone actions such as `Home`, `Capture`, `LS`, `RS`, and `L+R` pairing\n- Inspect HID connection status\n- Disconnect the serial session manually when needed\n- Send custom test commands and review scrollable logs\n\n### Repository Layout\n\n```text\napps\u002Fdesktop\u002Fsrc\n  app\u002F               Draw plan generation\n  cli\u002F               CLI argument parsing\n  config\u002F            Default config and official palette tables\n  image\u002F             Image resizing, quantization, preview, and background removal\n  path\u002F              Path generation and lightweight optimization\n  protocol\u002F          Command objects and serialization\n  serial\u002F            Serial enumeration and ACK sending\n  web\u002F               Local web workspace\n\nfirmware\u002Fesp32\n  src\u002F               ESP32 firmware and Bluetooth controller implementation\n\nprofiles\u002F            Example profiles\nexamples\u002F            Demo images and sample commands\ndocs\u002F                Development and trial documents\ndocs\u002Fmedia\u002F          README images and videos\n```\n\n### Documentation\n\n- [docs\u002Fuser-trial-guide.md](docs\u002Fuser-trial-guide.md): startup and usage guide for trial users\n- [docs\u002Fdevelopment-manual.md](docs\u002Fdevelopment-manual.md): current development manual and known rules\n- [docs\u002Fsetup-mac.md](docs\u002Fsetup-mac.md)\n- [docs\u002Farrival-checklist.md](docs\u002Farrival-checklist.md)\n- [docs\u002Fwiring.md](docs\u002Fwiring.md)\n\n### Current Limitations\n\n- The Switch connection and drawing workflow still depend on fixed scenario assumptions\n- `Custom multicolor` is still in the testing stage, and its overall stability is clearly weaker than `mono drawing` and `official palette drawing`\n- Automatic custom-color tuning and long-run fault tolerance are not stable yet, so `official palette drawing` is still the recommended color path\n- The highest priority is still input stability, not drawing speed\n\n### Development Status\n\nThe repository already provides a usable end-to-end loop:\n\n```text\nFlash firmware in the web UI\n  -> test controller connection\n  -> import image\n  -> pixelization \u002F quantization \u002F background removal\n  -> generate command script\n  -> serial ACK sender\n  -> ESP32 protocol parser\n  -> Bluetooth Classic Switch controller output\n  -> in-game drawing\n```\n\n### License\n\nThis repository is licensed under **GPL-3.0-or-later**.  \nSee [LICENSE](LICENSE) for the full license text.\n\nThe Switch Bluetooth compatibility implementation under `firmware\u002Fesp32` borrows from and adapts ideas and code paths from [UARTSwitchCon](https:\u002F\u002Fgithub.com\u002Fnullstalgia\u002FUARTSwitchCon), so this repository follows GPL to keep the license compatible.\n\n### Attribution\n\n- Original author source: Xiaohongshu creator `惜羽拓麻镇`\n- If you publicly repost, mirror, or share this project, it is recommended that you credit `惜羽拓麻镇`\n- It is also recommended that you include the original publication link\n","朋友制作器是一个面向macOS\u002FWindows和ESP32的工具，用于将图片转换成像素网格和手柄动作脚本，在Nintendo Switch的《朋友收集：梦想生活》或《Tomodachi Life》中自动绘制。其核心功能包括支持多种画笔大小、单色与官方色绘制模式以及自定义多色测试，同时提供了一键安装启动、固件刷写、手柄测试及调试测速等功能。该工具适用于需要在Switch上进行自动化像素艺术创作的场景，特别适合希望提高绘图效率或实现复杂图案绘制的用户。","2026-06-11 02:42:27","CREATED_QUERY"]