Protocol Gateways¶

Protocol Gateways are responsible for running the gateway logic, analyzing and generating model/product/device data or updating device data after receiving the corresponding data specified by the device protocol. The generated data will be in the EnOS Management Console and the subsequent updating of the device data can be done using protocols such as MQTT.

You can create, view, edit, delete, and start/stop the protocol gateways. You can also export protocol gateway details in JSON and use it to import a new protcol gateway with the same configuration.

Before You Start¶

You need to be assigned the Device Management Administrator policy. If you are not assigned, contact your OU administrator. For more information about policies in EnOS, see Policies, Roles, and Permissions.
Ensure that you have created the required Network Module and Device Protocol.
Ensure that you have applied for the Protocol Gateway Resource at EnOS Console Management > Resource Management > Resource List. For more information about requesting resources, see Resource Management on EnOS.

Managing Protocol Gateways¶

Creating Protocol Gateways¶

Log in to the EnOS Management Console, go to Device Onboarding > Protocol Gateways > Private Gateways, and you will see the list of protocol gateways that have been created.
Click New Protocol Gateway.
You can create a protocol gateway from scratch or create it based on template. To view the list of available templates and their details, go to Protocol Gateways > Public Gateways. For more information, see System-Defined Templates.
- Create from Scratch: Proceed to the next step.
- Create from Template: Select a template from the Template drop-down and proceed to the next step. Type, Network Module, and Protocol Route will be auto-filled based on the selected template.
Fill in the information as per the below.
- Name: Enter a name for the protocol gateway. You can click the Internationalization icon to enter customized names for different locales.
- Type: Select the network module type.
- Network Module: Select the network module. The choice of network module will determine the protocol connection method. For more information on how to establish a connection using MQTT/Websocket protocol, see Establishing Connection Using MQTT/WebSocket Protocols.
- Protocol Route: Click + URL to map a URL route to a device protocol. Enter the route starting with “/”, and select the device protocol to map it with. The maximum number of routes that you can add is 5.
  
  The choice of the device protocol will determine the data processing method. By mapping protocols to different routes, the same protocol gateway will be able to handle different requests.
  - For example, for HTTP protocol, mapping “/createDevice” and “/updateModel” routes to the corresponding device protocols for creating a device and updating a model enables the creating of device and updating of model when sending a POST request to http://URL/createDevice and http://URL/updateModel respectively.
  - For MQTT/WebSocket, the routes are the topics. For example, the subscribe topic for “/createDevice” would be /createDevice_reply and the publish topic would be /createDevice.
  For more information on how to generate the URL for different protocols, see Generating URL.
- Authenticate Token: Toggle on the switch for token authentication for added security. If toggled on, there is a need to add the token information in the header for HTTP and in the client ID for MQTT/WebSocket during connection. For more information on how to generate the token and how to use it, see Generating and Using the Token.
- Access Key and Secret Key: The access key and secret key of the application that you have registered in Application Registration. The keys are used for permission-related verifications, such as checking whether an application has the permission to create a device or update a model.
- Description: Enter a description for the device protocol.
Click OK to create the protocol gateway, and it will appear in the list of private gateways with a system generated ID.

Viewing Protocol Gateways¶

The list of created protocol gateways is displayed in Device Onboarding > Protocol Gateway, where the time the gateways are created, their IDs, names, respective notwork modules, and status (Starting, Started, Not Started, Stopped, Failed) are shown.
Locate the protocol gateway you wish to view from the list and click the View icon .
The details of the protocol gateway will be displayed in the pop-up-window.

Editing Protocol Gateways¶

In Device Onboarding > Protocol Gateway, locate the protocol gateway you wish to edit from the list and click the Edit icon . Note that protocol gateways with a Started or Starting status cannot be edited.
All fields can be edited, except for Protocol ID.
After editing, click OK to save the changes.

Exporting Protocol Gateways¶

You can export the details of the protocol gateway in JSON, after which you can either use it as it is or edit it and then import it as a new protocol gateway.

In Device Onboarding > Protocol Gateway, locate the protocol gateway you wish to download from the list and click the Download icon .
Save the JSON file.

Importing Protocol Gateways¶

You can import protocol gateways using a JSON file. For the required details, refer to the downloaded file in Exporting Protocol Gateway Details.

In Device Onboarding > Protocol Gateway, click Import.
You can either drag and drop a JSON file in the pop-up window or click it to select a JSON file to upload.
Click OK to import the protocol gateway.

Deleting Protocol Gateways¶

In Device Onboarding > Protocol Gateway, locate the protocol gateway you wish to delete from the list and click the Delete icon .
Deleted protocol gateways cannot be recovered. To delete the protocol gateway, click the Delete button in the pop-up window.

Allocating Runtime Resource¶

The default runtime resource allocated for each protocol gateway is 1. You can change the allocation if required.

In Device Onboarding > Protocol Gateway, locate the protocol gateway you wish to allocate resource for from the list.
Click … > Allocate Resource. Note that the allocation cannot be changed while the Status of the protocol gateway is Starting or Started.
Edit the Single Instance Resource accordingly.
- Single Instance Resource: Represents the computing resources consumed by each protocol gateway in CU. It is recommended to allocate more resources for complicated device protocol logic as that requires more resources for computing. The maximum computing resource for a single instance is 8 CU.
- Total Runtime Resource: The total amount of Protocol Gateway resource applied for your OU.
- Remaining Resource: The remaining resources you can use.
Click OK to save the changes.

Starting and Stopping Protocol Gateways¶

