### Clone OwnTracks Quick Setup Repository

Source: https://owntracks.org/booklet/guide/quicksetup

Downloads the quicksetup installer script and its associated files from GitHub. Requires Git to be installed.

```shell
$ sudo apt install -y git    # not required on Ubuntu
$ git clone --depth=1 https://github.com/owntracks/quicksetup
$ cd quicksetup
```

--------------------------------

### OwnTracks Configuration File Example

Source: https://owntracks.org/booklet/guide/quicksetup

Example structure for the `configuration.yaml` file, showing how to define friends with their tid, username, and devicename.

```yaml
friends:
  - { tid: JJ, username: jane,   devicename: nokia }
  - { tid: ip, username: jip,    devicename: iPad }
  - { tid: j2, username: jjolie, devicename: Phone }
```

--------------------------------

### Execute OwnTracks Bootstrap Script

Source: https://owntracks.org/booklet/guide/quicksetup

Launches the main installation and configuration process for OwnTracks using the prepared configuration file. Requires sudo privileges.

```shell
$ sudo ./bootstrap.sh
```

--------------------------------

### Configure OwnTracks Settings

Source: https://owntracks.org/booklet/guide/quicksetup

Copies the example configuration file and opens it for editing. Key settings include DNS domain, email for Let's Encrypt, OpenCage API key, and friend details.

```shell
$ cp configuration.yaml.example configuration.yaml
$ nano configuration.yaml
```

--------------------------------

### Subscribe to OwnTracks MQTT Topics with mosquitto_sub

Source: https://owntracks.org/booklet/guide/quicksetup

Subscribes to all topics under 'owntracks/#' to monitor published location data from OwnTracks devices. Requires mosquitto clients to be installed.

```bash
$ mosquitto_sub -v -t 'owntracks/#\n'
```

--------------------------------

### Sample OwnTracks Configuration File (JSON)

Source: https://owntracks.org/booklet/features/remoteconfig

An example of a JSON configuration file used to initially set up an OwnTracks device or update its settings. This file can be imported directly into the app.

```json
{
  "_type": "configuration",
  "auth": true,
  "username": "jjolie",
  "password": "s1kr3t",
  "host": "mybroker.example.org",
  "port": 8883
}
```

--------------------------------

### Install Paho MQTT Python Client

Source: https://owntracks.org/booklet/tech/program

This snippet shows the commands to create a Python virtual environment, activate it, and install the Paho MQTT client library using pip.

```bash
$ python3 -mvenv venv
$ source venv/bin/activate
(venv) $ pip install paho-mqtt
```

--------------------------------

### Subscribe to All MQTT Topics

Source: https://owntracks.org/booklet/guide/quicksetup

Subscribe to all topics published by the MQTT broker to view the raw payloads. This helps in verifying that data is being received correctly.

```shell
$ mosquitto_sub -v -t '#'

```

--------------------------------

### Check Operating System with hostnamectl

Source: https://owntracks.org/booklet/guide/quicksetup

Verifies if the operating system is a supported version, such as Debian GNU/Linux 12 (bookworm).

```shell
$ hostnamectl
...
Operating System: Debian GNU/Linux 12 (bookworm)
...
```

--------------------------------

### Display System Information

Source: https://owntracks.org/booklet/guide/quicksetup

View the contents of the `sys.info` file, which contains details about the last bootstrap, Ansible version, and OS distribution. Helpful for environment-specific debugging.

```shell
$ cat sys.info

```

--------------------------------

### GET /locations

Source: https://owntracks.org/booklet/guide/quicksetup

Retrieves location data for a specified user and device. This endpoint allows fetching historical location records, which can be filtered and displayed.

```APIDOC
## GET /locations

### Description
Retrieves location data for a specified user and device. This endpoint allows fetching historical location records, which can be filtered and displayed.

### Method
GET

### Endpoint
`/owntracks/api/0/locations`

### Parameters
#### Query Parameters
- **user** (string) - Required - The username for authentication.
- **device** (string) - Required - The device name to retrieve data for.

### Request Example
```
curl -u jane -sSf 'https://owntracks.example/owntracks/api/0/locations' \
     -d user=jane -d device=nokia
```

### Response
#### Success Response (200)
- **count** (integer) - The number of locations returned.
- **data** (array) - An array of location objects.
  - **_type** (string) - The type of data, e.g., "location".
  - **SSID** (string) - The Wi-Fi network name.
  - **alt** (integer) - Altitude in meters.
  - **batt** (integer) - Battery level.
  - **conn** (string) - Connection type (e.g., "w" for Wi-Fi).
  - **lat** (float) - Latitude coordinate.
  - **lon** (float) - Longitude coordinate.
  - **tid** (string) - Tracker ID.
  - **tst** (integer) - Timestamp of the location data.
  - **vel** (integer) - Velocity in m/s.
  - **ghash** (string) - Geohash of the location.
  - **cc** (string) - Country code.
  - **addr** (string) - Formatted address of the location.
  - **locality** (string) - City or locality name.
  - **isorcv** (string) - ISO 8601 timestamp of when the data was received.
  - **isotst** (string) - ISO 8601 timestamp of the location.
  - **disptst** (string) - Display-formatted timestamp.
- **status** (integer) - The HTTP status code of the response.

#### Response Example
```json
{
  "count": 1,
  "data": [
    {
      "_type": "location",
      "SSID": "mywifi",
      "alt": 154,
      "batt": 53,
      "conn": "w",
      "lat": 48.856826,
      "lon": 2.292713,
      "tid": "j1",
      "tst": 1706858149,
      "vel": 0,
      "ghash": "u09tunj",
      "cc": "FR",
      "addr": "11 Av de Suffren, 75007 Paris, France",
      "locality": "Paris",
      "isorcv": "2024-02-02T07:15:49Z",
      "isotst": "2024-02-02T07:15:49Z",
      "disptst": "2024-02-02 07:15:49"
    }
  ],
  "status": 200
}
```
```

