{"id":25750687,"url":"https://github.com/finger563/esp-usb-ble-hid","last_synced_at":"2026-06-13T17:32:05.830Z","repository":{"id":277333950,"uuid":"929021624","full_name":"finger563/esp-usb-ble-hid","owner":"finger563","description":"USB BLE HID adapter using ESP32S3 to have a BLE central which supports receiving HID input from a remote device and outputting over USB.","archived":false,"fork":false,"pushed_at":"2025-10-31T14:46:58.000Z","size":172,"stargazers_count":19,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-02T18:03:59.339Z","etag":null,"topics":["ble","ble-hid","esp32","nintendo-hacking","nintendo-switch","switch-pro-controller","usb","usb-hid","xbox","xbox-controller"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/finger563.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}},"created_at":"2025-02-07T17:01:32.000Z","updated_at":"2026-05-31T16:06:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"6ad1fac6-9e2d-40c2-991c-e74e48efc16a","html_url":"https://github.com/finger563/esp-usb-ble-hid","commit_stats":null,"previous_names":["finger563/esp-usb-ble-hid"],"tags_count":11,"template":false,"template_full_name":"esp-cpp/template","purl":"pkg:github/finger563/esp-usb-ble-hid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fesp-usb-ble-hid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fesp-usb-ble-hid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fesp-usb-ble-hid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fesp-usb-ble-hid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/finger563","download_url":"https://codeload.github.com/finger563/esp-usb-ble-hid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finger563%2Fesp-usb-ble-hid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34294410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ble","ble-hid","esp32","nintendo-hacking","nintendo-switch","switch-pro-controller","usb","usb-hid","xbox","xbox-controller"],"created_at":"2025-02-26T13:19:14.886Z","updated_at":"2026-06-13T17:32:05.824Z","avatar_url":"https://github.com/finger563.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP USB BLE HID\n\nExample code for using BLE gamepad (such as Xbox wireless controller) with the\nNintendo Switch via a USB dongle.\n\nThis repository contains example code for using an ESP32s3 to act as a USB-BLE\nHID bridge. You would run this code for instance on a QtPy ESP32s3 or a LilyGo\nT-Dongle S3, connected to a computer or other device which is a USB HID host.\nThe main HID host that this targets is the Nintendo Switch. The QtPy / this code\nwould then start a BLE GATT Client to connect to a BLE HID device (this example\ntargets a gamepad), and will allow the wireless HID device (gamepad) to talk to\nthe HID Host.\n\n![image](https://github.com/user-attachments/assets/d76558db-c34e-48d4-9771-06fa4ebdb05a)\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n**Table of Contents**\n\n- [ESP USB BLE HID](#esp-usb-ble-hid)\n  - [Plug and Play](#plug-and-play)\n    - [Purchase Dongle](#purchase-dongle)\n    - [Program It](#program-it)\n    - [Plug it into your Switch](#plug-it-into-your-switch)\n  - [Cloning](#cloning)\n  - [Configuration](#configuration)\n  - [Build and Flash](#build-and-flash)\n  - [How To Use](#how-to-use)\n    - [Pairing Mode](#pairing-mode)\n    - [Reconnection Mode](#reconnection-mode)\n    - [Connected](#connected)\n    - [Note about system power](#note-about-system-power)\n  - [Output](#output)\n  - [Helpful Links](#helpful-links)\n\n\u003c!-- markdown-toc end --\u003e\n\n## Plug and Play\n\nIf you just want to get a dongle and use your BLE controller with the switch,\nsimply get the dongle, plug it into your computer, and run the programmer\nexecutable from the release.\n\n### Purchase Dongle\n\nSources:\n- [LilyGo](https://lilygo.cc/products/t-dongle-s3?srsltid=AfmBOopsToYDfOeA4GJiUlQNNcefgA_lMLmWoF99lzdWc_j5Ysd9FUeW)\n- [Amazon](https://www.amazon.com/LILYGO-T-Dongle-S3-ESP32-S3-Development-Display/dp/B0BK9162QY)\n\n### Program It\n\nThe dongle will require one-time programming to function as a BLE HID USB\ndongle.\n\nDownload the release `programmer` executable from the latest [releases\npage](https://github.com/finger563/esp-usb-ble-hid/releases) for `windows`,\n`macos`, or `linux` - depending on which computer you want to use to perform the\none-time programming.\n\n1. Download the programmer\n2. Unzip it\n3. Double click the `exe` (if windows), or open a terminal and execute it from\n   the command line `./esp-usb-ble-hid_programmer_v2.0.2_macos.bin`.\n\n### Plug it into your Switch\n\nNow that the dongle is programmed, simply plug it into your Switch and turn your\nswitch on.\n  \nSee the [How To Use](#how-to-use) section for information about how to pair /\nreconnect your controller to the dongle.\n\nhttps://github.com/user-attachments/assets/a0789d38-bd0e-4215-bf2c-ebedd9958495\n\nhttps://github.com/user-attachments/assets/c81b947a-24a1-4a44-b5d0-5d4c274beb93\n\n\n## Cloning\n\nSince this repo contains a submodule, you need to make sure you clone it\nrecursively, e.g. with:\n\n``` sh\ngit clone --recurse-submodules https://github.com/finger563/esp-usb-ble-hid\n```\n\nAlternatively, you can always ensure the submodules are up to date after cloning\n(or if you forgot to clone recursively) by running:\n\n``` sh\ngit submodule update --init --recursive\n```\n\n## Configuration\n\nYou can run `idf.py menuconfig` to configure the project to run on either the\n`T-Dongle-S3` or the `QtPy (ESP32 or ESP32S3)`. The configuration is under the\n`Hardware Configuration` menu from the main menu and is the `Target Hardware`\noption.\n\n![CleanShot 2025-04-10 at 07 57 26](https://github.com/user-attachments/assets/be355584-251d-4c2c-81ed-15089b45f4e1)\n\n## Build and Flash\n\nBuild the project and flash it to the board, then run monitor tool to view serial output:\n\n```\nidf.py -p PORT flash monitor\n```\n\n(Replace PORT with the name of the serial port to use.)\n\n(To exit the serial monitor, type ``Ctrl-]``.)\n\nSee the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.\n\n## How To Use\n\n\u003e NOTE: you must turn on the `support wired controllers` setting on your switch\n\u003e for the dongle (or any wired controllers for that matter) to work.\n\nThe dongle can store up to 5 paired devices at a time. When it turns on / is\nplugged in it will attempt to reconnect to one of those devices. If there are no\npaired devices, then it will enter pairing mode.\n\nIf at any time you want to pair a new controller, simply press and hold the\nbutton on the dongle until the LED starts pulsing blue.\n\n### Pairing Mode\n\nWhile in pairing mode, the device will scan for any BLE devices which expose a\nHID service. It will connect and attempt to bond to the first device it finds.\n\n### Reconnection Mode\n\nWhen in this mode, the device will scan for the devices in its pairing list and\nconnect to the first one it finds.\n\n### Connected\n\nWhile connected, the device will translate xbox controller inputs received via\nBLE into Nintendo Switch Pro controller inputs which will then be transmitted\nover USB.\n\nIf the controller disconnects, then the dongle will re-enter reconnection mode.\n\n### Note about system power\n\nThe switch turns off its USB-C port when it enters sleep mode. This means that\nwhile the Switch Dock's USB-A port still has power, the dongle will not properly\nmount as a usb device until the Switch comes out of sleep. \n\nFor this reason, you cannot use this dongle or the associated BLE controller to\npower on your switch unfortunately. The only way (currently) to remotely wake\nyour switch is via Bluetooth Classic.\n\nThat being said, I have read online that if you plug a usb-to-ethernet adapter\ninto your Switch Dock, then the Switch may keep its USB-C port awake during\nsleep.\n\n## Output\n\nhttps://github.com/user-attachments/assets/a0789d38-bd0e-4215-bf2c-ebedd9958495\n\n![CleanShot 2025-02-25 at 08 54 49](https://github.com/user-attachments/assets/d06a53cb-c20c-4de8-9987-38a7bc05b60a)\n\n![CleanShot 2025-02-25 at 09 02 40](https://github.com/user-attachments/assets/6c3820d1-b9f0-4188-96a6-0d1d8b44e1fb)\n\n![CleanShot 2025-02-25 at 09 03 03](https://github.com/user-attachments/assets/89f524e4-1737-4aec-92ac-e3a64f69c6fe)\n\n## Helpful Links\n\nThe links below were invaluable in developing the switch pro implemenation\nwithin this repo such that it would work on MacOS, Android, iOS, and (most\nimportantly) the Nintendo Switch.\n\n* https://github.com/Brikwerk/nxbt/blob/master/nxbt/controller/protocol.py\n* https://github.com/dekuNukem/Nintendo_Switch_Reverse_Engineering/blob/master/bluetooth_hid_subcommands_notes.md\n* https://github.com/dekuNukem/Nintendo_Switch_Reverse_Engineering/blob/master/USB-HID-Notes.md\n* https://github.com/dekuNukem/Nintendo_Switch_Reverse_Engineering/blob/master/spi_flash_notes.md\n* https://github.com/EasyConNS/BlueCon-esp32/tree/master/components/joycon\n* https://github.com/mzyy94/nscon/blob/master/nscon.go\n* https://www.mzyy94.com/blog/2020/03/20/nintendo-switch-pro-controller-usb-gadget/\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinger563%2Fesp-usb-ble-hid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinger563%2Fesp-usb-ble-hid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinger563%2Fesp-usb-ble-hid/lists"}