Types

OwnTracks publishes its message payloads in JSON format. The different payload types are identified by a _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
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 commands
  • owntracks/user/device/event with _type=transition for enter/leave events
  • owntracks/user/device/step to report step counter
  • owntracks/user/device/beacon for beacon ranging
  • owntracks/user/device/dump for config dumps

In MQTT mode apps subscribe to:

  • owntracks/user/device/cmd if remote commands are enabled
  • owntracks/+/+ for seeing other user's locations, depending on broker ACL
  • owntracks/+/+/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/integer/meters/optional)
  • alt Altitude measured above sea level (iOS/integer/meters/optional)
  • batt Device battery level (iOS,Android/integer/percent/optional)
  • cog Course over ground (iOS/integer/degree/optional)
  • lat latitude (iOS,Android/float/meters/required)
  • lon longitude (iOS,Android/float/meters/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)
    • c circular region enter/leave event (iOS/Android)
    • b beacon region enter/leave event (iOS/Android)
    • 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 by Settings/Privacy/Locations Services/System Services/Frequent Locations monitoring (iOS)
  • tid Tracker ID used to display the initials of a user (iOS,Android/string/optional)
  • tst UNIX epoch timestamp in seconds of the location fix (iOS,Android/integer/epoch/required)
  • vac vertical accuracy of the alt element (iOS/integer/meters/optional)
  • vel velocity (iOS/integer/kmh/optional)
  • p barometric pressure (iOS/integer/kPa/optional/extended data)
  • 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)
  • cp copy mode enabled; only if true, missing otherwise (iOS)
  • topic (only in HTTP payloads) contains the original publish topic (e.g. owntracks/jane/phone). (iOS)

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
  • Elements marked with extended data are only added if extendedData=true is configured

Greenwich

The OwnTracks edition of the Choral Greenwich device reports the following additional elements in a _type=location message:

{
    "_type": "location",
    elements
}
  • alt Altitude measured above sea level (integer/meters/optional)
  • batt Device battery level (integer/percent/optional)
  • cog Course over ground (integer/degree/optional)
  • dist Distance travelled since the last location report (integer/meters/optional)
  • trip Distance travelled since the last reboot (integer/meters/optional)
  • vel velocity (integer/kmh/optional)
  • t trigger for the location report (string/optional)
    • f First publish after reboot
    • m Manually requested locations (e.g. by publishing to /cmd)
    • t Time for location published because device is moving.
    • T Time for location published because of time passed while device is stationary (maxInterval)
    • k Transitioning from move to stationary (park)
    • v Transitioning from stationary to move (mo-v-e)
    • l Last known position when device lost GPS fix
    • L Last known position before gracefull shutdown

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 denote specific geographical regions that you want to keep track of. You define a waypoint in the OwnTracks app, and OwnTracks publishes this waypoint if the waypoint is marked as shared. 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 (iOS,Android,string/required)
  • lat Latitude (iOS,Android/float/meters/optional)
  • lon Longitude (iOS,Android/float/meters/optional)
  • rad Radius around the latitude and longitude coordinates (iOS,Android/integer/meters/optional)
  • tst Timestamp of waypoint creation to identify the waypoint. Copied into the wtst element of the transition message (iOS,Android/integer/epoch/required)_
  • tid Tracker ID that is included in the sent transition message (iOS/string/optional)
  • uuid UUID of the BLE Beacon (iOS,Android/string/optional)
  • major Major number of the BLE Beacon (iOS,Android/integer/optional)
  • minor Minor number of the BLE Beacon_(iOS,Android/integer/optional)_

Notes

  • In iOS version >= 9.1.0 and in Android version >= 0.6.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 and rad 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.
  • Shared Waypoint are sent to the broker and transition messages contain a desc and event element. Not shared ones are not sent to the broker and transition messages contain an event attribute only