--------------------------------

### OwnTracks Waypoint MQTT Publish Example

Source: https://owntracks.org/booklet/guide/waypoints

This example illustrates the MQTT topic and payload format for publishing waypoint information from OwnTracks devices. It shows how the topic is constructed and the expected JSON payload structure.

```MQTT
Topic: owntracks/<user>/<device>/waypoint
Payload: {"_type": "waypoint", "desc": "Waypoint Description", "lat": 37.7749, "lon": -122.4194, "rad": 100, "tst": 1678886400}
```

--------------------------------

### Ansible Playbook Execution Output

Source: https://owntracks.org/booklet/guide/quicksetup

Sample output from the Ansible playbook execution during the OwnTracks bootstrap process, showing task status such as 'ok', 'changed', and 'failed'.

```text
PLAY [OwnTracks Quick Setup] ********************************************************

TASK [Gathering Facts] **************************************************************
ok: [localhost]

TASK [system: template out sys.info] ************************************************
changed: [localhost]

TASK [verify some requirements] *****************************************************
ok: [localhost] => {
    "changed": false,
    "msg": "All assertions passed"
}

TASK [detect: acme] *****************************************************************
ok: [localhost]

TASK [system: install OwnTracks repository key] *************************************
changed: [localhost]

TASK [system: install OwnTracks repository] *****************************************
changed: [localhost]

TASK [system: install required packages]
...

```

--------------------------------

### Check Service Status

Source: https://owntracks.org/booklet/guide/quicksetup

Verify if the OwnTracks recorder, MQTT broker, and Nginx services are running. This is a fundamental step in diagnosing issues.

```shell
$ systemctl status ot-recorder
$ systemctl status mosquitto
$ systemctl status nginx

```

--------------------------------

### iBeacon Configuration Examples

Source: https://owntracks.org/booklet/features/beacons

These examples demonstrate how to configure OwnTracks to monitor either all beacons with a specific UUID or a single specific beacon using UUID, major, and minor identifiers.

```text
Name  myBeacons
UUID  CA271EAE-5FA8-4E80-8F08-2A302A95A959
Major 0
Minor 0

Name  mySpecificBeacon
UUID  CA271EAE-5FA8-4E80-8F08-2A302A95A959
Major 1
Minor 33000
```

--------------------------------

### Test DNS domain association

Source: https://owntracks.org/booklet/guide/quicksetup

Verifies that the chosen DNS domain correctly resolves to the VPS's IP address. This is crucial for external accessibility and is tested using the 'ping' command.

```shell
$ ping owntracks.example
...

```

--------------------------------

### HTML Link for URL Configuration

Source: https://owntracks.org/booklet/features/remoteconfig

An HTML snippet demonstrating how to create a clickable link that uses the base64-encoded configuration URL to configure the OwnTracks app.

```html
<html><body><p>
<a href="@@">Click to configure OwnTracks</a>
</p></body></html>
```

--------------------------------

### Monitor Mosquitto MQTT Broker Logs

Source: https://owntracks.org/booklet/guide/quicksetup

Stream the log file for the Mosquitto MQTT broker to observe incoming requests and connection information. Useful for tracking message flow.

```shell
$ tail -f /var/log/mosquitto/mosquitto.log

```

--------------------------------

### Query OwnTracks Data with ocat and jq

Source: https://owntracks.org/booklet/guide/quicksetup

Retrieves and formats location data for a specific user and device using the 'ocat' utility, piped to 'jq' for pretty-printing. Demonstrates data enrichment like timezone and address lookup.

```bash
$ ocat --user jane --device nokia | jq\n{\n  \"count\": 1,\n  \"locations\": [\n    {\n      \"_type\": \"location\",\n      \"SSID\": \"mywifi\",\n      \"alt\": 154,\n      \"batt\": 53,\n      \"conn\": \"w\",\n      \"lat\": 48.856826,\n      \"lon\": 2.292713,\n      \"tid\": \"j1\",\n      \"tst\": 1706858149,\n      \"vel\": 0,\n      \"ghash\": \"u09tunj\",\n      \"cc\": \"FR\",\n      \"addr\": \"11 Av de Suffren, 75007 Paris, France\",\n      \"locality\": \"Paris\",\n      \"tzname\": \"Europe/Paris\",\n      \"isorcv\": \"2024-02-02T07:15:49Z\",\n      \"isotst\": \"2024-02-02T07:15:49Z\",\n      \"isolocal\": \"2024-02-02T08:15:49+0100\"\n      \"disptst\": \"2024-02-02 07:15:49\"\n    }\n  ]\n}
```

