anil.recoil.org
Owntracks location tracking with MQTT and HTTPS (recorder) support
1# owntracks
2
3OCaml types and JSON codecs for OwnTracks MQTT location messages.
4
5## Overview
6
7[OwnTracks](https://owntracks.org/) is an open-source location tracking application that publishes GPS coordinates, accuracy, speed, battery, and other device state over MQTT. This library provides type-safe parsing and serialization of all OwnTracks message types.
8
9## Packages
10
11- **owntracks** - Core types and jsont codecs
12- **owntracks-cli** - Command-line tools for MQTT subscription and data export
13
14## Installation
15
16```
17opam install owntracks # Core library
18opam install owntracks-cli # CLI tools
19```
20
21## Usage
22
23### Decoding Messages
24
25```ocaml
26let json = {|{"_type":"location","lat":51.5,"lon":-0.1,"tst":1234567890}|} in
27match Jsont_bytesrw.decode_string Owntracks.Message.jsont json with
28| Ok (Location loc) ->
29 Printf.printf "Location: %.4f, %.4f\n"
30 (Owntracks.Location.lat loc)
31 (Owntracks.Location.lon loc)
32| Ok _ -> print_endline "Other message type"
33| Error e -> Printf.printf "Error: %s\n" e
34```
35
36## Message Types
37
38| Type | Description |
39|------|-------------|
40| Location | GPS coordinates, accuracy, speed, battery |
41| Transition | Region entry/exit events |
42| Waypoint | Monitored region definitions |
43| Card | User information for display |
44| LWT | Last Will and Testament (disconnect notification) |
45
46## Integration Modules
47
48- **Mqtt** - MQTT message parsing and topic helpers
49- **Recorder** - OwnTracks Recorder HTTP API parsing
50- **Geojson** - Convert locations to GeoJSON format
51
52## CLI Tools
53
54The `owntracks-cli` package provides:
55
56- Real-time MQTT monitoring
57- GeoJSON export
58- OwnTracks Recorder API queries
59
60## References
61
62- [OwnTracks JSON Format](https://owntracks.org/booklet/tech/json/)
63- [OwnTracks Recorder](https://owntracks.org/booklet/guide/recorder/)
64
65## License
66
67ISC