EdgeSense
Contents
- 1 Introduction
- 2 Installation Guide
- 3 Cloud
- 3.1 WISE-PaaS/EnSaaS
- 3.2 Azure
- 3.3 AWS
- 3.3.1 Connect device and data to AWS for Windows device – Protocol Converter using Node-Red
- 3.3.2 Connect device and data to AWS for Linux Ubuntu device – Protocol Converter using Greengrass
- 3.3.2.1 Prerequisites
- 3.3.2.2 Create Greengrass Group
- 3.3.2.3 Setup Greengrass Group
- 3.3.2.4 Run Greengrass Core in Your Device
- 3.3.2.5 Deploy Your Greengrass Group
- 3.3.2.6 Set Up Your AWS IoT Things
- 3.3.2.7 Install Your IoT Thing Certificate
- 3.3.2.8 Configure The Samples
- 3.3.2.9 Run the Protocol Converter Sample
- 4 IoT connectivity
- 5 Release
Introduction
WISE-PaaS/EdgeSense is an edge intelligence and sensing integration software solution that incorporates sensor data aggregation, cloud applications, edge analytics, and secure end-to-end data protection for fast and easy device-to-cloud operation. “Protocol Converter” is one of the major part of EdgeSense, it is an all-in-one message broker service which collects sensor data via various industrial protocols and then upload to cloud.
Installation Guide
For Windows Device
How To Install
- Step 1. Execute EdgeSense installer, click "Next >".
- Step 2. Select "I accept the ..." then click "Next >".
- Step 3. Select any cloud you would like to connect then click "Next >". (here we take WISE-PaaS/EnSaaS and RMM as example for below steps)
- Step 4. Click "Next >".
- Step 5. Click "Install".
- Step 6. Wait for installation finished.
- Step 7. Select "I agree to the ..." then click "Install".
- Step 8. Select "I agree to the ..." then click "Install".
- Step 9. Click "Finish". Now you have necessary component and agent installed in your device.
For Linux Ubuntu ( Docker version )
Basic Requirment:
- Host OS must be Linux Distribution (we developed and tested our software offering with Ubuntu 16.04 environment so below content is referring to this specific Linux distribution.)
- Docker Engine - Installation Guide ( Ubuntu )
- Docker compose - Installation Guid
- Hardward: Advantech x86_64 Platforms ( e.g. ARK-2121L...)
How To Install and Run - Protocol Converter Docker Container Services
# unzip installation package tar zxvf EdgeSense_1.0.2.tar.gz # Follow the readme to install your converter protocol
How To modify EnSaaS ID/Password and resart
# To fill your "IoTKey" then save and exit <IoTKey>304a99b5b452444c749a83bbb9e35dpow</IoTKey> $cd {Installed path}/Installer/packages/Plugins/docker-edgesense-image-x86/EdgeSense/AgentService/config/ $sudo vim agent_config.xml $sudo docker restart ensaas-ei-agent
How To config Modbus and resart service
$cd {Installed path}/Installer/packages/Plugins/docker-edgesense-image-x86/EdgeSense/EService-Modbus/config/ $sudo vim Modbus_Handler.ini $sudo docker restart service-modbus
How To Restart Service
// MQTT-BUS $sudo docker restart advigw-mqtt-bus // Node-RED $sudo docker restart advigw-node-red // Modbus_Handler Service $sudo docker restart service-modbus // HDD PMQ $sudo docker restart service-hddpmq // SUSIControl $sudo docker restart service-susi
How To Uninstall Edgent Sense Docker Image
$cd {Installed path}/Installer/packages/Plugins/docker-edgesense-image-x86/ $sudo ./deploy.sh rmi
Cloud
WISE-PaaS/EnSaaS
WISE-PaaS/EnSaaS is an open and standardized industrial IoT platform provided by Advantech Corp., and EdgeSense leverages cloud services on top of it to offer device management and visualization service.
You will be re-directed to WISE-PaaS online documentation site via below links.
Register account on EdgesSense Portal
Please visit this page for step by step instruction.
How to Connect Edge Devices to RMM Cloud
Please visit this page for step by step instruction.
Azure
Create Azure IoT Hub
To utilize Azure services, we need a Microsoft account to log in to azure portal. Following steps will create an azure iot hub to communicate with Advantech protocol converter modules.
Step 1. Log in to Microsoft Azure Portal
Step 2. Create a resource group
- Search “resource group” and create new one
- Input resource group name: protocol-conn-rg (for example)
- Select a location (service region): East Asia (for example)
Step 3. Create an azure iot hub
- Search “iot hub” and create new one
- Select Resource group created at step 2: click “Use existing” and select “protocol-conn-rg”
- Select Region: East Asia
- Input IoT hub name: protocol-con-hub (for example)
- Click on Review+Create
- Click on Create
Connect device and data to Azure for Windows device – Protocol Converter Using Node-RED
Cloud Environment Setup
Following steps will create an azure iot device to connect to iot hub created at previous section.
Step 1. Go to iot hub created at previous section: Resource groups → protocol-conn-rg → Overview → protocol-con-rg (for example)
Step 2. IoT Devices → Add
- Device ID: protocol-conn-device (for example)
- Authentication Type: select “Symmetric Key” for this tutorial
- Check “Auto Generate Keys”
- Connect device to IoT Hub: select “Enable”
- Save the configurations
- Select the created iot device to get device connection string
- Click to copy “Connection string-primary key” and make sure the "Connect device to IoT Hub" is "Enable"
"Connection string-primary key" will be used later in Node-Red "Connection String" field.
- Save the connection string in a text file for later use
Device Environment Setup
Following steps will configure device Node-RED nodes to enable communications between Advantech protocol converter modules and azure iot hub.
Step 1. Open Node-RED page in the web browser (default URI is http://127.0.0.1:1880)
Step 2. Copy following content and import it into Node-RED
[ {"id": "ce169f53.786dd" , "type": "tab", "label": "Protocol Connector ", "disabled": false, "info": ""}, {"id": "104120.85f37ee" , "type": "mqtt in", "z": "ce169f53.786dd", "name": "Data Recieved", "topic": "/cagent/admin/+/deviceinfo", "qos": "2", "broker": "23acb8c5.a15ad8", "x": 150, "y": 132, "wires": [["12642914.e549c7", "95d1843d.e8a5c8"]]}, {"id": "97d0f87d.614ea8", "type": "mqtt out", "z": "ce169f53.786dd", "name": "Auto-Report Request", "topic": "", "qos": "0", "retain": "false", "broker": "23acb8c5.a15ad8", "x": 692.0001220703125, "y": 401, "wires": []}, {"id": "12642914.e549c7", "type": "debug", "z": "ce169f53.786dd", "name": "", "active": true, "console": "false", "complete": "payload", "x": 340, "y": 112, "wires": []}, {"id": "6bacc623.4bc318", "type": "comment", "z": "ce169f53.786dd", "name": "Send Protocol Connector Sensor Data to Azure IoT Hub", "info": "", "x": 270, "y": 69.36331176757812, "wires": []}, {"id": "4a9698eb.3deed8", "type": "comment", "z": "ce169f53.786dd", "name": "Send Auto-Report Request to Internal MQTT", "info": "", "x": 240, "y": 296, "wires": []}, {"id": "3a7f0c9.34066f4", "type": "mqtt in", "z": "ce169f53.786dd", "name": "Handler Registered", "topic": "/cagent/admin/+/agentinfoack", "qos": "2", "broker": "23acb8c5.a15ad8", "x": 160, "y": 364.8398742675781, "wires": [["3cd5a503.a6b2ca"]]}, {"id": "3cd5a503.a6b2ca", "type": "function", "z": "ce169f53.786dd", "name": "pack auto report command", "func": "var auto_rpt_msg = function(device) {\n return {\n topic: \"/cagent/admin/\" + device + \"/agentcallbackreq\",\n payload: {\n \"susiCommData\": {\n \"commCmd\": 2053,\n \"requestItems\": {\"All\":{}},\n \"autoUploadIntervalSec\": 10,\n \"handlerName\": \"general\"\n }\n }\n };\n};\n\nvar registered = context.get(\"registered\") || [];\nvar dev_id = msg.topic.replace(/^\\/cagent\\/admin\\/|\\/agentinfoack$|\\/notify$/g, \"\");\nvar is_reg_msg = (\n msg.topic.endsWith(\"agentinfoack\") && JSON.parse(msg.payload).susiCommData.status\n);\nvar msg_out = (is_reg_msg || (!~registered.indexOf(dev_id)))? auto_rpt_msg(dev_id) : null;\n\nif(!~registered.indexOf(dev_id)) {\n registered.push(dev_id);\n}\n\ncontext.set(\"registered\", registered);\nreturn msg_out;\n", "outputs": 1, "noerr": 0, "x": 418.0195617675781, "y": 401.00390625, "wires": [["97d0f87d.614ea8"]]}, {"id": "95d1843d.e8a5c8", "type": "azureiothub", "z": "ce169f53.786dd", "name": "Send to Azure IoT Hub", "protocol": "http", "x": 370, "y": 152, "wires": [["ecc11415.86a138"]]}, {"id": "ecc11415.86a138", "type": "debug", "z": "ce169f53.786dd", "name": "", "active": true, "console": "false", "complete": "payload", "x": 601.5, "y": 151.29998779296875, "wires": []}, {"id": "bf50c923.03a288", "type": "comment", "z": "ce169f53.786dd", "name": "Display Cloud to Device Messages", "info": "", "x": 671, "y": 192, "wires": []}, {"id": "71829e36.9c78c" , "type": "mqtt in", "z": "ce169f53.786dd", "name": "Handler Heartbeat", "topic": "/cagent/admin/+/notify", "qos": "2", "broker": "23acb8c5.a15ad8", "x": 157, "y": 438, "wires": [["3cd5a503.a6b2ca"]]}, {"id": "23acb8c5.a15ad8", "type": "mqtt-broker", "z": "", "broker": "127.0.0.1", "port": "1883", "clientid": "", "usetls": false, "compatmode": true, "keepalive": "60", "cleansession": true, "willTopic": "", "willQos": "0", "willPayload": "", "birthTopic": "", "birthQos": "0", "birthPayload": ""} ]
Step 3. Select "Protocol Converter" tab and double click "Send to Azure IoT Hub" node to configure node settings.
Step 4. Copy the saved device "Connection String" and paste to "Connection String" field
Step 5. Click to complete edge device environment setups and make sure the states of MQTT nodes are "connected"Step 6. Jump to Monitor Messages for further steps.
Connect device and data to Azure for Linux Ubuntu device – Protocol Converter Using IoT Edge
Prerequisites
Before to perform Azure IoT Edge environment setup steps, please make sure all following packages and tools are available and are correctly setup.
Linux Host
- Docker:
1. Install Docker and check "docker" command is available. (the version number may be different).
Protocol Converter will install Python and IoT Edge Runtime Control Tool automatically, user could check the version to see if it's well installed.
- Python pip:
1. Install Python pip command.
sudo apt-get install python-pip
2. Make sure the “pip” command is available.
- IoT Edge Runtime Control Tool:
1. Install IoT Edge control script (may need to run as root)
pip install -U azure-iot-edge-runtime-ctl==1.0.0rc17
2. Make sure the “iotedgectl” command is available. (the version number may be different)
Cloud Environment Setup
Following steps will create an azure iot edge device at previously created iot hub.
Step 1. Create an iot edge device
- Go to iot hub created at previous section: Resource groups → protocol-conn-rg → protocol-conn-hub
- IoT Edge → Add IoT Edge Device
- Device ID: protocol-conn-device (for example)
- Authentication Type: select “Symmetric Key” for this tutorial
- Check “Auto Generate Keys”
- Connect device to IoT Hub: select “Enable”
- Select the created iot edge device to get device connection string
- Click to copy “Connection string-primary key” and make sure the "Connect device to IoT Hub" is "Enable"
- Save the connection string in a text file for later use
Device Environment Setup
Following steps will configure edge device to bind to azure iot edge device previously created.
Step 1. Configure the iot edge runtime (need administrator privileges on windows 10 host or root privileges on linux host)
- Open a command prompt and type following command. Replace "{your iot edge device connection string}" with the saved device connection string
sudo iotedgectl setup --connection-string "{your iot edge device connection string}" --auto-cert-gen-force-no-passwords
- Start the IoT Edge runtime
sudo iotedgectl start
- Check Docker to see that the IoT Edge agent is running as a module
sudo docker ps
Deploy an IoT edge device module to edge device
Step 1. Select iot edge device created at previous section
Step 2. Set Modules → Add IoT Edge Module
- Name: protocol-connector-module
- Image URI: advigw4x86/protocol-connector-azure-iot-edge:latest
- Container Create Options:
- In Windows host, paste following content
{ "Env": ["MQTT_HOST=10.0.75.1", "MQTT_PORT=1883"] }
- In Linux host, paste following content
{ "Env": ["MQTT_HOST=172.17.0.1", "MQTT_PORT=1883"] }
- Restart Policy: select “always”
- Desired Status: select “running”
- Click “Next” to specify routes step
- Paste following content to specify route and click “Next” to review template
{ "routes": { "moduleToIoTHub": "FROM /messages/modules/protocol-connector-module/outputs/output1 INTO $upstream" } }
- In the Review Template step, click “Submit”
- Return to the IoT Edge device details page and click Refresh. The "protocol-connector-module" should be running along with the IoT Edge runtime
Monitor Messages
.Device to Cloud (D2C)
- Get IoT Hub Connection String from below steps.
- Use iothub-explorer tool (require nodejs and npm) to monitor D2C messages.
npm install -g iothub-explorer iothub-explorer monitor-events {Your IoT Device id} --login "{your iot hub connection string}"When Installing iothub-explorer on Windows system, please use administrator role to execute cmd. Otherwise, the environment variable cannot be correctly written to the system. You can add the environment variable manually.
Cloud to Device (C2D)
- C2D message is not yet ready on IoT Edge public preview.
- For Node-RED protocol converter modules, we can take following steps to send C2D messages.
Step 1. Open Node-RED in web browser, select Protocol Converter and click the debug tab
Step 2. Go to iot device created at previous section: Resource groups → protocol-conn-rg → protocol-conn-hub → protocol-conn-device, then select "Message To Device"
Step 3. Type our cloud to device messages in "Message Body" field then click "Send Message".
Step 4. Back to Node-RED page, we can see the received message
AWS
Connect device and data to AWS for Windows device – Protocol Converter using Node-Red
Prerequisites:
- AWS account
- this example use service which is region in US East (N. Virginia).
Cloud Environment Setup
Step 1.Return the AWS console and go to IAM menu. Step 2.Click “user” menu Step 3.Click “Add user” button Step 4.Enter your user name. In this example user name is “Adv_test”.→ chose Programmatic access → Click “Next Permissions” button. Step 6.Choose AdministratorAccess → Click “Next: Review” button Step 7.Click “Create user”Step 8.Download the credentials. This is the last time these credentials will be available to download.
Step 9.Click “Download .csv” button Step 10. Go to AWS IoT Core. Step 11. Copy the endpoint from "Setting". The endpoint will be used in Node-Red setting later. Check if the region is N. Virginia before copying the endpint.Device Environment Setup
In this section, you will install Advantech Node-Red tool for and Configurate the setting to connect AWS IoT
- click on desktop to open NodeRED in web browser
Set up edge device environment
- Copy following NodeRED flow and import it into NodeRED:
[ {"id":"79179714.505328","type":"tab","label":"Protocol Connector ","disabled":false,"info":""},{"id":"d79da03e.4ac02","type":"mqtt in","z":"79179714.505328","name":"Data Recieved","topic":"/cagent/admin/+/deviceinfo","qos":"2","broker":"7c9c4d87.a21bd4","x":150,"y":132,"wires":[["f9b3112b.9e99a","d48faaf7.aded28"]]}, {"id":"d48faaf7.aded28","type":"debug","z":"79179714.505328","name":"","active":true,"console":"false","complete":"payload","x":340,"y":112,"wires":[]},{"id":"27eaa5d8.f85fea","type":"comment","z":"79179714.505328","name":"Send Protocol Connector Sensor Data to AWS IoT","info":"","x":260,"y":69.36331176757812,"wires":[]},{"id":"3dc94fa0.0fb2d","type":"comment","z":"79179714.505328","name":"Send Auto-Report Request to Internal MQTT","info":"","x":220,"y":296,"wires":[]},{"id":"f9b3112b.9e99a","type":"function","z":"79179714.505328","name":"messgae topic","func":"var device_id = 'DK10';\nvar plugin_id = msg.topic.replace(/^\\/cagent\\/admin\\/|\\/deviceinfo$/g, \"\");\nmsg.topic = 'protocol-conn/' + device_id + '/' + plugin_id;\nreturn msg;","outputs":1,"noerr":0,"x":350,"y":157.10000610351562,"wires":[["21def20a.3d43ae"]]},{"id":"a99e0e2f.e33a3","type":"mqtt out","z":"79179714.505328","name":"Auto-Report Request","topic":"","qos":"0","retain":"false","broker":"7c9c4d87.a21bd4","x":692.0001220703125,"y":401,"wires":[]},{"id":"d10bad11.60342","type":"mqtt in","z":"79179714.505328","name":"Handler Registered","topic":"/cagent/admin/+/agentinfoack","qos":"2","broker":"7c9c4d87.a21bd4","x":160,"y":364.8398742675781,"wires":[["e0848357.efe7a"]]},{"id":"e0848357.efe7a","type":"function","z":"79179714.505328","name":"pakcage auto report command","func":"var auto_rpt_msg = function(device) {\n return {\n topic: \"/cagent/admin/\" + device + \"/agentcallbackreq\",\n payload: {\n \"susiCommData\": {\n \"commCmd\": 2053,\n \"requestItems\": {\"All\":{}},\n \"autoUploadIntervalSec\": 10,\n \"handlerName\": \"general\"\n }\n }\n };\n};\n\nvar registered = context.get(\"registered\") || [];\nvar dev_id = msg.topic.replace(/^\\/cagent\\/admin\\/|\\/agentinfoack$|\\/notify$/g, \"\");\nvar is_reg_msg = (\n msg.topic.endsWith(\"agentinfoack\") && JSON.parse(msg.payload).susiCommData.status\n);\nvar msg_out = (is_reg_msg || (!~registered.indexOf(dev_id)))? auto_rpt_msg(dev_id): null;\n\nif(!~registered.indexOf(dev_id)) {\n registered.push(dev_id);\n}\n\ncontext.set(\"registered\", registered);\nreturn msg_out;\n","outputs":1,"noerr":0,"x":418.0195617675781,"y":401.00390625,"wires":[["a99e0e2f.e33a3"]]}, {"id":"5b81aa8.282ba54","type":"mqtt in","z":"79179714.505328","name":"Handler Heartbeat","topic":"/cagent/admin/+/notify","qos":"2","broker":"7c9c4d87.a21bd4","x":157,"y":438,"wires":[["e0848357.efe7a"]]}, {"id":"21def20a.3d43ae","type":"AWS IotData","z":"79179714.505328","aws":"b610e400.9f9db8","operation":"Publish","thingName":"","topic":"","payload":"","endPoint":"","name":"","x":535,"y":156.75,"wires":[[]]}, {"id":"7c9c4d87.a21bd4","type":"mqtt-broker","z":"","broker":"127.0.0.1","port":"1883","clientid":"","usetls":false,"compatmode":true,"keepalive":"60","cleansession":true,"willTopic":"","willQos":"0","willPayload":"","birthTopic":"","birthQos":"0","birthPayload":""}, {"id":"b610e400.9f9db8","type":"amazon config","z":"","name":"AWS","region":"us-east-1"} ]
- Switch to Protocol Converter tab and double click “IotData Publish” node to set device configuration.
- Click button
- Enter the Access Id and Secret Key which is on credentials .csv file.
- Enter the Name “IoT Pubilsh” and Endpoint, Endpoint is copied in AWS IoT Core.
- Check your message topic on the "message topic' function node
- Enter {your device id} in device_id, you can choose {your device id} which you want.
- Click NodeRED “Debug” tab, the sent messages will be displayed.
- For more information, see https://docs.aws.amazon.com/iot/latest/developerguide/topics.html
- if your settings is correct, then you can see the message in this area.
Connect device and data to AWS for Linux Ubuntu device – Protocol Converter using Greengrass
Prerequisites
AWS Account Linux Host OS version : Ubuntu 16.04 x64 Protocol Converter installation steps
Create Greengrass Group
Using the AWS IoT console, create an AWS IoT thing, certificate, and policy for your AWS Greengrass core device: Step 1. Go to the AWS IoT console and click Greengrass. Step 2. Create an AWS Greengrass group and name it GGC Step 3. Create an AWS IoT for Greengrass core Step 4. One-click to create Greengrass certificate and attach policy. Step 5. Download Certificate and Greengrass config. This Certificate will be used later for setup AWS IoT device.
Setup Greengrass Group
To define your Greengrass group, follow these steps:
- Add devices to your group
- Add Lambda functions to your group
- Add subscriptions to your group
Add Device to Your Group
Step 1.Go to the AWS IoT console. Step 2.In the navigation pane, select Greengrass and then Groups. Step 3.Click on your group, "GGC" Step 4.In the navigation pane, click Devices and then Add Device. Step 5. Enter AWS IoT Name Device and click Next Step 6. Using default setting to quick create access permissions and certificate. Step 7. Download certificate and finish this process. This Certificate will be used for running GreenGrass Core.Add Subscriptions to Your Group
Step 1.In the navigation pane, click Subscriptions and then Add Subscription. Step 2.Under Select a source, select the source of the subscription and click on Next.Step 3.Under Select a target, select the target of the subscription and click on Next.
Step 4.In the Optional topic filter, type the topic of the subscription " topic/MQTT ". Step 5.Click on finish to confirm and save subscription. Step 6.Review the subscription information.Run Greengrass Core in Your Device
/greengrass is located under Installer folder, e.g. {$Unzip Path} is ~/Desktop/Installer/packages/AWS/EISXGCC
To configure your core to recognize the AWS IoT thing, update the /greengrass/config/config.json file. and /greengrass/certs.
Copy certs and config with root permission, use the certificate for GreenGrass Core.
Step 1.sudo cp -R certs/ {$Unzip Path}/greengrass/
Step 2.sudo cp -R config/ {$Unzip Path}/greengrass/
Step 3.sudo cp root.ca.pem {$Unzip Path}/greengrass/certs/
root.ca.pem is just located under {$Unzip Path}.
If the original file under {$Unzip Path} is root-ca.pem, just rename it to root.ca.pem after copying to {$Unzip Path}/greengrass/certs/
# mv root-ca.pem root.ca.pem
The Greengrass core software is installed inside the /greengrass directory of your device.
Step 1.Make sure your device is connected to the Internet.
Deploy Your Greengrass Group
After running Greengrass core, you can deploy your Greengrass group to your device.
Step 1.Go to the AWS IoT console.
Step 2.In the navigation pane, select Greengrass and then Groups.
Step 3.Click on your group, GGC.
Step 4.In the navigation pane, click Deployments.
Set Up Your AWS IoT Things
When Greengrass group is deployed successful. You can setup AWS IoT Device which is defined in Greengrass group with Protocol Converter.
AWS IoT devices need certificates to authenticate with AWS IoT and retrieve the connectivity information of your Greengrass core. You downloaded these certificates in Add devices to your group Create device things.
Install Your IoT Thing Certificate
Use Certificate for setup AWS IoT device.
cp root-ca.pem {$Unzip Path}/ProtocolConnectorSample/certs
cp <id>.cert.pem {$Unzip Path}/ProtocolConnectorSample/certs
cp <id>.private.key {$Unzip Path}/ProtocolConnectorSample/certs
Configure The Samples
Inside the ProtocolConnectorSample/config/ directory you can find the configuration files SampleConfig.json for your things:
1. Please find your endpoint in Settings page in AWS IoT Console.
2. Fill in relative path of root-ca.pem.
3. Fill in relative path of <id>.cert.pem.
4. Fill in relatvie path of <id>.private.key
Run the Protocol Converter Sample
After setting AWS IoT you can execute protocol converter sample, In the ProtocolConnectorSample folder
IoT connectivity
How to use SUSI (Advantech HW information) plugin
Page under construction...
How to use Modbus plugin
Please visit this page for more details and plugin configuration.
How to use OPC-UA plugin
Currently our OPC-UA plugin is only available on Windows platform. Please visit this page for more details and plugin configuration.
How to use PMQ plugin
Advantech storage PMQ solution includes the deployment of the trained model to make predictions and visualization UI, and recommendations for corresponding strategies. Except storage PMQ service for Advantech hardware, the objective is to provide software developers basic concepts and better understating of PMQ deployment and to be more effective to bring your predictive model to production with Advantech PMQ architecture.
Visit this page for more details.
Release
Pages under construction...