--------------------------------

### View OwnTracks Recorder Diagnostics

Source: https://owntracks.org/booklet/guide/quicksetup

Access the diagnostics output from the OwnTracks Recorder using journalctl or by tailing the syslog. This provides insights into the recorder's internal operations.

```shell
$ journalctl -u ot-recorder -f
$ tail -f /var/log/syslog | grep ot-recorder

```

--------------------------------

### OwnTracks iBeacon QR URI Example

Source: https://owntracks.org/booklet/tech/qr

An example of a URI that can be encoded into a QR code for configuring an OwnTracks iBeacon. It includes parameters for the unique identifier (rid), name, UUID, major, and minor version numbers.

```uri
owntracks:///beacon?rid=ac3def&name=MyBeacon&uuid=12345678-1234-1234-1234-123456789A&major=2&minor=1
```

--------------------------------

### Verify root privileges

Source: https://owntracks.org/booklet/guide/quicksetup

Checks if the current user has root privileges by displaying user ID and group information. This is a preliminary step to ensure necessary permissions for subsequent commands.

```shell
$ sudo id
uid=0(root) gid=0(root) groups=0(root)
```

--------------------------------

### View OwnTracks Location Data Format

Source: https://owntracks.org/booklet/guide/quicksetup

Displays the JSON structure of location data published by an OwnTracks device, including coordinates, timestamps, and device information.

```json
{\n  "_type": "location",\n  "SSID": "mywifi",\n  "alt": 154,\n  "batt": 53,\n  "conn": "w",\n  "created_at": 1706858149,\n  "lat": 48.856826,\n  "lon": 2.292713,\n  "tid": "j1",\n  "tst": 1706858149,\n  "vel": 0\n}
```

--------------------------------

### Define Friend-Specific MQTT ACLs (Shell)

Source: https://owntracks.org/booklet/features/qs-config

Provides an example of creating a user-specific MQTT Access Control List (ACL) file for a friend named 'anouk'. This file defines read/write permissions for specific topics.

```shell
$ cat acl/anouk.acl
user anouk
topic readwrite owntracks/anouk/#
topic read owntracks/jane/nokia
topic read owntracks/jane/+/event
topic read owntracks/jane/+/info

```

--------------------------------

### Configure OTR_HTTPPREFIX (Shell)

Source: https://owntracks.org/booklet/features/tours

Example shell commands to set the OTR_HTTPPREFIX environment variable, which is crucial for constructing the public URL for generated tours.

```shell
export OTR_HTTPPREFIX="https://example.net/owntracks"
```

```shell
export OTR_HTTPPREFIX="http://localhost:8085"
```

--------------------------------

### Verify OwnTracks Recorder Data with tail

Source: https://owntracks.org/booklet/guide/quicksetup

Checks the latest entries in the OwnTracks recorder's store file to ensure location data is being saved correctly. The path includes user and device names, and a date stamp.

```bash
$ tail /var/spool/owntracks/recorder/store/rec/jane/nokia/2024-02.rec\n2024-02-02T07:15:49Z    *                   {\"_type\":\"location\",\"SSID\":\"mywifi\",\"alt\":154,\"batt\":53,\"conn\":\"w\",\"lat\":48.856826,\"lon\":2.292713,\"tid\":\"j1\",\"tst\":1706858149,\"vel\":0}\n
```

--------------------------------

### Traccar API Response Example

Source: https://owntracks.org/booklet/features/traccar

Example of a Traccar API response showing position data received from an OwnTracks client.

```APIDOC
## Traccar API Position Data

### Description
An example of the JSON structure returned by the Traccar API when querying device positions, which may include attributes derived from OwnTracks payloads.

### Method
GET

### Endpoint
`/api/positions` (Example endpoint for retrieving positions)

### Parameters
N/A for this example response structure.

### Request Example
N/A

### Response
#### Success Response (200)
- **id** (number) - Unique identifier for the position record.
- **attributes** (object) - Additional attributes from the payload (e.g., battery, tid, ip).
- **deviceId** (number) - The ID of the device associated with the position.
- **type** (string) - Type of the record (often null for OwnTracks).
- **protocol** (string) - The protocol used (e.g., 'owntracks').
- **serverTime** (string) - Timestamp when Traccar processed the data.
- **deviceTime** (string) - Timestamp from the device.
- **fixTime** (string) - Timestamp of the location fix.
- **outdated** (boolean) - Whether the data is considered outdated.
- **valid** (boolean) - Whether the location data is valid.
- **latitude** (number) - Latitude.
- **longitude** (number) - Longitude.
- **altitude** (number) - Altitude.
- **speed** (number) - Speed.
- **course** (number) - Course over ground.
- **address** (string) - Geocoded address.
- **accuracy** (number) - Accuracy of the fix.
- **network** (object) - Network information (often null).

#### Response Example
```json
[
  {
    "id": 475,
    "attributes": {
      "t": "u",
      "battery": 41,
      "tid": "JJ",
      "ip": "127.0.0.1",
      "distance": 0,
      "totalDistance": 0
    },
    "deviceId": 4,
    "type": null,
    "protocol": "owntracks",
    "serverTime": "2017-06-15T06:37:32.000+0000",
    "deviceTime": "2017-06-15T06:37:31.000+0000",
    "fixTime": "2017-06-15T06:37:31.000+0000",
    "outdated": false,
    "valid": true,
    "latitude": 48.85833,
    "longitude": 2.29513,
    "altitude": 167,
    "speed": 1.18575,
    "course": 271,
    "address": "9 Avenue Anatole France, Paris, Île-de-France, FR",
    "accuracy": 5,
    "network": null
  }
]
```

```

