Geo Analytics, Geo Alerts for Your Customer device Type Simplified with WSO2 IoT Server

WSO2 IoT Server is a combination WSO2's Open Source IoT Device Managment Platform and Mobile Device Platform. WSO2 IoT server's capabilities are exposed through industry standard Swagger annotated REST APIs. So that the novice players to the Experts n the IoT or Mobile device Management field, can use the full capabilities of the IoT server to manage there devices.

Lets see how simply connect your customer IoT device that required geo analytics and related alerts with IoT server and get a proper geo analytics dash board up and running.

Step 1: 

Get your copy of WSO2 IoT Server.

First of all Lets Download IoT Server from WSO2's official web site.

Step 2: 

Setting up Your WSO2 IoT Server.

WSO2 Server setup guide is well detailed setting up documentation. Please refer the documentation if you get more in-depth detail of the configurations and related details. 

Lets take a look at the basic configuration of IoT Server,

Enable geo fencing geo fencing configuration can be done following the following instructions,

1. Navigate to the <IOTS_HOME>/wso2/analytics/scripts directory and run the following command. This installs the geo extension feature to WSO2 IoT Server.

   mvn clean install -f siddhi-geo-extention-deployer.xml

2. Open the cdm-config.xml file found in the <IOTS_HOME>/conf folder and set the following properties under the <GeoLocationConfiguration> tag to true.
   This enables the geo extension feature in WSO2 IoT Server.
4. Please refer the official Monitoring Devices Using Location Based Services documentation for more details.

Step 3 :

Creating a new Device Type for You Custom IoT devices.

Creating a custom device type in WSO2 IoT Server is really simple. This can be achieved via the default device management console or via the REST API provided. Let's see how we can get this done,

Step 4 :

Customize the device view page for your new device type.

The new device type will be utilizing the default user interface defined in IoT server as it’s User Interface.

Device management console and needed configuration can be found in <IoT_HOME>/repository/deployment/server/jaggeryapps/devicemgt/ folder. You can simply follow the following instructions to customize the user interface of the new device type according to your needs,

You can see the set of units related to the default UI listed below, which can be found inside the devicemgt/app/units directory.

By Simply adding a new unit to the units folder with the following naming guideline you can change the user interface of your device type without changing the default device type views/UIs.

If your new devicetype name is my-new-device-type, Create new units with the naming by following the pattern below,

cdmf.unit.device.type.<YOUR DEVICE TYPE>.<UNIT NAME>

Example :

cdmf.unit.device.type.my-new-device-type.device-view

Please find the set of units created to have a separate ui for the device type android_sense listed below,

Same as the above approach by utilizing the provided device management APIs you have the ability of creating separate application with your own User interface.

Step 5:

How to communicate to the WSO2 IoT Server from your IoT Devices.

You can call the below API to communicate to the WSO2 IoT server using the access information you receive when creating an device on the Step 3.

How the new devices/device agent can communicate with the IoT server.

Sending the device details like listed below will enroll a new device and the API will return the needed details for the device communication and connectivity as listed below.

Device Payload :

{
"name":"newDevice",
"deviceIdentifier":"device001",
"description":"this is a sampledevice",
"Type":"sample-device-type",
"enrolmentInfo":{"status":"ACTIVE","ownership":"BYOD"},
"Properties":[]
}

API Response :

{
"type": "sample-device-type",
"deviceId": "device001",
"clientId": "0JVM6Tj5ypS7lNfTKDe5C1xipA8a",
"clientSecret": "jQHxLg1mOMlCh1WXt49nEvUX3mka",
"accessToken": "918f1640-005d-3030-9935-b5cd6ce38d15",
"refreshToken": "3a351691-4284-343d-bc5b-21837d980425",
"mqttGateway": "tcp://iot-host-name:1886",
"httpsGateway": "https://iot-host-name:8243",
"httpGateway": "http://iot-host-name:8280"
}

You can use the above details to establish the device communication with the server.

This API is to modify the device details. Please find a sample payload for this API is provided below,

