If you use HTTP mode skip this chapter.
You now know that MQTT is a messaging protocol, and that it uses
topic names to label messages. topic names can be structured into multiple
topic levels by separating them with a forward slash (
/). topic levels are
UTF-8 text strings, and almost any character is valid except
The last two are used to address sets of topic names.
The principles during the design of the OwnTracks topic-naming scheme were
- human readability
- traffic minimization
- granular access control
topic name Root
Typically an MQTT broker hosts multiple applications. To create a separate name space
for OwnTracks we use a topic name root as the beginning of a topic name. Per default
owntracks/, but you may choose any other root (e.g.
if you prefer, the empty string. In order to change the default behaviour of
create a personalized configuration from scratch or, export
your current configuration, edit that and re-import to your device. On Android you trigger
the import function by opening the
.otrc file in a file manager; on iOS by, say, opening
the file in Mail, Dropbox or similar app. The settings which have to be changed are
Locations are captured in OwnTracks by devices (e.g. your Smartphone). The device name forms the second component of the topic name. In order to avoid clashes in naming and to simplify subscription and authorization we decided to use two topic levels
- The user name or identifier (e.g.
- The device name (e.g.
A typical topic name for a device would therefore be
device naming schemes are possible and transparent to OwnTracks (e.g. using
just one level
peters-iPhone or multiple levels
under any one OwnTracks name root the number of levels used for device names
have to be the same.
Base topic name
Combining the topic name root and the device name result in what we call base
topic name for each device (e.g.
owntracks/peter/iPhone). The devices label
their location messages with the base topic name when publishing to the MQTT
Subscribing to location Messages
Given the structure explained above, the topic filter you can use to subscribe to the
location messages of all devices is
owntracks/+/+ (the topic name root plus a so-called
wild card (
+) for each level of the device name.
Additional topic names
For additional communication from and to devices, OwnTracks uses topic names relative to the base topic name.
Devices listen to the relative topic name
cmd for commands you can publish to
OwnTracks devices (i.e.
owntracks/peter/iPhone/cmd). For example, if
authorized, you could request a location update from a friend's device by
publishing an appropriate payload to said topic.
The output of specific OwnTracks commands is published by the device to the
relative topic names
In addition, devices subscribe to the relative topic name
info for information about
other devices. Messages published with the relative topic name
owntracks/peter/iPhone/info) contain a card payload -- the name and
avatar of a user with which authorized users can identify, say, Peter within their OwnTracks app.
Devices publish their waypoints to the relative topic name
waypoint and the corresponding events the transition into or out of a
waypoint triggers, to the relative topic name
A device (named
peter/iPhone in this example) is connected to an MQTT
Broker with the OwnTracks name Root
owntracks. It publishes
location messages labeled with the topic name
same device publishes waypoints labeled as
owntracks/peter/iPhone/waypointand publishes to
owntracks/peter/iPhone/event when entering or leaving a waypoint (i.e. a monitored region).
The same device subscribes to
owntracks/+/+ to receive location messages of all
other devices it is authorized for which are connected to the same MQTT broker.
In addition, the device may listen to
owntracks/+/+/eventif the user of the devices
wants to be informed about other users entering or leaving monitored regions. Subscribing
owntracks/+/+/infogives the device access to additional information about the other
If a device's owner allows other users to ad-hoc request messages from his device,
the device will subscribe to
owntracks/peter/iPhone/cmd as well, and it will listen for OwnTracks
commands; responses to these commands will be published and labeled
A full set of supported topic names and expected payloads is documented in our JSON API.
- topic name
- OwnTracks topic name root
- OwnTracks device name
- OwnTracks base topic name
- relative topic names
- OwnTracks device
- OwnTracks user
- OwnTracks command