• Documentation
• Unit 2: Device Onboarding

Unit 2: Device Onboarding

To onboard a device using a protocol gateway, you need to first create a HTTP network module to upload data, a device protocol used to process the device onboarding protocol, and a protocol gateway to analyze and update the data.

Step 1: Creating a Network Module

1. In EnOS Management Console, select Device Onboarding > Network Modules.

2. Click New Network Module, and enter the following in the New Network Module window.

   • Name: HTTP Network Module
   • Type: HTTP Server
   • Description: HTTP server network module

   
   

3. Click OK to save the configuration.

   
   

   

For more information, see Network Modules.

Step 2: Creating a Device Protocol

In order to convert the data of the reported message, you need to create a method to “translate” the upstream data. This is done by following the method defined in https://github.com/EnvisionIot/third-party-protocol, and indicate the method that implements the ICodecPlugin into a JAR package.

For more information, see Device Protocols.

JAR Package

1. Include the dependency by adding the following code snippet.

   <dependency>
       <groupId>com.envisioniot.enos.third_party_protocol</groupId>
       <artifactId>core</artifactId>
       <version>1.0.0</version>
   </dependency>
   

   
   

2. Use the example code below to serialize the JSON data reported by the device into an object and obtain the measurement point information to report.

   
   

   • CustomData Class

   package com.envisioniot.enos.third_party_protocol.custom_codec.data;
   
   import lombok.AllArgsConstructor;
   import lombok.Data;
   import lombok.NoArgsConstructor;
   
   import java.util.List;
   
   @Data
   @NoArgsConstructor
   @AllArgsConstructor
   public class CustomData {
    private String identifier;
    private String msgType;
    private Integer hasMore;
    private Integer dtag;
    private List<ServiceItem> data;
   }
   

   
   

   • ServiceItem Class

   package com.envisioniot.enos.third_party_protocol.custom_codec.data;
   
   import lombok.AllArgsConstructor;
   import lombok.Data;
   import lombok.NoArgsConstructor;
   
   import java.util.Map;
   
   @Data
   @NoArgsConstructor
   @AllArgsConstructor
   public class ServiceItem {
    private String serviceId;
    private Map<String, Object> serviceData;
    private Long eventTime;
   }
   

   
   

   • PostMeasurePointPlugin Class

   package com.envisioniot.enos.third_party_protocol.custom_codec;
   
   import com.alibaba.fastjson.JSON;
   import com.envisioniot.enos.third_party_protocol.core.ICodecPlugin;
   import com.envisioniot.enos.third_party_protocol.core.element.PostedMeasurePoints;
   import com.envisioniot.enos.third_party_protocol.core.message.request.PostMeasurePointRequest;
   import com.envisioniot.enos.third_party_protocol.core.message.response.PostMeasurePointRspItemData;
   import com.envisioniot.enos.third_party_protocol.core.message.response.Response;
   import com.envisioniot.enos.third_party_protocol.custom_codec.data.CustomData;
   import com.envisioniot.enos.third_party_protocol.custom_codec.data.ServiceItem;
   import lombok.extern.slf4j.Slf4j;
   
   import java.util.*;
   
   @Slf4j
   public class PostMeasurePointPlugin implements ICodecPlugin<PostMeasurePointRequest, PostMeasurePointRspItemData> {
    private static final String FLOW_FIELD = "flow";
    private static final String INTERNAL_TEMPERATURE_FIELD = "internalTemperature";
   
    @Override
    public String getProtocol() {
      return "custom protocol";
    }
   
    @Override
    public PostMeasurePointRequest decode(Map<String, Object> meta, String originalReq) {
      try {
        final CustomData customData = JSON.parseObject(originalReq, CustomData.class);
   
        final String assetId = customData.getIdentifier();
   
        PostMeasurePointRequest request = new PostMeasurePointRequest();
   
        request.setIgnoreInvalidMeasurePoint(true);
        request.setRealtime(true);
   
        PostedMeasurePoints point = new PostedMeasurePoints();
        point.setAssetId(assetId);
   
        Map<String, Object> measurepoint = new HashMap<>();
        for (ServiceItem item : customData.getData()) {
          Map<String, Object> serviceData = item.getServiceData();
   
          try{
            final Integer flow = (Integer) serviceData.get(FLOW_FIELD);
              if (Objects.nonNull(flow)) {
                measurepoint.put(FLOW_FIELD, flow);
              }
          } catch (Throwable t) {
              log.warn(
                "convert data failed, field: {}, original data: {}",
                FLOW_FIELD,
                serviceData.get(FLOW_FIELD));
          }
   
          try{
            final String internalTemperature = (String) serviceData.get(INTERNAL_TEMPERATURE_FIELD);
            if (Objects.nonNull(internalTemperature)) {
              final Long numberOfTemperature = Long.valueOf(internalTemperature);
              measurepoint.put(INTERNAL_TEMPERATURE_FIELD, numberOfTemperature);
            }
          } catch (Throwable t) {
              log.warn(
                "convert data failed, field: {}, original data: {}",
                INTERNAL_TEMPERATURE_FIELD,
                serviceData.get(INTERNAL_TEMPERATURE_FIELD));
          }
        }
   
        point.setMeasurepoints(measurepoint);
   
        List<PostedMeasurePoints> measurepoints = new ArrayList<>();
        measurepoints.add(point);
   
        request.setMeasurepoints(measurepoints);
   
        return request;
      } catch (Throwable t) {
        log.error("fail to decode request, originalReq: {}", originalReq, t);
   
        return null;
      }
    }
   
    @Override
    public String encodeResponse(Map<String, Object> meta, String originalReq, Response<PostMeasurePointRspItemData> response) {
      return JSON.toJSONString(response);
    }
   }
   

   
   

3. Package the above into a JAR file.

Device Protocol

1. In EnOS Management Console, select Device Onboarding > Device Protocols.

2. Click New Device Protocol, and enter the following in the New Device Protocol window.

   • Name: Water Meter Codec
   • Method: JAR
   • Class Name: com.envisioniot.enos.third_party_protocol.custom_codec.PostMeasurePointPlugin
   • File: Upload the JAR file created above.
   • Description: Device protocol for water meter

   
   

3. Click Confirm to save the configuration.

   
   

   

Step 3: Creating a Protocol Gateway

Since the protocol gateway involves permission verification, before creating the protocol gateway, you need to create an application that can be used, and give the application read and write permissions for the device.

For more information, see Protocol Gateways.

Application

1. In EnOS Management Console, select Application Registration.

2. Click Create App, and enter the following in the Create App page.

   • Name: Water Meter App
   • Category: Other
   • Type: Web
   • Description: App for water meter

   
   

3. Click Confirm to save the configuration.

   
   

   

Protocol Gateway

1. In EnOS Management Console, select Device Onboarding > Protocol Gateways.

2. Click New Protocol Gateway, and enter the following in the New Protocol Gateway window.

   • New: Create from Scratch
   • Name: Water Meter Protocol Gateway
   • Type: HTTP Server
   • Network Module: HTTP Network Module
   • Protocol Route: /post > Water Meter Codec
   • Access Key: The access key of the application created above.
   • Secret Key: The secret key of the application created above.
   • Description: Protocol gateway for water meter

   
   

3. Click Confirm to save the configuration and the system will generate a protcol gateway ID.

   
   

   

Next Unit

Building the Routing Rule