--------------------------------

### Configure Recorder Lua Script Path (YAML)

Source: https://owntracks.org/booklet/features/qs-config

Explains how to configure the path to a Recorder Lua script using the `lua_script` option in the configuration. This script is written to `/etc/defaults/ot-recorder` and used for the next Recorder start.

```yaml
lua_script: "/path/to/your/recorder.lua"

```

--------------------------------

### Inspect Recorder Data Store

Source: https://owntracks.org/booklet/guide/quicksetup

Check the latest recorded location data for a specific user and device. This confirms that location updates are being saved by the recorder.

```shell
$ tail /var/spool/owntracks/recorder/store/jane/nokia/YYYY-MM.rec

```

--------------------------------

### Access OwnTracks Recorder API with curl

Source: https://owntracks.org/booklet/guide/quicksetup

Retrieves location data from the OwnTracks Recorder API using curl, requiring basic authentication with username and password. Shows data including enriched location details.

```bash
$ curl -u jane -sSf 'https://owntracks.example/owntracks/api/0/locations' \n     -d user=jane -d device=nokia\nEnter host password for user 'jane':\n{\"count\":1,\"data\":[{\"_type\":\"location\",\"SSID\":\"mywifi\",\"alt\":154,\"batt\":53,\"conn\":\"w\",\"lat\":48.856826,\"lon\":2.292713,\"tid\":\"j1\",\"tst\":1706858149,\"vel\":0,\"ghash\":\"u09tunj\",\"cc\":\"FR\",\"addr\":\"11 Av de Suffren, 75007 Paris, France\",\"locality\":\"Paris\",\"isorcv\":\"2024-02-02T07:15:49Z\",\"isotst\":\"2024-02-02T07:15:49Z\",\"disptst\":\"2024-02-02 07:15:49\"}],\"status\":200}
```

--------------------------------

### Base64 Encode OwnTracks Configuration for URL

Source: https://owntracks.org/booklet/features/remoteconfig

This command uses openssl to base64 encode the content of an OwnTracks configuration file, preparing it for inclusion in a URL for app configuration.

```bash
echo "owntracks:///config?inline=$(openssl enc -a -A -in j.otrc)"
```

--------------------------------

### Mosquitto Publish Log Entry Example

Source: https://owntracks.org/booklet/guide/broker

This snippet demonstrates a typical log entry from the Mosquitto broker indicating a successful publish of an OwnTracks location. It shows the sequence of messages exchanged for a quality of service level 2 publish.

```bash
mosquitto[1366]: Received PUBLISH from jane-5s-m-o (d0, q2, r1, m7, 'owntracks/jane/5s', ... (159 bytes))
mosquitto[1366]: Sending PUBREC to jane-5s-m-o (Mid: 7)
mosquitto[1366]: Received PUBREL from jane-5s-m-o (Mid: 7)
mosquitto[1366]: Sending PUBCOMP to jane-5s-m-o (Mid: 7)
```

--------------------------------

### Mosquitto TLS Configuration Example

Source: https://owntracks.org/booklet/features/tls

Shows how to configure the Mosquitto broker for TLS connections. It specifies the listener port, the CA certificate bundle, the server's certificate file, and the server's private key file.

```ini
listener 8883
cafile ca-bundle.crt
certfile server.crt
keyfile server.key

```

--------------------------------

### Traccar Server Connection URL for OwnTracks

Source: https://owntracks.org/booklet/features/traccar

An example URL format for OwnTracks clients to connect to the Traccar server. It includes the hostname and the configured port.

```http
http://traccar.example.net:5144
```

--------------------------------

### PEM Encoded Certificate Example

Source: https://owntracks.org/booklet/features/tls

Demonstrates the typical structure of a PEM-encoded X.509 certificate, including BEGIN/END markers and base64 encoded data. This format is commonly used for TLS/SSL communication.

```text
-----BEGIN CERTIFICATE-----
MIIDGTCCAoKgAwIBAgIJAODXne2yV51zMA0GCSqGSIb3DQEBBQUAMGcxCzAJBgNV
BAYTAkRFMQwwCgYDVQQIEwNOUlcxETAPBgNVBAcTCElyZ2VuZHdvMRYwFAYDVQQK
...
pjGM/XgBs62UhqXnoHrHh/AHIiHieuNFwOhUg0fD/vQ5O6UZkJTWY5LLmEyPN5sS
cPZ5pT/WCvGuIOgNdy1VyWJrrlAjeQlbK+GDcNc=
-----END CERTIFICATE-----
```