_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. If the corresponding waypoint is shared, it's description in desc is included too. 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/meters/optional)
  • lon Longitue at which the event occured (iOS,Android/float/meters/optional)
  • tst Timestamp at which the event occured (iOS,Android/integer/epoch/required)
  • acc Accuracy of the geographical coordinates (iOS,Android/float/meters/required)
  • tid Tracker ID of the waypoint (iOS/string/none/optional)
  • event Event that triggered the transition (iOS,Android/string/required)
    • enter The device entered the defined geographical region or BLE Beacon range (iOS, Android)
    • leave The device left the defined geographical region or BLE Beacon range (iOS, Android)
  • 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, Android)

_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,Android/boolean)
  • allowinvalidcerts Allow self signed certificates in user defined security policy (iOS/boolean)
  • auth Use username and password for endpoint authentication (iOS,Android/boolean)
  • autostartOnBoot Autostart the app on device boot (Android/boolean)
  • beaconLayout AltBeacon parser layout to understand different beacon advertisements other than the default iBeacons (Android/string)

  • beaconMode Backend mode for BLE beacon scanning (Android/Integer)

    • 0 Normal bluetooth scanning for regions with UUID
    • 1 Legacy beacon scanning instead of Android 6 scanning. Has no effect on devices running Android < 6.x
    • 2 Hard disable any Bluetooth functions even if regions with UUID are defined
  • 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)
  • cp Copy mode (iOS,Android/boolean)
  • cmd Respond to cmd messages (iOS,Android/boolean)
  • deviceId id of the device used for pubTopicBase and clientId construction. Defaults to the os name of the device (iOS,Android/string)
  • extendedData Add extended data attributes to location messages (iOS,Android/boolean)
  • host MQTT endpoint host (iOS,Android/string)
  • httpSchedulerConsiderStrategyDirect Directly send messages in HTTP mode and bypass the default scheduler if a network connection exists (Android/boolean)
  • ignoreInaccurateLocations Location accuracy below which reports are supressed (iOS,Android/integer/days)
  • ignoreStaleLocations Number of days after which location updates are assumed stale (iOS,Android/integer/days)
  • keepalive MQTT endpoint keepalive (iOS,Android/integer/seconds)
  • locatorDisplacement maximum distance between location source updates (iOS,Android/integer/meters)
  • locatorAccuracyBackground Location source power mode when the app is in the background (Android/integer)
    • 0 High power likely based on GPS location
    • 1 Balanced power based on multiple location sources
    • 2 Low power based on cell tower location
    • 3 No power based on locations requested by other apps
  • locatorAccuracyForeground Location source power mode when the app is in the foreground (Android/integer)
    • 0 High power likely based on GPS location
    • 1 Balanced power based on multiple location sources
    • 2 Low power based on cell tower location
    • 3 No power based on locations requested by other apps
  • locatorInterval maximum interval between location source updates (iOS,Android/integer/seconds)
  • locked Locks settings screen on device for editing (iOS/boolean)
  • mode Endpoint protocol mode (iOS,Android/integer)
    • 0 Private MQTT (iOS, Android)
    • 2 Public MQTT (iOS, Android)
    • 3 Private HTTP (iOS, Android)
    • 4 Watson IOT Quickstart (iOS)
    • 4 Watson IOT Registered (iOS)
  • monitoring Location reporting mode (iOS,integer)
    • -1 Quiet
    • 0 Manual
    • 1 Significant
    • 2 Move
  • mqttProtocolLevel MQTT broker protocol level (iOS,Android/integer)

    • 3 MQTT 3 (default)
    • 4 MQTT 3.1.1
  • notification Show ongoing notification. Required to keep running in the background (Android/boolean)

  • notificationGeocoder Resolve last reported location in ongoing notification to an address (Android/boolean)
  • notificationLocation Show last reported location in ongoing notification (Android/boolean)
  • passphrase Passphrase of the client pkcs12 file (iOS/string)
  • password Endpoint password (iOS,Android/string)
  • policymode User defined securiy policy mode (iOS/integer)
    • 0 Do not used pinned certificates to validate servers
    • 1 Validate host certificates against public keys of pinned certificates
    • 2 Validate host certificates against pinned certificates
  • port MQTT endpoint port (iOS,Android/integer)
  • positions Number of locatoins to keep and display (iOS/integer)
  • pub Automatic reporting (Android/boolean)
  • 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/boolean)
  • ranging Beacon ranging (iOS/boolean)
  • remoteConfiguration Allow remote configuration by sending a setConfiguration cmd message (Android/boolean)
  • servercer Blank separated list of certificate file names in DER format (iOS/string)
  • sub subscribe to subTopic via MQTT (iOS,Android/boolean)
  • subTopic A whitespace separated list of MQTT topics to which the app subscribes if sub 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)
  • updateAddressBook (iOS/boolean)
  • usepolicy Use user defined security policy (iOS/boolean)
  • username Endpoint username (iOS,Android/string)
  • validatedomainname Validate domain name during TLS handshake (iOS/boolean)
  • validatecertificatechain Validate the whole certificate chain or just the server certificate (iOS/boolean)
  • watsonAuthToken Auth token Watson IOT Registered mode (iOS/string)
  • watsonDeviceType Device type in Watson IOT Registered mode (iOS/string)
  • watsonDeviceId Device ID in Watson IOT Registered mode (iOS/string)
  • watsonOrganization Organization in Watson IOT Registered mode (iOS/string)
  • willRetain
  • willTopic
  • willQos
  • waypoints Array of waypoint messages (iOS,Android/array)
  • quickstartId Device ID in Watson IOT Quickstart mode (iOS/string)

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, an lwt message will be send.

