DE

EgiGeoZone

EgiGeoZone Forum

Download

 

EgiGeoZone manual

Creating a zone
Operation on Google Maps
Profiles
Server settings
Send text message
Send E-mail
Variables
More actions
Conditions/Requirements
Testing the settings
Change / Copy / Delete zone
Administration
Push messages with GCM
Live Tracking

General

EgiGeoZone is an easy-to-use Android app that can manage up to 100 geofences. You do need some experience if you want use it to connect to home automation servers, but even beginners should be able to use it for the simpler functions like sending a text message on leaving or entering an area you have chosen to geofence.

What exactly is a Geofence? I'll try to explain. A "geo-fence" (geographical fence) is a virtual containment or perimeter for a real geographical area. In this app, this area can only be defined as a circle. This circuit is derived from a geographical point (latitude and longitude) which is a point in the centre of that circle, plus the radius around it.

When entering or leaving one of these geographic zones the app can perform various actions. It makes use of the geofencing interface from Google Play services, which should be present on almost all Android smartphones and tablets. To determine the entering / exiting a zone, the Google interface uses a sophisticated process which is extremely energy efficient. Simply put, it uses GPS, Wi-Fi or mobile data to determine the location. Depending on the activated sensors (GPS, WiFi, mobile data) and on the range of things like the wireless hotspots or wireless masts, it may lead to different results. There are obviously technical limits and it is possible sometimes that the sensors are not able to determine the location in built-up areas, though this is rare.

Currently, the following actions are possible when an event occurs:

  • Send commands to a server. For example, for a home automation server such as FHEM
  • Send a text message
  • Send an e-mail
  • Show a notification when you enter or leave a zone
  • Switch Bluetooth, sound or wireless on or off

 New actions will be added in the future and you can let us know if there are features you would like to see.

Follow this link to download the free app: EgiGeoZone

Creating a zone

To create a new zone, click the plus sign. This takes you to a blank view to capture a geographical zone.
You can then fill in the required fields manually, or you can use the "Map" button to get the coordinates from Google Maps.

To create a zone, you will need to enter at least a name for your zone, the latitude and longitude, and a radius. Make sure the radius of the zone is not too small. The smaller the zone, the harder it is for your device's sensors to detect it. We suggest you always start with a radius of 500 meters. The minimum Radius is 50 meters.

Tips

  • Do not set radius too small. Start with 500 meters, if not bigger.
  • Select high accuracy on the device for the position detection. In the worst cases GPS is used.
  • Leave WIFI always on, as the recognition also uses the access point on the way
  • Switch between Google and Pathsense in the settings and see what suits better your circumstances

Functionality

The zone parameters are passed to the Google or Pathsense API, depending on the selection. These are services on mobile phones that support geofencing.

When an event occurs, the Google or Pathsense API reports the leaving or entering to the EgiGeoZone app. The app itself does not make any calculations and has no influence on it.

Once a zone has been entered, a green circle is placed in front of the zone name and the selected profiles are traversed. Likewise, when you leave a zone, a red circle is set and the associated actions are executed.

Note: It may also happen that the Google or Pathsense API does not report the entering / leaving of the zone. Since the app has unfortunately no influence on it! You will also be surprised that you have left the zone long ago, but the circle is still green in front of the zone. Likewise, you may be in the zone and the zone is marked red.

The distance to the zones is displayed correctly, since the distance is calculated when the app is opened. The entering / leaving but already happened long agot and was not reported by Google or Pathsense!

Therefore again: The displayed distance of the zone has nothing to do with geofencing!

Operation on Google Maps

Google Maps will show you your current location by default. If you want to select a different location, there are several possibilities:

  1. You can move or zoom the map to the desired location and and then make a long click to acquire the location. The coordinates are saved.
  2. Drag the marker showing your current location to the desired location and then click on the marker. That will pull up an information window. If you click on this, the coordinates are saved.
  3. Enter an address in the search box and then proceed as described in points 1 and 2. Only the first three results from your search are marked on the map.

Note about the radius

