{"id":20985158,"url":"https://github.com/dlenski/ttblue","last_synced_at":"2025-05-14T17:31:42.686Z","repository":{"id":35712099,"uuid":"39989949","full_name":"dlenski/ttblue","owner":"dlenski","description":"Bluetooth LE app for TomTom GPS watches: Runner, MultiSport, Cardio, Spark, Runner v2","archived":false,"fork":false,"pushed_at":"2023-11-28T21:02:22.000Z","size":241,"stargazers_count":59,"open_issues_count":7,"forks_count":16,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-02T21:03:06.944Z","etag":null,"topics":["bluetooth-le","bluez","fitness-tracker","hardware-hacking","tomtom-gps-watch"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dlenski.png","metadata":{"files":{"readme":"README.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-31T06:20:10.000Z","updated_at":"2025-03-01T15:34:24.000Z","dependencies_parsed_at":"2023-01-16T03:39:06.038Z","dependency_job_id":"307239ff-8620-41ef-8e2d-60b88df5d0bc","html_url":"https://github.com/dlenski/ttblue","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fttblue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fttblue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fttblue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fttblue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dlenski","download_url":"https://codeload.github.com/dlenski/ttblue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254194863,"owners_count":22030435,"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":["bluetooth-le","bluez","fitness-tracker","hardware-hacking","tomtom-gps-watch"],"created_at":"2024-11-19T05:55:35.041Z","updated_at":"2025-05-14T17:31:37.656Z","avatar_url":"https://github.com/dlenski.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://api.travis-ci.org/dlenski/ttblue.png)](https://travis-ci.org/dlenski/ttblue)\n\nTable of Contents\n=================\n\n  * [Introduction](#motivation)\n  * [Building](#building)\n    * [Requirements](#requirements)\n    * [Compiling](#compiling)\n  * [Use it](#use-it)\n    * [Why so slow?](#why-so-slow)\n  * [TODO](#todo)\n  * [Protocol documentation](#protocol-documentation)\n  * [Credits](#credits)\n  * [License](#license)\n\n# Introduction\n\nThe TomTom Multi-Sport and Runner are nice GPS watches and quite\naffordable, but they suffer from subpar official software. There is no\nofficial desktop app for interfacing *wirelessly* with the TomTom GPS watches,\n(only for Android and iPhone).\n\nNow you can use `ttblue` to download your activites wirelessly and\nkeep the QuickFix GPS ephemeris data up-to-date.\n\n# Building\n\n## Requirements\n\nYou need to be running a recent Linux kernel, with a Bluetooth **4.0** adapter\nsupporting [Bluetooth Low Energy](http://en.wikipedia.org/wiki/Bluetooth_low_energy).\nMany newer PCs include built in Bluetooth 4.0 adapters; if you need one, I've had\ngood success with [this $6\ndongle](http://www.amazon.com/ORICO-BTA-403-Bluetooth-Adapter-Windows/dp/B00ESBCT56),\nwhich works out-of-the-box with the `btusb` driver from recent Linux\nkernels.\n\nThe [`libbluetooth` (BlueZ)](http://www.bluez.org/),\n[`libcurl`](http://curl.haxx.se/libcurl), and\n[`popt`](http://directory.fsf.org/wiki/Popt) libraries are required.\nOn Debian/Ubuntu-based systems, these can be installed with:\n\n```bash\n$ sudo apt-get install libbluetooth-dev libcurl4-gnutls-dev libpopt-dev\n```\n\n## Compiling\n\nCompilation with `gcc` should be straightforward:\n\n```bash\n$ make\n$ make setcap # requires sudo/root access\n```\n\nTo fix the issue with [very slow file transfers](#why-so-slow), the\nmost secure solution I've been able to come up with so far is to give\nthe binary elevated capabilities as discussed\n[on StackExchange](http://unix.stackexchange.com/a/182559/58453):\n`make setcap` will do this automatically or you can do it manually as\nfollows:\n\n```bash\nsudo setcap 'cap_net_raw,cap_net_admin+eip' ttblue\n```\n\n(Note that this is *more* secure than giving the binary\n[setuid root](http://wikipedia.org/wiki/setuid) permissions, because\nit only allows root-like privileges for these specific capabilities.)\n\n# Use it\n\nFor initial pairing, you'll need to go to the **Phone|Pair New**\nmenu on the watch.\n\nFor subsequent reconnection, ensure that **Phone|Sync** is enabled,\nand you may need to \"wake up\" the device's BLE radio by pressing a\nfew buttons.\n\nTry the following command line:\n\n```\n./ttblue -a [-d \u003cbluetooth-address\u003e] [-c \u003cpairing-code\u003e] [-s \u003cactivity-store\u003e]\n```\n\n* `bluetooth-address` is the MAC address of your TomTom GPS watch, for\n  example `E4:04:39:17:62:B1`. If not specified, `ttblue` will attempt\n  to scan for BLE devices, and try to connect to the first one\n  matching TomTom's vendor ID (`E4:04:39`).\n\n* The `pairing-code` is a previously-used pairing code (can be from one of\n  the \"official\" TomTom mobile apps). If left blank, `ttblue` will try\n  to create a new pairing.\n\n* The `-a`/`--auto` option tells `ttblue` to download all activities and\n  update QuickFixGPS.\n\n* The `-s`/`--activity-store` option specifies a location for `.ttbin`\n  activity files to be output (current directory is the default).\n\nAs invoked above, `ttblue` will download your activity files (saved as\n`0091000n_YYYYMMDD_HHmmSS.ttbin`), and attempt to download the\nQuickGPSFix update and send it to the watch. (You can then use\n[`ttbincnv`](https://github.com/ryanbinns/ttwatch/tree/master/ttbincnv)\nto convert the TTBIN files to GPX/TCX format.)\n\n```none\n$ ./ttblue -a -d E4:04:39:17:62:B1 -c 123456\nOpening L2CAP LE connection on ATT channel:\n\t src: 00:00:00:00:00:00\n\tdest: E4:04:39:17:62:B1\nConnected to HC4354G00150.\n  maker     : TomTom Fitness\n  serial    : HC4354G00150\n  user_name : Lenski\n  model_name: Runner\n  model_num : 1001\n  firmware  : 1.8.42\n  rssi      : -90 dB\nSetting PHONE menu to 'dlenski-ultra-0'.\nFound 1 activity files on watch.\n  Reading activity file 00910000 ...\n11: read 55000 bytes from watch (1807/sec)\n    Saved 55000 bytes to ./00910000_20150801_123616.ttbin\n    Deleting activity file 00910000 ...\nUpdating QuickFixGPS...\n  Last update was at at Sat Aug 1 04:11:03 2015.\n  Downloading http://gpsquickfix.services.tomtom.com/fitness/sifgps.f2p3enc.ee?timestamp=1439172006\n  Sending update to watch (32150 bytes)...\n7: wrote 32150 bytes to watch (1891/sec)\n```\n\nThere's also a fairly rudimentary \"daemon\" mode wherein `ttblue` just\nloops over and over (by default it waits an hour to retry after a\nsuccessful connection, but only 10 seconds after a failed one), and a\n`-p`/`--post` option to specify a command to be run on each\nsuccessfully downloaded `.ttbin` file (see [`ttbin2strava.sh`](ttbin2strava.sh))\nfor an example):\n\n```none\n$ ./ttblue -a --daemon -d e4:04:39:17:62:b1 -c 123456 -s ~/ttbin -p ttbin2strava.sh\n```\n\n## Why so slow?\n\nBy default, Linux (as of 3.19.0) specifies a very intermittent connection interval for BLE devices. This makes sense for things like beacons and thermometers, but it is bad for devices that use BLE to transfer large files because the transfer rate is directly [limited by the BLE connection interval](https://www.safaribooksonline.com/library/view/getting-started-with/9781491900550/ch01.html#_data_throughput).\n \nIf you run as `root` or if you\n[give the `ttblue` binary elevated capabilities](http://unix.stackexchange.com/a/182559/58453), it will attempt to set the minimum connection interval (7.5\u0026nbsp;ms) and activity file downloads will proceed **much faster** (about 1800\u0026nbsp;B/s\nvs. 500\u0026nbsp;B/s for me).\n\nUnfortunately, elevated permissions are required to configure this feature of a BLE connection. For gory details, see [this thread on the BlueZ mailing list](http://thread.gmane.org/gmane.linux.bluez.kernel/63778).\n\n# TODO\n\n* More command line options?\n* Real config file?\n* Better daemon mode that actually puts itself in the background\n  and writes output to a log file?\n* Integrate with [`ttwatch`](http://github.com/ryanbinns/ttwatch)\n  which already does all these things, but over USB?\n\n# Protocol documentation\n\nSee [`tt_bluetooth.md`](tt_bluetooth.md) for reverse-engineered protocol documentation.\n\n# Credits\n\n[**@ryanbinns**](https://github.com/ryanbinns) did a lot of the heavy\nlifting by writing his excellent\n[`ttwatch`](http://github.com/ryanbinns/ttwatch) utility to sync with\nTomTom GPS watches over *USB*, and in the process documenting the\n`ttbin` binary format of the activity files, as well as many of the\ninternal data structures of the units.\n\n[**@Grimler91**](https://github.com/Grimler91) for adding support for\nTomTom GPS watches using the \"v2\" protocol. (Spark, Runner v2, etc.)\n\n# License\n\nI'd like to license it as **GPLv3 or later**, but it uses snippets from the BlueZ source which are **GPLv2** so... let's call it GPLv2 or later?\n\nBy Dan Lenski \u0026lt;\u003cdlenski@gmail.com\u003e\u0026gt; \u0026copy; 2015\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlenski%2Fttblue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdlenski%2Fttblue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlenski%2Fttblue/lists"}