Applying Policies on Devices Based on Geofencing

In this tutorial, you are writing an execution plan using the WSO2 EMM Siddhi extensions to disable the camera once the device enters a specified geo area and to enable the camera one the device leaves the specified geo area.

WSO2 IoT Server's analytics profile that runs on WSO2 Data Analytics Server (WSO2 DAS) uses execution plans to store the event processing logic. An execution plan is bound to an instance of the Siddhi Data Analytics Server runtime, which is responsible for the actual processing of events.

MobX employees bring their own devices to work. To ensure the security of corporate data, MobX wants the camera on the mobile devices to be disabled once the devices are within the office premise. Therefore, the MobX administrators write an execution plan using WSO2 IoT Server to disable the camera on the devices once the devices enter the office premise and to enable the camera on the devices once they leave the office premise.

Let's get started!

Setting up geofencing

Download WSO2 IoT Server's EMM solution.

If you are running WSO2 IoT Server, stop the server before proceeding to the next step.
Navigate to the <IOTS_HOME>/wso2/analytics/scripts directory via the terminal and run the following command. This installs the geo extension feature to WSO2 IoT Server.
```
mvn clean install -f siddhi-geo-extention-deployer.xml
```

Open the <IOTS_HOME>/conf/cdm-config.xml file and enable the GeoLocationConfiguration and PublishLocationResponse configurations.

This enables the geo extension feature in WSO2 IoT Server.

<GeoLocationConfiguration>
    <Enabled>true</Enabled>
</GeoLocationConfiguration>
<OperationAnalyticsConfiguration>
    <PublishLocationResponse>true</PublishLocationResponse>
    <PublishDeviceInfoResponse>false</PublishDeviceInfoResponse>
    <PublishOperationResponse>
        <Enabled>false</Enabled>
        <Operations>
            <!-- Publish specific operation responses -->
            <!--
                <Operation>BATTERY_LEVEL</Operation>
                <Operation>CHECK_LOCK_STATUS</Operation>
            -->
            <!-- use wildcard '*' to publish all responses -->
            <Operation>*</Operation>
        </Operations>
    </PublishOperationResponse>
</OperationAnalyticsConfiguration>

Start the WSO2 IoT Server broker, core, and analytics profiles, and sign in to the WSO2 IoT Server Device Management Console.
Click here for more information.
Start the WSO2 IoT Server broker profile.

cd <IOTS_HOME>/bin sh broker.sh

Start the WSO2 IoT Server core profile.

cd <IOTS_HOME>/bin sh iot-server.sh

Next, start the WSO2 IoT Server analytics profile.

cd <IOTS_HOME>/bin sh analytics.sh

Access the device management console.
For access via HTTP: http://<IOTS_HTTP_HOST>:9763/devicemgt/
For example: http://localhost:9763/devicemgt/
For access via secured HTTP: https://<IOTS_HTTPS_HOST>:9443/devicemgt/ For example: https://localhost:9443/devicemgt/
Enter the username and password, and sign in.

The system administrator will be able to log in using admin for both the username and password. However, other users will have to first register with WSO2 IoT Server before being able to log into the IoT Server device management console. For more information on creating a new account, see Registering with WSO2 IoT Server.
Click LOGIN. The respective device management console will change, based on the permissions assigned to the user.
For example, the device management console for an administrator is as follows:
Deploying in a multi-tenant environment
The geo analytics artifacts are deployed by default in the WSO2 IoT Server super tenant. However, if you are setting up geofencing in a multi-tenant environment, you have to deploy the geo analytics artifacts in each tenant.
1. Log in to the device management console using the tenant credentials.
2. Click the button and select Configuration Management > Platform Configurations.
3. Click the Deploy Geo Analytics Artifacts button. If required, you can use this button to re-deploy the geo analytics artifacts in the super tenant mode.

Creating the execution plan

In this step, you are creating the execution plan that contains the instructions on disabling and enabling the camera once the device enters and leaves the geo area respectively.

Access the WSO2 IoT Server's analytics management console: https://<IOTS_HTTPS_HOST>:9445/carbonFor example: https://localhost:9445/carbon/
Enter the Administrator credentials and sign in. The default administrator uses admin as the username and admin as the password.
On the Main tab, click Execution Plans.
Click Add Execution Plan.

Copy the execution plan that is given below and replace the sample content that is in the text box.

Want to know what happens in the execution plan?

Click here for more information.

Android and iOS devices that are enrolled with WSO2 IoT Server publishes the location updates to the org.wso2.iot.LocationStream. The execution plan that is given below is implemented to check the devices that belong to the group that has the ID 1. By default, in WSO2 IoT Server the Bring Your Own Device (BYOD) group has the group ID 1. If the device belongs to this group the device or devices are monitored to know if they enter or leave the geofence area.

If the device is inside the geofence, the camera on the device is disabled as the camera disable policy is enforced by the execution plan into the org.wso2.iot.operation stream. Similarly, if the device leaves the geofenced area, the camera is enabled as the camera enable policy is enforced by the execution plan into the org.wso2.iot.operation stream.

