Development Guide
Project Technology Stack
The Protocol Gateway Service (hereinafter referred to as Gateway) is developed in Java, by using Spring Boot 2 and Netty 4 to build the development framework, using Maven to build the project and manage the dependency, and using Lombok to simplify the code.
Please click to download SDK
Users are recommended to install Intellij IDEA for secondary development, and mark the /src/main/resource folder as Resources Root. In the project, the Java file starting with Sample represents example code.
The main class to launch in the project field is /src/main/java/com/cmiot/gateway/ProtocolGatewayService.java
Prerequisites
MQTT IoT Suite (new version) products and OneNET devices were created on the OneNET platform.
The Gateway service was created on the OneNET platform.
Configure Protocol Gateway Service
You can configure the Gateway using default configuration files. By default, the Gateway reads its configuration from gateway.conf under the default resource file path of your java project (default location: /src/main/resource/config). At the same time, the gateway project supports customized configuration. For this purpose, you just need to implement an interface for reading gateway configuration information (default location: /src/main/Java/com/cmiot/gateway/config) and annotate it as Spring Bean.
Default Configuration File
The Gateway uses typesafe.config to parse its configuration file, of which the parameters are described as follows.
| Parameter | Required or not | Description |
|---|---|---|
| connectionHost | No | The address at which MQTT connects to the OneNET platform is "tcp://183.230.40.96:1883" by default. Note here that this address should match the tlsSupport parameter. |
| serviceId | Yes | Gateway Service ID. |
| instanceName | Yes | Gateway service instance name. A tuple consisting of serviceId and instanceName identifies instance uniqueness. When the tuple is repeated, gateway control connection will be established only on the newly launched instance. |
| instanceKey | Yes | Gateway service instance, used for authentication. |
| transports | No | Gateway service protocol center, in this format: "transport:port, transport:port", e.g. "tcp:10086". Currently, the Gateway only supports TCP, and the default start port is 10086. |
| tlsSupport | No | Is OneNET MQTT access service TLS-encrypted? It is false by default, that is, not TLS encrypted. |
Implement Custom Protocol Encoder/Decoder
The function of Custom Protocol Encoder/Decoder is to realize the conversion between device data and internal protocol data, which should be implemented by users autonomously. The internal data are used to communicate with OneNET MQTT access service.
Default location: /src/main/java/com/cmiot/gateway/custom.
Custom Decoder
Custom Decoder decodes custom protocol data (binary array) into internal gateway data (ProtocolMessage). The Gateway performs different operations depending on MessageType in ProtocolMessage, e.g. LOGIN - device login, LOGOUT - device logout, etc. Please refer to the MessageType section for details.
Custom Encoder
Custom Decoder encodes internal gateway data (ProtocolMessage) into custom protocol data (binary array). Users can encode the internal data according to different MessageTypes, and then push them to the device or carry out continued processing.
MessageType
The Gateway processes the internal data according to different MessageTypes, which can be divided into two types: uplink and downlink. The uplink data are used for ascending data from device to OneNET MQTT access service, such as device login and logout (active), data point upload, etc.; and the downlink data are used for MQTT access response to the uplink data and actively descending data. MessageType is detailed as follows:
| MessageType | Uplink/ Downlink | Description |
|---|---|---|
| LOGIN | Uplink | Broker login (active) |
| LOGOUT | Uplink | Broker logout (active) |
| DP | Uplink | Data point upload |
| CMD_REPLY | Uplink | Command reply |
| IMAGE_UPDATE | Uplink | Device image update |
| IMAGE_GET | Downlink | Get device image |
| LOGIN_ACCEPTED_RESPONSE | Downlink | A response code to send when broker login succeeded |
| LOGIN_REJECTED_RESPONSE | Downlink | A response code to send when broker login failed |
| LOGOUT_ACCEPTED_RESPONSE | Downlink | A response code to send when broker logout succeeded |
| LOGOUT_NOTIFY_RESPONSE | Downlink | A response code to send when the broker is actively logged out by the platform |
| DP_ACCEPTED_RESPONSE | Downlink | A response code to send when the broker succeeded in uploading data points |
| DP_REJECTED_RESPONSE | Downlink | A response code to send when the broker failed to upload data points |
| DOWN_LINK_CMD | Downlink | The broker receives commands from the platform |
| CMD_REPLY_ACCEPTED_RESPONSE | Downlink | A response code to send when the broker succeeded in responding to the command |
| CMD_REPLY_REJECTED_RESPONSE | Downlink | A response code to send when the broker failed to respond to the command |
| IMAGE_UPDATE_ACCEPTED_RESPONSE | Downlink | A response code to send when the broker succeeded in updating device image |
| IMAGE_UPDATE_REJECTED_RESPONSE | Downlink | A response code to send when the broker failed to update device image |
| IMAGE_GET_ACCEPTED_RESPONSE | Downlink | A response code to send when the broker succeeded in getting device image |
| IMAGE_GET_REJECTED_RESPONSE | Downlink | A response code to send when the broker failed to get device image |
| IMAGE_DELTA | Downlink | A delta message to send when the broker receives device image from the platform |
| UNKNOWN | \ | Unknown type |