{"id":13826660,"url":"https://github.com/jerome-ps/jn516xsniffer","last_synced_at":"2025-07-09T00:34:24.902Z","repository":{"id":151378789,"uuid":"117896653","full_name":"Jerome-PS/JN516xSniffer","owner":"Jerome-PS","description":"Transform a Xiaomi Zigbee gadget into a Zigbee sniffer.","archived":false,"fork":false,"pushed_at":"2020-04-25T14:13:44.000Z","size":1684,"stargazers_count":41,"open_issues_count":3,"forks_count":14,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-08-05T09:15:32.080Z","etag":null,"topics":["linux","macos","sniffer","windows","wireshark","zigbee-sniffer"],"latest_commit_sha":null,"homepage":null,"language":"C","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/Jerome-PS.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}},"created_at":"2018-01-17T21:47:35.000Z","updated_at":"2023-09-28T10:47:33.000Z","dependencies_parsed_at":"2024-01-07T22:49:50.942Z","dependency_job_id":"715b5364-59cb-46e0-946c-9efd2bf20a12","html_url":"https://github.com/Jerome-PS/JN516xSniffer","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/Jerome-PS%2FJN516xSniffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-PS%2FJN516xSniffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-PS%2FJN516xSniffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-PS%2FJN516xSniffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jerome-PS","download_url":"https://codeload.github.com/Jerome-PS/JN516xSniffer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225476383,"owners_count":17480215,"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":["linux","macos","sniffer","windows","wireshark","zigbee-sniffer"],"created_at":"2024-08-04T09:01:42.124Z","updated_at":"2024-11-20T05:30:57.467Z","avatar_url":"https://github.com/Jerome-PS.png","language":"C","funding_links":[],"categories":["\u003ca id=\"7bf0f5839fb2827fdc1b93ae6ac7f53d\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"32739127f0c38d61b14448c66a797098\"\u003e\u003c/a\u003e嗅探\u0026\u0026Sniff"],"readme":"# Transform a Xiaomi Zigbee gadget into a Zigbee sniffer.\n\nThis has been tested on the Xiaomi Smart Button.\n\n## Quickstart on Linux\nStart sniffing session from terminal:\n```\n./Sniff.py /dev/ttyUSB0\n```\nRunning `./Sniff.py -h` will give you a list of detected serial ports.\n\n## Quickstart on macOS\nStart sniffing session from terminal:\n```\n./Sniff.py /dev/cu.usbserial\n```\nRunning `./Sniff.py -h` will give you a list of detected serial ports.\n\n## Quickstart on Windows\nOpen command line, cd to the folder containing the scripts and launch:\n```\npython Sniff.py COM3\n```\nRunning `python Sniff.py -h` will give you a list of detected serial ports.\n\n# Table Of Content\n- [Compiling the sniffer](#Compiling-the-sniffer)\n\t- [Precompiled binary](#Precompiled-binary)\n\t- [Compiling on macOS or Linux](#Compiling-on-macOS-or-Linux)\n\t- [Compiling on Windows](#Compiling-on-Windows)\n- [Interfacing to Wireshark](#Interfacing-to-Wireshark)\n- [Hardware](#Hardware)\n\t- [Xiaomi Door sensor](#Xiaomi-Door-sensor)\n\t- [Xiaomi smart button](#Xiaomi-smart-button)\n\t- [Xiaomi smart button UART1](#Xiaomi-smart-button-UART1)\n- [Using the GUI to set the preferences](#Using-the-GUI-to-set-the-preferences)\n- [Troubleshooting](#Troubleshooting)\n- [To do list](#To-do-list)\n- [Gory details](# Gory-details)\n\n# Compiling the sniffer\nYou will need the NXP JN-SW-4163 SDK in order to compile the source code.\n\n## Precompiled binary\nThere is a precompiled binary in the [bin folder](https://github.com/Jerome-PS/JN516xSniffer/tree/master/bin). **TODO: Check that it is up to date...**\n\n## Compiling on macOS or Linux\nFollow the instructions found here: https://github.com/alephsecurity/BA2-toolchain\n\nYou can use the latest version of [JennicModuleProgrammer](https://github.com/Jerome-PS/JennicModuleProgrammer) in order to flash you JN5169 device.\n\n## Compiling on Windows\nYou can download NXP's Beyond Studio in order to compile the source code. In eclipse, use the import from C/C++ Makefile menu.\nYou can then use the programmer integrated in the IDE. Do not use any other programmer provided by NXP, because they do not support JN5169 (at least none that I could try out).\n\n# Using the sniffer\n## Using on macOS or Linux\nOn Linux, you will need to be in the dialout group, in order to have enough access rights to access the serial port, as well as in the wireshark group for executing pcap.\nThe script will prompt you to do it if it detects the issue.\n```\nsudo usermod -a -G dialout $USER\nsudo usermod -a -G wireshark $USER\n```\n\n## Using on Windows\nIf you are using Windows, you will have to run the Sniffer.py script (you'll need the win32api and PySerial modules). You must pass the serial port name as the first parameter and optionally the wireshark.exe path as the second argument.\nSadly, lua script parameter forwarding does not seem to work. So you might have to use the GUI in order to set your preferences.\nYou can use an installed version of Wireshark or WiresharkPortable.\nYou will need to run the python script as follows (from the directory where the .py and .lua scripts are and change the **COM** port and **path** as needed):\n```\npython Sniff.py COM3 C:\\Users\\snif\\Downloads\\WiresharkPortable\\WiresharkPortable.exe\n```\n\n## General usage\nYou must send a start command in order to initialize Wireshark and the sniffer device and subsequently get packets. Use the ZB menu. **You will not see anything in Wireshark until you send the start command using the Tools/ZB/ZB Start menu command.**\n![ZB menu](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/WS_menu_ZB.png)\nPlease make sure to select the correct channel, or you won't capture any frames. The Sniffer will send you a dummy frame to indicate the current channel every time you change it.\n![ZB dialog](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/WS_dialog_Options.png)\n\n# Using the GUI to set the preferences\n![Preferences menu](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/WS_menu.png)\n![Preferences dialog](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/WS_dialog.png) \nNote that changing the parameters in this dialog will try and send an update to the MCU.\n\n# Hardware\n## Xiaomi Door sensor\nWiring colors are :\n1. Purple: Tx (OUT from MCU)\n2. Green : Rx (IN  to   MCU)\n3. Bleue : nBootloader\n4. Red   : 3V3\n5. White : nReset\n6. Black : GND\nYou can optionally connect the nReset signal to your serial port nRTS signal and your nBootloader to the nDTR output.\n![Xiaomi_smart_button](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/Xiaomi_Door_sensor.JPG)\n\n## Xiaomi smart button\n1. Purple: Tx (OUT from MCU)\n2. Green : Rx (IN  to   MCU)\n3. Bleue : nBootloader\n4. Red   : 3V3\n5. White : nReset\n6. Black : GND\nYou can optionally connect the nReset signal to your serial port nRTS signal and your nBootloader to the nDTR output.\n![Xiaomi_smart_button](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/Xiaomi_smart_button.JPG)\n\n## Xiaomi smart button UART1\n1. For UART1 Tx, on this side of the resistor, we have the CPU pin directly.\n2. You can find some GND on this tantalum capacitor.\n![Xiaomi_smart_button_UART1](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/Xiaomi_smart_button_UART1.JPG)\n\n\n# Acknowledgements\nThis project is based on [work](https://github.com/KiwiHC16/ZigBeeSniffer) from @KiwiHC16 . He also helped me debug this documentation and a few version incompatibilities.\n\n# Troubleshooting\nWireshark might get confused if your MCU sends data before Wireshark has been initialised properly. To avoid this, please reset your MCU and ask it to send data with the ZB/start menu.\n\nYou can debug the communication with the following command:\n```\nstty -f /dev/cu.usbserial 38400 raw \u0026 cat /dev/cu.usbserial | tee /tmp/sf.bin \u003e /tmp/sharkfifo\n```\nYou can view the file content like this:\n```\nhexdump -C /tmp/sf.bin\n```\n\nThe lua script creates a file named lua.log in the folder wireshark is started.\n\nYou can also pass the dissector parameters through environment varaibles:\n```\nenv ZBL_CHANNEL=12 ZBL_COMPORT=/dev/ttyUSB1 wireshark -X lua_script:zb.lua -k -i /tmp/sharkfifo \u0026\n```\n\n## FIFO troubles (obsolete)\n\nIf you get stuck with remaining data in the FIFO that repeatedly crashes wireshark, you can destroy the pipe and re-create it:\n```\nrm -f /tmp/sharkfifo \u0026\u0026 mkfifo /tmp/sharkfifo\n```\nThis should not be necessary any more, as the FIFOs are destroyed when leaving the Sniff.py script.\n\n## Python version\nThe Sniff.py script has been developped using Python3.6, so this, or a more recent, version of Python3 is recommended. It has not been extensively tested using Python2.\n\n# To do list\n- Add LQI information to the packet\n- Add frame duration computation as well as inter frame gap (wireshark)\n\n# Gory details\nOriginal serial queuing functions took 43125us for 26 bytes (166us/byte) and 4923 us for 31 bytes (159us/byte) with a 115200 baud/s UART\nand 10272us for 26 bytes (395us/byte) and 12860 for 31 bytes (415us/byte) with a 1MBaud/s UART!!! What the hell?\nmemcpy algo takes 636 us for 26 bytes (24us/byte) and 848 for 43 bytes (20us/byte).\nThe longer runtime/byte might come from the fact that the likeliness of having time stolen by an ISR is higher if you take more time. I might do some additional tests with disabled IT to try and get more consistent results...\n\n## Packets timestamps\nAt 2.4GHz, Zigbee uses a 62500 Hz symbol clock. These symbols encode 4 bits each, providing an on the air bitrate of 250Kbits/s.\n\nPackets are timed with this clock, and have therefore a 16µs resolution.\n\n## Timings\nSend ACK between \nmacSIFSPeriod = 12 symbols \u003e\u003e 192µs\nand \nmacAckWaitDuration = macSIFSPeriod + phySHRDuration + ceiling(7 × phySymbolsPerOctet) = 12 symbols + \n\nbits are 250kHz (4µs), symbols are 62.5kHz (16-ary, so 4 bits/symbol)\n192µs \u003c Tack \u003c 512µs\n\nInter Frame Spacing\nIf lengthMPDU ≤ aMaxSIFSFrameSize (18 octets)\nthen,\nsymbolsIFS ≥ aMinSIFSPeriod = 12 symbols (192µs)\nelse,\nsymbolsIFS ≥ aMinLIFSPeriod = 40 symbols (640µs)\n\n![MPDU](https://github.com/Jerome-PS/JN516xSniffer/blob/master/doc/MPDU.png)\n\n# TODO\n- Check IT priority, so UART does not prevent packet management at the radio level.\n- Fill Tx FIFO before starting Tx ISR to limit the number of ISR.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerome-ps%2Fjn516xsniffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjerome-ps%2Fjn516xsniffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerome-ps%2Fjn516xsniffer/lists"}