findmy-traccar-bridge

A simple script to continuously import OpenHaystack locations into Traccar. This project uses the excellent findmy.py project to load the encrypted location data of your custom tracking beacons from Apple's FindMy network.

Requirements

• Docker or Python 3.12
• Some OpenHaystack beacons generating data, or decrypted plist files for real Airtags
  • e.g. an esp32 or NRF51
  • I recommend following the instructions 2. Hardware setup from macless-haystack. This is also where you will generate the private key for later.
• Access to an Apple account with 2FA enabled

Important

Using Apple's internal API like this may get your account banned, depending on how "trustworthy" Apple deems your account. In general, one query every 30 minutes seems to be safe, even for new throwaway accounts (this project querys once per hour by default). Some anecdotes from others: [1] [2] [3]

Usage

Run the bridge via docker compose:

services:
  bridge:
    build: https://github.com/jannisko/findmy-traccar-bridge.git
    volumes:
      - ./data:/bridge/data
      # Optional: Mount a directory with plist files for AirTags
      - /path/to/your/plists:/bridge/plists
    environment:
      # For OpenHaystack beacons, specify their private keys
      BRIDGE_PRIVATE_KEYS: "<key1>,<key2>,..."
      BRIDGE_TRACCAR_SERVER: "<your traccar base url>:5055"

via docker

docker build -t findmy-traccar-bridge https://github.com/jannisko/findmy-traccar-bridge.git
docker run -d --name bridge \
-v ./:/data \
# Optional: Mount directory with plist files for AirTags
-v /path/to/your/plists:/bridge/plists \
-e BRIDGE_PRIVATE_KEYS="<key1>,<key2>,..." \
-e BRIDGE_TRACCAR_SERVER="<your traccar base url>" \
findmy-traccar-bridge

as a python package

# Set up environment variables
# you should probably start your own anisette server for this
export BRIDGE_PRIVATE_KEYS="<key1>,<key2>,..." BRIDGE_TRACCAR_SERVER="<your traccar base url>"
# If you want to use AirTags through plist files, they'll be detected automatically in /bridge/plists
# Optionally you can override the plist directory:
# export BRIDGE_PLIST_DIR="/path/to/your/plists"

# Run the bridge
uvx --from=git+https://github.com/jannisko/findmy-traccar-bridge findmy-traccar-bridge

Initialization

To query the internal Apple FindMy API you will need to interactively log into your Apple account with a 2FA challenge when initially setting up the containers. Until this is done, the bridge container will stay idle.

docker compose exec bridge .venv/bin/findmy-traccar-bridge-init

via docker

docker exec -it bridge .venv/bin/findmy-traccar-bridge-init

as a python package

uvx --from=git+https://github.com/jannisko/findmy-traccar-bridge findmy-traccar-bridge-init

Configuration

The script can be configured via the following environment variables:

• BRIDGE_PRIVATE_KEYS - comma separated string of base64 encoded private keys of your OpenHaystack beacons (e.g. can be generated via instructions from macless-haystack)
• BRIDGE_PLIST_DIR - (optional) override the default directory path for decrypted plist files. By default, the app will look for .plist files in /bridge/plists. Only set this if you need to use a different location.
• BRIDGE_TRACCAR_SERVER - required - url to your traccar server
• BRIDGE_POLL_INTERVAL - optional (default: 3600 (60 minutes)) - time to wait between querying the apple API. Too frequent polling might get your account banned.
• BRIDGE_LOGGING_LEVEL - optional (default: INFO)

Example

An example compose file running the bridge and Traccar locally can be found in the testing directory:

git clone https://github.com/jannisko/findmy-traccar-bridge
cd findmy-traccar-bridge/testing
# ... insert your haystack keys into the compose file ...
docker compose up -d
docker compose exec bridge .venv/bin/findmy-traccar-bridge-init