_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
}
  • 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)
  • proxRelative distance to the beacon (iOS/integer)
    • 0 Proximity of the beacon could not be determined
    • 1 Beacon is in the immediate vicinity
    • 2 Beacon is relatively close to the user
    • 3 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":"waypoints"}
{"_type":"cmd","action":"setConfiguration","configuration":{"_type":"configuration",...}
{"_type":"cmd","action":"setWaypoints","waypoints":{"_type":"waypoints","waypoints":[...]}
{"_type":"cmd","action":"action","content":"Backend maintenance scheduled for tonight\n\nhttp://support.owntracks.org"}
{"_type":"cmd","action":"action","content":"<a href='http://support.owntracks.org'>Backend Maintenance tonight</a>"}
{"_type":"cmd","action":"action","url":"http://support.owntracks.org"}
  • action action to be performed by the device (iOS,Android/string)
  • action Inserts an additional Featured Content tab in the UI (iOS)
  • dump Triggers the publish of a configuration message (iOS)
  • reportSteps Triggers the report of a steps messages_(iOS)_
    • from Timestamp (iOS/epoch/optional)
    • to Timestamp (iOS/epoch/optional)
  • reportLocation Triggers the publish of a location messages (iOS,Android)
  • setWaypoints Imports (merge) and activates new waypoints (iOS,Android)
    • waypoints Array of waypoint 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 a waypoints message (iOS,Android)

Notes

  • If url for the action cmd message is specified, the URL is opened in a full screen web view within the app
  • If the optional extern boolean is true a click on the notification will launch an external browser instead
  • If url is not specified the text of the content element is displayed. Links embedded in the text are operational.
  • If the content consists of HTML, it is rendered
  • The Featured Content tab can be removed with an action cmd message without content and without url element
  • 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 invalid lat or lon (invalid means out of range number value e.g. -1000000, a string like "foo" will result in a 0 in app) the waypoint is deleted.

_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
}
  • 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.

{
    "_type": "waypoints",
    elements
}
  • _creator Identification of what created the array. Ignored by the apps (iOS,Android/string/optional)
  • waypoints Array of waypoint 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 dataelement. 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)