{"id":19374515,"url":"https://github.com/rosvall/cc2531_oem_flasher","last_synced_at":"2025-08-02T23:12:43.623Z","repository":{"id":176849770,"uuid":"658054092","full_name":"rosvall/cc2531_oem_flasher","owner":"rosvall","description":"Hack to flash a stock Texas Instruments CC2531USB-RD dongle, no tools required","archived":false,"fork":false,"pushed_at":"2025-04-01T11:34:33.000Z","size":51,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T12:30:53.575Z","etag":null,"topics":["cc2531","dfu","ieee802154","usb","wpan"],"latest_commit_sha":null,"homepage":"http://rosvall.github.io/","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/rosvall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/GPL-3.0-or-later.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}},"created_at":"2023-06-24T16:10:24.000Z","updated_at":"2025-04-01T11:31:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"aecc54d5-6813-43a1-bef9-5c41595161e4","html_url":"https://github.com/rosvall/cc2531_oem_flasher","commit_stats":null,"previous_names":["rosvall/cc2531_oem_flasher"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rosvall/cc2531_oem_flasher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosvall%2Fcc2531_oem_flasher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosvall%2Fcc2531_oem_flasher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosvall%2Fcc2531_oem_flasher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosvall%2Fcc2531_oem_flasher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rosvall","download_url":"https://codeload.github.com/rosvall/cc2531_oem_flasher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rosvall%2Fcc2531_oem_flasher/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260163010,"owners_count":22968173,"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":["cc2531","dfu","ieee802154","usb","wpan"],"created_at":"2024-11-10T08:35:22.937Z","updated_at":"2025-06-16T12:35:58.923Z","avatar_url":"https://github.com/rosvall.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flash a stock Texas Instruments CC2531USB-RD dongle, no tools required.\n\n## What?\nThis is a hack to get your own firmware running on a stock CC2531 USB dongle over USB, without a programmer.\nIt can only transfer about 3 kB of code, but that is enough to get a short flasher stub and a simple DFU bootloader onto the dongle. From there, you can flash all the firmware you want using [dfu-util](https://sourceforge.net/projects/dfu-util/) or something else that speaks USB device firmware upgrade protocol.\n\n## Why?\nBecause the TI CC2531 is a fun chip for experimenting with IEEE 802.15.4 WPAN stuff from a desktop computer.\n\nCC2531 based USB dongles [like CC2531USB-RD](https://www.ti.com/tool/CC2531USB-RD) are cheaply available (~$5 from China), but usually comes with the simple packet sniffer firmware that doesn't support upgrading over USB, instead requiring either buying a programming device from TI or hacking something together with an arduino.\n\n## How does it work?\nThe TI sniffer firmware expects some packet filtering parameters of limited length when it receives a USB control transfer with bmRequestType 0x40 and bRequest 0xD2.\nThe control transfer payload is written to xdata 0x020F, and the (fat) write pointer is located at 0x0371. As the length of the transfer is not checked, it's possible to overwrite the pointer with an arbitrary address, and have subsequent writes go there.\nAdditionally, the CC2531 has most special function registers mapped into xdata, and allows running code from xdata. This program exploits those features, by writing the given executable binary to xdata, setting the XMAP bit in the MEMCTR special function register, and finally overwriting a return pointer on stack to\njump to the code written to xdata.\n\n## How to use\nGrab [the binary release](https://github.com/rosvall/cc2531_oem_flasher/releases) or follow the build instructions below.\n\nThen:\n\n```sh\n# Flash bootloader to CC2531 dongle (that runs stock sniffer firmware)\npython oem_flasher.py stub.bin bootloader/bootloader.bin\n```\n\nOr use oem_flasher.py to run whatever else code you want on the dongle. The source of both `oem_flasher.py` and `stub.s` is written with readability and hack-ability in mind.\n\nIt should be relatively simple to modify dfu_mode.s from the bootloader to run directly from ram, for example.\n\n## Known issues\n### Works only for stock firmware with bcdDevice = 83.91 (0x8391), 8.21 (0x0821) and 25.17 (0x2517)\n\nIf you get an error message about your dongle not being supported, please open an issue stating where to get that dongle, and if at all possible, attach a copy of the firmware.\n\n## Build requirements:\n- [SDCC](https://sourceforge.net/projects/sdcc/) to assemble and link the flasher stub\n- [binutils](https://www.gnu.org/software/binutils/) to convert intel hex to raw binary\n- [pyusb](https://github.com/pyusb/pyusb) to run oem_flasher.py\n- [make](https://www.gnu.org/software/make/)\n\n## How to build\n```sh\n# Check out repo with all sub-modules:\ngit clone --recursive 'https://github.com/rosvall/cc2531_oem_flasher.git' \ncd cc2531_oem_flasher\n\n# Build flasher stub and bootloader\nmake\n\n# Flash bootloader to CC2531 dongle (that runs stock sniffer firmware)\npython oem_flasher.py stub.bin bootloader/bootloader.bin\n#or simply\nmake flash\n```\n\n\n## See also\n - [Simple USB DFU bootloader for TI CC2531](https://github.com/rosvall/cc2531_bootloader)\n - [WPAN Adapter firmware for CC2531 USB Dongle](https://github.com/rosvall/cc2531_usb_wpan_adapter)\n - [Linux kernel driver for CC2531 WPAN Adapter firmware](https://github.com/rosvall/cc2531_linux)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosvall%2Fcc2531_oem_flasher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frosvall%2Fcc2531_oem_flasher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosvall%2Fcc2531_oem_flasher/lists"}