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,
- Navigate to the <IOTS_HOME>/wso2/analytics/scripts directory and run the following command. This installs the geo extension feature to WSO2 IoT Server.
- 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. - 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 :
{API Response :
"name":"newDevice",
"deviceIdentifier":"device001",
"description":"this is a sampledevice",
"Type":"sample-device-type",
"enrolmentInfo":{"status":"ACTIVE","ownership":"BYOD"},
"Properties":[]
}
{You can use the above details to establish the device communication with the server.
"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"
}
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].
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=####
Job well done !!!
ReplyDelete