From 8e6ecb3f415ed1f35bbfc41a806e9b6349cb0773 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Thu, 8 Dec 2016 18:37:44 +0100 Subject: [PATCH] elaborate --- doc/FENCES.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/doc/FENCES.md b/doc/FENCES.md index b73c1aa..95dff1b 100644 --- a/doc/FENCES.md +++ b/doc/FENCES.md @@ -1,10 +1,12 @@ ## Geo fences -Since a version > 0.6.9, Recorder has support for Geofences (irrespective of their use on the OwnTracks devices). In particular, Recorder can read a list of fences from `.otrw` files, and it will monitor a user's position to determine whether the user is transitioning in to or out of a fence, in which case Recorder will invoke a Lua hook (called `transition`). +Since version > 0.6.9, Recorder has compiled-in support for Geofences irrespective of their use on the OwnTracks devices. (What we mean by this is that OwnTracks iOS/Android apps do native geofences, but if you have some device which just publishes its location in OwnTracks JSON format, you can now process geofences for it with the Recorder.) + +In particular, Recorder can read a list of fences from `.otrw` files, and it will monitor a user's position to determine whether the user is transitioning in to or out of a fence, in which case Recorder will invoke a Lua hook (called `otr_transition`) upon detecting such a transition event. This Lua hook function is one which you provide, and it could, say, publish a new message to an MQTT broker, invoke a REST API, etc. ### `.otrw` -Recorder reads `.otrw` files from `/waypoints/user/device/user-device.otrw` upon startup and loads these into an internal LMDB database. Each waypoint (geo fence) is keyed by `user-device-geohash(lat,lon)` in the LMDB sub table. +Recorder reads `.otrw` files from `/waypoints/user/device/user-device.otrw` upon startup and loads these into an internal LMDB database. Each waypoint (geo fence) is keyed by `user-device-geohash(lat,lon)` in the LMDB sub table. In addition, when Recorder receives a waypoint dump (say, from an OwnTracks device), it will also inspect said dump and merge new waypoints for the user/device into this database. For example, the following otrw @@ -35,7 +37,7 @@ Note how the `io` (in / out) element in the JSON indicates whether the last posi ### Transition hook -When Recorder determines that the user's device has entered or left the geo fence, it invokes a user-provided Lua function called `otr_transition`: +When Recorder determines that the user's device has entered or left the geo fence, it invokes a user-provided Lua function called `otr_transition()`: ```lua function otr_init() @@ -50,6 +52,8 @@ function otr_transition(topic, _type, data) end ``` +`topic` is the topic on which the message was originally received, `_type` is `"transition"` and `data` is a Lua table with the full payload plus merged data for the event. + In addition to the payload as described in the Booklet, recorder enhances the table passed to the Lua function with the following elements: - `wplat` / `wplon` are the latitude / longitude of the original waypoint definition