{
"name":"newDevice",
"deviceIdentifier":"device001",
"description":"this is a sampledevice",
"enrolmentInfo":{"status":"ACTIVE","ownership":"BYOD"},
"Properties":[]
}

This API is used to disenroll and device from the system.

How to Execute/Retrieve command issued from the server

This API will provide the next pending operation in the operation queue, if there any. You can implement a pooling mechanism and check for pending operation iteratively and perform the operation when there is a operation and update the status accordingly if you are using HTTP transport. When using MQTT you can simply listen to the operation queue and get the operation requests when there is a new operation to be executed.

This API is used to update the status of a operation. You can change the life cycle of a operation like below,

PENDING/REPEAT >> IN PROGRESS >> COMPLETED/ERROR


This API is to list all the pending operation for a device.


This API is to check the status of operations of the a given device.
Publishing events to the IoT analytics server.


This API is to publish events received by the device client to the WSO2 Data Analytics Server (DAS).

Step 6:

Geofencing Dashboard Implementation - Read location data from the IoT server.

There are API’s available to retrieve geo data from the server,

GET /geo-services/stats/{deviceType}/{deviceId}

By simply calling the above API you can obtain all the resources related to the geo service functionalities.

GET /geo-services/deviceLocations

By Simple calling the above API you can obtain the location data of the devices.

You can find a sample implementation in [1].

[1] https://github.com/wso2/carbon-device-mgt/tree/master/components/device-mgt/org.wso2.carbon.device.mgt.ui/src/main/resources/jaggeryapps/devicemgt/app/units/cdmf.unit.geo-dashboard

Create Geo Alerts

Creating and Managing Geo Alerts can be performed via the APIs Listed below,
Find the API Details below for Geo Alert Management

POST alerts/{alertType}/{deviceType}/{deviceId}

Create Geo alerts for the device

PUT alerts/{alertType}/{deviceType}/{deviceId}

Update Geo alerts for the device

GET alerts/{alertType}/{deviceType}/{deviceId}

Retrieve Geo alerts for the device

GET alerts/history/{deviceType}/{deviceId}

Retrieve Geo alerts history for the device

DELETE alerts/{alertType}/{deviceType}/{deviceId}

Deletes Geo alerts for the device

Create Enter Alerts

Simply Send a POST request to /api/device-mgt/v1.0/geo-services/alerts/Within/<DEVICE_TYPE>/<DEVICE_ID> with the a payload which follow the following sample’s formatting,

{

           'parseData': {

                                           'geoFenceGeoJSON': <GEO_FENCE_BORDER_JSON>,

                                           'executionPlanName': <PLAN_NAME>,

                                           'areaName': <AREA_NAME>,

                                           'deviceId' : <DEVICE_ID>

                                       },

           'executionPlan': ‘Within’’,

           'customName': <AREA_NAME>,

           'queryName': <QUERT_NAME>,

           'cepAction': 'deploy',

           'deviceId' : <DEVICE_ID>

}

Create Exit Alerts

Simply Send a POST request to /api/device-mgt/v1.0/geo-services/alerts/Exit/<DEVICE_TYPE>/<DEVICE_ID> with the a payload which follow the following sample’s formatting,

{

           'parseData': {

                                           'geoFenceGeoJSON': <GEO_FENCE_BORDER_JSON>,

                                           'executionPlanName': <PLAN_NAME>,

                                           'areaName': <AREA_NAME>,

                                           'deviceId' : <DEVICE_ID>

                                       },

           'executionPlan': ‘Exit’,

           'customName': <AREA_NAME>,

           'queryName': <QUERT_NAME>,

           'cepAction': 'deploy',

           'deviceId' : <DEVICE_ID>

}

Create Speed/Movement Alerts

Simply Send a POST request to /api/device-mgt/v1.0/geo-services/alerts/Speed/<DEVICE_TYPE>/<DEVICE_ID> with the a payload which follow the following sample’s formatting,

{

           'parseData':{

'speedAlertValue': <SPEED>,

'deviceId': <DEVICE_ID>

},

           'executionPlan': 'Speed',

           'customName': <CUSTOME_NAME / NULL>,

           'cepAction': 'edit',

           'deviceId': <DEVICE_ID>

}