Initially, the radius is set by default to 500 meters on the map. This cannot be changed on the map currently. But you can override the radius in the previous view.

By clicking on the globe icon at the top right of the search bar, you can switch between satellite and normal map view.

The GeoZones are displayed in a fold-out list on the right.

Profiles

Under profiles we understand:

  • Server settings

  • SMS/Text message settings

  • E-mail settings

  • More actions

  • Conditions/Requirements

Once you have configured the profiles, you may reuse them in different zones.

Server profiles

Server settings are intended for more experienced users who have some technical knowledge of running and setting up interfaces with servers.

In the Server Settings option you can now enter the call to a URL. You can either use FHEM or set up two user-defined URLs of your own for entering and leaving the zone. All other fields are optional.

In "URL FHEM Geofancy", for example, the following URL is entered: http://mein.dyndns.org:1028/webhook/geo
This URL is then supplemented by the app and then sent in the following format: http://mein.dyndns.org:1028/webhook/geo? in which

id = AndroidId or DeviceId as UUID
name = name that you chose for the geozone. If an alias is set, then the alias will be used
entry = 1 or 0 (1 = entering and 0 = leaving)
date = date and time of the triggering of events
latitude = latitude of the centre of the zone
longitude = longitude of the centre of the zone
device = see id

As long as another server can evaluate/parse this Geofancy-URL, it will be able to use it.

OR

You can define a URL for "URL enter zone" and one for "URL leave zone". The App doesn't add or alter the URL at all. The URL will remain as it was entered.

Example:
http://my.dyndns.org:1028/jbu/enter
and
http://my.dyndns.org:1028/jbu/leave

The timeout is adjustable. By default, it is set to 30 seconds.
You can make changes to the parameters (see the description below), using the "Enter URL" and "URL Exit". This is not possible if you use the "URL FHEM Geofancy" however, because this URL has a fixed format. These parameters can also be used for E-Mail and text messages.

Further examples of HTTP (S) calls:
Calling a URL for entering the zone and one for leaving the zone:
URL area enter - example: https://srv.xxxx.de:1994/fhem?cmd.Absent=set Absent no
Leave URL Zone - example: https://srv.xxxx.de:1994/fhem?cmd.Absent=set Absent yes

All calls can be protected with basic authentication and/or SSL with client certificate.

The certificates must be filed under "internal memory"/egigeozone.
The client certificate is expected to be in p12 format. The server certificate relates to the CA certificate and is expected to be in PEM format.
If the inputs are not complete, you will see an error notification (red icon).

SMS/Text Message profiles

In this section, you can set up an action to send a text message when entering and leaving a zone. Please note: Your carrier may charge you for sending text messages.

Email profiles

Since sending the email has to happen in the background, this cannot be done via the standard Android e-mail programs, because this would require a user action. Therefore, the e-mail configuration in the app must be set up separately.

In the subject line and body of the e-mail and SMS text variables can be inserted, which will then be inserted automatically at runtime. See below for examples of these.

Predefined variables

  • Geozone = ${zone}
  • Entering / Leaving = ${transition}
  • 1/0 = ${transitionType} 1 for enter and 0 for exit
  • Latitude = ${latitude} the latitude from the zone
  • Longitude = ${longitude} the longitude from the zone
  • Real latitude = ${realLatitude} reported from Google services, when the event is received
  • Real longitude = ${realLongitude} reported from Google services, when the event is received
  • Accuracy = ${accuracy} reported from Google services, when the event is received
  • Radius = ${radius}
  • DeviceId = ${deviceId}
  • AndroidId = ${androidId}
  • Date = ${date} UTC date and time like "yyyy-MM-dd'T'HH:mm:ss'Z'"
  • Local date = ${localDate} local date and time like "yyyy-MM-dd'T'HH:mm:ss"
  • UTC location date = ${locationDate} UTC location date reported from Google services, when the event was received. Format "yyyy-MM-dd'T'HH:mm:ss'Z'"
  • Local location date  = ${localLocationDate} local location date reported from Google services, when the event was received. Format  "yyyy-MM-dd'T'HH:mm:ss"

