Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/koenvervloesem/openhaystack-zephyr

Zephyr-based OpenHaystack firmware to track your personal Bluetooth devices via Apple's Find My network
https://github.com/koenvervloesem/openhaystack-zephyr

bbc-microbit ble bluetooth-low-energy find-my nrf52840 openhaystack ruuvitag zephyr zephyr-rtos

Last synced: about 2 months ago
JSON representation

Zephyr-based OpenHaystack firmware to track your personal Bluetooth devices via Apple's Find My network

Awesome Lists containing this project

README 

        
OpenHaystack Zephyr firmware

############################



This project implements firmware with an `OpenHaystack `_ application based on the real-time operating system `Zephyr `_.



OpenHaystack is a framework for tracking personal Bluetooth devices via Apple's massive `Find My `_ 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.



After 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.



Disclaimer

**********



The 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.



There 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.



Requirements

************



* A Bluetooth Low Energy device, supported by Zephyr

* A `Zephyr development environment `_

* OpenHaystack's macOS application to view the location of your device



Initialization

**************



The 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:



.. code-block:: shell



  # Initialize Zephyr workspace folder for the application (main branch)

  west init -m https://github.com/koenvervloesem/openhaystack-zephyr --mr main zephyr-workspace

  # Update Zephyr modules

  cd zephyr-workspace

  west update

  cd openhaystack-zephyr



Build

*****



To build the firmware, run:



.. code-block:: shell



   west build -p auto -b $BOARD -s app



Replace ``$BOARD`` by your target board.



Once you have built the application, the firmware image is available in ``build/zephyr``.



Use your own key

****************



You need to specify a public key in the firmware image. There are two ways to do this:



* Make the change directly in the source (the char array ``public_key`` in `main.c `_) 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.

* 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 `_ for a way to do this).



Flash

*****



How to flash the image to a device depends on the device and its bootloader. For many devices you can run:



.. code-block:: shell



   west flash



Refer to your `board's documentation `_ for alternative flash instructions if your board doesn't support the ``flash`` target.



For the nRF52840 Dongle with the built-in bootloader, run:



.. code-block:: shell



  nrfutil pkg generate --hw-version 52 --sd-req=0x00 \

          --application build/zephyr/zephyr.hex \

          --application-version 1 openhaystack.zip



This packages the application in the file ``openhaystack.zip``. Now press the reset button and flash the package onto the board with:



.. code-block:: shell



  nrfutil dfu usb-serial -pkg openhaystack.zip -p /dev/ttyACM0



Have a look at ``ls /dev/tty*`` for the right device on Linux and macOS. On Windows it should be something like ``COMx``.



For devices with the `Adafruit nRF52 bootloader `_ 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``:



.. code-block:: shell



  python3 ../zephyr/scripts/uf2conv.py -f 0xADA52840 -c build/zephyr/zephyr.hex



And then drag and drop the file ``flash.uf2`` to the storage device mounted by your operating system.



Supported devices

*****************



This procedure has been tested with:



* Nordic Semiconductor's `nRF52840 Dongle `_ (board name ``nrf52840dongle_nrf52840``), as well as its derivatives `April USB Dongle 52840 `_ and `makerdiary nRF52840 MDK USB Dongle `_, which are both using the Adafruit nRF52 bootloader

* the nRF52833-based `BBC micro:bit v2 `_ (board name ``bbc_microbit_v2``)

* Ruuvi's nRF52832-based `RuuviTag `_ (board name ``ruuvi_ruuvitag``) using the `RuuviTag Development Kit `_



Other 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.



Using OpenHaystack as a module

******************************



The base code is written as a Zephyr module, in the directory `modules/openhaystack `_. You can reuse this in your own Zephyr applications. For examples of how you do this, take a look at:



* the application of this repository in the directory `app `_

* the `Send My Sensor `_ project, which uses the OpenHaystack module to upload sensor data via Apple's Find My network.



Debugging

*********



A sample debug configuration to read logs from the USB UART is also provided. You can apply it by running:



.. code-block:: shell



  west build -p auto -b $BOARD -s app -- -DOVERLAY_CONFIG=debug-usb-uart.conf



This only works with boards that support this, such as Nordic Semiconductor's nRF52840 Dongle.



For 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.



Learn more about Bluetooth Low Energy development

*************************************************



If 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 `_ and the accompanying GitHub repository `koenvervloesem/bluetooth-low-energy-applications `_.



Acknowledgments

***************



This project is inspired by and has used code from:



* the original `OpenHaystack firmware for ESP32 `_

* the original `OpenHaystack firmware for nRF51822 `_

* Antonio Calatrava's alternative `OpenHaystack firmware using Nordic Semiconductor's Softdevice `_

* the `Zephyr Example Application `_ for the project structure and GitHub Actions workflow



License

*******



This project is provided by `Koen Vervloesem `_ as open source software with the MIT license. See the `LICENSE file `_ for more information.