Types#
OwnTracks uses JSON format for its message payloads. The different payload types are identified by a mandatory _type
element. Depending on the app platform, different payload types are supported.
_type |
iOS | Android |
---|---|---|
beacon |
Y | N |
card |
Y | Y |
cmd |
Y | Y |
configuration |
Y | Y |
encrypted |
Y | Y |
location |
Y | Y |
lwt |
Y | Y |
request |
Y | N |
status |
Y | N |
steps |
Y | N |
transition |
Y | Y |
waypoint |
Y | Y |
waypoints |
Y | Y |
Topics#
In MQTT mode the apps publish to:
owntracks/user/device
with_type=location
for location updates, and with_type=lwt
owntracks/user/device/cmd
with_type=cmd
for remote commandsowntracks/user/device/event
with_type=transition
for enter/leave eventsowntracks/user/device/step
to report step counterowntracks/user/device/beacon
for beacon rangingowntracks/user/device/dump
for config dumpsowntracks/user/device/status
for status messagesowntracks/user/device/waypoint
when a geofence is created on the deviceowntracks/user/device/waypoints
(plural) when exporting a list of configured waypoints from device to backend
In MQTT mode apps subscribe to:
owntracks/user/device/cmd
if remote commands are enabledowntracks/+/+
for seeing other user's locations, depending on broker ACLowntracks/+/+/event
for transition messages (enter
/leave
)owntracks/+/+/info
for obtaining cards.
In HTTP mode the apps POST their data to a single endpoint you configure.
_type=location
#
This location object describes the location of the device that reported it.
{
"_type" : "location",
elements
}
acc
Accuracy of the reported location in meters without unit (iOS,Android/integer/meters/optional)alt
Altitude measured above sea level (iOS,Android/integer/meters/optional)batt
Device battery level (iOS,Android/integer/percent/optional)bs
Battery Status 0=unknown, 1=unplugged, 2=charging, 3=full (iOS, Android)cog
Course over ground (iOS/integer/degree/optional)lat
latitude (iOS,Android/float/degree/required)lon
longitude (iOS,Android/float/degree/required)rad
radius around the region when entering/leaving (iOS/integer/meters/optional)t
trigger for the location report (iOS,Android/string/optional)p
ping issued randomly by background task (iOS,Android)c
circular region enter/leave event (iOS,Android)C
circular region enter/leave event for +follow regions (iOS)b
beacon region enter/leave event (iOS)r
response to a reportLocation cmd message (iOS,Android)u
manual publish requested by the user (iOS,Android)t
timer based publish in move move (iOS)v
updated bySettings/Privacy/Locations Services/System Services/Frequent Locations
monitoring (iOS)
tid
Tracker ID used to display the initials of a user (iOS,Android/string/optional) required forhttp
modetst
UNIX epoch timestamp in seconds of the location fix (iOS,Android/integer/epoch/required)vac
vertical accuracy of thealt
element (iOS/integer/meters/optional)vel
velocity (iOS,Android/integer/kmh/optional)p
barometric pressure (iOS/float/kPa/optional/extended data)poi
point of interest name (iOS/string/optional)conn
Internet connectivity status (route to host) when the message is created (iOS,Android/string/optional/extended data)w
phone is connected to a WiFi connection (iOS,Android)o
phone is offline (iOS,Android)m
mobile data (iOS,Android)
tag
name of the tag (iOS/string/optional)topic
(only in HTTP payloads) contains the original publish topic (e.g.owntracks/jane/phone
). (iOS,Android >= 2.4,string)inregions
contains a list of regions the device is currently in (e.g.["Home","Garage"]
). Might be empty. (iOS,Android/list of strings/optional)inrids
contains a list of region IDs the device is currently in (e.g.["6da9cf","3defa7"]
). Might be empty. (iOS,Android/list of strings/optional)SSID
, if available, is the unique name of the WLAN. (iOS,string/optional)BSSID
, if available, identifies the access point. (iOS,string/optional)created_at
identifies the time at which the message is constructed (if it differs fromtst
, which is the timestamp of the GPS fix) (iOS,Android/integer/epoch/optional)m
identifies the monitoring mode at which the message is constructed (significant=1
, move=2
) (iOS/integer/optional)_id
random identifier to be used by consumers to correlate & distinguish send/return messages (Android/string)
Notes#
- The
tst
in a ping is a current timestamp, so that it doesn't look like a duplicate. - The
tid
defaults to the last two characters of the topic - A missing
t
element also indicates an automatic location update - A publish of
"_type": "location"
with a"b"
trigger is sent when an iOS device enters or leaves a beacon in addition to a"_type": "transition"
: if somebody leaves and enters his home without having left the radius of detection for significant changes, a subscriber to his main topic would otherwise not get notified of any location change although beacon or circular region enter and leave transitions were generated. - The
acc
,alt
,cog
,vac
,vel
elements are only added if they are not zero - Some Android devices always return 0 for
alt
orvel
- Elements marked with extended data are only added if
extendedData=true
is configured - Android devices using a VPN might not report either of SSID/BSSID which might be expected behaviour. #1888
Queclink#
OwnTracks works with a selection of trackers by Queclink, for which the protocol conversion is done via qtripp.
Queclink devices report the following additional elements in a _type=location
message:
{
"_type": "location",
elements
}
t
trigger for the location report (string/optional)o
CornerM
Mileage!
Tow or fake tow or sensor without ignitiona
motionless (aka park)i
ignition onI
ignition offe
external power offE
external power ON1
Devices powered up2
Battery stop charging3
Battery start charging9
Battery power lowh
harsh behaviors
speed alarm
odometer
total distance of the device (float/kilometers/optional)hmc
total hours of operation (float/seconds/optional)ubatt
voltage of the battery (float/volts/optional)uext
voltage of the external power source (float/volts/optional)vin
vehicle identification number (string/optional)imei
identification number (string/optional)name
vehicle name (string/optional)don
is duration since ignition on (float/seconds/optional)doff
is duration since ignition off (float/seconds/optional)aiv
is analog input voltage (float/volts/optional)rpm
is engine rounds per minute (float/rounds per minute/optional)fcon
is fuel consumption (float/L per 100km/optional)flvl
is fuel level (float/percent/optional)anum
is number of analog inputs (integer/optional)adid-xx
is id of analog input number xx (string/optional)adty-xx
is type of analog input number xx (string/optional)adda-xx
is data of analog input number xx (string/optional)temp_c-xx
is temperature of analog input number xx (float/celsius/optional)can
is can data (string/optional)din1
is status of digital input 1 (boolean/optional)din2
is status of digital input 2 (boolean/optional)dout1
is status of digital output 1 (boolean/optional)dout2
is status of digital output 2 (boolean/optional)ign
is status of ignition (boolean/optional)motion
is motion status (boolean/optional)tow
is status of tow sensor (boolean/optional)fake
is status of fake tow sensor (boolean/optional)sens
is status of motion sensor (boolean/optional)sent
is epoch when message was sent (integer/epoch/optional)mcc
is mobile country code (integer/optional)mnc
is mobile network code (integer/optional)lac
is location area code (string/optional)cid
is cell id (string/optional)nmds
is non movement detection status (boolean/optional)rit
queclink record id and type (integer/optional)rty
queclink record type (integer/optional)rid
queclink record id (integer/optional)mst
queclink motion state (integer/optional)count
is counter of message (string/optional)raw_line
raw data (string/optional)counter
number of ignored positions (integer/optional)ignored
indicates counter positions have been ignored (boolean/optional)
Notes#
- The device can be configured to produce or not produce fields marked as optional
_type=lwt
#
A last will and testament is published automatically by the MQTT broker when it loses contact with the app. This typically looks like this:
{
"_type":"lwt",
elements
}
tst
UNIX epoch timestamp at which the app first connected (iOS,Android/integer/epoch/required)
_type=waypoint
#
Waypoints / regions denote specific geographical regions that you want to keep track of. You define a region in the OwnTracks app, and OwnTracks publishes this waypoint to the topic branch ../waypoint
(singular). OwnTracks also monitors these waypoints and will publish {_type: "transition", ...}
message when entering or leaving the region. A waypoint may also define a BLE Beacon instead of a geographical region.
{
"_type" : "waypoint",
elements
}
desc
Name of the waypoint that is included in the sent transition message, copied into thelocation
messageinregions
array when a current position is within a region. (iOS,Android,string/required)lat
Latitude (iOS,Android/float/degree/optional)lon
Longitude (iOS,Android/float/degree/optional)rad
Radius around the latitude and longitude coordinates (iOS,Android/integer/meters/optional)tst
Timestamp of creation of region, copied into thewtst
element of the transition message (iOS,Android/integer/epoch/required)uuid
UUID of the BLE Beacon (iOS/string/optional)major
Major number of the BLE Beacon (iOS/integer/optional)minor
Minor number of the BLE Beacon_(iOS/integer/optional)_rid
region ID, created automatically, copied into thelocation
payloadinrids
array (iOS/string)_
Notes#
- In iOS version >= 9.1.0 the last three elements (uuid, major, and minor) are used to configure Beacon waypoints instead of encoding these values into the
desc
element. - If
lat
,lon
andrad
elements are present, transition messages are sent when entering and leaving the geographical region - If
uuid
,major
,minor
elements are present, BLE becons with that specifications are monitored - Beacons and Geographical regions can be defined together
- Waypoint messages are published non-retained because the second waypoint would overwrite the first: a client would only get the last one which makes no sense. Your application will typically store waypoints to some kind of persistent storage.
- Waypoints are sent to the broker and transition messages contain a
desc
andevent
element.
_type=transition
#
A transition message is sent, when entering or leaving a previously configured geographical region or BLE Beacon. In addition to the coordinates where the event fired, the message contains the timestamp of the waypoint creation as well as the event that triggered the transition message with its description. MQTT transition messages are published non retained.
{
"_type": "transition",
elements
}
wtst
Timestamp of waypoint creation (iOS,Android/integer/epoch/required)lat
Latitude at which the event occured (iOS,Android/float/degree/optional)lon
Longitue at which the event occured (iOS,Android/float/degree/optional)tst
Timestamp at which the event occured (iOS,Android/integer/epoch/required)acc
Accuracy of the geographical coordinates (iOS,Android/int/meters/required)tid
Tracker ID of the (iOS/string/none/optional) required in http mode.event
Event that triggered the transition (iOS,Android/string/required)enter
The device entered the defined geographical region or BLE Beacon range (iOS)leave
The device left the defined geographical region or BLE Beacon range (iOS)
desc
Name of the waypoint (iOS,Android/string/optional)t
Trigger of the event (iOS,Android/string/optional)c
Circular geographical region (iOS, Android)b
BLE Beacon (iOS)l
Location update (Android)
rid
Region ID (iOS/Android, after January 2021)
_type=configuration
#
The device configuration can be imported and exported as JSON. The exported configuration can contain an array of waypoints that are defined on the device. If enabled, apps also accept remote configuration messages.
{
"_type": "configuration",
elements
}
allowRemoteLocation
Respond to reportLocation cmd message (iOS/boolean)allowinvalidcerts
disable TLS certificate checks insecure (iOS/boolean)auth
Useusername
andpassword
for endpoint authentication (iOS,Android/boolean)autostartOnBoot
Autostart the app on device boot (Android/boolean)cleanSession
MQTT endpoint clean session (iOS,Android/boolean)clientId
client id to use for MQTT connect. Defaults to "user deviceId" (iOS,Android/string)clientpkcs
Name of the client pkcs12 file (iOS/string)cmd
Respond to cmd messages (iOS,Android/boolean)connectionTimeoutSeconds
(default 30) TCP timeout for establishing a connection to the MQTT / HTTP broker, (Android/int)debugLog
(default false) whether or not debug logs should be shown in the log viewer / exporter activity (Android/bool)deviceId
id of the device used forpubTopicBase
andclientId
construction. Defaults to the os name of the device (iOS,Android/string)downgrade
battery level below which to downgrade monitoring from move mode (iOS/integer/percent/optional)encryptionKey
the secret key used for payload encryption (iOS,Android/string)extendedData
Add extended data attributes to location messages (iOS,Android/boolean)host
MQTT endpoint host (iOS,Android/string)httpHeaders
extra HTTP headers:field names and field content are separated by a colon (:), multiple fields by a backslash-n (\n) \<field-name>:\<field-content>\n\<field-name>:\<field-content>... (iOS only/string)ignoreInaccurateLocations
Location accuracy below which reports are supressed (iOS,Android/integer/meters)ignoreStaleLocations
Number of days after which location updates are assumed stale. Locations sent by friends older than the number of days specified here will not be shown on map or in friends list. Defaults to 0, which means stale locations are not filtered. (iOS,Android/integer/days)keepalive
MQTT endpoint keepalive (iOS,Android/integer/seconds)locatorDisplacement
maximum distance between location source updates (iOS,Android/integer/meters)locatorInterval
maximum interval between location source updates (iOS,Android/integer/seconds)locatorPriority
source/power setting for location updates (Android/integer)0
NO_POWER / best accuracy possible with zero additional power consumption (Android)1
LOW_POWER / city level accuracy (Android)2
BALANCED_POWER / block level accuracy based on Wifi/Cell (Android)3
HIGH_POWER / most accurate accuracy based on GPS (Android)
locked
Locks settings screen on device for editing (iOS/boolean)maxHistory
Number of notifications to store historically. Zero (0) means no notifications are stored and history tab is hidden. Defaults to zero. (iOS/integer)mode
Endpoint protocol mode (iOS,Android/integer)0
MQTT (iOS, Android)3
HTTP (iOS, Android)
monitoring
Location reporting mode (iOS,Android/integer)-1
Quiet0
Manual1
Significant2
Move
mqttProtocolLevel
MQTT broker protocol level (iOS,Android/integer)3
MQTT 3 (default)4
MQTT 3.1.15
MQTT 5 (iOS only)
notificationLocation
Show last reported location in ongoing notification (Android/boolean)opencageApiKey
API key for alternate Geocoding provider. See OpenCage for details. (Android/string)osmTemplate
URL template for alternate tile provider. Defaults tohttps://tile.openstreetmap.org/{z}/{x}/{y}.png
. (iOS/string)osmCopyright
Attribution text shown with OSM map. Defaults to(c) OpenStreetMap contributors
. (iOS/string)passphrase
Passphrase of the client pkcs12 file (iOS/string)password
Endpoint password (iOS,Android/string)pegLocatorFastestIntervalToInterval
(default false) - if true, requests that that the device provide locations no faster than the specified interval. Location providers often use the requested interval as a "at least every" setting, and may return locations more frequencly. Some people wanted the behaviour where it also meant "no more frequently than", so this setting lets them specify this (Android/bool)ping
Interval in which location messages of witht
:p
are reported (Android/integer)port
MQTT endpoint port (iOS,Android/integer)positions
Number of locations to keep and display (iOS/integer)pubTopicBase
MQTT topic base to which the app publishes;%u
is replaced by the user name,%d
by device (iOS,Android/string)pubRetain
MQTT retain flag for reported messages (iOS,Android/boolean)pubQos
MQTT QoS level for reported messages (iOS,Android/integer)ranging
Beacon ranging (iOS/boolean)remoteConfiguration
Allow remote configuration by sending asetConfiguration
cmd message (Android/boolean)sub
subscribe tosubTopic
via MQTT (iOS,Android/boolean)subTopic
A whitespace separated list of MQTT topics to which the app subscribes ifsub
is true (defaults see topics) (iOS,Android/string)subQos
(iOS,Android/boolean)tid
Two digit Tracker ID used to display short name and default face of a user (iOS,Android/string)tls
MQTT endpoint TLS connection (iOS,Android/boolean)tlsClientCrtPassword
Passphrase of the client pkcs12 file (Android/string)url
HTTP endpoint URL to which messages are POSTed (iOS,Android/string)username
Endpoint username (iOS,Android/string)ws
use MQTT over Websocket, defaultfalse
(iOS,Android/boolean)waypoints
Array of waypoint messages (iOS,Android/array)
Notes#
- When importing a configuration message, all contained values are imported for the currently active mode. If the message also contains a
mode
element, the mode is changed first and all remaining elements are imported for the new mode. - In MQTT mode the server will consider the client as dead if it the keepalive interval plus 50% passed without receiving any MQTT packet from the client (e.g. after 90 sec if
keepalive
was 60). Afterwards, anlwt
message will be send.
_type=status
#
The device status contains information about the settings on the device which are not configured in the app.
{
"_type": "status",
"iOS": <iOS specific elements>,
"android": <android specific elements>
<other elements>
}
- iOS specific elements
altimeterAuthorizationStatus
used for steps (iOS/string) as defined in CMAuthorizationStatusaltimeterIsRelativeAltitudeAvailable
used for steps (iOS/boolean) as defined in isRelativeAltitudeAvailablebackgroundRefreshStatus
(iOS/boolean) as defined in UIBackgroundRefreshStatusAvailabledeviceIdentifierForVendor
used for default DeviceID (iOS/string) as defined in identifierForVendordeviceModel
(iOS/string) as defined in modeldeviceSystemName
(iOS/string) as defined in systemNamedeviceSystemVersion
(iOS/string) as defined in systemVersiondeviceUserInterfaceIdiom
(iOS/string) as defined in userInterfaceIdiomlocale
the current locale on the device (iOS/string) as defined in localeIdentifierlocaleUsesMetricSystem
(iOS/boolean) as defined in usesMetricSystem"locationManagerAuthorizationStatus"
used for all locations (iOS/string) as defined in "CLAuthorizationStatus"version
version of the OwnTracks app (iOS/string)
- android specific elements
hib
app can hibernate if not used (Android/integer)bo
app is configured with battery optimizations (Android/integer)loc
app location permissions (Android/integer)ps
phone power save mode (Android/integer)wifi
wifi is on/off (Android/integer)
- other elements
_id
random identifier to be used by consumers to correlate & distinguish send/return messages (Android/string)
_type=beacon
#
These messages are published when beacon ranging (iOS only) is enabled. Be advised that beacon ranging publishes a lot of messages and has a strong impact on battery life.
{
"_type":"beacon",
elements
}
desc
name of the seen beacon (iOS/String)uuid
UUID of the seen beacon (iOS/String)major
Major number of the seen beacon (iOS/integer/epoch)minor
Minor number of the seen beacon (iOS/integer/epoch)tst
Timestamp at which the beacon was seen (iOS/integer/epoch)acc
Accuracy of the proximity value (iOS/integer/meters)rssi
Received signal strength of the beacon (iOS/integer/decibel)prox
Relative distance to the beacon (iOS/integer)0
Proximity of the beacon could not be determined1
Beacon is in the immediate vicinity2
Beacon is relatively close to the user3
Beacon is far away
Notes#
- The theoretical relationship between RSSI and distance is
RSSI[dbm] = −(10n log10(d) − A)
where d is the distance and A is the offset which is the measured RSSI one meter point away from the beacon.
_type=cmd
#
{"_type":"cmd", "action":"reportLocation"}
{"_type":"cmd", "action":"reportSteps"}
{"_type":"cmd", "action":"dump"}
{"_type":"cmd", "action":"status"}
{"_type":"cmd", "action":"waypoints"}
{"_type":"cmd", "action":"clearWaypoints"}
{"_type":"cmd", "action":"setConfiguration", "configuration":{"_type":"configuration",...}
{"_type":"cmd", "action":"setWaypoints", "waypoints":{"_type":"waypoints","waypoints":[...]}
action
action to be performed by the device (iOS,Android/string)dump
Triggers the publish of aconfiguration
message (iOS)status
Triggers the publish of astatus
message to../status
(iOS)reportSteps
Triggers the report of asteps
messages_(iOS)_from
Timestamp (iOS/epoch/optional)to
Timestamp (iOS/epoch/optional)
reportLocation
Triggers the publish of alocation
messages (iOS,Android) Don‘t expect device to be online. Send with QoS>0. Device will receive and repond when activated next time.clearWaypoints
deletes all waypoints/regions (iOS)setWaypoints
Imports (merge) and activates new waypoints (iOS,Android)waypoints
Array ofwaypoint
messages to import (iOS,Android/array/required)
setConfiguration
Imports and activates new configuration values (iOS,Android)configuration
Configuration message to import (iOS,Android/required)
waypoints
Triggers publish of awaypoints
message (iOS,Android)
Notes#
- On iOS, the array of waypoints to the
setWaypoints
command allows updates / removal; the key of the waypoint is its name (desc
). If you specify an invalidlat
orlon
(invalid means out of range number value e.g.-1000000
, a string like"foo"
will result in a0
in app) the waypoint is deleted. - On Android there's a primary key which isn't surfaced to the API, and
tst
is a uniquely-constrained value which effectively acts like a key.
_type=steps
#
{
"_type":"steps",
elements
}
tst
Timestamp of the request (iOS/integer/epoch)steps
Steps walked with the device in the specfied time period (iOS/integer/steps)from
Effective start of time period (iOS/integer/epoch)to
Effective end of time period (iOS/integer/epoch)
Notes#
steps
is -1 if device does not support step counting or specified time period is invalid
_type=card
#
Apps read Card to display a name and icon for a user.
{
"_type": "card",
elements
}
tid
Tracker ID to associate the card with (iOS,Android/string/required)name
Name to identify a user (iOS,Android/string/optional)face
Base64 encoded PNG image that is displayed instead of the Tracker ID (iOS,Android/string/optional)
_type=waypoints
#
The app can export a list of configured waypoints to the endpoint ../waypoints
(plural).
{
"_type": "waypoints",
elements
}
_creator
Identification of what created the array. Ignored by the apps (iOS,Android/string/optional)waypoints
Array ofwaypoint
messages (iOS,Android/array/required)
_type=encrypted
#
Apps can optionally encrypt outgoing messages with a shared symmetric key. The encrypted message is contained in the data
element.
For security reasons, the encryption key is not exported with configuration messages and cannot be imported.
{
"_type": "encrypted",
elements
}
data
Encrypted and Base64 encoded original JSON message (iOS,Android/string/required)
_type=request
#
Apps can request the creation of tours which elicit a cmd
response from the Recorder. See tours for the details.
{
"_type": "request",
"request": "tour",
"tour": {
...
}
}