Link IoT Edge allows you to deploy built-in drivers to your gateway. This feature allows you to manage the on-premises driver files, configure the drivers on the cloud, and then deploy the drivers to the edge.

Prerequisites

A built-in driver that complies with the driver specifications of Link IoT Edge. For more information, see Driver development.

Background information

IoT Link Edge supports the use of built-in drivers. You can upload the built-in drivers to your gateway and configure the driver information (such as the driver name, coding language, runtime environment, and hardware architecture) on the cloud. You can then configure the driver channel and device on the cloud.Publish built-in drivers
The following figure shows the process of publishing a built-in driver.The flowchart for publishing a built-in driver

1. Procedure on the cloud

  1. Log on to the IoT Platform console. In the left-side navigation pane, choose Link IoT Edge > Drivers.
  2. On the Drivers page, click the Custom Drivers tab. On this tab, click Create Driver.
  3. On the Create Driver page, specify the parameters as prompted.
    • Driver InformationPublish built-in drivers
      Table 1. Parameter descriptions
      Parameter Description
      Driver Name The name of the custom driver. The name must be 1 to 20 characters in length, and can contain letters, digits, and underscores (_). The name must start with a letter.
      Communication Protocol The communications protocol that is used to develop the driver. The valid values are Modbus, OPCUA, and Custom.
      Language The programming language that is used to develop the driver. The valid values are Node.js 8, Python 3.5, C, and Java 8.

      If you select C, then you must also select the CPU Architecture of the driver.

      Built-in Driver Specifies whether the driver is built-in.
      • If you select Yes, a local built-in driver is used. You do not need to upload a driver file.
      • If you select No, you must upload a driver file and deploy the driver to the cloud. For more information, see Publish drivers to the cloud.

      To publish a built-in driver, you must select Yes.

      Driver Version The version number of the driver. You cannot specify two identical version numbers for a driver.
      Link IoT Edge Version for the Driver The Link IoT Edge version that supports the driver. The driver can run only in the gateways for Link IoT Edge of the specified version or later.
      Version Description Optional. The description of the driver version.
    • Driver ConfigurationsPublish drivers to the cloud (driver configurations)
      Table 2. Parameters
      Parameter Description
      Configuration Format The configuration method. Valid values:
      • Key-value Configuration
      • JSON Format
      • Configuration File
      Configuration Format (Key-value Configuration) If you select Key-value Configuration, click Add Configuration on the Driver Configurations page. Then, specify the Configuration Name, Value, and Description parameters.

      You can add a maximum of 100 key-value pairs.

      Configuration Format (JSON Format) If you select JSON Format, enter the JSON-formatted data to configure the driver. The data size cannot exceed 1 KB. Link IoT Edge automatically verifies the format. If the format is invalid, modify the data as prompted.
      Configuration Format (Configuration File) If you select Configuration File, edit a local configuration file and upload it to the console.
    • Container ConfigurationsPublish drivers to the cloud (container configurations)
      Table 3. Parameters
      Parameter Description
      Host Mode Specifies whether to isolate the container network from the host network. The valid values are described as follows:
      • Yes: This value indicates that the container network is the same as the host network.
      • No: This value indicates that the container network is isolated from the host network. If you select this option, you must configure the Network Port Mapping settings.
      Network Port Mapping The mappings between host network ports and container network ports. This parameter is available only when Host Mode is set to No. The network where the function runs is isolated from the host network. You can map the listening port of the function in the container to a host network port. This allows client programs on various hosts to access the services that are provided by the function. You can specify a maximum of 10 entries.

      For example, the fc-http-server function runs in a host container, and provides services by using socket port 80. The client programs on other hosts cannot access the fc-http-server function by accessing port 80 on the current host. To enable the client programs on other hosts to access the fc-http-server function, you must map the network port (port 80) in the container where the function runs to a host network port, such as port 8080. Then, the client programs on other hosts can access the IP address:port 8080 in the host network, and use the services provided by the fc-http-server function.

      Privilege Mode

      Specifies whether to enable the privilege mode. Root users of containers can access host services only as general users. If you want to change the system time or run the mount command in containers, you must be granted the required root permissions. In this scenario, you must enable the privilege mode for the containers.

      Note If you enable the privilege mode, applications and programs in the containers are granted the host root permissions, and all the host devices are mapped to the containers. Therefore, you do not need to configure the Device Mapping settings.
      Device Mapping The device mappings. This parameter is available only when you select No for Privilege Mode. The network where the device management system resides is isolated from the host network. To enable a function to access a host device such as a serial interface, you must map the device to the container where the function runs. You can specify a maximum of 10 entries.
      Volume Mapping The volume mappings. The network where the file system resides is isolated from the host network. To enable a function to access a host file, you must map the file to the container where the function runs. You can specify a maximum of 10 entries.
    • Configuration VerificationConfiguration Verification
      Table 4. Parameters
      Parameter Description
      Driver Configurations If you select the check box, you must complete driver configurations before you can deploy the edge instance. The driver configurations are specified after the driver is assigned to an edge instance and sub-devices are assigned to the driver.
      Device Configurations If you select the check box, you must complete device configurations before you can deploy the edge instance. The device configurations are specified after the driver is assigned to an edge instance and sub-devices are assigned to the driver.
  4. After the parameters are set, click Confirm. You can find the driver that has been created on the Custom Drivers tab.
    Driver ID

    You can move the pointer over the driver name to view the driver ID. Click Copy and save the driver ID, which will be used in subsequent steps.

