Connecting Devices to EnOS through EnOS Edge


This tutorial walks you through how to connect devices to EnOS Cloud through EnOS Edge.


EnOS Edge, as a software, can be deployed on various hardware. For this tutorial, the EnOS Edge software is installed on a Dell Edge Gateway 3000. The deployment of Edge software on a hardware does not require any user action. For Edge deployment, contact the EnOS Edge deployment personnel.

Scenario

  • An IEC104 simulator is installed on a laptop to simulate three electric meters that communicate through the IEC104 protocol.

    Note

    The tools can only be installed on a separate machine (not Envision Digital office laptop or PC) under a controlled environment for testing purpose only. DO NOT connect to the office network. Uninstall it after testing.

  • The simulated devices are connected to the EnOS Edge as sub-devices.

  • EnOS Edge is connected to the network to communicate with EnOS Cloud through the standard protocol, MQTT.


../_images/tutorial_blueprint.png

Step 1: Defining Models

A model is the abstraction of the features of an object connected to EnOS. It defines the features of a device, including the attributes, measurement points, services, and events. For more information about models, see Device Modeling.


The model of the EnOS Edge is provided as a public model in EnOS. In the EnOS Management Console, click Model from the left navigation menu, click the Public tab, and search for EnOS_Edge_Standard_Model. You can view its basic information and feature definitions by clicking the View icon view.


In this step, we need to create models for the simulated sub-devices before they can be connected to EnOS.

  1. Go to Model. At the Private tab, click New Model.

  2. In the New Model pop-up, fill in the following fields.

    Model Information

    Field

    Value

    Identifier

    TrainingMeter

    Model Name

    TrainingMeter

    Catetory

    Training

    Created From

    No

    Source Model

    No

    Description

    Meter model for training


    ../_images/tutorial_creating_model.png


  3. Click the Edit icon edit for TrainingMeter. Go to the Feature Definition tab and create 4 measurement points by doing the following for each measurement point.

    1. Click Add > Create Custom Feature.

    2. Fill in the fields as per the table below in the pop-up.

    3. Click Confirm.

    Measurement Point Information

    Measurement Point

    Feature Type

    Name

    Identifier

    Point Type

    Quality Indicator

    Data Type

    Default Value

    Unit

    Required

    Description

    1

    Measurement Points

    Ua

    Meter.Ua

    AI

    No

    double

    Electric Potential: volt | V

    Leave it blank

    2

    Measurement Points

    P

    Meter.ActivePower

    AI

    No

    double

    Power: kilowatt | kW

    Leave it blank

    3

    Measurement Points

    Q

    Meter.ReactivePower

    AI

    No

    double

    Power: KiloVolt Ampere Reactive | kVar

    Leave it blank

    4

    Measurement Points

    Ia

    Meter.Ia

    AI

    No

    double

    Electric Current: ampere | A

    Leave it blank
    ../_images/tutorial_create_measuring_points.png


You have now created the model for the simulated sub-devices we will use to connect to the Edge.

Step 2: Creating Products

Now that we have defined the model, we need to create products based on the device and Edge models.


A product is a collection of devices with identical features. While a model abstracts device features from 4 aspects (attributes, measurement points, services, and events), a product further defines the communication parameters for the device.


  1. Go to Asset Management > Product. Click New Product.

  2. In the New Product pop-up, fill in the following fields.

    Product Information for Simulated Devices

    Field

    Value

    Product Name

    training_meter

    Asset Type

    Device

    Model

    TrainingMeter

    Data Type

    JSON

    Certificate-Based Authentication

    Disabled

    Description

    Electric meter for training


    ../_images/tutorial_creating_product_for_device.png


You have created the product for simulated meters. Now do the same thing for the Edge device.

../_images/tutorial_creating_product_for_edge.png


We are now ready to create the device instances on EnOS.

Step 3: Creating Device Instances

A device is created from a product so that it inherits not only the basic features of the model, but also the communication parameters of the product (such as the product key and device key used for authentication). In this step we need to create devices on EnOS for the Edge and its sub-devices.


  1. Go to Asset Management > Device Asset and click New Device.

  2. In the New Device pop-up window, fill in the following fields.

    Device Information for Edge

    Field

    Value

    Product

    EnOS_Edge_Standard_Product

    Device Key

    Leave it blank

    Device Name

    Edge01

    Time Zone/City

    UTC+08:00

    edge_type

    0: EdgeGateway


    ../_images/tutorial_creating_device_for_edge.png


