How to use geolocation

0. Introduction

This easy tutorial helps you to determine if a device is outside the established coordinates.
In this project you will learn how to:

  • Update devices coordinates from a data stream.
  • Determine if a device is outside the established coordinates.

Difficulty:

TOP

1. Create device coordinates

In your device you can configure latitude and longitude:

  • config latitude and longitude

Now you can view device position on the map:

  • device position on the map

TOP

2. Create listener

We have enhanced the listener creation process with our Flow Tool.

A listener in Altair SmartWorks can be associated to any hierarchy entity, from Project to Device. If you associate a listener to a project, all devices below the services of that project will be affected. If you associate a listener to service, all devices below the groups of that services will be affected. And so on.

In this example, we create a listener associated with our device. This listener waits for an event to occur in the context of the device and then evaluates the content: it updates the geolocation data of our device from the stream data and checks if the new position is within some predefined bounds.

To create a listener go to the control panel, then to “Rules” → “Listeners” and click on the new button. Select "Device" as "Entity type" and locate your device in the "Id" field.

Fill the fields with the following values and continue to the next step.

  • Name: The name that you prefer
  • Description: The description that you prefer
  • Entity type: Device
  • Entity id: Your id device
  • Event to listen: Event Data Persisted
  • Be sure to have your listener enabled if you want it to be executed
  • Click on the "Next Step: design the code" button to visually design the listener functionality
  • Listener creation

In the Flow editor we'll need to follow these steps:

  • Step 1: Drag and drop in the editor workspace a "update device" node and Double-click it to configure it with the values:
    Label: descriptive name of the node in the editor view. For example "Update geo data"
    Id_device: here you could directly type the Id_developer of our device (defaultDevice@exampleuser.exampleuser). But let's use a more generic way to define the searched device: select "metadata" in the drop-down associated to this field (so the content won't be treated as a literal string) and then select "Device". This indicates the node to use the id_developer of the device that "receives" the stream.
    Lat: here we want to assign the lat data contained in the stream payload data that triggers our listener. For this select "payload data" in the drop-down associated to this field and type lat.toFloat() (this is a facility to not have to write the former contaxt.data.lat.toFloat())
    Lon: again select "payload data" and type lon.toFloat()
    Click on the button "Done" to apply the changes
    Note that with the "Update device" node you only have to fill the data you want to update. The rest of the device data will remain unchanged.
  • Step 1: Update device node
  • Step 2: Drag and drop in the editor workspace a "function" node (a general purpose node that allows the user to use a custom Groovy code) and Double-click it to configure it with the values:
    Label: descriptive name of the node in the editor view. For example "Check new geolocation"
    Payload: here you can type the custom Groovy code device_in = device.inside(-3.693142, 40.4158134, 1000)
    Click on the button "Done" to apply the changes and connect the nodes.
  • Step 2: Check new geolocation
  • Step 3: Drag and drop in the editor workspace a "switch" node and Double-click it to configure it with the values:
    Label: descriptive name of the node in the editor view. For example "If outside"
    If condition: select "if" and fill in the following field with the code !device_in (the variable device_in was created in the previous node)
    Click on the button "Done" to apply the changes and connect the nodes.
  • Step 3: Switch node
  • Step 4: Drag and drop in the editor workspace a "send email" node and Double-click it to configure it with the values:
    Label: descriptive name of the node in the editor view. For example "Send OUT email"
    To: [[Your Email Here]]
    Subject: Device OUT of bounds
    Message: The device is now out of bounds!!!
    Click on the button "Done" to apply the changes and connect the nodes.
  • Step 4: Send email node
  • Step 5: Click on the "Save" button and check the listener data in the "Show" screen. You can have a look at the generated source code and use it later for debugging purposes.
  • Step 6: Resulting listener + source code

As you can see in the step 2 we use the method 'inside' of Device instance. This method is used to determine if a point is within coordinates.

  • Dynamic method: boolean device.inside(float longitude, float latitude, float distance)
  • Static method: boolean Device.inside(float longitude, float latitude, float distance, String id_developer_device)

Its time to test our listener. Send a data stream to this device.

TOP

3. Send data stream with coordinates

Now you can try to send a stream with coordinates.
In your data: {'lat': 40.4158134, 'lon': -3.693142}

Now your listener will be executed and you can view the new position on the map.

  • device updated with new location

Marker color

You can see that the marker on the map changes color depending on device status.

  • Green: OK
  • Orange: Disconnected
  • Grey: No status or data

TOP