{"id":49534244,"url":"https://github.com/zhouxiyu1997/friendmaker","last_synced_at":"2026-05-04T11:01:48.559Z","repository":{"id":354314979,"uuid":"1222509270","full_name":"zhouxiyu1997/friendmaker","owner":"zhouxiyu1997","description":"Friend Maker is a macOS/Windows toolkit for turning images into pixel grids and ESP32 controller scripts, enabling automatic drawing on Nintendo Switch in Tomodachi Life and related workflows.","archived":false,"fork":false,"pushed_at":"2026-05-03T09:05:24.000Z","size":104304,"stargazers_count":130,"open_issues_count":1,"forks_count":10,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T10:03:01.463Z","etag":null,"topics":["esp32","nintendo-switch","pro-controller-emulator","tomodachi-life"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhouxiyu1997.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T12:40:57.000Z","updated_at":"2026-05-03T10:00:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"6c205df0-1eb4-466c-8bba-e12c1f707431","html_url":"https://github.com/zhouxiyu1997/friendmaker","commit_stats":null,"previous_names":["zhouxiyu1997/friendmaker"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/zhouxiyu1997/friendmaker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouxiyu1997%2Ffriendmaker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouxiyu1997%2Ffriendmaker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouxiyu1997%2Ffriendmaker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouxiyu1997%2Ffriendmaker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhouxiyu1997","download_url":"https://codeload.github.com/zhouxiyu1997/friendmaker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouxiyu1997%2Ffriendmaker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32604587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","nintendo-switch","pro-controller-emulator","tomodachi-life"],"created_at":"2026-05-02T09:04:51.659Z","updated_at":"2026-05-04T11:01:48.305Z","avatar_url":"https://github.com/zhouxiyu1997.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Friend Maker\n\n[中文说明](#中文说明) | [English](#english)\n\n![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)\n![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-black.svg)\n![Hardware](https://img.shields.io/badge/hardware-ESP32--WROOM--32-orange.svg)\n![Status](https://img.shields.io/badge/status-alpha-yellow.svg)\n\n\u003cp\u003e\n  \u003ca href=\"docs/media/demo-video.mov\"\u003e\n    \u003cimg src=\"docs/media/demo-real-device.jpeg\" alt=\"Friend Maker real device demo on Nintendo Switch\" width=\"760\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"docs/media/ui-studio-page.png\" alt=\"Friend Maker studio page for image import, preview, brush size, color modes, and serial execution\" width=\"32%\" /\u003e\n  \u003cimg src=\"docs/media/ui-firmware-page.png\" alt=\"Friend Maker firmware flashing page with PlatformIO integration\" width=\"32%\" /\u003e\n  \u003cimg src=\"docs/media/ui-controller-page.png\" alt=\"Friend Maker controller test page with connection status and button testing\" width=\"32%\" /\u003e\n\u003c/p\u003e\n\n## 中文说明\n\n`朋友制作器` 是一个面向 `macOS / Windows + ESP32-WROOM-32 / ESP-32S` 的自动绘制工具。  \n它会将图片转换成像素网格和手柄动作脚本，再通过 ESP32 模拟 Switch Pro Controller 输入，在游戏画板中自动完成绘制。当前版本主要面向《朋友收集：梦想生活》与 `Tomodachi Life` 的绘图场景。\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这个项目仍在持续完善中，当前版本在部分图片或设备环境下可能出现 `颜色偏差`，复杂图片偶尔可能出现 `色块偏移`，建议优先从 `简单图片` 开始尝试。\n\n### 平台支持\n\n- 完整支持：`macOS`\n- 支持一键安装与手动启动：`Windows`\n- 暂未正式支持：`Linux`\n\n当前版本已经提供：\n\n- `macOS` 的完整试用流程与一键启动\n- `Windows` 的一键安装脚本与手动启动流程\n\n参考文档：\n\n- [macOS / Windows 试用说明](docs/user-trial-guide.md)\n- [Windows 安装说明](docs/setup-windows.md)\n\n### 演示\n\n- [查看演示视频](docs/media/demo-video.mov)\n\n### 项目功能\n\n- 导入 `PNG / JPG / SVG` 图片，并生成绘制预览\n- 支持 `1 / 3 / 7 / 13 / 19 / 27` 六种画笔大小\n- 支持 `单色绘制` 与 `官方色绘制`\n- 支持 `256x256` 脚本坐标画布工作流\n- 支持 `自动扣背景`，适合白底、浅灰底、棋盘格假透明图\n- 通过带 `SEQ \u003csession\u003e \u003cseq\u003e` 去重帧的串口协议将绘制脚本逐条发送给 ESP32，并等待 `ACK`\n- 在网页中完成脚本生成、固件刷写、手柄连接与按钮测试，以及暂停、继续和中断绘制\n\n### 整体架构\n\n```text\n图片输入\n  -\u003e 像素化 / 量化 / 路径规划\n  -\u003e 指令脚本\n  -\u003e 串口 ACK 发送\n  -\u003e ESP32-WROOM-32\n  -\u003e Bluetooth Classic HID\n  -\u003e Nintendo Switch\n  -\u003e 游戏内画布绘制\n```\n\n### 当前主流程\n\n当前最稳定、也是文档默认采用的使用顺序：\n\n1. `刷入固件`\n2. `手柄测试`\n3. `脚本生成`\n\n对应的实际动作是：\n\n1. 在 `刷入固件` 页更新推荐固件并确认串口正常\n2. 在 `手柄测试` 页完成蓝牙连接、按钮和方向测试\n3. 回到 `脚本生成` 页导入图片、检查预览并正式开始绘制\n\n### 绘制模式\n\n#### 单色绘制\n\n- 深色像素会被绘制\n- 浅色像素会保留为空白\n- 适合黑白图、轮廓图与简单像素素材\n\n#### 官方色绘制\n\n- 会量化到游戏内置的 `7 x 12` 官方色盘\n- 当前支持 `8 / 16 / 32 / 64 / 84` 色量化档位\n- 当前按游戏原始 `9` 个色盘槽位的默认颜色起步\n\n### 运行要求\n\n#### 硬件\n\n- Mac 或 Windows 电脑\n- `ESP32-WROOM-32 / ESP-32S`\n- Nintendo Switch\n- 可传输数据的 USB 线\n\n#### 软件\n\n- `Node.js 20+`\n- `npm 10+`\n- `PlatformIO Core 6+`\n\n### 快速开始\n\n路径说明：\n\n- 将 `/path/to/friendmaker` 替换为你自己的本地项目目录\n- 将 `\u003cyour-serial-port\u003e` 替换为你自己的串口设备，例如 macOS 上的 `/dev/cu.usbserial-0001` 或 Windows 上的 `COM3`\n- 如果 `pio` 已经在 shell 的 `PATH` 中，可以直接使用 `pio ...`\n- 如果没有，请使用完整的 PlatformIO 路径\n- macOS 路径：`~/.platformio/penv/bin/pio`\n- Windows 路径：`%USERPROFILE%\\\\.platformio\\\\penv\\\\Scripts\\\\pio.exe`\n\n#### macOS 一键启动\n\n你现在可以通过下面两种方式启动应用：\n\n- 双击 [`Start Friend Maker.command`](./Start%20Friend%20Maker.command)\n- 或运行下面的命令：\n\n```bash\ncd /path/to/friendmaker\n./Start\\ Friend\\ Maker.command\n```\n\n这个启动器会：\n\n- 检测 `Node.js`、`npm`、`Python 3` 和 `PlatformIO`\n- 在缺失时尝试自动安装所需软件\n- 在需要时自动安装项目依赖\n- 启动本地 Web UI\n- 自动打开 `http://127.0.0.1:4307`\n\n补充说明：\n\n- 如果缺少 `Homebrew`，启动器会询问是否安装\n- 第一次安装软件时，终端可能会请求输入系统密码\n- 使用过程中请保持终端窗口开启\n\n#### Windows 一键安装\n\n你现在可以通过下面两种方式完成安装：\n\n- 双击 [`Install Friend Maker.cmd`](./Install%20Friend%20Maker.cmd)\n- 或在 `CMD` / `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/setup-windows.md) 走原本的手动安装流程\n- 这个脚本负责安装，当前 Windows 仍然需要手动运行 `npm run ui:dev` 启动网页\n\n#### 1. 安装依赖\n\n```bash\ncd /path/to/friendmaker\nnpm install\n```\n\n#### 2. 检查项目\n\n```bash\nnpm run check\n```\n\n#### 3. 刷入固件\n\n```bash\ncd /path/to/friendmaker/firmware/esp32\n~/.platformio/penv/bin/pio 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 /path/to/friendmaker\nnpm run ui:dev\n```\n\n打开：\n\n```text\nhttp://127.0.0.1:4307\n```\n\n### 开始绘制前必须确认\n\n这 3 条是试用时最容易漏掉的前提：\n\n1. Switch 中的画笔大小要和网页当前选择一致\n2. 开始绘制前，画笔和光标必须停在画布中心\n3. 如果使用官方色绘制，保持游戏默认的 `9` 个色盘槽位颜色即可\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- 调用本机 PlatformIO\n- 编译并刷入 ESP32 固件\n- 返回刷写结果与滚动日志\n\n#### 手柄测试\n\n- 连接手柄\n- 重置手柄蓝牙\n- 如果连接手柄连不上，先点击 `重置手柄蓝牙`，再点击 `连接手柄`\n- 如果还是连不上，可以按一下实体板上的 `EN` 键重启开发板，再重新点击 `连接手柄`\n- 如果还是连不上，回到 `刷入固件` 页重新刷一次固件后再试\n- 单步测试按钮、方向键与摇杆\n- 查看 HID 连接状态\n- 发送自定义测试命令并查看滚动日志\n\n### 仓库结构\n\n```text\napps/desktop/src\n  app/               绘制计划生成\n  cli/               CLI 参数解析\n  config/            默认配置与官方色表\n  image/             图片缩放、量化、预览与扣背景\n  path/              路径生成与轻量优化\n  protocol/          指令对象与序列化\n  serial/            串口枚举与 ACK 发送\n  web/               本地网页工作台\n\nfirmware/esp32\n  src/               ESP32 固件与蓝牙控制器实现\n\nprofiles/            示例 profile\nexamples/            演示图片与示例命令\ndocs/                开发与试用文档\ndocs/media/          README 展示图片与视频\n```\n\n### 文档\n\n- [docs/user-trial-guide.md](docs/user-trial-guide.md)：给试用者的启动与使用说明\n- [docs/development-manual.md](docs/development-manual.md)：当前开发手册与已知规则\n- [docs/setup-mac.md](docs/setup-mac.md)\n- [docs/arrival-checklist.md](docs/arrival-checklist.md)\n- [docs/wiring.md](docs/wiring.md)\n\n### 当前限制\n\n- 当前 UI 是轻量 Web 原型，不是 Electron 桌面应用\n- Switch 连接和绘图流程仍然依赖固定场景假设\n- 官方 `7x12` 色盘仍在持续校准中\n- 自定义颜色自动调色还不稳定，当前更推荐 `官方色绘制`\n- 实验性的 `多色绘制` 已从前端试用版中隐藏，避免对试用者造成误导\n- 第一优先级仍然是输入稳定性，而不是绘制速度\n\n### 当前状态\n\n当前仓库已经具备可试用的闭环：\n\n```text\n网页刷入固件\n  -\u003e 测试手柄连接\n  -\u003e 导入图片\n  -\u003e 像素化 / 量化 / 扣背景\n  -\u003e 生成命令脚本\n  -\u003e 串口 ACK 发送\n  -\u003e ESP32 协议解析\n  -\u003e Bluetooth Classic Switch 控制器输出\n  -\u003e 游戏内绘制\n```\n\n### 许可证\n\n本仓库采用 **GPL-3.0-or-later** 开源协议。  \n完整协议内容请查看 [LICENSE](LICENSE)。\n\n当前 `firmware/esp32` 中的 Switch 蓝牙兼容实现，引入并改写自 [UARTSwitchCon](https://github.com/nullstalgia/UARTSwitchCon) 的思路与代码路径，因此当前仓库采用 GPL 以保持许可证一致。\n\n### 作者与来源\n\n- 来源作者：小红书作者 `惜羽拓麻镇`\n- 如果你公开转发、转载或分享这个项目，建议注明作者名称 `惜羽拓麻镇`\n- 建议同时附上原始发布地址\n\n## English\n\n`Friend Maker` is an automatic drawing toolkit for `macOS / Windows + ESP32-WROOM-32 / 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\nKeywords: `Friend Maker`, `Tomodachi Life`, `Nintendo Switch auto draw`, `ESP32 Pro Controller emulator`, `pixel art drawing automation`, `Bluetooth Classic HID`.\n\n### Note\n\nThis project is still being improved; the current version may show `color deviation` on some images or device setups, and complex drawings may occasionally produce `misaligned color blocks`, so starting with `simple images` is recommended.\n\n### Compatibility\n\n- Fully supported: `macOS`\n- One-click install and manual launch supported: `Windows`\n- Not officially supported yet: `Linux`\n\nThe current version already provides:\n\n- a complete trial workflow and one-click launcher for `macOS`\n- a one-click installer and manual startup instructions for `Windows`\n\nReference documents:\n\n- [macOS / Windows Trial Guide](docs/user-trial-guide.md)\n- [Windows Setup Guide](docs/setup-windows.md)\n\n### Showcase\n\n- [Watch demo video](docs/media/demo-video.mov)\n\n### What It Does\n\n- Import `PNG / JPG / SVG` images and generate drawing previews\n- Support six brush sizes: `1 / 3 / 7 / 13 / 19 / 27`\n- Support both `mono drawing` and `official palette drawing`\n- Use a `256x256` script-coordinate canvas workflow\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\u003e \u003cseq\u003e` deduplicating serial protocol and wait for `ACK`\n- Handle script generation, firmware flashing, controller connection and button testing, plus pause, resume, and stop actions from the web interface\n\n### Architecture\n\n```text\nImage input\n  -\u003e Pixelization / Quantization / Path planning\n  -\u003e Command script\n  -\u003e Serial ACK sender\n  -\u003e ESP32-WROOM-32\n  -\u003e Bluetooth Classic HID\n  -\u003e Nintendo Switch\n  -\u003e 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. `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. Return to the `Script Studio` page, import an image, review the preview, and start drawing\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 / 16 / 32 / 64 / 84` quantization levels\n- Starts from the game's default colors for the `9` palette slots\n\n### Requirements\n\n#### Hardware\n\n- A Mac or Windows computer\n- `ESP32-WROOM-32 / ESP-32S`\n- Nintendo Switch\n- A USB cable that supports data transfer\n\n#### Software\n\n- `Node.js 20+`\n- `npm 10+`\n- `PlatformIO Core 6+`\n\n### Quick Start\n\nPath notes:\n\n- Replace `/path/to/friendmaker` with your own local project directory\n- Replace `\u003cyour-serial-port\u003e` with your own serial device, such as `/dev/cu.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: `~/.platformio/penv/bin/pio`\n- Windows path: `%USERPROFILE%\\\\.platformio\\\\penv\\\\Scripts\\\\pio.exe`\n\n#### 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`](./Start%20Friend%20Maker.command)\n- or run:\n\n```bash\ncd /path/to/friendmaker\n./Start\\ 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://127.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#### 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`](./Install%20Friend%20Maker.cmd)\n- or run in `CMD` / `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/setup-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 /path/to/friendmaker\nnpm install\n```\n\n#### 2. Type check\n\n```bash\nnpm run check\n```\n\n#### 3. Flash firmware\n\n```bash\ncd /path/to/friendmaker/firmware/esp32\n~/.platformio/penv/bin/pio 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 /path/to/friendmaker\nnpm run ui:dev\n```\n\nOpen:\n\n```text\nhttp://127.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\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 or official palette drawing\n- Generate previews and command scripts\n- Review official palette previews, statistics, and execution status\n- Start drawing with one click\n\n#### Firmware Flash\n\n- Enumerate serial ports\n- Call the local PlatformIO installation\n- Build and flash the ESP32 firmware\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\n- Inspect HID connection status\n- Send custom test commands and review scrollable logs\n\n### Repository Layout\n\n```text\napps/desktop/src\n  app/               Draw plan generation\n  cli/               CLI argument parsing\n  config/            Default config and official palette tables\n  image/             Image resizing, quantization, preview, and background removal\n  path/              Path generation and lightweight optimization\n  protocol/          Command objects and serialization\n  serial/            Serial enumeration and ACK sending\n  web/               Local web workspace\n\nfirmware/esp32\n  src/               ESP32 firmware and Bluetooth controller implementation\n\nprofiles/            Example profiles\nexamples/            Demo images and sample commands\ndocs/                Development and trial documents\ndocs/media/          README images and videos\n```\n\n### Documentation\n\n- [docs/user-trial-guide.md](docs/user-trial-guide.md): startup and usage guide for trial users\n- [docs/development-manual.md](docs/development-manual.md): current development manual and known rules\n- [docs/setup-mac.md](docs/setup-mac.md)\n- [docs/arrival-checklist.md](docs/arrival-checklist.md)\n- [docs/wiring.md](docs/wiring.md)\n\n### Current Limitations\n\n- The current UI is a lightweight web prototype, not an Electron desktop app\n- The Switch connection and drawing workflow still depend on fixed scenario assumptions\n- The official `7x12` palette is still being calibrated\n- Automatic custom-color tuning is not stable yet, so `official palette drawing` is currently recommended\n- Experimental `multi-color drawing` has been hidden from the frontend trial build to avoid misleading trial users\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  -\u003e test controller connection\n  -\u003e import image\n  -\u003e pixelization / quantization / background removal\n  -\u003e generate command script\n  -\u003e serial ACK sender\n  -\u003e ESP32 protocol parser\n  -\u003e Bluetooth Classic Switch controller output\n  -\u003e 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/esp32` borrows from and adapts ideas and code paths from [UARTSwitchCon](https://github.com/nullstalgia/UARTSwitchCon), 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhouxiyu1997%2Ffriendmaker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhouxiyu1997%2Ffriendmaker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhouxiyu1997%2Ffriendmaker/lists"}