--------------------------------

### OwnTracks Client HTTP Mode Configuration

Source: https://owntracks.org/booklet/features/traccar

Example of how to configure an OwnTracks client to connect to a Traccar server in HTTP mode.

```APIDOC
## OwnTracks Client Configuration

### Description
Configure an OwnTracks client to connect to your Traccar server via HTTP.

### Method
Client Configuration

### Endpoint
N/A (Client Configuration)

### Parameters
#### Client Configuration Parameters
- **Server URL** (string) - Required - The URL of the Traccar server, including the port configured for OwnTracks.
- **Identifier** (string) - Required - The identifier used by OwnTracks to match with Traccar. This can be `tid` or `topic`.

### Request Example
```
http://traccar.example.net:5144
```

### Response
N/A (Client Configuration)

```

--------------------------------

### Store Encryption Secret in a File

Source: https://owntracks.org/booklet/features/encrypt

This example demonstrates storing the encryption secret in a separate file. The path to this file is then used in the quicksetup configuration, enhancing security by not embedding the secret directly in the main config.

```shell
$ printf "mysecreTpass01" > .jjolie.key
```

--------------------------------

### Example Card JSON Payload

Source: https://owntracks.org/booklet/features/card

A sample JSON payload representing a card, including the type, a full name, and an encoded image (face). This is typically published as a retained message.

```json
{
  "_type": "card",
  "name": "Jane Jolie",
  "face": "iV1CFEVkMhmCIKBUKh3 ... ghAAAAABJRU5ErkJggg=="
}
```

--------------------------------

### OwnTracks Lua Script Example for File Writing

Source: https://owntracks.org/booklet/tech/lua

A basic Lua script that demonstrates how to initialize a file for writing, log messages using `otr.log`, format timestamps with `otr.strftime`, and write location data to a file on each publish event. It requires the Recorder to be compiled with Lua support.

```lua
local file

function otr_init()
    otr.log("example.lua starting; writing to /tmp/lua.out")
    file = io.open("/tmp/lua.out", "a")
    file:write("written by OwnTracks Recorder version " .. otr.version .. "\n")
end

function otr_hook(topic, _type, data)
    local timestr = otr.strftime("It is %T in the year %Y", 0)
    print("L: " .. topic .. " -> " .. _type)
    file:write(timestr .. " " .. topic .. " lat=" .. data['lat'] .. data['addr'] .. "\n")
end

function otr_exit()
end

```

--------------------------------

### ACL for Publishing Tour Data (MQTT)

Source: https://owntracks.org/booklet/features/tours

An example Access Control List (ACL) configuration required for the MQTT broker to allow the OwnTracks Recorder to publish tour data.

```mqtt
topic write owntracks/+/+/cmd
```

--------------------------------

### Distinguishing OwnTracks HTTP Payloads with Headers

Source: https://owntracks.org/booklet/tech/http

This example shows the HTTP headers used by OwnTracks apps to identify the user and device when sending data via HTTP. These headers are crucial for backend systems to correctly attribute incoming data.

```http
Content-Type: application/json
X-Limit-U: jjolie
X-Limit-D: myphone
```

--------------------------------

### AWS IoT Basic Policy Configuration (JSON)

Source: https://owntracks.org/booklet/tech/mqtt

A basic IAM policy for AWS IoT that grants all actions for a specific 'thing'. This is often used as a starting point for device permissions.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:*",
      "Resource": "*"
    }
  ]
}
```

--------------------------------

### Python Script for Daily Step Reports

Source: https://owntracks.org/booklet/features/pedometer

A Python script to generate the JSON command payload for requesting daily step reports from OwnTracks. It calculates the Unix epoch timestamps for the start and end of the day.

```python
#!/usr/bin/env python

import datetime
import time
import json
import sys

days = 0

def unix_epoch(t, delta):
    dt = t + delta

    # print dt
    return int(time.mktime(dt.timetuple()))

now = datetime.datetime.today()

f = now.replace(now.year, now.month, now.day, 0, 0, 1, 0)
t = now.replace(now.year, now.month, now.day, 23, 59, 59, 0)

delta = datetime.timedelta(days=days)


payload = {
        '_type' : 'cmd',
        'action' : 'reportSteps',
        'from'  : unix_epoch(f, delta),
        'to'    : unix_epoch(t, delta),
}
print json.dumps(payload)

```

--------------------------------

### OwnTracks Waypoint Configuration JSON Example

Source: https://owntracks.org/booklet/features/waypoints

This JSON payload is published to a specific topic (e.g., owntracks/<user>/<device>/waypoint) when a region is configured or updated on an OwnTracks device. It contains the region's description, coordinates, radius, and a unique region ID.

```json
{
    "_type": "waypoint",
    "desc": "My favorite coffee shop (Delaville)",
    "lat": 48.87069,
    "lon": 2.34916,
    "rad": "50",
    "tst": "1385997757",
    "rid": "f7676c",
    "wtst": 1610104395
}
```

--------------------------------

### Test HTTP Endpoint with cURL

Source: https://owntracks.org/booklet/tech/http

This shell script demonstrates how to test an HTTP endpoint by sending a POST request with a JSON payload simulating data from an OwnTracks app. It uses `jo` to create the JSON payload and `curl` to send it to a specified URL. Ensure `jo` and `curl` are installed.

```sh
#!/bin/sh

