{"id":15142167,"url":"https://github.com/radiantwf/esp32-circuitpython-switch-joystick","last_synced_at":"2025-10-23T19:31:18.048Z","repository":{"id":62032294,"uuid":"538142840","full_name":"radiantwf/esp32-circuitpython-switch-joystick","owner":"radiantwf","description":"A virtual HID USB joystick created using ESP32S2/S3","archived":false,"fork":false,"pushed_at":"2023-07-28T08:43:15.000Z","size":21845,"stargazers_count":53,"open_issues_count":0,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-09-27T09:23:58.365Z","etag":null,"topics":["circuitpython","esp32","gamepad","joystick","micropython","pokemon","switch"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radiantwf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-09-18T14:54:07.000Z","updated_at":"2024-07-18T06:16:35.000Z","dependencies_parsed_at":"2024-09-21T15:00:36.889Z","dependency_job_id":"7aefc9a3-de87-46b4-a9df-66d7f84ab693","html_url":"https://github.com/radiantwf/esp32-circuitpython-switch-joystick","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiantwf%2Fesp32-circuitpython-switch-joystick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiantwf%2Fesp32-circuitpython-switch-joystick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiantwf%2Fesp32-circuitpython-switch-joystick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radiantwf%2Fesp32-circuitpython-switch-joystick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radiantwf","download_url":"https://codeload.github.com/radiantwf/esp32-circuitpython-switch-joystick/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219867955,"owners_count":16555810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["circuitpython","esp32","gamepad","joystick","micropython","pokemon","switch"],"created_at":"2024-09-26T09:24:10.680Z","updated_at":"2025-10-23T19:31:15.356Z","avatar_url":"https://github.com/radiantwf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp32-circuitpython-switch-joystick\n\nA virtual HID USB joystick created using ESP32S2/S3/RP2040\n\n## 硬件需求\n\n1. Switch主机 * 1\n2. ESP32S2/ESP32S3/RP2040开发板 * 1\n   - 本人测试用设备：\n   - LOLIN S2 Mini：ESP32S2芯片，单核240MHz，N4R2    12.5元   \u003cfont color=red\u003e注意近期有10%左右的网友无法刷入circuitpython官方固件，猜测可能是模块问题，如果担心设备问题，尽量选择Raspberry Pi Pico\u003c/font\u003e\n   - ESP32-S3-DevKitC-1-N16R8：ESP32S3芯片，双核240MHz，N16R8，支持蓝牙    59元\n   - Raspberry Pi Pico (W): 带W版本 包含网络模块 51元，不带W 25元\n   - 由于我希望降低大家的使用成本，后续的研发，测试，我将在LOLIN S2 Mini上进行\n3. USB线（连接主机与开发板） * 1\n\n\u003cimg src=\"imgs/devices.jpg\" style=\"zoom: 25%;\" /\u003e\n\n## 常见问题汇总\n\n[跳转](./SCRIPTS.md)\n\n使用前请一定要看一下\n\n## 功能\n\n1. 模拟NS手柄，控制NS主机\n2. 支持自定义宏脚本，实现游戏自动化\n3. 内部集成部分宝可梦剑盾功能的宏脚本\n4. TCP管理基本功能\n\n## 预计追加功能\n\n### 近期\n\n1. ~~\u003cfont color=grey\u003eLCD单色液晶显示支持（已废弃，计划采用WEB方式代替）\u003c/font\u003e~~\n\n2. ~~\u003cfont color=grey\u003e实体按键支持（已废弃，计划采用WEB方式代替）\u003c/font\u003e~~\n\n3. Web管理（脚本的启动、停止、参数配置）\n\n4. 远程管理功能（首选HTTP服务，其次TCP/UDP或MQTT，尽量不依赖其他服务器或客户端软件，独自实现远程管理功能）\n\n### 计划\n\n1. 通过NS的HDMI输出连接PC端，实现简单图像识别，增强脚本功能\n\n2. **宝可梦朱紫脚本制作**\n\n## 简介\n\n### ESP32S3固件\n\n#### 固件编译\n\n##### 8.0.0-beta.4 ~\n\n直接使用circuitpython官方固件即可，[固件下载链接](https://circuitpython.org/downloads)（\u003chttps://circuitpython.org/downloads\u003e）。\n\n##### 7.3.3\n\n1. 设备OTG口连接PC，Windows与Mac都可\n\n2. 如果设备为 **EPS32S3-N16R8** 或 **LOLIN S2 Mini**，可直接使用**项目中打包好固件**，不需要自行编译，直接进行固件写入操作\n\n3. PC安装docker\n\n4. 修改firmware/esp32s3-n16r8/Dockerfile文件：\n\n   ```dockerfile\n   WORKDIR /root/circuitpython/ports/espressif/boards\n   # https://github.com/adafruit/circuitpython/tree/main/ports/espressif/boards/espressif_esp32s3_devkitc_1_n8r2\n   RUN cp -r espressif_esp32s3_devkitc_1_n8r2 espressif_esp32s3_devkitc_1_n16r8 \u0026\u0026 \\\n    sed -i 's/ESP32-S3-DevKitC-1-N8R2/ESP32-S3-DevKitC-1-N16R8/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.h \u0026\u0026 \\\n    sed -i 's/USB_VID = 0x303A/USB_VID = 0x0F0D/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    sed -i 's/USB_PID = 0x7003/USB_PID = 0x00C1/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    sed -i 's/USB_PRODUCT = \"ESP32-S3-DevKitC-1-N8R2\"/USB_PRODUCT = \"HORI CO.,LTD.\"/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    sed -i 's/USB_MANUFACTURER = \"Espressif\"/USB_MANUFACTURER = \"HORIPAD S\"/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    # CIRCUITPY_ESP_FLASH_MODE DIO -\u003e QIO\n    sed -i 's/dio/qio/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    # CIRCUITPY_ESP_FLASH_SIZE 8MB -\u003e 16MB\n    sed -i 's/8MB/16MB/g' espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    echo 'CIRCUITPY_ESP32_CAMERA = 0' \u003e\u003e espressif_esp32s3_devkitc_1_n16r8/mpconfigboard.mk \u0026\u0026 \\\n    #  QUAD -\u003e OCTAL\n    sed -i 's/CONFIG_SPIRAM_MODE_QUAD/CONFIG_SPIRAM_MODE_OCT/g' espressif_esp32s3_devkitc_1_n16r8/sdkconfig \u0026\u0026 \\\n    # 2MB -\u003e 8MB\n    sed -i 's/2097152/8388608/g' espressif_esp32s3_devkitc_1_n16r8/sdkconfig\n   ```\n\n   由于官方固件不支持N16R8，所以在N8R2上进行修改。请修改时，参考自己的设备，根据自己设备信息修改。\n\n   *注：VID与PID改为0x0F0D与0x00C1是依据模拟设备修改，不修改是否可以使用我没做尝试，还是尽量修改。*\n\n5. 进入firmware/esp32s3-n16r8目录，运行下面脚本进行编译：\n\n   ```shell\n   docker build . -t circuitpython\n   docker run -d --rm -v $(PWD)/build:/root/build circuitpython\n   ```\n\n   由于网络环境等因素问题，可能有些资源下载比较慢或经常中断，这个问题需要自行解决。\n\n   等待很长一段时间后，编译完成，build目录会生成大量文件，保留firmware.bin或firmware.uf2文件即可（依据自己刷入固件的方式）\n\n#### 固件写入\n\n1. Chrome浏览器打开[ESP Web Flasher 页面](https://nabucasa.github.io/esp-web-flasher/)（\u003chttps://nabucasa.github.io/esp-web-flasher/\u003e）刷写固件\n\n2. ESP32进入固件写入模式（按住0或BOOT，点击RST，松开0或BOOT即可）\n\n3. 页面操作，连接设备，**Baudrate**选择**460800 (LOLIN S2 Mini)** / **921600 (ESP32S3N16R8)**\n\n4. 擦除设备，选择bin固件，同时把起始地址改为0x0，开始写入\n\n5. 写入完成后双击设备上的RST按钮，或重新插拔设备即可\n\n#### 程序部署\n\n1. 修改src/resources/config.json中的wifi节点，type分为wifi和ap两种模式。\n\n2. 把工作目录src下所有文件目录，拷贝至ESP32S3被识别出盘符即可，相同文件目录覆盖\n\n3. 下载依赖库\n\n   - 本地安装python，并且配置环境变量（python运行目录，pip下载包运行目录加入Path）。\n\n   - 运行下面代码：\n\n     本地安装circup：\n\n     ```\n     pip3 install circup\n     ```\n\n     esp32安装库：\n\n     ```\n     circup install asyncio adafruit-circuitpython-hid adafruit-circuitpython-ntp\n     ```\n\n\u003ccenter\u003e\u003cfont color=red size=72\u003e恭喜！环境部署成功！\u003c/font\u003e\u003c/center\u003e\n\n## 脚本语法\n\n[跳转](./SCRIPTS.md)\n\n## 配置文件\n\n配置文件路径：ESP32目录/resources/config.json\n\n## 远程管理\n\n采用TCP方式进行管理，默认开启5000端口\n\n### 运行效果\n\n\u003cimg src=\"imgs/show.webp\"/\u003e\n\n\u003cimg src=\"imgs/registeel2.webp\"/\u003e\n\n​        后续，删除游戏，并重新安装后，卡顿问题解决，对运行效率有需求的朋友可自行修改脚本。\n\n​        更新OpenCV图像识别方式，效果如下：\n\n\u003cimg src=\"imgs/recognition.webp\"/\u003e\n\n#### 开发笔记（不定期更新）\n\n[跳转](./NOTE.md)\n\n#### 特别感谢\n\n- 燃烧の小宇宙 提供朱紫无限复制道具（1.01版BUG)脚本\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradiantwf%2Fesp32-circuitpython-switch-joystick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradiantwf%2Fesp32-circuitpython-switch-joystick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradiantwf%2Fesp32-circuitpython-switch-joystick/lists"}