{"id":13576300,"url":"https://github.com/koenvervloesem/openhaystack-zephyr","last_synced_at":"2025-08-21T12:42:10.185Z","repository":{"id":46264581,"uuid":"390397478","full_name":"koenvervloesem/openhaystack-zephyr","owner":"koenvervloesem","description":"Zephyr-based OpenHaystack firmware to track your personal Bluetooth devices via Apple's Find My network","archived":false,"fork":false,"pushed_at":"2022-06-10T13:57:41.000Z","size":22,"stargazers_count":65,"open_issues_count":0,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-30T12:21:07.430Z","etag":null,"topics":["bbc-microbit","ble","bluetooth-low-energy","find-my","nrf52840","openhaystack","ruuvitag","zephyr","zephyr-rtos"],"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/koenvervloesem.png","metadata":{"files":{"readme":"README.rst","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}},"created_at":"2021-07-28T15:16:59.000Z","updated_at":"2025-02-23T06:25:17.000Z","dependencies_parsed_at":"2022-08-03T09:15:27.271Z","dependency_job_id":null,"html_url":"https://github.com/koenvervloesem/openhaystack-zephyr","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/koenvervloesem/openhaystack-zephyr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koenvervloesem%2Fopenhaystack-zephyr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koenvervloesem%2Fopenhaystack-zephyr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koenvervloesem%2Fopenhaystack-zephyr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koenvervloesem%2Fopenhaystack-zephyr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koenvervloesem","download_url":"https://codeload.github.com/koenvervloesem/openhaystack-zephyr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koenvervloesem%2Fopenhaystack-zephyr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271484026,"owners_count":24767760,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"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":["bbc-microbit","ble","bluetooth-low-energy","find-my","nrf52840","openhaystack","ruuvitag","zephyr","zephyr-rtos"],"created_at":"2024-08-01T15:01:08.964Z","updated_at":"2025-08-21T12:42:10.095Z","avatar_url":"https://github.com/koenvervloesem.png","language":"C","funding_links":[],"categories":["C","Libraries"],"sub_categories":["IoT \u0026 Cloud"],"readme":"OpenHaystack Zephyr firmware\n############################\n\nThis project implements firmware with an `OpenHaystack \u003chttps://github.com/seemoo-lab/openhaystack\u003e`_ application based on the real-time operating system `Zephyr \u003chttps://www.zephyrproject.org/\u003e`_.\n\nOpenHaystack is a framework for tracking personal Bluetooth devices via Apple's massive `Find My \u003chttps://developer.apple.com/find-my/\u003e`_ network. Thanks to this firmware based on Zephyr, you can create your own tracking tags with one of the many Bluetooth Low Energy devices that Zephyr supports.\n\nAfter flashing the firmware to your device, it sends out Bluetooth Low Energy advertisements that will be visible in Apple's Find My network using the OpenHaystack application in macOS.\n\nDisclaimer\n**********\n\nThe firmware is just a proof-of-concept and currently only implements advertising a single static key. This means that devices running this firmware are trackable by other devices in proximity.\n\nThere is also no power management yet. So if you're running this firmware on a battery-powered device, it won't be as energy-efficient as possible. If you want to improve this, all patches are welcome.\n\nRequirements\n************\n\n* A Bluetooth Low Energy device, supported by Zephyr\n* A `Zephyr development environment \u003chttps://docs.zephyrproject.org/latest/getting_started/index.html\u003e`_\n* OpenHaystack's macOS application to view the location of your device\n\nInitialization\n**************\n\nThe first step is to initialize a workspace folder (for instance ``zephyr-workspace``) where the application and all Zephyr modules will be cloned. You can do that by running:\n\n.. code-block:: shell\n\n  # Initialize Zephyr workspace folder for the application (main branch)\n  west init -m https://github.com/koenvervloesem/openhaystack-zephyr --mr main zephyr-workspace\n  # Update Zephyr modules\n  cd zephyr-workspace\n  west update\n  cd openhaystack-zephyr\n\nBuild\n*****\n\nTo build the firmware, run:\n\n.. code-block:: shell\n\n   west build -p auto -b $BOARD -s app\n\nReplace ``$BOARD`` by your target board.\n\nOnce you have built the application, the firmware image is available in ``build/zephyr``.\n\nUse your own key\n****************\n\nYou need to specify a public key in the firmware image. There are two ways to do this:\n\n* Make the change directly in the source (the char array ``public_key`` in `main.c \u003chttps://github.com/koenvervloesem/openhaystack-zephyr/blob/main/app/src/main.c\u003e`_) and then build the firmware. You have to initialize the public key like this: ``static char public_key[28] = {0x61, 0xc4, 0xc2, 0x55, ...}`` with all bytes of the key instead of the ellipsis. Note that this is the raw key, not the Base64 encoded key.\n* Patch the default public key ``OFFLINEFINDINGPUBLICKEYHERE!`` in the bin file (``build/zephyr/zephyr.bin``) to your own key and save the resulting firmware image (see the script `openhaypatch.sh \u003chttps://github.com/koenvervloesem/openhaystack-zephyr/blob/main/openhaypatch.sh\u003e`_ for a way to do this).\n\nFlash\n*****\n\nHow to flash the image to a device depends on the device and its bootloader. For many devices you can run:\n\n.. code-block:: shell\n\n   west flash\n\nRefer to your `board's documentation \u003chttps://docs.zephyrproject.org/latest/boards/index.html\u003e`_ for alternative flash instructions if your board doesn't support the ``flash`` target.\n\nFor the nRF52840 Dongle with the built-in bootloader, run:\n\n.. code-block:: shell\n\n  nrfutil pkg generate --hw-version 52 --sd-req=0x00 \\\n          --application build/zephyr/zephyr.hex \\\n          --application-version 1 openhaystack.zip\n\nThis packages the application in the file ``openhaystack.zip``. Now press the reset button and flash the package onto the board with:\n\n.. code-block:: shell\n\n  nrfutil dfu usb-serial -pkg openhaystack.zip -p /dev/ttyACM0\n\nHave a look at ``ls /dev/tty*`` for the right device on Linux and macOS. On Windows it should be something like ``COMx``.\n\nFor devices with the `Adafruit nRF52 bootloader \u003chttps://github.com/adafruit/Adafruit_nRF52_Bootloader\u003e`_ such as the April USB Dongle 52840 or makerdiary nRF52840 MDK USB Dongle, first generate a UF2 file from the hex file with ``uf2conv.py``:\n\n.. code-block:: shell\n\n  python3 ../zephyr/scripts/uf2conv.py -f 0xADA52840 -c build/zephyr/zephyr.hex\n\nAnd then drag and drop the file ``flash.uf2`` to the storage device mounted by your operating system.\n\nSupported devices\n*****************\n\nThis procedure has been tested with:\n\n* Nordic Semiconductor's `nRF52840 Dongle \u003chttps://docs.zephyrproject.org/latest/boards/arm/nrf52840dongle_nrf52840/doc/index.html\u003e`_ (board name ``nrf52840dongle_nrf52840``), as well as its derivatives `April USB Dongle 52840 \u003chttps://wiki.aprbrother.com/en/BleUsbDongle.html#april-usb-dongle-52840\u003e`_ and `makerdiary nRF52840 MDK USB Dongle \u003chttps://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/\u003e`_, which are both using the Adafruit nRF52 bootloader\n* the nRF52833-based `BBC micro:bit v2 \u003chttps://docs.zephyrproject.org/latest/boards/arm/bbc_microbit_v2/doc/index.html\u003e`_ (board name ``bbc_microbit_v2``)\n* Ruuvi's nRF52832-based `RuuviTag \u003chttps://docs.zephyrproject.org/latest/boards/arm/ruuvi_ruuvitag/doc/index.html\u003e`_ (board name ``ruuvi_ruuvitag``) using the `RuuviTag Development Kit \u003chttps://ruuvi.com/products/ruuvitag-development-kit/\u003e`_\n\nOther Bluetooth Low Energy devices supported by Zephyr should work as well. Please let me know if you manage to run this firmware on another board, so I can add it to the list of devices it has been tested with.\n\nUsing OpenHaystack as a module\n******************************\n\nThe base code is written as a Zephyr module, in the directory `modules/openhaystack \u003chttps://github.com/koenvervloesem/openhaystack-zephyr/tree/main/modules/openhaystack\u003e`_. You can reuse this in your own Zephyr applications. For examples of how you do this, take a look at:\n\n* the application of this repository in the directory `app \u003chttps://github.com/koenvervloesem/openhaystack-zephyr/tree/main/app\u003e`_\n* the `Send My Sensor \u003chttps://github.com/koenvervloesem/send-my-sensor\u003e`_ project, which uses the OpenHaystack module to upload sensor data via Apple's Find My network.\n\nDebugging\n*********\n\nA sample debug configuration to read logs from the USB UART is also provided. You can apply it by running:\n\n.. code-block:: shell\n\n  west build -p auto -b $BOARD -s app -- -DOVERLAY_CONFIG=debug-usb-uart.conf\n\nThis only works with boards that support this, such as Nordic Semiconductor's nRF52840 Dongle.\n\nFor the UART logs: run ``ls /dev/tty*`` (Linux) or ``ls /dev/cu.*`` (macOS) in a terminal window, connect your board and run the command again to check which port appears. On Linux, this will probably be /dev/ttyACM0. Then run ``screen /dev/ttyACM0 115200`` to connect to port /dev/ttyACM0 with a speed of 115200 bits per second.\n\nLearn more about Bluetooth Low Energy development\n*************************************************\n\nIf you want to learn more about Bluetooth Low Energy development, read my book `Develop your own Bluetooth Low Energy Applications for Raspberry Pi, ESP32 and nRF52 with Python, Arduino and Zephyr \u003chttps://koen.vervloesem.eu/books/develop-your-own-bluetooth-low-energy-applications/\u003e`_ and the accompanying GitHub repository `koenvervloesem/bluetooth-low-energy-applications \u003chttps://github.com/koenvervloesem/bluetooth-low-energy-applications\u003e`_.\n\nAcknowledgments\n***************\n\nThis project is inspired by and has used code from:\n\n* the original `OpenHaystack firmware for ESP32 \u003chttps://github.com/seemoo-lab/openhaystack/tree/main/Firmware/ESP32\u003e`_\n* the original `OpenHaystack firmware for nRF51822 \u003chttps://github.com/seemoo-lab/openhaystack/tree/main/Firmware/Microbit_v1\u003e`_\n* Antonio Calatrava's alternative `OpenHaystack firmware using Nordic Semiconductor's Softdevice \u003chttps://github.com/acalatrava/openhaystack-firmware\u003e`_\n* the `Zephyr Example Application \u003chttps://github.com/zephyrproject-rtos/example-application\u003e`_ for the project structure and GitHub Actions workflow\n\nLicense\n*******\n\nThis project is provided by `Koen Vervloesem \u003chttp://koen.vervloesem.eu\u003e`_ as open source software with the MIT license. See the `LICENSE file \u003cLICENSE\u003e`_ for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoenvervloesem%2Fopenhaystack-zephyr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoenvervloesem%2Fopenhaystack-zephyr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoenvervloesem%2Fopenhaystack-zephyr/lists"}