In Device Onboarding > Protocol Gateway, locate the protocol gateway you wish to start or stop from the list and click … > Start Gateway or … > Stop Gateway.
The status column will reflect the changes accordingly.
After starting the protocol gateway, requests can be sent through the network protocol defined in the network module.

Note

It takes about 3 to 5 minutes after clicking Start Gateway to change to an Started status. Refresh the page to reflect the changes.

Establishing Connection Using MQTT/WebSocket Protocols ¶

The formats of the client ID, username, and password are as per the below.

Client ID: {clientId}|securemode={secureMode},signmethod=sha256,connect-type={connectType}},access-token={token},protocol-gateway-id={protocolGateWayId},timestamp={timeStamp}|
Username: {deviceKey}&{productKey}
Password: toUpperCase(sha256({content}{deviceSecret}/{productSecret}))

Client ID
- clientId: Required. The identifier of the device, which can be the MAC address or device serial number. It must contain no more than 64 characters.
- securemode: Required. The secure mode that is used.
  - For static authentication, where the productKey, deviceKey, and deviceSecre is provided to activate the device, the value is 2.
  - For dynamic authentication, where the productKey, productSecret, and deviceKey is provided to activate the device, the value is 3.
- signmethod: Required. The signing method where “sha256” means the SHA256 signature algorithm is used.
- connect-type: Required. Supports “integration” and “login”. Note that if “login” is used, there is no need for token authentication, even if the Authenticate Token switch is toggled on.
- access-token: Depends on whether the Authenticate Token switch is toggled on and whether connect-type is “integration”. If yes for both, it is required. For more information on how to generate the access token, see Generating and Using Token.
- protocol-gateway-id: Required. The system generated ID after successfully creating the protocol gateway.
- timestamp: Required. The UNIX timestamp of the current time in milliseconds.
For example, if the following parameter values are used for Client ID:
- clientId=id123456
- securemode=2
- signmethod=sha256
- connect-type=integration
- access-token=44b1d16f9754e739206969b8e2d509bb328b20e2
- protocol-gateway-id=607f884bc6b5090250d87321
- timestamp=1619168502866
The Client ID in this case would be: clientId= id123456|securemode=2,signmethod=sha256,connect-type=integration,access-token=44b1d16f9754e739206969b8e2d509bb328b20e2,protocol-gateway-id=607f884bc6b5090250d87321,timestamp=1619168502866|

Username: If connect-type for Client ID is “integration”, the username would be as per what is parsed in the JAR file. If connect-type is “login”, the format would be a concatenation of deviceKey, “&”, and `productKey.
- deviceKey: Device key of a product. You can find it in the EnOS Management Console after you register the device.
- productKey: Product key of a product. You can find it in the EnOS Management Console after you register the device.
For example, if the deviceKey is abcdefg and the productKey is 1234567, the Username in this case would be `abcdefg&1234567.

Password: If connect-type for Client ID is “integration”, the password would be as per what is parsed in the JAR file. If connect-type is “login”, the format would be as per the below.

For static authentication, it is a string concatenated by content and deviceSecret. For dynamic authentication, it is a string concatenated by content and productSecret. Use the SHA256 algorithm to generate a new string from this concatenation and turn the new string into upper case letters.
- content: It is concatenated by the clientId and its value, the deviceKey and its value, the productKey and its value, and the timestamp and its value. The parameter names must be sorted in alphabetical order and concatenated without concatenation symbols.
  
  For example, if the following parameter values are used for content,
  - clientId = id123456
  - deviceKey = dK987654
  - productKey = pK11111
  - timestamp = 1234567890
  The content in this case would be clientIdid123456deviceKeydK987654productKeypK11111timestamp1234567890
- deviceSecret: The device secret of a device. You can find it in the EnOS Management Console.
- productSecret: The product secret of a device. You can find it in the EnOS Management Console.
The value of the deviceSecret or productSecret should be appended to content without any space or symbols.

Generating URL ¶

The URLs for the different protocols are as per the below, where {address} and {port} can be found by logging in to the EnOS Management Console and click Help > Environment Information at the top right, under Third-party Connection.

HTTP: http://{protocolGatewayId}.{address}:{port}{path}
- protocolGatewayId: The system generated ID when the procotol gateway is successfully created, for example: 60ffd12940c3768039f6aa55.
- path: The route entered for Protocol Route when creating a protocol gateway, for example: /createDevice.
WebSocket: ws://{address}:{port}/mqtt
MQTT: tcp://{address}:{port}

Using the examples above, the generated URL for the beta environment for HTTP would be http://60ffd12940c3768039f6aa55.third-party-protocol-beta1.eniot.io:9091/createDevice.

Generating and Using Token ¶

Use the following format to generate a token.

sha1(accessKey+accessSecret+timestamp)

accessKey: The access key entered when creating the protocol gateway, for example: abc.
secretKey: The secret key entered when creating the protocol gateway, for example: xyz.
timestamp: The timestamp field in the header of the request, for example: 1619168502866.

Concatenate the above values into a string.
Encode the concatenated string using sha1 algorithm and convert it to lower case.
```
sha1 ("abcdxyz1619168502866")
```
The token obtained would be 44b1d16f9754e739206969b8e2d509bb328b20e2.
The way the token is used would depend on the protocol.
- HTTP: Follow the format below for the HTTP request header.
```
{
 accessToken: 44b1d16f9754e739206969b8e2d509bb328b20e2,
 timestamp: 1619168502866
}
```
- WebSocket and MQTT: Use the token as the value for the access-token parameter in the client ID. For more information, see Establishing Connection Using MQTT/WebSocket Protocols.