Usage:

Entering and leaving a zone: usage in emails (subject and body), server calls(URL entry and exit) and SMS Tracking: usage for emails (subject and body) and server calls (tracking URL)
${zone} X X
${transition} X --
${transitionType} X --
${latitude} X --
${longitude} X --
${realLatitude} X X
${realLongitude} X X
${accuracy} X X
${radius} X --
${deviceId} X X
${androidId} X X
${date} X X
${localDate} X X
${locationDate} X X
${localLocationDate} X X

 

SMS example:

Input in the SMS configuration:
       
Egmont has just ${transition} ${zone} zone.

Result of SMS:
        Egmont has just exited work zone.

 

Profile for more actions

  • Calling an predefined 'Tasker' task.

    I think most people know about the 'Tasker' app.
    If not, you can google or read this: http://tasker.dinglisch.net/index.html

    Conditions that this function can be used:
    - Tasker must have been previously installed from here https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm.
    - At least one task, which you want to access
    from the EgiGeoZone app must have been previously created in Tasker.
    - In Tasker under Preferences -> Misc -> "Allow External Access"> you must allow access from external apps.
    - Note the
    task names and enter them in the EgiGeoZone app under the "More actions" for entering and leaving a zone..

    Note
    s for experienced Tasker users or those which plan to write a Tasker plugin:
    EgiGeozone sends the following parameters and variables with the Tasker
    call.

    Parameters:
    name of zone
    Transition: 1 = Enter; 0 = Exit
    Latitude
    Longitude

    Variables:
    "zone"=name of zone
    "transition"=Transition: 1 = Enter; 0 = Exit
    "latitude"=Latitude
    "longitude"=Longitude
  • Wi-Fi on or off

  • Sound on or off

  • Bluetooth on or off

Conditions/Requirements profiles

This allows you to list under what conditions an action will be triggered.

Currently, you can only specify following conditions:

- An action can be triggered when a selected Bluetooth device is connected to the smartphone/tablet.
- The action will be executed, if the actual weekday is marked.

Actions testing

All combinations, such as server, e-mail and text messages can be tested using the glasses symbol from the bar. Whatever values were set will be used for the test. If the test fails, you will receive a failure notification (please remember to check you have enabled Notifications via Settings).

When testing the server settings, the process follows the sequence set out below, which is also used for live operation:

  • If the FHEM Geofancy URL is filled in, this is called first. So has this URL has priority.
  • If the FHEM Geofancy is not filled in, then the URLs for entering and leaving should be entered . Depending on the event (enter or leave) the corresponding URL is invoked.
  • If the Tracking URL is also set, then this connection will be also tested.

The goal of testing is to check the accessibility of the URLs, as they were configured. For testing the connection, almost faked parameters will be sent.

The test itself does not trigger any actions, it only tests the connections. In addition, the following assumptions are made:

  • The event will always be the entry event(transition = 1) ==> It will be called the FHEM Geofancy URL or the entering URL, depending on the configuration. During testing, the leaving URL is never called.
  • The remaining fields are transferred.

You will get an dialog with the test result. You should also check on the server whether the request was correct.

When testing text messages and email, the text message/e-mail is sent with the entered text from the configuring view.

Changing a zone

All values for a zone can be changed except name.

Copying a zone

Click the existing zone. Change the name and all the necessary values and save it. A new zone is created.

Removing a zone

Select the existing zone and click Remove. Then confirm in the following dialogue box.