A device instance for Edge is now created. For the sub-devices, we will use our laptop to simulate three electric meters that will be connected to Edge. We will name them “meter01”, “meter02”, and “meter03”. Repeat the steps for creating a device instance and use the information as per the below for the 3 sub-devices.

Device Information for Sub-devices (Electric meter)

Field

Value

Product

training_meter

Device Key

Leave it blank

Device Name

meter01, meter02, and meter03

Time Zone/City

UTC+08:00


The Edge and sub-device instances are now in the device list.

../_images/tutorial_device_list.png

Step 4: Creating Device Template to Map Data Points

The device template determines how data collected from a device by using a protocol is mapped to the model measurement points defined on EnOS Cloud.


  1. Go to EnOS Edge > Template and click New Template.

  2. In the Add Template pop-up and fill in the following fields.

    Asset Tree Information for Edge

    Field

    Value

    Template Name

    meter

    Brand

    Envision (or any brand as you see fit)

    Device Type

    Envision sample (or any type as you see fit)

    Version

    v1.0 (or any random version number)

    Model

    TrainingMeter


    ../_images/tutorial_add_template.png


  3. Find the template you just created and click its Edit icon edit.

  4. In the Edit Template pop-up, click the Download Template icon download. Next, click the Download icon download2 to download the point.xlsx of the “IEC104-Client-linux v3.0_debug” as this is the protocol we are going to use for this tutorial.

  5. Open the point.xlsx you just downloaded.


    point.xlsx contains the attributes of the collection and control points to be reported to Edge. Since we have defined 4 measurement points for the device model in Step 1, we need to create 4 collection points so that they can be mapped to the 4 measurement points later.


    When you first open the point.xlsx, it will look like the following with the Chinese characters from left to right on the first row meaning measurement point, point number, value type, point type, coefficient, base value, and alias.

    ../_images/tutorial_point_csv_original.png


    Let us edit point.xlsx so that it looks like this.

    ../_images/tutorial_point_csv_edited.png


    As you can see, we changed the measurement point, value type, and point type to match the “Identifier”, “Data Type”, and “Point Type” defined in the model in Step 1.

    Note

    For point numbers, they must be continuous positive integers and follow the order in which the collection points are sent to EnOS as prescribed in the channel table.


  6. Save and close point.xlsx.

  7. Go back to EnOS Edge > Template > Edit Template. Click the Upload icon upload to upload the point.xlsx you just edited.

  8. In the Edit Template page, click the Mapping Points icon point_mapping for each measurement point.

  9. In the pop-up, select the collection point in the Collect tab with the description that matches the measurement point’s identifier and click Confirm.


    By doing this, you map the measurement points defined in our model to the collection points defined in point.xlsx.

    ../_images/tutorial_point_mapping.png


  10. Repeat #8 and #9 until all the measurement points are properly mapped. Then click Save.


By now we have completed configuring our template. This means that when we set up our Edge and connects it to EnOS Cloud and thesub-devices, the collection points from the simulated sub-devices can be properly mapped to the measurement points defined in the model.

Step 5: Configuring Edge

