Ⓣ OwnTags

I work on this for a little in the evenings after work. Thanks for visiting!

This project makes it possible to use OwnTracks apps (Android, iOS and web) as the app for following and viewing Haystack tags.

OwnTracks is well integrated into home automation projects like Home Assistant and OpenHab. I can imagine some really cool things that could be done.

Updated on May 27, 2023:

• introduced settings TOML file for configuration. Hopefully, comments in the file make it self explanatory.
• simplified directory structure to reduce clutter and makes the project easier to look at.
• timeframe to retreive location reports is done with --time hh:mm flag
• location reports can be stored to TinyDB, this will change to tinyfluxDB soon.
• tweaked terminal output

This is a very new project and is under active development. I'm not the greatest programmer (something I picked up during COVID) so I learn as I go... meaning this thing could break at any moment for very silly reasons. That said, I am excited about it and hope a few others will join me to build something interesting. This work builds the work of others.

Installation

To track tags with OwnTracks using this project you will need:

1. MacOS Monterrey (v12) or higher. (This can be an actual Mac or a virtual one. Check out Headless Haystack for a complete solution.)

2. Python 3.7 or newer. Homebrew is probably the easiest way to get this.

3. An MQTT broker. Homebrew is the recommended way to get this. Cloud MQTT brokers are an interesting option. Have a look at:

   • HiveMQ
   • MyQttHub
   • CloudMQTT
   • fogwing

4. A working OwnTracks app. Before going any further stop here. Make sure you have OwnTracks up and running before doing anything else! Apps are availble for Android and iOS. The web frontend has extra reqirements and additional, cool, features but is very worth the effort after getting the apps to work.

Install

These instructions are based on a Homebrew installed Python with a locally hosted MQTT broker. Make changes to reflect your system. Python commands should work with regualar Python as well. If you are using Anaconda then you probably know how to do these things in a conda environment.

Download

• Download the files in this branch.
• Unzip and navigate to the folder in the terminal

cd /Users/lukeskywalker/Projects/owntags

Create a virtual environment for Python

python3 -m venv venv

Activate the environment

Deactivate it when done by closing the terminal or typing deactivate.

source venv/bin/activate

Upgrade PIP & Install required libraries:

pip install --upgrade pip
pip install pyobjc cryptography six paho-mqtt  # tinydb, only if you want to export locations to this database

Configure

You will need:

• keyfiles of your tags
  • Unfortunately, these tags can be used in nefarioius ways. So, it'll take some exploring to learn how to make them. These are good places to start: OpenHaystack or headless-haystack
• iTunes passoword (to decrypt location reports)
• MQTT broker information
• OwnTracks broker topics

KeyFiles

Create directory applicaton/keys/ and put your keyfiles in there:

owntags/
└── application/
    └── keys/
        ├── prefix-1.keyfile
        └── prefix-2.keyfile

Settings

Add your iTunes password, MQTT broker details and OwnTracks topics to the settings.toml file.

[owntag_options]
password = "password"  # macOS password
print_history = 1
    # positive numbers (4), the number of locations to print in the console
    # negative numbers (-1) will print all fetched locations,
    # 0 will turn printing fetched locations off
status_msg = false  # publish status and metadata to MQTT
    # Status messages can be sent to an MQTT Topic
status_base = "status/owntags"  # topic for status messages

[mqtt_secrets]
mqtt_broker = "your-broker.com"  # broker address
mqtt_port = 1883  # 1883 if no TLS; 8883 if TLS
mqtt_tls = "None"  # Comment out if using TLS
mqtt_user = "username"  # Broker user
mqtt_pass = "password"  # Broker password
 # [mqtt_secrets.mqtt_tls]  # If TLS is activated, use this
 # ca_certs = "output/isrgrootx1.cer"  # where the cert file located
    # download HiveMQ certificate: https://community.hivemq.com/t/frequently-asked-questions/514
    # create users at https://console.hivemq.com

[owntracks_options]
# The script publishes waypoints to a user's topic, which makes the tags act like they are owned
# by the user. It is possible to publish tags to other topics. Read the OwnTracks booklet
# for more: https://owntracks.org/booklet/guide/topics/
owntracks_device = "owntracks/iphone"  # Topic Base of your phone, used for publishing waypoints. 
owntags_base = nan  # topic Base for tags. If `nan` owntracks_devce will be used.


# Each tag has its own options. When published to OwnTracks they can behave as `locations` or as `waypoints`.
# Learn about locations here: https://owntracks.org/booklet/features/location/
# Learn about waypoints here: https://owntracks.org/booklet/guide/waypoints/
# OwnTracks identifies `waypoints` by their creation timestamp. Here, you assign the timestamp manually to
# ensure it is unique.
[tag_options.prefix]
location = true   # (not required) locations are seen by everyone with access to the topic (they act like users)
waypoint = false  # (not required) waypoints are only seen on your phone (or device)
timestamp = 1000000001   # (required for wayponts) Must be unique, can be any past Unix/Posix timestamp.
radius = false    # (not required) use number for radius in meters, if `false` turn off, if `true` use confidence
mqtt_topic = nan  # (not required)  topic for this tag, if `nan` owntags_base will be used
status_topic = false    # (not required) if `True` messages will be published to `status_base`/prefix

Run

There are a couple of ways to start. The owntags.sh bash script will load the Python environment and fetch reports. Time is specified with hh:mm format. Plain double digits (42) will be interpreted as minutes.

./owntags.sh 0:30

Optionally, drop into the application folder and start request_reports.py manually. --owntags tells the script to send locations to OwnTracks:

cd application
request_reports.py --time 0:60 --owntags

[Sorry all, this all I had time for tonight. I add a little each day after work.]

Notes of Gratitude

None of this would be possible without building on the work of many others who are much more talented than I am. This project builds on the amazing work of many projects and those involved:

• OpenHaystack: the original project that figured out how to piggy-back onto Apple's FindMay real-time location system (RTLS) framework.

• openhaystack-python: who wrote the AirTagCrypto library to decode location reports that is used in many of the projects below.

• FindMy: who wrote the server, client and standalone scripts that allow fetching and decrypting location reports without a GUI and without an Apple Mail plugin.

• Headless Haystack: who assembled, and is refining, the various parts to create an integrated solution that simplifies managing devices that leverage Apples' FindMy RTLS.

OwnTags builds directly on the work of @dchristl in Headless Haystack. I've humbly taken that code, cleaned it up a bit, and added what is needed to forward locaton reports to an OwnTracks system.