Anth's Computer Cave


AAIMI GPS Mapper features and setup

10th May 2017

AAIMI GPS Mapper is a Python-based geo-fencing system to configure and run perimeters for your other programs to use.

The AAIMI GPS Mapper web-interface to create GPS perimeters
The AAIMI GPS Mapper configuration web-interface.

It is a multi-user, multi-location mapper designed to run alongside programs and web applications on htaccess-enabled servers. It creates a list of coordinates for your users' defined areas and compares them to their current location on request from your own programs. With AAIMI GPS Mapper your programs can focus less on detecting where users are, and more on what to do when they get there.

How it works


You run AAIMI GPS mapper alongside your programs on the server. In my case the server is the Raspberry Pi that runs my home automation system. There is a setup wizard to perform the initial setup, then the configuration web-interface allows users to create and test their perimeters, and allows the admin user to add and remove users.

The rest of the functions work in the background whenever your programs need to know where users are. By default you import this into your Python programs, but any program that can launch bash commands and recieve web-requests can utilize the AAIMI GPS Mapper system. For web apps you can use PHP's system() command to run the Python program on-demand.


To see where users are, you obviously need a way to communicate with their phones and other GPS devices. AAIMI GPS Mapper offers two ways to manage this.

You can use your own web page or the default AAIMI Mapper web-interrface to request the location from the user's device. This works on both Android and iPhone, but you can only know the user's coordinates when they have the page open in their browser and the phone is awake.

The more dynamic alternative is AAIMI's new Python script that runs 24/7 on an Android phone, checking in with your server at pre-determined intervals. This requires less user interraction, although it is only tested on Android phones. On Android we are using the QPython interpreter to run Python and it can run the required Requests library for our Python script. It's possible one of the various Python interpreters available for iPhones can also run Request, but I'll leave the Apple stuff for someone who knows how to use an iPhone.

I'm using both the web page method and the phone-side Python script together for the AAIMI Home Automation system and it works well. My Android devices use both methods and my son's iPhone uses just the web page method.

Setting up new perimeters

All users can configure as many areas as they like, but there is only one "home" perimeter configured only by admin. No areas can have coordinates inside that home perimeter, although users can have areas overlapping with other users' areas outside home. Your programs can configure privacy settings to decide which map details are visible to other users, and which areas are considered in its inner functions.

To add a new area a user can open the configuration web-interface in their phone's browser. Creating a perimeter is as easy as walking to the north/south/east/west boundaries of your area, pressing the corresponding button on the phone at each boundary. On completion, give the new area a name, eg, work, etc. Your programs then, instead of just knowing this user is away from home, know they are at "work", or at "shops", and can react accordingly.

Download and setup

You can download AAIMI GPS Mapper here. Extract the folder to the webroot folder on your sever.

You'll need to set the ownership and permissions for the folder to match your server's configuration.

Now open a terminal and type: python

When prompted, enter your name. This must be your htaccess username for the server. Next, add any other users as prompted.

AAIMI will then prompt for the full path to your webroot directory on the server, then reconfigure some program files and that's it for the wizard.

You can now test the program.

Configure and test

Open a browser on your phone and go to yourServer/mapper/aaimi_mapper.html, substituting your server's IP address or domain name for 'yourServer'. If your server is on a domain with HTTPS enabled(recommended), you should be able to use any browser. If you don't have HTTPS enabled, you'll need to use a browser other than Chrome. Chrome won't allow location requests from non-HTTPS sites.

The AAIMI GPS Mapper web-interface to create GPS perimeters

The page will open in New mode so you can add your home perimeter. This will be the primary area the program monitors for both you and your housemates. The north/south/east/west images on the page demonstrate the concept of creating a virtual boundary in line with the corners of your property if it is not aligned exactly north/south. Walk to your first virtual boundary and click the corresponding image on your phone. The image border will turn green. Walk to the next virtual boundary and repeat the process until all four image borders are green.

You should see a prompt to enter a name for the area. Enter home.

If you go to the Places tab now you should see your home area, with the four perimeter coordinates displayed.

The AAIMI GPS Mapper web-interface Places tab

To add another area, be it work, shops, friends' places, go there and repeat the steps, entering a new name for each place.

Now you can test your home area. Click the Here tab at the top of the page.

The AAIMI GPS Mapper results for a user

If you are at home you should see "you are home". If not, you'll see either 'away' if you are in none of your areas, or the name of the other area you are in.

Now the system is configured, it's time to link it to your programs. In the next article I'll show you some ways your programs can utilize AAIMI GPS Mapper.




Next: Using AAIMI GPS Mapper



Leave a comment on this article

Leave a comment on this article