This page is part of archived documentation for openHAB 2.5. Go to the current stable version

# OpenPaths Binding v1

OpenPaths (opens new window) is an app you can install on your Android or iOS device which will periodically upload your location to the OpenPaths servers. Using the OpenPaths binding, openHAB will periodically request your latest location data from the OpenPaths servers and calculate your presence relative to a specified location (usually your home).

# Prerequisites

First you will need to install the OpenPaths app on your mobile device. You will then need to sign up to the OpenPaths service. At this point you should be issued with an ACCESS_KEY and SECRET_KEY which you will need to configure the OpenPaths binding. You will also need to link your app to your new OpenPaths account.

# Binding Configuration

You need to let the binding know exactly where 'home' is and what size the geofence (opens new window) is. You can also optionally specify the refresh interval which determines how often openHAB will poll the OpenPaths servers. This information can be entered in the file services/openpaths.cfg.

Beside a location named 'home' (mandatory) you may specify any number of additional locations, each of it optionally having its own geofence.

Finally, you need to add entries for each OpenPaths account you wish to track. You can track as many different OpenPaths accounts as you like, you will just need a set of entries in your openhab.cfg for each account, containing the ACCESS_KEY and SECRET_KEY from each account.

Property Default Required Description Yes Latitude of home in decimal degrees
home.long Yes Longitude of home in decimal degrees
home.geofence Value of geofence No Size of the geofence around home
<location>.lat Latitude of <location> in decimal degrees. You may define any number of additional locations.
<location>.long Longitude of <location> in decimal degrees
<location>.geofence Geofence around <location> in decimal degrees
geofence 100 No Distance in metres a user must be from 'home' to be considered inside the geofence
refresh 300000 No Interval in milliseconds to poll for user location (defaults to 5mins)
<user>.accesskey Yes OpenPaths access key for <user>
<user>.secretkey Yes OpenPaths secret key for <user>

# Item Configuration

To track the location/presence of a mobile device, all you need to do is add a Switch item and specify the name you entered in your binding configuration file (for <user>) for the OpenPaths account you wish to track.

You can also bind the distance (direct view line) of a tracked phone to a Number item. The coordinates as delivered from OpenPaths API are available as String 'latitude, longitude' and in addition as separate Numbers.

Switch  User1PresenceHome     "User 1 @ Home"                    { openpaths="user1:home" }
Number  User1HomeDistance     "User 1 away from home: [%.2f km]" { openpaths="user1:home:distance" }

Switch  User1PresenceWork     "User 1 @ work"                    { openpaths="user1:work" }
Number  User1WorkDistance     "User 1 away from work: [%.2f km]" { openpaths="user1:work:distance" }

String  User1Phone_currentLoc "User1 current location: [%s]"     { openpaths="user1:currentLocation" }
Number  User1Phone_currentLat "User1 latitude: [%.4f °]"         { openpaths="user1:currentLatitude" }
Number  User1Phone_currentLon "User1 longitude: [%.4f °]"        { openpaths="user1:currentLongitude" }