[Documentation] Markdown improvements f to m (#13866)
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
committed by
GitHub
GitHub
parent
3c236b3103
commit
0e68936663
@@ -4,8 +4,8 @@ This binding allows you to connect mobile GPS tracker applications to openHAB an
|
||||
|
||||
Currently two applications are supported:
|
||||
|
||||
* [OwnTracks](https://owntracks.org/booklet/) - iOS, Android
|
||||
* [GPSLogger](https://gpslogger.app/) - Android
|
||||
- [OwnTracks](https://owntracks.org/booklet/) - iOS, Android
|
||||
- [GPSLogger](https://gpslogger.app/) - Android
|
||||
|
||||
GPS location reports are sent to openHAB using HTTP.
|
||||
Please be aware that this communication uses the public network so make sure your openHAB installation is [secured](https://www.openhab.org/docs/installation/security.html#encrypted-communication) (but accessible from public internet through myopenhab.org or using a reverse proxy) and you configured HTTP**S** access in tracking applications.
|
||||
@@ -13,8 +13,8 @@ The easiest way to achieve this is to use the [openHAB Cloud Connector](https://
|
||||
|
||||
The binding can process two message types received from trackers:
|
||||
|
||||
* **Location** - This is a simple location report with coordinates extended with some extra information about the tracker (e.g. tracker device battery level). [OwnTracks, GPSLogger]
|
||||
* **Transition** - This report is based on regions defined in tracker application only. A message is sent every time the tracker enters or leaves a region. [OwnTracks only] See "Distance Channel and Presence Switch" how this behavior can be achieved with openHAB's on-board tools.
|
||||
- **Location** - This is a simple location report with coordinates extended with some extra information about the tracker (e.g. tracker device battery level). [OwnTracks, GPSLogger]
|
||||
- **Transition** - This report is based on regions defined in tracker application only. A message is sent every time the tracker enters or leaves a region. [OwnTracks only] See "Distance Channel and Presence Switch" how this behavior can be achieved with openHAB's on-board tools.
|
||||
|
||||
## Configuration
|
||||
|
||||
@@ -24,15 +24,15 @@ Install [OwnTracks for Android](https://play.google.com/store/apps/details?id=or
|
||||
|
||||
Go to Preferences/Connection and set:
|
||||
|
||||
* **Mode** - select Private HTTP
|
||||
* **Host**
|
||||
* https://<your.ip.address>/gpstracker/owntracks or
|
||||
* https://home.myopenhab.org/gpstracker/owntracks
|
||||
* **Identification**
|
||||
* Turn Authentication ON
|
||||
* Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as host)
|
||||
* Device ID is not important. Set it to e.g. phone
|
||||
* Tracker ID - This id identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
|
||||
- **Mode** - select Private HTTP
|
||||
- **Host**
|
||||
- `https://<your.ip.address>/gpstracker/owntracks` or
|
||||
- `https://home.myopenhab.org/gpstracker/owntracks`
|
||||
- **Identification**
|
||||
- Turn Authentication ON
|
||||
- Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as host)
|
||||
- Device ID is not important. Set it to e.g. phone
|
||||
- Tracker ID - This id identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
|
||||
|
||||
### GPSLogger
|
||||
|
||||
@@ -40,19 +40,19 @@ Install [GPSLogger for Android](https://github.com/mendhak/gpslogger/releases) o
|
||||
After the launch, go to General Options.
|
||||
Enable **Start on boot-up** and **Start on app launch**.
|
||||
|
||||
Go to *Logging details* and enable **Log to custom URL**.
|
||||
If you only want to use GPSLogger for this binding, you can disable all other "*Log to*" entries.
|
||||
Right after enabling, the app takes you to the *Log to custom URL* settings:
|
||||
Go to _Logging details_ and enable **Log to custom URL**.
|
||||
If you only want to use GPSLogger for this binding, you can disable all other "_Log to_" entries.
|
||||
Right after enabling, the app takes you to the _Log to custom URL_ settings:
|
||||
|
||||
* **URL**
|
||||
* https://<your.ip.address>/gpstracker/gpslogger or
|
||||
* https://home.myopenhab.org/gpstracker/gpslogger
|
||||
* **HTTP Body** - type in: { "_type":"location", "lat":%LAT, "lon":%LON, "tid":"XY", "acc":%ACC, "batt":%BATT, "tst":%TIMESTAMP }
|
||||
* Note: "*tid*" is the tracker id that identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
|
||||
* **HTTP Headers** - type in: *Content-Type: application/json*
|
||||
* **HTTP Method** - type in: *POST*
|
||||
* **Basic Authentication** - Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as URL)
|
||||
* Check if everything is ok by clicking on **Validate SSL Certificate**.
|
||||
- **URL**
|
||||
- `https://<your.ip.address>/gpstracker/gpslogger` or
|
||||
- `https://home.myopenhab.org/gpstracker/gpslogger`
|
||||
- **HTTP Body** - type in: { "_type":"location", "lat":%LAT, "lon":%LON, "tid":"XY", "acc":%ACC, "batt":%BATT, "tst":%TIMESTAMP }
|
||||
- Note: "_tid_" is the tracker id that identifies the tracker as a thing. This must be unique for each tracker connected to the same openHAB instance (e.g. family members).
|
||||
- **HTTP Headers** - type in: _Content-Type: application/json_
|
||||
- **HTTP Method** - type in: _POST_
|
||||
- **Basic Authentication** - Set username and password to be able to reach your openHAB server (myopenhab.org credential, if choosen as URL)
|
||||
- Check if everything is ok by clicking on **Validate SSL Certificate**.
|
||||
|
||||
### Things
|
||||
|
||||
@@ -68,11 +68,11 @@ If the things are not defined in **.things** files the first time the tracker se
|
||||
|
||||
Basic channels provided by the tracker things:
|
||||
|
||||
* **Location** - Current location of the tracker
|
||||
* **Accuracy** - GPS accuracy
|
||||
* **Last Report** - Timestamp of the last location report
|
||||
* **Battery Level** - Battery level of the device running the tracker application
|
||||
* **Region trigger channel** - Used by regions defined in tracker application. Event is fired with payload of the region name when the binding receives a **transition** log record or a distance calculation for a **location** record indicates that the tracker is outside of the region circle. Payload is suffixed with `/enter` for entering and with `/leave` for leaving events.
|
||||
- **Location** - Current location of the tracker
|
||||
- **Accuracy** - GPS accuracy
|
||||
- **Last Report** - Timestamp of the last location report
|
||||
- **Battery Level** - Battery level of the device running the tracker application
|
||||
- **Region trigger channel** - Used by regions defined in tracker application. Event is fired with payload of the region name when the binding receives a **transition** log record or a distance calculation for a **location** record indicates that the tracker is outside of the region circle. Payload is suffixed with `/enter` for entering and with `/leave` for leaving events.
|
||||
|
||||
#### Distance Calculation
|
||||
|
||||
@@ -90,8 +90,8 @@ Distance values will be updated each time a GPS location log record is received
|
||||
|
||||
When this calculated distance is less than the defined geofence radius the binding also fires event on Region Trigger channel.
|
||||
|
||||
* When the tracker is approaching (the new calculated distance is less then the previous one) the payload is <<region_name>>/enter.
|
||||
* If the tracker is distancing (the new calculated distance is greater then the previous one) payload is <<region_name>>/leave.
|
||||
- When the tracker is approaching (the new calculated distance is less then the previous one) the payload is <<region_name>>/enter.
|
||||
- If the tracker is distancing (the new calculated distance is greater then the previous one) payload is <<region_name>>/leave.
|
||||
|
||||
If the tracker is moving inside/outside the region (both the previous and the current calculated distance value is less/greater than the radius) no events are fired.
|
||||
This means that the region events are triggered **ONLY IN CASE THE REGION BORDER IS CROSSED**.
|
||||
@@ -105,8 +105,8 @@ These events are fired in case of distance channels as well when the tracker cro
|
||||
In order to have this state available in stateful switch items (e.g. for rule logic) switch type items can be linked to **regionTrigger** channel.
|
||||
There is a special profile (gpstracker:trigger-geofence) that transforms trigger enter/leave events to switch states:
|
||||
|
||||
* **<<region_name>>/enter** will update the switch state to **ON**
|
||||
* **<<region_name>>/leave** will update the switch state to **OFF**
|
||||
- **<<region_name>>/enter** will update the switch state to **ON**
|
||||
- **<<region_name>>/leave** will update the switch state to **OFF**
|
||||
|
||||
To link a switch item to regionTrigger channel the following parameters are required by the item link:
|
||||
|
||||
@@ -119,7 +119,7 @@ To link a switch item to regionTrigger channel the following parameters are requ
|
||||
|
||||
### Things
|
||||
|
||||
```
|
||||
```java
|
||||
//tracker definition
|
||||
Thing gpstracker:tracker:1 "XY tracker" [trackerId="XY"]
|
||||
|
||||
@@ -137,12 +137,12 @@ Thing gpstracker:tracker:EX "EX tracker" [trackerId="EX"] {
|
||||
|
||||
### Items
|
||||
|
||||
```
|
||||
```java
|
||||
//items for basic channels
|
||||
Location locationEX "Location" {channel="gpstracker:tracker:1:lastLocation"}
|
||||
DateTime lastSeenEX "Last seen" {channel="gpstracker:tracker:1:lastReport"}
|
||||
Number batteryEX "Battery level" {channel="gpstracker:tracker:1:batteryLevel"}
|
||||
Number:Length accuracyEX "GPS Accuracy [%d m]" {channel="gpstracker:tracker:1:gpsAccuracy"}
|
||||
Location locationEX "Location" {channel="gpstracker:tracker:1:lastLocation"}
|
||||
DateTime lastSeenEX "Last seen" {channel="gpstracker:tracker:1:lastReport"}
|
||||
Number batteryEX "Battery level" {channel="gpstracker:tracker:1:batteryLevel"}
|
||||
Number:Length accuracyEX "GPS Accuracy [%d m]" {channel="gpstracker:tracker:1:gpsAccuracy"}
|
||||
|
||||
//linking switch item to regionTrigger channel. assuming the Home distance channel is defined in the binding config (see above)
|
||||
Switch atHomeEX "Home presence" {channel="gpstracker:tracker:EX:regionTrigger" [profile="gpstracker:trigger-geofence", regionName="Home"]}
|
||||
@@ -153,7 +153,7 @@ Switch atWorkEX "Work presence" {channel="gpstracker:tracker:EX:regionTrigger" [
|
||||
|
||||
### Sitemaps
|
||||
|
||||
```
|
||||
```perl
|
||||
sitemap gpstracker label="GPSTracker Binding" {
|
||||
Text item=distanceEX
|
||||
Text item=atWorkEX
|
||||
@@ -172,7 +172,7 @@ In order to see detailed debug information [set TRACE debug level](https://www.o
|
||||
|
||||
### Binding Start
|
||||
|
||||
```
|
||||
```text
|
||||
2018-10-03 18:12:38.950 [DEBUG] [org.openhab.binding.gpstracker ] - ServiceEvent REGISTERED - {org.openhab.core.config.discovery.DiscoveryService, org.openhab.binding.gpstracker.internal.discovery.TrackerDiscoveryService}={service.id=425, service.bundleid=183, service.scope=bundle, component.name=org.openhab.binding.gpstracker.internal.discovery.TrackerDiscoveryService, component.id=268} - org.openhab.binding.gpstracker
|
||||
2018-10-03 18:12:38.965 [DEBUG] [org.openhab.binding.gpstracker ] - ServiceEvent REGISTERED - {org.openhab.core.thing.binding.ThingHandlerFactory, org.openhab.core.config.core.ConfigOptionProvider}={location=47.536178,19.169812, service.id=426, service.bundleid=183, service.scope=bundle, radius=100, name=Home, component.name=org.openhab.binding.gpstracker.internal.GPSTrackerHandlerFactory, component.id=267, additionalRegionsJSON=[
|
||||
], triggerEvent=false, service.pid=binding.gpstracker} - org.openhab.binding.gpstracker
|
||||
@@ -187,7 +187,7 @@ In order to see detailed debug information [set TRACE debug level](https://www.o
|
||||
|
||||
Please note the lines about started servlets:
|
||||
|
||||
```
|
||||
```text
|
||||
Started GPSTracker Callback servlet on /gpstracker/owntracks
|
||||
Started GPSTracker Callback servlet on /gpstracker/gpslogger
|
||||
```
|
||||
@@ -196,7 +196,7 @@ Started GPSTracker Callback servlet on /gpstracker/gpslogger
|
||||
|
||||
In case the discovery is used the first message from a tracker registers it in the inbox:
|
||||
|
||||
```
|
||||
```text
|
||||
2018-10-05 08:36:14.283 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"location","tid":"XX","acc":10.0,"lat":41.53,"lon":16.16,"tst":1527966973,"wtst":1524244195,"batt":96}
|
||||
2018-10-05 08:36:14.286 [DEBUG] [nal.provider.AbstractCallbackServlet] - There is no handler for tracker XX. Check the inbox for the new tracker.
|
||||
```
|
||||
@@ -205,7 +205,7 @@ In case the discovery is used the first message from a tracker registers it in t
|
||||
|
||||
The next location message already calculates the distance for System location:
|
||||
|
||||
```
|
||||
```text
|
||||
2018-10-05 08:38:33.916 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"location","tid":"XX","acc":10.0,"lat":41.53,"lon":16.16,"tst":1527966973,"wtst":1524244195,"batt":96}
|
||||
2018-10-05 08:38:33.917 [DEBUG] [cker.internal.handler.TrackerHandler] - Update base channels for tracker XX from message: org.openhab.binding.gpstracker.internal.message.LocationMessage@31dfed63
|
||||
2018-10-05 08:38:33.941 [TRACE] [cker.internal.handler.TrackerHandler] - batteryLevel -> 96
|
||||
@@ -220,20 +220,20 @@ The next location message already calculates the distance for System location:
|
||||
|
||||
Assumptions:
|
||||
|
||||
* A Home distance channel is added to the tracker with parameters:
|
||||
* Channel ID: distanceHome
|
||||
* Region Name: Home
|
||||
* Region Radius: 100
|
||||
* Region Center: 42.53,16.16
|
||||
* Presence switch is linked to the regionTrigger channel with parameters:
|
||||
* Profile: Geofence(gpstracker:trigger-geofence)
|
||||
* Region Name: Home
|
||||
- A Home distance channel is added to the tracker with parameters:
|
||||
- Channel ID: distanceHome
|
||||
- Region Name: Home
|
||||
- Region Radius: 100
|
||||
- Region Center: 42.53,16.16
|
||||
- Presence switch is linked to the regionTrigger channel with parameters:
|
||||
- Profile: Geofence(gpstracker:trigger-geofence)
|
||||
- Region Name: Home
|
||||
|
||||
|
||||
|
||||
After a location message received from the tracker the log should contain these lines:
|
||||
|
||||
```
|
||||
```text
|
||||
2018-10-05 09:27:58.768 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"location","tid":"XX","acc":10.0,"lat":42.53,"lon":17.16,"tst":1527966973,"wtst":1524244195,"batt":96}
|
||||
2018-10-05 09:27:58.769 [DEBUG] [cker.internal.handler.TrackerHandler] - Update base channels for tracker XX from message: org.openhab.binding.gpstracker.internal.message.LocationMessage@67e5d438
|
||||
2018-10-05 09:27:58.770 [TRACE] [cker.internal.handler.TrackerHandler] - batteryLevel -> 96
|
||||
@@ -253,12 +253,12 @@ After a location message received from the tracker the log should contain these
|
||||
|
||||
Assumptions:
|
||||
|
||||
* A **shared** region is defined in OwnTracks application. Lets call it Work.
|
||||
* Presence switch is linked to the regionTrigger channel with parameters:
|
||||
* Profile: Geofence(gpstracker:trigger-geofence)
|
||||
* Region Name: Work
|
||||
- A **shared** region is defined in OwnTracks application. Lets call it Work.
|
||||
- Presence switch is linked to the regionTrigger channel with parameters:
|
||||
- Profile: Geofence(gpstracker:trigger-geofence)
|
||||
- Region Name: Work
|
||||
|
||||
```
|
||||
```text
|
||||
2018-10-05 09:35:27.203 [DEBUG] [nal.provider.AbstractCallbackServlet] - Post message received from OwnTracks tracker: {"_type":"transition","tid":"XX","acc":10.0,"desc":"Work","event":"enter","lat":42.53,"lon":18.22,"tst":1527966973,"wtst":1524244195,"t":"c"}
|
||||
2018-10-05 09:35:27.204 [DEBUG] [cker.internal.handler.TrackerHandler] - ConfigHelper transition event received: Work
|
||||
2018-10-05 09:35:27.204 [DEBUG] [cker.internal.handler.TrackerHandler] - Update base channels for tracker XX from message: org.openhab.binding.gpstracker.internal.message.TransitionMessage@5e5b0d59
|
||||
@@ -275,5 +275,5 @@ Assumptions:
|
||||
|
||||
**Note**:
|
||||
|
||||
* If the binding was restarted only the second transition update will trigger event as the binding has to know the previous state.
|
||||
* The distance is not calculated for Work as the binding doesn't know the Work region center.
|
||||
- If the binding was restarted only the second transition update will trigger event as the binding has to know the previous state.
|
||||
- The distance is not calculated for Work as the binding doesn't know the Work region center.
|
||||
|
||||
Reference in New Issue
Block a user