user=jane
device=phone

payload=$(jo _type=location \
   t=u \
   batt=11 \
   lat=48.856826 \
   lon=2.292713 \
   tid=JJ \
   tst=$(date +%s) \
   topic="owntracks/$user/$device")

curl --data "${payload}" http://127.0.0.1:8085/pub?u=${user}&d=${device}
```

--------------------------------

### OwnTracks Transition Event JSON Example

Source: https://owntracks.org/booklet/features/waypoints

This JSON object represents a transition event published by the OwnTracks app when a device enters or leaves a configured region. It includes details such as the region description, event type (enter/leave), region ID, location, tracker ID, and timestamps.

```json
{
      "_type": "transition",
      "desc": "My favorite coffee shop (Delaville)",
      "event": "enter",
      "lat": 48.87069,
      "lon": 2.34916,
      "rid": "f7676c",
      "tid": "j1",
      "tst": 1707057574,
      "wtst": 1610104395
}
```

--------------------------------

### Publish MQTT Messages with Specific User

Source: https://owntracks.org/booklet/features/qs-extra

Demonstrates how to publish MQTT messages using the `mosquitto_pub` command with a specific user (`_lr`) and password retrieved from a file. This is useful for clearing or managing other users' OwnTracks topics.

```shell
$ mosquitto_pub -u _lr -P "$(cat /usr/local/owntracks/userdata/.lr.pw)" ...
```

--------------------------------

### Creating Card with github2card.py and Publishing via mosquitto_pub

Source: https://owntracks.org/booklet/features/card

Demonstrates creating a card using the `github2card.py` script and then publishing it as a retained message to an MQTT broker using `mosquitto_pub`. It highlights the topic structure and the use of retain and QoS flags.

```bash
./github2card.py defunkt > my-card.json
mosquitto_pub -t owntracks/jjolie/phone/info -f my-card.json -r -q 2
```

--------------------------------

### OwnTracks Step Data Payload

Source: https://owntracks.org/booklet/features/pedometer

Example JSON payload received from OwnTracks after a request, containing the number of steps counted within a specified time frame.

```json
{
    "_type": "steps", 
    "from": 1400455130, 
    "steps": 1234, 
    "to": 1400458000, 
    "tst": 1400455130
}

```

--------------------------------

### Configure Friend Waypoints (YAML)

Source: https://owntracks.org/booklet/features/qs-config

Demonstrates defining waypoints for a friend using a YAML file. This format is presented as a more convenient alternative to JSON for editing.

```yaml
- _type: waypoint
  desc: "Delaville Café"
  rid: delaville-cafe
  tst: 1708879121
  rad: 70
  lat: 48.870737
  lon: 2.3491583

```

--------------------------------

### Comprehensive OwnTracks HTTP Payload with Attributes

Source: https://owntracks.org/booklet/features/traccar

An example of a detailed HTTP POST payload from an OwnTracks app, including various sensor and device attributes that Traccar can store.

```json
{
  "cog": 271,
  "batt": 41,
  "lon": 2.29513,
  "acc": 5,
  "vel": 61,
  "vac": 21,
  "lat": 48.85833,
  "t": "u",
  "tst": 1497508651,
  "alt": 167,
  "_type": "location",
  "topic": "owntracks/jane/iphone",
  "p": 71,
  "tid": "JJ"
}
```

--------------------------------

### Configure Friends List in configuration.yaml (YAML)

Source: https://owntracks.org/booklet/features/qs-config

Defines the syntax for adding friends to the OwnTracks configuration file (`configuration.yaml`). It shows how to specify friend details like `tid`, `username`, and `devicename` in a YAML array format.

```yaml
friends:
  - { tid: JJ, username: jane,   devicename: nokia }

```

```yaml
friends:
  - tid: JJ
    username: jane
    devicename: nokia

```

```yaml
friends:
  - tid: JJ
    username: jane
    devicename: nokia
  - tid: m1
    username: another
    ...

```

--------------------------------

### Configure Friend Payload Encryption (YAML)

Source: https://owntracks.org/booklet/features/qs-config

Shows how to configure payload encryption for a specific friend using either a direct secret string or a path to a file containing the secret.

```yaml
secret: "bla009"

```

```yaml
secret: "/home/jane/.secret"