2. Procedure at the edge

Link IoT Edge provides the led_driver sample driver. For more information, visit led_driver source code. You can use the sample driver for testing and debugging.

  1. Create an edge instance and connect the edge gateway to IoT Platform. For more information, see Set up environments.
  2. Log on to the gateway and run the following command to create a driver directory:
    sudo -E mkdir -p /linkedge/pre-installed/
  3. Run the following command to create a folder with built-in drivers. Save the driver files and dependent libraries that you have prepared in the Prerequisites section to this folder.
    sudo -E mkdir -p /linkedge/pre-installed/{your_driver_name}/

    {your_driver_name} is the name of your driver. For example, if the driver name is led_driver, the actual command is as follows:

    sudo -E mkdir -p /linkedge/pre-installed/led_driver/
  4. Check whether the following tools for built-in driver are installed on the gateway.
    Tool Function
    sed Finds and replaces the contents of text files.
    jq Parses JSON files.
    base64 Provides Base64 encryption.
  5. Optional. If the gateway does not have tools such as sed, jq, or base64, you must perform the following steps to ensure that the shell script tool for the built-in driver runs normally:
    1. Go to the default configuration directory of Link IoT Edge.
      cd /linkedge/gateway/build/config/config-manager
    2. Open the config_default.json file, and find the config parameter.
    3. Under config, add the following key: value pair:
      {
          "config": {
              "gw_drivercode_{your_driver_id}": "{your_driver_path}",
          }
      }

      {your_driver_id} is the driver ID that you copied in the 1. Procedure on the cloud section. {your_driver_path} is the built-in driver folder path after Base64 encryption.

      In the following example, the driver ID is f16f13322***********3959 cf3, the path of the built-in driver folder is /linkedge/pre-installed/led_driver/, and the Base64-encrypted path is L2xpbmtlZGdlL3ByZS1pbnN0YWxsZWQvbGVkX2RyaXZlcg==. Then the correct key: value pair is as follows:

      {
          "config": {
              "gw_drivercode_f16f133222************3959cf3": "L2xpbmtlZGdlL3ByZS1pbnN0YWxsZWQvbGVkX2RyaXZlcg==",
          }
      }
  6. In the built-in driver folder, download and decompress the shell script tool for built-in drivers.
    The following figure shows the directory structure of the script tool after decompression.
    .
    └── led_driver
        |—— pre-installed.sh
        |—— lib
        └── main
  7. Go to the directory where the built-in driver is located and run the shell script tool.
    cd /linkedge/pre-installed/{your_driver_name}/
    sudo -E ./pre-installed.sh {your_driver_id} --default

    {your_driver_name} is the driver name and {your_driver_id} is the driver ID that you saved in the 1. Procedure on the cloud section.

    For example, if the driver name is led_driver and the driver ID is f16f13322***********3959 cf3, the actual command is as follows:

    cd /linkedge/pre-installed/led_driver/
    sudo -E ./pre-installed.sh f16f13322**********3959cf3
  8. Assign the built-in driver to the edge instance and deploy the edge instance to complete the process of publishing the build-in driver. For more information, see Debug drivers.

FAQ

Q: Why does my devices not come online after I run the shell script?

A: You must finish the driver configuration on the cloud and deploy the driver to the gateway before the associated sub-devices can come online.

What to do next

  1. Log on to the IoT Platform console. In the left-side navigation pane, choose Link IoT Edge > Drivers.
  2. On the Custom Drivers tab of the Drivers page, click Version Management in the Actions column.Driver version management
  3. On the Version Management page, you can manage the driver versions. The following table lists the available operations.
    Operation Description
    Create Version You can click Create Version to create a new version of the driver. For parameter configurations, see the 1. Procedure on the cloud section of in this topic.
    Publish You can click Publish to publish the specified version. In the Publish Driver dialog box, confirm the driver information, and click Publish.
    Note After the version of the driver is published, you cannot Delete the version of the driver. You can only View the version details or Download the version of the driver.
    Edit You can edit the driver configurations only when the driver version is in the Unpublished state. Click Edit to edit the driver configurations. For more information, see the 1. Procedure on the cloud section of this topic.
    Download You can click Download to download the specified version of the driver.
    Delete You can delete a driver version only when the driver version is in the Unpublished state. You can click Delete to delete the specified version of the driver.
    View You can view the driver version details only when the driver version is in the Published state. Click View to view the driver version details or modify the configurations of the driver version. For more information, see the 1. Procedure on the cloud section of this topic.
  4. After you publish the driver on the cloud, you can assign the driver to an edge instance and assign sub-devices to the driver. Then, you can deploy the driver and its sub-devices to the edge by deploying the edge instance. For more information, see Debug drivers.