You can simulate data using the WSO2 analytics server inorder to test and develop geo alert relate scenarios. Let's see how we can simulate geo location using WSO2 Analytics in IoT Server.

Combine location and geo alert for visualizations

In order to retrieve the updated location data from devices open a web socket for the below socket,

https://iot.analytics.host/iot.per.device.stream.geo.FusedSpatialEvent/1.0.0?deviceId=####&deviceType=#####&websocketToken=#####

In order to retrieve the alerts and related data from devices open a web socket for the below socket,

https://iot.analytics.host/iot.per.device.stream.geo.AlertsNotifications/1.0.0?deviceId=####"&deviceType=####&websocketToken=#### 

Lets take a look at the final result you can archive by following above steps.

Configure Device communication when using an existing SSL Certificated with Enterprise Mobility Manager

The two main components of WSO2 Enterprise Mobility Manager are mobile device management and mobile application management. Setting up WSO2 EMM can be done by following the “Getting Started” guide as mentioned in the documentation. This article mainly emphasizes on how to obtain the certification configuration for your personal domain.

Enrolled devices and WSO2 Enterprise Mobility Manager communicates using the HTTPS protocol. This is to make sure that the private and sensitive data stored in the mobile device cannot be retrieved by a third party or unauthorized personals. All the communication carried out between devices, APNS and EMM server is based on certificates included in the key-store files with the extension “jks”. These security features are critical since EMM supports both cooperate owned (COPE) and personal (BOYD) device management. In the section “Configuring the product” guide you have been provided with the steps to configure the EMM server to used in your local subnet where the server and the devices uses a SSL certificate issued by the inbuilt Certificate Authority of the EMM server.

Communications between devices and EMM server

WSO2 EMM server consists of the following components:

• SCEP server component.
• CA server component.
• Device Management Component.

The iOS device acts as a SCEP client where it sends the SCEP request to the Server. For enrollment purposes, this communication requires a certificate which will be generated by the CA server component of EMM. The iOS device will generate a private/public key pair and send a certificate signing/authorization request to the CA where the CA component will need to generate the public key certificate and store the public key for encryption which will be used later.

There is communication between IOS devices and APNS as well as Android devices and GCM for policy monitoring and to perform operations. All the devices will communicate with the EMM server using the agent applications. All these communications must be secured using certificates.

You can see the communication flow in Figure 1 given below.

In order to provide secure communication between the components represented in Figure 1, you have to obtain an SSL certificate for your domain from a Certificate Authority. When hosted under a public domain the obtained SSL certificates needs to be included into the key stores.

Obtaining an SSL Certificates for your domain

You can choose one of the SSL certificate providers available in the market according to your requirements and budget. You can successfully obtain an SSL certificate for your domain by following the steps provided below accordingly:

1. Purchase a SSL certificate.
2. Create a CSR form including your domain and project data
3. Submit the CSR to the SSL vendor
4. Verify the CSR request by validating that you control the domain the certificate will protect.
5. Your SSL certificate will be delivered to you or can be downloaded as facilitated by your certificate vendor.

You can follow the “Get SSL on my website” guide for more information on how to obtain SSL certification.

Configuring for IOS device management

Configuring the IOS device management and communications is a three step process :

1. Obtaining a signed CSR from WSO2.
2. Configuring EMM server for IOS device management.
3. Configuring the IOS client.

Obtaining a signed CSR from WSO2

Create a Certificate Signing Request (CSR) file from the EMM server using your private key. You can use commands given below to generate the CSR file:

openssl genrsa -des3 -out <Your_Private_Key_File> 2048

openssl req -new -key <Your_Private_Key_File> -out <You_CSR_File>

Make sure to create both Your_Private_Key_File and Your_CSR_File files with .pem extension