```

--------------------------------

### Remote Waypoint Configuration (JSON)

Source: https://owntracks.org/booklet/features/remoteconfig

A JSON payload structure used to remotely configure or modify waypoints on an OwnTracks device via MQTT. This payload can also be used for beacon configurations.

```json
{
  "_type": "cmd",
  "action": "setWaypoints",
  "waypoints": {
    "waypoints": [
      {
        "desc": "Some place",
        "rad": 8867,
        "lon": 10.428771973,
        "lat": 46.935260881,
        "tst": 1437552714,
        "_type": "waypoint"
      }
    ],
    "_type": "waypoints"
  }
}
```

--------------------------------

### Configure Friend Waypoints (JSON)

Source: https://owntracks.org/booklet/features/qs-config

Shows how to define waypoints (geofences) for a specific friend ('anouk') using a JSON file. Each waypoint object includes details like type, timestamp, ID, description, radius, latitude, and longitude.

```json
[
  {
    "_type": "waypoint",
    "tst": 1361636517,
    "rid": "blauw-utrecht-nl",
    "desc": "Restaurant Blauw",
    "rad": 50,
    "lat": 52.08782,
    "lon": 5.119438
  }
]

```

--------------------------------

### Traccar API Response for OwnTracks Data

Source: https://owntracks.org/booklet/features/traccar

An example of the JSON response from the Traccar API when querying for position data sent by an OwnTracks client. It shows parsed attributes and standard position fields.

```json
[
  {
    "id": 475,
    "attributes": {
      "t": "u",
      "battery": 41,
      "tid": "JJ",
      "ip": "127.0.0.1",
      "distance": 0,
      "totalDistance": 0
    },
    "deviceId": 4,
    "type": null,
    "protocol": "owntracks",
    "serverTime": "2017-06-15T06:37:32.000+0000",
    "deviceTime": "2017-06-15T06:37:31.000+0000",
    "fixTime": "2017-06-15T06:37:31.000+0000",
    "outdated": false,
    "valid": true,
    "latitude": 48.85833,
    "longitude": 2.29513,
    "altitude": 167,
    "speed": 1.18575,
    "course": 271,
    "address": "9 Avenue Anatole France, Paris, Île-de-France, FR",
    "accuracy": 5,
    "network": null
  }
]
```

--------------------------------

### Publish OwnTracks JSON Payload with mosquitto_pub

Source: https://owntracks.org/booklet/tech/program

This shell script demonstrates how to publish a simulated OwnTracks location update to an MQTT broker using `mosquitto_pub`. It uses the `jo` utility to create a JSON payload and then pipes it to `mosquitto_pub`.

```bash
#!/bin/sh

jo _type=location \
    lat=48.856826 \
    lon=2.292713 \
    tid=j1 \
    tst=$(date +%s) | \
    mosquitto_pub -r -t owntracks/jane/nokia -l

```

--------------------------------

### Generate Client Certificate and Key

Source: https://owntracks.org/booklet/features/tlscert

Generates a client certificate and key using a provided script. This produces `.key` and `.crt` files required for OwnTracks devices.

```bash
./generate-CA.sh client jjolie
```

--------------------------------

### Configuration Parameters for OwnTracks

Source: https://owntracks.org/booklet/guide/topics

These are key configuration parameters within OwnTracks that define how it interacts with MQTT. 'pubTopicBase' sets the base for publishing topics, and 'subTopic' likely relates to subscription topics.

```ini
pubTopicBase
subTopic
```

--------------------------------

### OwnTracks MQTT Topics - Publish

Source: https://owntracks.org/booklet/tech/json

Describes the MQTT topics to which OwnTracks apps publish data, including location updates, commands, events, and more.

```APIDOC
## MQTT Topics - Publish

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
* `owntracks/user/device/status` for status messages
* `owntracks/user/device/waypoint` when a geofence is created on the device
* `owntracks/user/device/waypoints` (plural) when exporting a list of configured waypoints from device to backend
```

--------------------------------

### Set Friend-Specific Password (YAML)

Source: https://owntracks.org/booklet/features/qs-config

Demonstrates how to set a specific password for a friend in the `configuration.yaml` file. This overrides auto-generated passwords.

```yaml
password: "supersecr1t"

```

--------------------------------

### Request a New Tour (JSON)

Source: https://owntracks.org/booklet/features/tours

This JSON payload is sent to the OwnTracks Recorder to request the creation of a new location sharing 'Tour'. It includes a label and the desired start and end times for the tour.

```json
{
  "_type": "request",
  "request": "tour",
  "tour": {
    "label": "Meeting with C. in Essen",
    "from": "2022-08-01T05:35:58",
    "to": "2022-08-02T15:00:58"
  }
}
```

--------------------------------

### Publishing Waypoints via MQTT

Source: https://owntracks.org/booklet/features/waypoints

This command publishes a JSON payload containing waypoint configurations to an MQTT broker. It uses `jq` to format the JSON and `mosquitto_pub` to send it to a specified topic with authentication. The `-q 1` sets the quality of service level, and `-l` ensures lines are sent as separate messages.

```bash
$ jq -c . wp.json |
      mosquitto_pub -u username -P 'password' -t owntracks/jane/nokia/cmd -q 1 -l