In this step, we will add the Edge device we created in Asset Management to Edge Management, configure its connection with the sub-devices, and configure the offset value for the measurement points of each sub-device.


  1. Go to EnOS Edge > Edge Management and click New Edge.

  2. In the New Edge pop-up window, select the Edge we added and click Confirm.

  3. Click the View icon view of the Edge you just added.

  4. In the Edge Detail page, click More beside the Publish button and select Download Edge Info(Main) to download the configuration file for the Edge device.

  5. Give the downloaded box.conf to an EnOS Edge support personnel and let the support personnel configure the Edge device using the box.conf. After the support personnel has configured the Edge device, it can connect to EnOS once it is powered on.

  6. In the Edge Detail page, click the Access Management tab. Click the Add Connection icon add_conn in the Ethernet tab.

  7. In the Add Connection pop-up window, fill in the following fields.

    Asset Tree Information for Edge

    Field

    Value

    Name

    Meter_Training

    Mode

    TCP/IP Client

    Short Connection

    Disabled

    Dynamic Template

    Disabled

    Primary Interface

    The IPv4 Address of your laptop. For port you can give it a random integer grater than or equals to 1000.

    Standby Interface

    Leave it blank

    Protocol Type

    IEC104

    Protocol

    IEC104-Client-linux v3.0_release

    Configuration File

    No action is required. But you might have to modify the configuration if you use other protocols or as needed.


    ../_images/tutorial_add_connection.png


  8. Click Confirm. You have now created a connection for the Edge device.

  9. Click to expand the connection you just created.

  10. Click Add Device. In the Add Device window, select the product training_meter we just created, and check all three devices meter01, meter02, and meter03.

  11. Under Template Setting, select the template we created for these device, meter.

  12. Click Save.

  13. Click to expand the connection. In the device list, click the Edit icon edit of any device.

  14. In the Edit Device pop-up, set the AI Offset using the format “a-b#c-d”, with a, b, c, d representing integers and a < b, c < d. “-” indicates that this is a value range, while “#” indicates that the range can be discontinuous.


    The offset value range is used to identify which values in the simulation scheme file belong to this device.


    We need to do a little bit of math here. Since there are 4 measurement points we need to map to every device, we must make sure that there are 4 integers in the value ranges of one device, both ends of a range included.


    In this example, in order to have four integers for one device. We can set the AI Offset as “2-5” or “2-3#6-7”. We shall use “2-5” for convenience’s sake.


  15. Click Confirm.

  16. Repeat #14 and #15 for the remaining devices. Ensure that all the four AI offset ranges are unique, and do not overlap.

Step 6: Installing and Configuring the IEC104 Protocol Simulator

We are almost there! In this step, we will install a protocol simulator, which simulates devices that send measurement point data in the IEC104 protocol to Edge, on our laptop. We will then configure how this simulator sends data to EnOS and finally, kick off the simulation.


  1. Download the IECServer.exe and iec_ai_12.properties.

  2. Open iec_ai_12.properties with a text editor (we recommend Notepad++).


    Each item in this file represents a measurement point. As we have 4 measurement points each for 3 electric meters, the total measurement points is 12, as there are in this file.


    We need to change their “IOB” values so that they can be properly mapped to the measurement points of each device.


    Dividing the items into 3 groups, ITEM1 to ITEM4, ITEM5 to ITEM8, and ITEM9 to ITEM12, each group represents the 4 measurement points of an electric meter.


    Suppose ITEM1 to ITEM4 are the measurement points of meter01, whose AI offset is 2-5 as configured in Step 6. Then the IOB values of ITEM1 to ITEM4 should be 16385+2, 16385+3, 16385+4, 16385+5, i.e., 16387, 16388, 16389, 16390. 16385 is the start address for the AI data prescribed in the protocol IEC104’s protocol.sys.


    Repeat this step for all items in this configuration file and save your changes.


  3. Open IECServer.exe, click Load, locate and select the configuraion file you just edited, and click Open to load the configuration file into the simulator.

  4. Fill in the box next to the StartServer button with the same port as you set as the address of your sub-device connection. In this case, it is 2404.


    You can find the port number as follows.

    1. Go to EnOS Edge > Edge Management.

    2. Click the View icon view to go to the Edge Detail page of the Edge you created.

    3. Click to the Access Management tab, and you can see the port number in the Address field of the connection.


  5. Click StartServer to start the simulation.

    ../_images/tutorial_iec104_simulator.png

Step 7: Viewing the Data on EnOS Management Console

Now let us go to EnOS Edge > Edge Management, click the View icon view for the Edge, and go to the Access Management tab. Click to expand the connection. The devices now have a green light in front of them, indicating a successful connection.

../_images/tutorial_connection_success.png


Click the View icon view of any device to view the data that is coming from our simulator.

../_images/tutorial_device_data.png


Congratulations! You have learned how to connect an Edge device to EnOS, and use a simulator to simulate devices transferring data through Edge to EnOS cloud.