{"id":15161535,"url":"https://github.com/arduino/dfu-discovery","last_synced_at":"2025-07-17T20:36:53.054Z","repository":{"id":176570764,"uuid":"599520361","full_name":"arduino/dfu-discovery","owner":"arduino","description":null,"archived":false,"fork":false,"pushed_at":"2024-09-03T20:28:56.000Z","size":277,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-29T10:51:30.699Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/arduino.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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},"funding":{"github":["arduino"],"custom":"https://www.arduino.cc/en/Main/Donate"}},"created_at":"2023-02-09T10:09:09.000Z","updated_at":"2024-09-03T20:29:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"85b7decc-023a-45b1-b80a-c09775a621f0","html_url":"https://github.com/arduino/dfu-discovery","commit_stats":{"total_commits":71,"total_committers":7,"mean_commits":"10.142857142857142","dds":0.6619718309859155,"last_synced_commit":"121f0cd32507c7eed338972cafbc8adfec67c8c6"},"previous_names":["arduino/dfu-discovery"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arduino%2Fdfu-discovery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arduino%2Fdfu-discovery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arduino%2Fdfu-discovery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arduino%2Fdfu-discovery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arduino","download_url":"https://codeload.github.com/arduino/dfu-discovery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237092402,"owners_count":19254209,"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":[],"created_at":"2024-09-27T00:23:36.792Z","updated_at":"2025-02-04T09:31:16.998Z","avatar_url":"https://github.com/arduino.png","language":"Go","funding_links":["https://github.com/sponsors/arduino","https://www.arduino.cc/en/Main/Donate"],"categories":[],"sub_categories":[],"readme":"# Arduino pluggable discovery for dfu devices\n\n[![Sync Labels status](https://github.com/arduino/dfu-discovery/actions/workflows/sync-labels.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/sync-labels.yml)\n[![Check Go Dependencies status](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-dependencies-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-dependencies-task.yml)\n[![Check License status](https://github.com/arduino/dfu-discovery/actions/workflows/check-license.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-license.yml)\n[![Check Go status](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-go-task.yml)\n[![Publish Tester Build status](https://github.com/arduino/dfu-discovery/actions/workflows/publish-go-tester-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/publish-go-tester-task.yml)\n[![Check Taskfiles status](https://github.com/arduino/dfu-discovery/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-taskfiles.yml)\n[![Check Workflows status](https://github.com/arduino/dfu-discovery/actions/workflows/check-workflows-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-workflows-task.yml)\n[![Check Markdown status](https://github.com/arduino/dfu-discovery/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/dfu-discovery/actions/workflows/check-markdown-task.yml)\n\nThe `dfu-discovery` tool is a command line program that interacts via stdio. It accepts commands as plain ASCII strings terminated with LF `\\n` and sends response as JSON.\n\n## How to build:\n\n[Docker](https://www.docker.com/) is required to build this project, along with [task](https://taskfile.dev/).\n\nJust run `task download-dfu-util` to download dfu-util source code and then `task dist:\u003cplatform-to-build\u003e`\nThe platform to build can be one of:\n\n- Windows_32bit\n- Windows_64bit\n- Linux_32bit\n- Linux_64bit\n- Linux_ARMv6\n- Linux_ARMv7\n- Linux_ARM64\n- macOS_64bit\n- macOS_ARM64\n\nThe executable `dfu-discovery` will be produced inside `dist/dfu-discovery-\u003cplatform\u003e/dfu-discovery`.\n\n## Usage\n\nAfter startup, the tool waits for commands. The available commands are: `HELLO`, `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.\n\n#### HELLO command\n\nThe `HELLO` command is used to establish the pluggable discovery protocol between client and discovery.\nThe format of the command is:\n\n`HELLO \u003cPROTOCOL_VERSION\u003e \"\u003cUSER_AGENT\u003e\"`\n\nfor example:\n\n`HELLO 1 \"Arduino IDE\"`\n\nor:\n\n`HELLO 1 \"arduino-cli\"`\n\nin this case the protocol version requested by the client is `1` (at the moment of writing there were no other revisions of the protocol).\nThe response to the command is:\n\n```json\n{\n  \"eventType\": \"hello\",\n  \"protocolVersion\": 1,\n  \"message\": \"OK\"\n}\n```\n\n`protocolVersion` is the protocol version that the discovery is going to use in the remainder of the communication.\n\n#### START command\n\nThe `START` starts the internal subroutines of the discovery that looks for ports. This command must be called before `LIST` or `START_SYNC`. The response to the start command is:\n\n```json\n{\n  \"eventType\": \"start\",\n  \"message\": \"OK\"\n}\n```\n\n#### STOP command\n\nThe `STOP` command stops the discovery internal subroutines and free some resources. This command should be called if the client wants to pause the discovery for a while. The response to the stop command is:\n\n```json\n{\n  \"eventType\": \"stop\",\n  \"message\": \"OK\"\n}\n```\n\n#### QUIT command\n\nThe `QUIT` command terminates the discovery. The response to quit is:\n\n```json\n{\n  \"eventType\": \"quit\",\n  \"message\": \"OK\"\n}\n```\n\nafter this output the tool quits.\n\n#### LIST command\n\nThe `LIST` command returns a list of the currently available dfu ports. The format of the response is the following:\n\n```json\n{\n  \"eventType\": \"list\",\n  \"ports\": [\n    {\n      \"address\": \"0-1\",\n      \"label\": \"0-1\",\n      \"properties\": {\n        \"pid\": \"0x0399\",\n        \"vid\": \"0x2341\",\n        \"serialNumber\": \"321315255931323671D633314B572C41\"\n      },\n      \"hardwareId\": \"321315255931323671D633314B572C41\",\n      \"protocol\": \"dfu\",\n      \"protocolLabel\": \"USB DFU\"\n    }\n  ]\n}\n```\n\nThe `ports` field contains a list of the available serial ports. If the serial port comes from an USB serial converter the USB VID/PID and USB SERIAL NUMBER properties are also reported inside `properties`.\n\nThe list command is a one-shot command, if you need continuous monitoring of ports you should use `START_SYNC` command.\n\n#### START_SYNC command\n\nThe `START_SYNC` command puts the tool in \"events\" mode: the discovery will send `add` and `remove` events each time a new port is detected or removed respectively.\nThe immediate response to the command is:\n\n```json\n{\n  \"eventType\": \"start_sync\",\n  \"message\": \"OK\"\n}\n```\n\nafter that the discovery enters the \"events\" mode.\n\nThe `add` events looks like the following:\n\n```json\n{\n  \"eventType\": \"add\",\n  \"port\": {\n    \"address\": \"0-1\",\n    \"label\": \"0-1\",\n    \"protocol\": \"dfu\",\n    \"protocolLabel\": \"USB DFU\",\n    \"properties\": {\n      \"pid\": \"0399\",\n      \"serial\": \"321315255931323671D633314B572C41\",\n      \"vid\": \"2341\"\n    },\n    \"hardwareId\": \"321315255931323671D633314B572C41\"\n  }\n```\n\nit basically gather the same information as the `list` event but for a single port. After calling `START_SYNC` a bunch of `add` events may be generated in sequence to report all the ports available at the moment of the start.\n\nThe `remove` event looks like this:\n\n```json\n{\n  \"eventType\": \"remove\",\n  \"port\": {\n    \"address\": \"0-1\",\n    \"label\": \"0-1\",\n    \"protocol\": \"dfu\",\n    \"protocolLabel\": \"USB DFU\",\n    \"properties\": {\n      \"pid\": \"0399\",\n      \"serial\": \"321315255931323671D633314B572C41\",\n      \"vid\": \"2341\"\n    },\n    \"hardwareId\": \"321315255931323671D633314B572C41\"\n  }\n}\n```\n\nin this case only the `address` and `protocol` fields are reported.\n\n### Example of usage\n\nA possible transcript of the discovery usage:\n\n```bash\n$ ./serial-discovery\nHELLO 1 \"arduino-cli\"\n{\n  \"eventType\": \"hello\",\n  \"protocolVersion\": 1,\n  \"message\": \"OK\"\n}\nSTART\n{\n  \"eventType\": \"start\",\n  \"message\": \"OK\"\n}\nLIST\n{\n  \"eventType\": \"list\",\n  \"ports\": [\n    {\n      \"address\": \"0-1\",\n      \"label\": \"0-1\",\n      \"protocol\": \"dfu\",\n      \"protocolLabel\": \"USB DFU\",\n      \"properties\": {\n        \"pid\": \"0399\",\n        \"serial\": \"321315255931323671D633314B572C41\",\n        \"vid\": \"2341\"\n      },\n      \"hardwareId\": \"321315255931323671D633314B572C41\"\n    }\n  ]\n}\nSTART_SYNC\n{\n  \"eventType\": \"start_sync\",\n  \"message\": \"OK\"\n}\n{\n  \"eventType\": \"list\",\n  \"ports\": [\n    {\n      \"address\": \"0-1\",\n      \"label\": \"0-1\",\n      \"protocol\": \"dfu\",\n      \"protocolLabel\": \"USB DFU\",\n      \"properties\": {\n        \"pid\": \"0369\",\n        \"serial\": \"321315255931323671D633314B572C41\",\n        \"vid\": \"2341\"\n      },\n      \"hardwareId\": \"321315255931323671D633314B572C41\"\n    }\n  ]\n}\n{\n  \"eventType\": \"remove\",\n  \"port\": {\n    \"address\": \"0-1\",\n    \"label\": \"0-1\",\n    \"protocol\": \"dfu\",\n    \"protocolLabel\": \"USB DFU\",\n    \"properties\": {\n      \"pid\": \"0399\",\n      \"serial\": \"321315255931323671D633314B572C41\",\n      \"vid\": \"2341\"\n    },\n    \"hardwareId\": \"321315255931323671D633314B572C41\"\n  }\n}\n{\n  \"eventType\": \"list\",\n  \"ports\": [\n    {\n      \"address\": \"0-1\",\n      \"label\": \"0-1\",\n      \"protocol\": \"dfu\",\n      \"protocolLabel\": \"USB DFU\",\n      \"properties\": {\n        \"pid\": \"0369\",\n        \"serial\": \"321315255931323671D633314B572C41\",\n        \"vid\": \"2341\"\n      },\n      \"hardwareId\": \"321315255931323671D633314B572C41\"\n    }\n  ]\n}\nQUIT\n{\n  \"eventType\": \"quit\",\n  \"message\": \"OK\"\n}\n$\n```\n\n## Security\n\nIf you think you found a vulnerability or other security-related bug in this project, please read our\n[security policy](https://github.com/arduino/dfu-discovery/security/policy) and report the bug to our Security Team 🛡️\nThank you!\n\ne-mail contact: security@arduino.cc\n\n## License\n\nCopyright (c) 2018 ARDUINO SA (https://www.arduino.cc)\n\nThe software is released under the GNU General Public License, which covers the main body\nof the dfu-discovery code. The terms of this license can be found at:\nhttps://www.gnu.org/licenses/old-licenses/gpl-2.0.html\n\nSee [LICENSE.txt](https://github.com/arduino/dfu-discovery/blob/master/LICENSE.txt) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farduino%2Fdfu-discovery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farduino%2Fdfu-discovery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farduino%2Fdfu-discovery/lists"}