Settings

  • Use Google or Pathsense API for geofencing. Depending on the circumstances, you can try which one of the two interfaces is more suitable. This can only be ascertained by trying out.
  • Turn notifications on or off
  • Turn error notifications on or off
  • Transfer data to plugins, if desired. Plugins are additional apps (modules) that can perform special actions. Example is the Telegram plugin.
  • The GCM (Google Cloud Messaging) project ID
  • GCM receive messages. This setting enables push messages. When activating this, a dialogue box with a generated key is displayed. More details here: GCM configuration
  • Logging and viewing of GCM notifications.
    The GCM notifications can be saved to the file gcmnotifications.txt in the "internal memory"/egigeozone directory.
    By clicking on the trash symbol in the "GCM logging" view, you can delete the GCM log file.
    If you want to see the GCM log, you may also tap on a GCM notification and you will see the log file.
  • View Log File: Displays the most recent log file.
  • Log level setting: You can set the level for debugging purposes in the menu. By default, ERROR is set. The log file is located under "internal memory"/egigeozone/egigeozone.log
  • Send the latest log file
  • View registered plugins
  • Basic Settings for Location Tracking
  • Customize the app colors
  • Backing up and restoring the configuration. Useful for example for mobile exchange or for fault analysis. The configuration file can be found under "internal memory" /egigeozone/egigeozone_export.xml
    Additional you may export the configuration to or from Dropbox, Google Drive or other supported targets. The configuration file is also saved on the device on the known place!
  • Reset zone status: all are set to red

GCM messages

EgiGeoZone can now receive GCM (Google Cloud Messaging) messages.
Google Cloud Messaging (GCM) is a free service where messages or data can be sent from servers on Android Apps. Mostly these are simple short messages, which indicate, for example, the status of equipment.

This kind of notifications is also a type of push messaging.

To set GCM client and server please see the following link for further details: GCM configuration

Live Tracking

EgiGeoZone has introduced now Live Tracking.
The track points plus other information you can:
- write to the device in a file. The file is written into the egigeozone-directory under locationtracker_ <zonen_name>.txt.
- send by e-mail
- send to a server.

The recording can be started when entering or leaving a zone automatically.

General settings

These settings are responsible for the location updates (polling). The location fix is then remembered and delivered later, how configured for each zone.

Under settings and location tracking you can make the following setting:

- Time in minutes between the location updates. This is not the time for the real logging, but the time when the app reports the location! To save power, do not choose this interval too short. This location is noted and sent to the specified zones, which were configured to track.

- Type of location-determination:
    
Low power accuracy (about 10 km accuracy) = battery intensive
    
Balanced power accuracy (about 100 meter accuracy) = balanced consumption of batteries
    
Low power accuracy (about 10 km accuracy) = very little consumption of batteries

- Also you may stop all trackings for all zones with one click.

At the top you can see an icon, which indicates the recording. By clicking on the icon, you can see the zones for which a recording are in progres
s.

Zone settings and starting/stoping the live tracking

Here you can start or stop the recording when entering or leaving a zone.

By starting the live tracking when leaving or entering zones, the following combinations are possible:

Exit zone Enter zone Tracking
yes no tracking runs from leaving to entering
no yes tracking runs from entering until leaving
yes yes tracking is always running. The result is, that the tracking runs continuously.
no no tracking is not running


Under logging interval you can specify the time in minutes, when the track should be logged/sent. This interval is not accurate
, because of Android power saving, but logging is already happening in a time frame.

You can enter a server address to specify the data to be sent in a server profile under URL for tracking. This URL is configurable. After that, you have to choose the server profile in the zone settings for the live tracking.

The GET method is here used. Example:
http://<server:port>/<pfad>/track.php?latitude=${realLatitude}&longitude=${realLongitude}&date=${date}&device=${androidId}&zone=${zone}

A sample PHP script I have stored here: https://www.egigeozone.de/download/track.zip

The variables you can use are described here: variables



Finally there is the option to send the location to a configured e-mail profile. Please select a profile.
In the text the variables can  be used.

The recording is always displayed in the notification bar. This permanent notification can not be deactivated.

Other

In the menu of the main window there are the following items:

  • Refresh. Means that the distance to the zones can be recalculated. This can also be achieved by swiping down in the main window
  • Show all geozones.You can click on the zone names to zoom in or out
  • Technical info
  • Info
  • Help
  • Privacy policy

If you have questions, please check out the EgiGeoZone forum: https://rpi.spdns.eu/egigeozone/index.php