This documentation of the komoot mobile apps BLEConnect interface is outdated. You can find the the most recent documentation linked on the komoot website 👉 here 👈.
With komoot BLE Connect, you enable your BLE device to show navigation instructions for cycling, running and outdoor routes delivered by komoot Apps for Android and iOS. https://www.komoot.com/b2b/connect
All you need to implement this is found here:
The user activates BLE Connect inside the komoot app settings. When doing so, the app starts advertising the komoot navigation BLE service and tells the user to start pairing via their external BLE device. The komoot app stops advertising once the connection to the characteristic is established.
The external BLE device is responsible to establish the connection and subscribing to the komoot navigation service characteristic. Your device should search for the komoot navigation service (UUID defined below). Otherwise it might be possible that you won’t find the komoot app while the app is in background (not visible on iOS in that case).
Please note: The advertisement data on iOS are different while the app is running in background. For details please check Apple developer documentation.
The komoot app sends instructions data about once per second when a navigation gets started or resumed in the komoot app. The transferred data format is described in detail below.
The komoot app announces new data by updating a BLE characteristic. Once you receive a notification about the change, you have to start a read request on that characteristic to get the data object of the last navigation instruction.
The komoot app delivers the first 22 Bytes with the first request. You can do subsequent read request with shifted offsets (22) to retrieve more information if the streetname is long. When the komoot app delivers an offset error or a zero-sized byte array you know that you got the complete Navigation Instruction.
The komoot app repeats the last navigation instruction every 2 seconds. It observes your read requests, and if there hasn’t been a read request for a longer time (5 sec. ), the app assumes that the connection got lost and will start advertising the service again. Your device configured as a BLE central should then initiate a reconnect.
You have to start scanning for the navigation service once you detect the connection to the peripheral got lost. After a few seconds, the komoot app will start advertising.
To make development easier for you, we created two simulator apps you can find in this repository. Just clone the repository and open the Xcode Project to start the simulators on your iOS device.
Note: Set the signing team in the General tab, if you run the simulator apps with Xcode 8 or above.
| KomootAppSimulator | BLEDeviceSimulator |
|---|---|
 |
 |
| Simulates the behavior of the komoot app. (BLE Peripheral) | Simulates a BLE device that receives the BLE Navigation Service. (BLE Central) |
| UUID | Description | Access |
|---|---|---|
| 71C1E128-D92F-4FA8-A2B2-0F171DB3436C | GATT Primary Service Declaration | Readonly |
| 503DD605-9BCB-4F6E-B235-270A57483026 | GATT Characteristic to subscribe for navigation updates | Notify, Readonly |
When you read the GATT characteristic after you got notified, you will receive the following data.
- Identifier (UInt32)
- Direction Arrow (UInt8)
- Street (UTF8 string)
- Distance (UInt32)
UInt32 value to identify a single navigation instruction. Use this identifier for sending the read request to the characteristic. If we get a read request without this identifier, we will deliver the last data object.
The direction will be represented as an UInt8 value. The following list shows the mapping between the image and the corresponding UInt8 value. This list could be extended in future.
You can download the arrows here or make your own design.
| Direction | Number value | Description |
|---|---|---|
| No image | 0 | Reserved |
 |
1 | Go Straight |
 |
2 | Start |
 |
3 | Finish |
 |
4 | Slight Left |
 |
5 | Left |
 |
6 | Sharp Left |
 |
7 | Sharp Right |
 |
8 | Right |
 |
9 | Slight Right |
 |
10 | Fork Right |
 |
11 | Fork Left |
 |
12 | U-Turn |
| No image | 13 | Reserved |
| No image | 14 | Reserved |
 |
15 | Roundabout Exit Left |
 |
16 | Roundabout Exit Right |
 |
17 | Roundabout Counter Clockwise Exit 1 of 1 |
 |
18 | Roundabout Counter Clockwise Exit 1 of 2 |
 |
19 | Roundabout Counter Clockwise Exit 1 of 3 |
 |
20 | Roundabout Counter Clockwise Exit 2 of 2 |
 |
21 | Roundabout Counter Clockwise Exit 2 of 3 |
 |
22 | Roundabout Counter Clockwise Exit 3 of 3 |
 |
23 | Roundabout Clockwise Exit 1 of 1 |
 |
24 | Roundabout Clockwise Exit 1 of 2 |
 |
25 | Roundabout Clockwise Exit 1 of 3 |
 |
26 | Roundabout Clockwise Exit 2 of 2 |
 |
27 | Roundabout Clockwise Exit 2 of 3 |
 |
28 | Roundabout Clockwise Exit 3 of 3 |
 |
29 | Roundabout Fallback |
 |
30 | Out Of Route |
| No image | 31…n | We might enhance the table in future versions. |
The street is provided as UTF-8 string. The street is starting at byte 21 until the end of the data object.
The distance is provided in meters. There is no rounding done by the komoot app. Your implementation is responsible to round and convert into the right measurement system.
This is an example how we do rounding in the komoot app:
| Distance Range | Rounding step | Examples |
|---|---|---|
| 0 - 5 | 0 | Now |
| 6 - * | 10 | 14 -> 10, 15 -> 20 |