Provide correct information to the prompted questions related to your organization and the project. Make sure to provide the actual organization name as this is a required field. The Email address provided should be valid as this will act as the identification of your CSR request in order to identify you in a CSR expiration situation. Common name stands for the fully qualified domain name of your server. Make sure that the information you have provided is of high accuracy since the artifacts provided will bind to the provided domain name. IOS device can be only managed by the server which is hosted under the provided host name.

You can submit the CSR request to the “Obtain the signed CSR file” form. Make sure to enter the same information as you entered in the CSR request when filling the above form.

You will be provided with the following artifacts which is required to configure the EMM server to manage IOS devices:

1. The signed CSR file in .plst format.
2. Agent source code.
3. P2 repository, which contains the feature list.

Please refer “Obtaining the Signed CSR File” guide for more information on obtaining a signed CSR file.

Configuring EMM server for IOS device management

IOS server configuration is a complex and prolonged process which can be described by the following steps. By following these steps in order you can easily configure the EMM server for iOS device management:

1. Installing IOS feature to EMM server.
2. Configure general IOS server settings.
3. Generate the MDM APNS certificate.

Installing IOS feature to the EMM server

Start the EMM server in order to install the features from the P2 repository obtained via the CSR request.

You can navigate to the carbon console using <YOUR_DOMAIN>/carbon and then navigate to the configure tab. Then select the features option from the list.

IOS related features will be available in the P2 repository provided to you with the signed CSR. Install all the three features given. After the installation of the features is completed, stop the EMM server and process to the following location : <EMM_HOME>/repository/conf

You will find a new configuration file “ios-config.xml” in the directory. Modify the “iOSEMMConfigurations” accordingly. Please refer to “Installing WSO2 EMM iOS Features via the P2 Repository” guide for more information.

Configure general IOS server settings.

In order to setup your server with IOS, follow the instructions given in “ General iOS Server Configurations” guide until Step 5.

After completing Step 5 follow the instructions given below:

• Convert the downloaded ssl certificates from your vendor to .pem files.

openssl x509 -in <RA CRT> -out <RA CERT PEM>

Example:

openssl x509 -in your-domain-com-apache.crt -out your-domain-com-apache.pem

openssl x509 -in your-domain-com-ee.crt -out your-domain-com-ee.pem

• Create a certificate chain with the root and intermediate certifications.

cat <CERTIFCATE 1> <CERTIFICATE 2> ... >> <CERTIFICATE CHAIN>

Example:

cat your-domain-com-apache.pem your-domain-com-ee.pem >> clientcertchain.pem

cat your-domain-com-apache.crt your-domain-com-ee.crt >> clientcertchain.crt

• Export the SSL certificate chain file as a PKCS12 file with "wso2carbon" as the alias.

openssl pkcs12 -export -out <KEYSTORE>.p12 -inkey <RSA_key>.key -in clientcertchain.crt -CAfile clientcertchain.pem -name "<alias>"

Example:

openssl pkcs12 -export -out KEYSTORE.p12 -inkey ia.key -in clientcertchain.crt -CAfile clientcertchain.pem -name "wso2carbon"

After following the steps as above resume the configuration from Step 7.b as in “General iOS Server Configurations” guide.

Note that Step 6 and 7.a need to be skipped since the server configuration mentioned in those steps is for the public domain with already obtained SSL certificates.

Generate the MDM APNS certificate.

Go to the Apple Push Certificate Portal and upload the .plist file provided with the signed CSR from WSO2 and generate the MDM certificate. Follow the instructions given in “Generate MDM APNS Certificate” guide in order to convert the downloaded certificate to .pxf format.

After completing the instructions given, you can proceed with the IOS platform configuration as instructed in the “IOS Platform Configuration” guide.

Configuring Android device management

To enable secure communication between android devices and your EMM server please follow the “Android Configurations” guide. You can skip the certificate generation described in Step 1 under “Generating a BKS File” and move to Step 2 directly since you have already completed the above when configuring the IOS device communication.

If not follow the IOS Configuration instructions given above for certificate generation. Do not follow Step 1 mentioned under “Generating a BKS File” in the documentation.

Configuring Windows device management

There are no additional configurations needed to enable windows device management.