Further, the device is notified of the camera enable and disable status using the notification operation.

GeoFence_OfficeArea_operations execution plan

@Plan:name('GeoFence_OfficeArea_operations')

@Plan:statistics('false')

@Import('org.wso2.iot.LocationStream:1.0.0')
define stream dataIn (meta_deviceId string, meta_deviceType string, timeStamp long, latitude double, longitude double);

@Export('org.wso2.iot.operation:1.0.0')
define stream dataOut (meta_deviceIdentifiers string, meta_deviceType string, code string, type string, isEnabled bool, payLoad string);

define stream deviceWithinFenceStream (meta_deviceId string, meta_deviceType string, isWithin bool);
define stream deviceWithinFencePatternedStream (meta_deviceIdentifiers string, meta_deviceType string, isWithin bool);

/* Check if the device is within the geofence. */
from dataIn [device:isInGroup(1, meta_deviceId, meta_deviceType)]
select meta_deviceId, meta_deviceType, geo:within(longitude,latitude,"{'type':'Polygon','coordinates':[[[79.85213577747345, 6.909673257977737],[79.85266149044037,6.909673257977737],[79.85266149044037,6.91003538888127],[79.85213577747345,6.91003538888127],[79.85213577747345,6.909673257977737]]]}") as isWithin
insert into deviceWithinFenceStream;

/* Notify if the device moves across the geofence. */
partition with ( meta_deviceId of deviceWithinFenceStream )
begin
    from every fs1=deviceWithinFenceStream, fs2=deviceWithinFenceStream[fs1.isWithin != isWithin]
    select json:getArray(fs2.meta_deviceId) as meta_deviceIdentifiers, fs2.meta_deviceType, fs2.isWithin
    insert into deviceWithinFencePatternedStream;
end;

/* Push the camera policy to the device if the device enters the geofenced area. */
from deviceWithinFencePatternedStream
select meta_deviceIdentifiers, meta_deviceType, "CAMERA" as code, "COMMAND" as type, not isWithin as isEnabled, "{}" as payLoad
insert into dataOut;

/* Send a notification to the device indicating that the camera is disabled. */
from deviceWithinFencePatternedStream [isWithin == true]
select meta_deviceIdentifiers, meta_deviceType, "NOTIFICATION" as code, "PROFILE" as type, true as isEnabled, "{'messageText':'Your are in a restricted area that does not allows your to use the camera.','messageTitle':'Camera Disabled'}" as payLoad
insert into dataOut;

/* Send a notification to the device indicating that the camera is enabled.  */
from deviceWithinFencePatternedStream [isWithin == false]
select meta_deviceIdentifiers, meta_deviceType, "NOTIFICATION" as code, "PROFILE" as type, true as isEnabled, "{'messageText':'You able to use the camera as you are no longer in the restricted area.','messageTitle':'Camera Enabled'}" as payLoad
insert into dataOut;

Click Add Execution Plan.

Congratulations, you have successfully configured WSO2 IoT Server to enable and disable the camera based on the geo area!

Try it out

To try this tutorial out you need to enroll an Android Virtual Device, and follow the steps given below:

Enroll an Android Virtual Device as a Bring Your Own Device (BYOD). By default, the BYOD device group has the group ID 1.

For more information, see Android Virtual Device.
Updating the location of the device so that it is inside the geofenced area:
1. After the Android virtual device starts and it is enrolled with WSO2 IoT Server, click the more button.
2. Click Location, define the Longitude as 79.8525 and Latitude as 6.9099, and click Send.
  These coordinates are within the geofenced area that is defined in the execution plan.
  
  In order to save the device's energy, the WSO2 IoT Server's Android agent sends the device location to the server after five minutes from the last location update. Therefore, it takes a maximum of five minutes to update the location change. To verify if the location is updated, go to the enrolled device's page and click the location tab after five minutes.
  Five minutes after your last location update you see a notification on the Android Virtual Device mentioning that the device's camera is disabled.
  The execution plan you created, disables the device's camera when you enter the geofenced area.
  Now, when you try to access the camera you see the following message:
Updating the location of the device so that it is outside the geofenced area:
1. Click the more button on the Android Virtual Device.
2. Click Location, define the Longitude as 78.8525 and Latitude as 6.9099, and click Send. These coordinates are outside of the geofenced area that is defined in the execution plan.
  Five minutes after your last location update you see a notification on the Android Virtual Device mentioning that the device's camera is enabled.
  The execution plan you created, enables the device's camera when you move out of the geofenced area.
3. Try to access the device camera. You see that you are able to access it.
  Are you getting a Camera Error message?
  If the Android virtual device is unable to connect to your machine's camera, you get a message saying Camera Error. It is not caused by WSO2 IoT Server.

What's next?

Want to know more about the WSO2 IoT Server Siddhi extensions? See WSO2 EMM Siddhi Extensions.
Try out the tutorials listed below and see how the extensions described above are put into use.
- Sending Operations to Devices Based on Time
- Analyzing the Data Gathered from Devices