Overview

Skill Level: Intermediate

This recipe will show you how to create a simple geofence solution using standard components on IBM Cloud. Node-Red is used to handle IOT location events and a mobile-enabled web GUI generates location events from your phone.

Ingredients

  1. IBM Cloud account (signup here)
  2. Mapbox account (signup here)

 

Before starting you should make sure you have space on your IBM Cloud account for 3 applications and 3 services. You may be able to reuse some services you have already but please note that the recipe assumes all Cloud services are created from scratch.

Step-by-step

  1. Create bluemix services

    a) Log on to Bluemix, select catalog and search for “IOT”.

    IOT platform

    b) Select the “internet Of Things Platform” and add it as a service. Take note of the name you give the service.

    c) Select the bluemix catalog again and search for “geospatial”

    r2

    d) Select “Geospatial Analytics” and add it as a service. Take note of the name you give the service.

    e) Finally search the bluemix catalog for “node-red”.

    r3

    f) Select “node-red Starter” and add the service. Take note of the name you give the service and also the name of the cloudant DB added in the boilerplate. This will be used as the main db by the applications we will create in this recipe

     

    We now have the three bluemix services we need for this recipe and the first of our three applications.

  2. Download code and node-red flows

    Download the zip file at this link

    Extract to a suitable location on your local computer. A single “geofence” directory will be created.

    The “geofence” directory contains the following:

    • geofence-device: a node.js application that provides an IOT device simulator
    • geofence-manager: a node.js application that manages the geospatial analytics service and provides a geofence GUI
    • node-red flows: contains a single text file with the node-red flows used by this service
  3. Create geofence manager

    open a command shell on your local system and navigate to the geofence/geofence-manager directory

    login to bluemix on the command line using the bluemix command tools (“> Bluemix login”)

    open the file “public\javascripts\mapdisplay.js”.

     

    r13a

    At the head of the file is a dummy mapbox token value – this needs to be replaced with an actual token from mapbox.

    In your browser, navigate to¬†https://www.mapbox.com/studio/ and login with your mapbox credentials. You can sign up here if you haven’t done so yet.

    Now select the “add or revoke tokens” button.

    r12

    You can then either use an existing token you have or create a new one. Please copy the token onto the clipboard.

    switch to the text editor which you have open and paste the mapbox token in place of  the dummy token value XXXXXX.

    Save mapdisplay.js

    now open the file “manifest.yml” in your text editor. It is at the top level of the geofence-manager directory.

    r14a

    Replace name and host with the name you wish to give your geofence manager application on bluemix.

    Replace the dummy services with the actual names of the services you created earlier.

    Save the file and return to the command prompt and make sure you are in the top-level directory of geofence-manager.

    At the command prompt, type the command “cf push”

    This will push the application to bluemix, associate it with the defined services and deploy the application.

    r21

    If the command completes successfully, then the command output will finish with a view of the application showing a state of “running”. The output will also have the url of the application which should be copied for use in the next step.

  4. Run the geofence manager

    We can now run the geofence manager and add some geofence regions of our own.

    The url copied in the previous step should be pasted into the browser with the prefix “https://”. This loads the GUI of the geofence manager in your browser.

    r15

    The map will be centered on your location.

    You can now start the geospatial service by pressing the button as highlighted above.

    Switch to another tab in the browser and login to bluemix. On the dashboard, select the geospatial service

    r16

    This should show that the geospatial service is started but no regions are being monitored. It may take a few seconds to refresh on startup

    We now need to create some regions so we switch back to the geofence manager GUI.

    r17

    In the diagram above, we can see that some regions have been created. One is currently selected and shows the parameters associated with the region. This region is a regular polygon with a radius of 800 metres. We can set parameters for the number of vertices (0 corresponds to a circle – which is approximated with a 45-vertex polygon). Additionally we can define a human-readable id for the region and set values for notification on entry to or exit from the polygon. A full description of these parameters is given in the geospatial analytics documentation on bluemix. A regular polygon can be selected and moved and its radius changed.

    The highlighted area shows the polygon tools. The # tool allows the creation of a custom multi-point polygon – as for instance when creating a region along a road. points can be edited and moved as required. The point tool creates a regular polygon as selected above. A selected polygon can be deleted using the delete tool.

    The buttons allow region data to be saved to or read from database. The project name is used to identify the database. The service automatically creates databases as needed in cloudant – each has the name “<project>_db”

    The “Set geofence region” button stores the current on-screen regions as regions in the geospatial analytics service. The “get geofence region” button supports¬† getting geofence regions from the service e.g. to verify current regions.

  5. Create IOT application

    We will create an IOT application to store device location events and also handle region entry and exit events.

    In a browser window we login to bluemix and select the node-red application we created earlier.

    r4

    When the screen above is shown, select the “connections” tab on the left hand side (highlighted)

    r5

    On the connections screen, select “connect existing”.

    Now select the IOT platform service created previously and press “connect” to connect it to the application.

    You will be alerted that you need to restage the application. Accept the option to restage immediately.

    This may take some time to complete and, if unsuccesful, you may need to restart the node-red application manually.

    When you are certain that the application is running again, check that the iot platform is connected.

    Now press “view app” to view the application.

    When the application is shown, you can press the “go to your node-red editor” button.

    This will show an empty flow.

    On your local system edit the file “flow.txt” from the “node-red flows” directory using your preferred text editor. Select all the content and copy to your clipboard.

    switch back to the node red browser window.

    r6

    Select the “import” option from the tool bar (highlighted) and then select “clipboard”. In the buffer, paste the clipboard contents and press “import” to import into the current flow.

    r7

    The imported flow supports two separate processes. The top message sequence handles device events and writes them to the event database. It also updates the device location in the device database.

    The bottom message sequence handles events from the geospatial analytics service -e.g. when a device enters or leaves a region. The message sequence writes these events to the event database. It also sends commands back to the device to let it know when it enters or leaves a region.

    This sequence is ready to deploy but beforehand we need to check the IOT and storage nodes to ensure they are configured correctly.

  6. Configure IOT application

    We now need to ensure that the IOT nodes are configured correctly.

    r8

    We click on the device input IOT node to view its confguration. We need to select the Authentication entry and ensure it references “bluemix service” as shown above. We then click “done”

    r9

    We now repeat for the two other IOT nodes highlighted above.

    Next we need to check the database node configurations

    r10

    We click on the top leftmost devdb node. We then check the “service” entry references the correct database service and make any change needed. Then click “done”.

    r11

    We then repeat these checks for each of the database nodes highlighted above.

    It is important to click on, and save the configuration of each database and IOT node even if it appears the configuration is populated correctly. This population only happens when the node configuration is selected so missing a node will cause problems.

    Finally – press “deploy” to deploy the configured node-red application. When the flow is active, you will see that all IOT nodes are showing as being connected”.

  7. Create IOT device application

    We now need an IOT device to generate location events. We can simulate such a device by using a phone browser which accesses our IOT device application.

    On the command line we change directory to geofence-device and run a text editor to edit “manifest.yml”

    r18

    Replace name and host with the name you wish to give your geofence device application on bluemix.

    Replace the dummy services with the actual names of the services you created earlier.

    Save the file and return to the command prompt and make sure you are in the top-level directory of geofence-device.

    At the command prompt, type the command “cf push”

    This will push the application to bluemix, associate it with the defined services and deploy the application.

     

    If the command completes successfully, then the command output will finish with a view of the application showing a state of “running”. The output will also have the url of the device application which should be copied.

    Now we can run the device application either on a phone browser or on a desktop browser. The url we just copied should be pasted but with a prefix of “https://” added. This ensures all services will work – as some of the browser scripts require https.

    You will be prompted to allow location services to be used and this should be allowed as otherwise the application will not work correctly. A device id of minimum 8 characters should be entered – this will be stored for future use. On the phone browser it is probably best to bookmark the URL for any repeated use.

    r19

    When the application starts up in the browser it connects to the bluemix device service, reads its device credentials and connects to the IOT platform over MQTT. It then published events every 15 seconds. Whenever the device enters a region the Geospatial service detects this, informs the IOT application and the IOT application notifies the device in an MQTT command. As the picture above shows, this causes an alert to be displayed to the user.

  8. View geospatial sensor data

    Once events have been published to the IOT platform we can view this data using the cloudant geospatial functions.

    To do this, login to bluemix and select the cloudant service used by these applications. Click on the “launch” button to bring up the cloudant dashboard.¬†

    This shows all the databases used above – select “eventdb” to bring up the dashboard for the events database.

    r22

    Click on the “+” button for design documents and select new geospatial index.

    Give the document a name (e.g. dd1) and press “create document and build index”.

    Now we have a new design document in the dashboard which can be used to view geospatial data. Clicking on this document launches a graphical view of the sensor data. 

    r20

    It there are many sensor reading, it may be necessary to increase the number of documents per page.

  9. Summary

    Here is our complete geofencing solution

     

    r0

    We have developed this using standard Bluemix components and some simple javascript applications. This allows us to track devices and check if they are entering or leaving regions. We have also seen how MQTT can be used to feed this information back to the device itself. Finally, we have viewed this sensor data on bluemix using standard geospatial tools in cloudant.

     

3 comments on"Geofencing with IOT, IBM Geospatial Analytics and Mapbox"

  1. mohanakrishna January 05, 2017

    Hello this project doesn’t work for after the third step when I am opening the ul to run the geofence manage I am getting error like this
    This page contains the following errors:

    error on line 1 at column 1: Document is empty
    Below is a rendering of the page up to the first error.

    please try to fix it

    thank in advance

  2. When I try to run the application the map UI does not show up, has anyone faced this problem and knows if there is some problem with the MAPS API or the files in the source code of the project?

  3. […] amount of data you can collect from mobile users is immense. With¬†IoT-enabled technology like geofencing¬†you can find out how much time each user spent in specific locations (booths, vendors, food, […]

Join The Discussion