```

--------------------------------

### Steps Data (_type=steps)

Source: https://owntracks.org/booklet/tech/json

Contains information about steps walked by the user. Includes the timestamp of the measurement, the number of steps, and the effective start and end times for the period. The 'steps' field will be -1 if the device does not support step counting or if the time period is invalid.

```json
{
    "_type":"steps",
    "elements"
}
```

--------------------------------

### OwnTracks MQTT Publish Topics

Source: https://owntracks.org/booklet/tech/json

This snippet outlines the MQTT topics used by OwnTracks apps to publish different types of data. It includes topics for location updates, commands, events, step counting, beacon ranging, configuration dumps, status messages, and waypoints.

```mqtt
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
owntracks/user/device/status for status messages
owntracks/user/device/waypoint when a geofence is created on the device
owntracks/user/device/waypoints (plural) when exporting a list of configured waypoints from device to backend
```

--------------------------------

### Generate iBeacon QR Code with qrencode

Source: https://owntracks.org/booklet/tech/qr

This command uses the qrencode utility to generate a PNG image of a QR code for an OwnTracks iBeacon configuration. It specifies error correction level (H), version (10), resolution (300 DPI), output file (mybeacon.png), and the iBeacon configuration URI.

```shell
qrencode -l H -v 10 -d 300 -o mybeacon.png 'owntracks:///beacon?rid=ac3def&name=MyBeacon&uuid=12345678-1234-1234-1234-123456789A&major=2&minor=1'
```

--------------------------------

### Macrodroid: Trigger OwnTracks Move Mode

Source: https://owntracks.org/booklet/features/android

This example demonstrates setting the OwnTracks monitoring mode to 'Move' using Macrodroid. It involves creating a 'Send Intent' action with the correct package, action, and extra parameters for the monitoring mode.

```text
Target: Service
Action: org.owntracks.android.CHANGE_MONITORING
Package: org.owntracks.android
Class: [LEAVE FIELD BLANK]
Mime Type: [LEAVE FIELD BLANK]
Data: [LEAVE FIELD BLANK]
Extra 1 parameter name: monitoring
Extra 1 value: 2
Extra(2): [LEAVE FIELD BLANK]
Extra(3): [LEAVE FIELD BLANK]
Extra(4): [LEAVE FIELD BLANK]
```

--------------------------------

### Configure Friend HTTP Mode (YAML)

Source: https://owntracks.org/booklet/features/qs-config

Illustrates how to set `httpmode` to `True` for a specific friend in `configuration.yaml` to change data transfer from MQTT to HTTP for that friend.

```yaml
httpmode: True

```

--------------------------------

### Mosquitto Broker TLS Configuration

Source: https://owntracks.org/booklet/features/tls

This snippet shows the essential configuration directives for enabling TLS on the Mosquitto MQTT broker. It specifies the port, CA certificate file, server certificate file, and the server's private key file. Ensure these paths are correct and the key file is kept secret.

```ini
listener 8883
cafile .xe2x80xa6
certfile .xe2x80xa6
keyfile .xe2x80xa6
```

--------------------------------

### OwnTracks MQTT Topics - Subscribe

Source: https://owntracks.org/booklet/tech/json

Details the MQTT topics to which OwnTracks apps subscribe for receiving commands, viewing other users' locations, and handling events.

```APIDOC
## MQTT Topics - Subscribe

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.
```

--------------------------------

### Automagic: Trigger OwnTracks Move Mode

Source: https://owntracks.org/booklet/features/android

This snippet illustrates how to use Automagic to set the OwnTracks monitoring mode to 'Move'. It requires a 'Start Service' action with specific intent details, including the package name and an extra integer value for monitoring.

```text
Action: org.owntracks.android.CHANGE_MONITORING
Category List: [LEAVE FIELD BLANK]
Data URI: [LEAVE FIELD BLANK]
Data MIME Type: [LEAVE FIELD BLANK]
Explicit Component: ticked
Package Name: org.owntracks.android
Class Name: [LEAVE FIELD BLANK]
Flag List: [LEAVE FIELD BLANK]
Extra: putInt("MONITORING": 2)
```

--------------------------------

### Losant IoT MQTT Connection Configuration (JSON)

Source: https://owntracks.org/booklet/tech/mqtt

Configuration settings for connecting OwnTracks to the Losant IoT Developer Platform via MQTT. This includes connection details, authentication credentials, and protocol settings.

```json
{
    "_type": "configuration",
    "mode":0,
    "mqttProtocolLevel": 4,
    "host":"broker.losant.com",
    "port":8883,
    "tls":true,
    "pubRetain": false,
    "pubQos": 0,
    "subQos":0,
    "cleanSession": true,
    "clientId":"CLIENT_ID",
    "auth":true,
    "username":"ACCESS_KEY",
    "password":"ACCESS_SECRET"
}
```

--------------------------------

### Command Topic for OwnTracks Devices

Source: https://owntracks.org/booklet/guide/topics

This shows the structure of a topic used to send commands to OwnTracks devices. It appends '/cmd' to the base topic name, allowing for remote control functionalities.

```mqtt
owntracks/peter/iPhone/cmd
```

--------------------------------

### OpenHAB Item for Yesterday's Steps

Source: https://owntracks.org/booklet/features/pedometer

Defines an OpenHAB item to display the number of steps from the previous day. It subscribes to the MQTT topic and uses JSONPATH to extract the 'steps' value.

```items
Number Steps_Yesterday "[%d]"  { mqtt="<[mqtt:owntracks/jj/5s/step:state:JSONPATH($.steps)]" }

```