After you perform driver encoding, you must debug drivers. During the driver debugging phase, you can perform the following operations: compile drivers, create driver packages, upload drivers, set up environments, create Thing Specification Language (TSL) models, deploy drivers, view debugging results, check data transmission between devices and the cloud, and locally replace drivers.

Prerequisites

An edge instance is created to provide a runtime environment for the driver that is developed by using the SDK for the C programming language. For more information, see Ubuntu 16.04.

Step 1: Compile a driver and create a driver package

For information about driver packages, see Driver package considerations in this topic.

  1. Download the sample code.
    git clone https://github.com/aliyun/linkedge-thing-access-sdk-c.git
  2. Go to the linkedge-thing-access-sdk-c directory and complete driver compilation.
    cd linkedge-thing-access-sdk-c
    make prepare && make && make install
  3. View the compilation result.
    cd build/bin/demo/demo_led/ && ls -l

    The following figure shows that the driver has been compiled and a driver package has been created.

    Execution result

Step 2: Upload and publish the driver

For information about how to publish drivers and specify the related parameters, see Publish drivers.

  1. Log on to the IoT Platform console. In the left-navigation pane, choose Link IoT Edge > Drivers. On the page that appears, click the Custom Drivers tab, and click Create Driver.
    On the page that appears, specify the driver parameters. For more information, see Publish cloud-hosted drivers.Specify parameters for a custom driver

    In this example, select No for Built-in Driver, and click Upload File under Driver File to upload the led_driver.zip file that is obtained in Step 1.

  2. Click Confirm. You can find the driver that has been created on the Custom Drivers tab.

Step 3: Assign the driver and device to the edge instance

Before deploying the driver, you must create an edge instance to provide a runtime environment for the driver, as described in Prerequisites.

  1. Log on to the IoT Platform console. In the left-side navigation pane, choose Link IoT Edge > Edge Instances. On the page that appears, find an existing edge instance, and click View in the Actions column.
  2. On the Instance Details page, click the Devices & Drivers tab, and click the + icon on the right side of All Drivers.
  3. In the Assign Driver dialog box, select Custom Drivers from the drop-down list, find the custom driver that you have created, and then click Assign in the Actions column. Then, click Close.
    Assign the custom driver to the edge instance
  4. In the All Drivers section, click the demo_driver driver that has been assigned to the edge instance. On the page that appears, click Assign Sub-device. In the demo_driver settings, you can assign the device to the edge instance. To do this, follow these steps:
    1. On the Assign Sub-device page that appears on the right side of the console, click Add Sub-device.
      Add Sub-device
    2. In the Add Device dialog box, click Create Product to create a product.
      Create a product (living room lamp)
    3. In the Create Product dialog box, specify the required parameters, and click OK.
      Table 1. Parameters
      Parameter Description
      Product Name The name of the product. The product name must be unique for the current account. The product name must be 4 to 30 characters in length, and can contain letters, digits, underscores (_), hyphens (-), at signs (@), and parentheses ().
      Gateway Connection Protocol The communications protocol that is used by the gateway. In this example, select Custom.
      Authentication Mode The authentication method. Select an authentication method that is suitable for your device. For more information, see Authenticate devices.
      Product Description The description of the product. This parameter is optional.
    4. You are automatically directed to the Add Device dialog box. In this dialog box, click Configure to define the product features.
      Configure

      You are directed to the Product Details page. On the Define Feature tab of this page, click Edit Draft, and click Add Self-defined Feature. In the dialog box that appears, specify the Properties and Events settings. For more information, see Define features.

      • Add PropertiesAdd self-defined feature
      • Add EventsSpecify event parameters

        The following figure shows the output parameters that you must configure when you add an event.

        Edit event parameters
    5. Go back to the Add Device dialog box to add a device.
      Add Device
    6. In the Assign Sub-device dialog box, find the device that you have created, and click Assign in the Actions column.
  5. After the device is assigned to the edge instance, click Device Configurations in the Actions column for the device. In the dialog box that appears, configure the device information.
    Device configurations

    The size of the specified JSON-formatted data cannot exceed 1 KB. After the specified data passes the Validation Format, click OK.

Step 4: Deploy the edge instance

  1. In the upper-right corner of the Instance Details page, click Deploy to deploy the edge instance. After the edge instance is deployed, Deployed is displayed next to the instance name.
  2. View the debugging information.
    After the edge instance is deployed, you can view the device connection status and running status. To view the device information, you can use two methods: IoT Platform console (on the cloud) and driver operations log in the runtime environment of the edge gateway (on-premises).
    • View device information from the IoT Platform console (on the cloud)
      1. Go to the Instance Details page. On this page, click the Devices & Drivers tab, and click the demo_driver custom driver. On the page that appears, you can view the device connection status.Online sub-device
      2. Click View in the Actions column. You are then directed to the Device Details page of the IoT Platform console.
      3. Click the Status tab. On this tab, you can view the data that is reported from the device.Device status
    • View device information from the driver operations log (on-premises)
      1. Run the ./fctl show command to find the directory where the driver is deployed.
        cd /linkedge/gateway/build/bin/
        ./fctl show
        The following figure shows a command output example.Execution result
        Table 2. Parameters
        Parameter Description
        DriverName The name of the driver. The name of the driver is specified in Step 2: Upload and publish the driver.
        CodePath The directory where the driver is deployed to the edge gateway.
        Process PID The ID of the process after the driver is started.
      2. Check the driver running status by using the driver operations log. The driver operations log records the driver running information. The log files of custom drivers are stored in the /linkedge/run/logger/fc-base directory. The format of the directory for each log file is /linkedge/run/logger/fc-base/xxxx/log_xxxx.txt.
        Note In this format, xxxx indicates the name that you specified when you uploaded the driver file.
        cd /linkedge/run/logger/fc-base/demo_driver && ls -l
        The following figure shows a command output example.Execution result
        Driver operations logs allow you to check the driver running status in most cases. However, to obtain more detailed information, you must view other logs. For example, if a device fails to be published, you can view the dimu log in the /linkedge/run/logger/dimu/log_xxxxx.txt directory for troubleshooting.
        cd /linkedge/run/logger/dimu
        ls -l
        The following figure shows a command output example.Execution result
        If the device is published as expected but fails to report data, you can view the cloud_proxy log in the /linkedge/run/logger/cloud-proxy/log_xxxxx.txt directory for troubleshooting.
        cd /linkedge/run/logger/cloud-proxy
        ls -l
        The following figure shows a command output example.Execution result

Step 5: Check data transmission between devices and the cloud

After the device is published, you can use the Online Debug tab in the IoT Platform console to debug drivers and devices. On this tab, you can view the data reported by the device in real time, and send requests to call device services.

  1. Log on to the IoT Platform console. In the left-side navigation pane, choose Maintenance > Online Debug. On the Online Debug page, select the product and device for debugging.
  2. On the page that appears, select the functions and services for debugging. You can also view the real-time operations log of the device.
    Online debugging

(Optional) Step 6: Locally replace drivers

If you find one or more issues during the driver debugging, you can modify the driver code and develop a new driver for debugging. Then, you only need to locally replace the faulty driver with the new driver that has been compiled.

  1. Find the location of the driver. You can run the fctl command to find the location. For information about parameter description, see the "View the debugging information" section in this topic.
    cd /linkedge/gateway/build/bin/
    ./fctl show
    Execution result
  2. Find the directory of the driver configuration files based on the value of the CodePath parameter, and replace the faulty driver with the new driver.
  3. Find the process ID based on the value of the Process PID parameter. Then, run the kill -9 Pid command to terminate the original process and restart a new process.
    Kill-9 Pid # Pid indicates the driver process ID. You can run the fctl command to find the process ID.
  4. After you replace the faulty driver with the new driver and debug the new driver, publish the new driver to the IoT Platform console. For more information, see Step 2: Upload and publish the driver.

Now you have debugged and published the driver.

Driver dependency considerations

To meet the requirements for various communications protocols and scenarios, you may need to install third-party library dependencies for drivers. You must comply with the following rules for third-party library dependencies if you use the C, Node.js, and Python SDKs to develop drivers.

  • SDKs for the C programming language

    The C programming language is a type of compiled language. If the compilation environment is different from the runtime environment, running errors may occur. If you use SDKs for the C programming language to develop a driver, you must ensure that the compilation environment is the same as the runtime environment.

    Driver packages may contain driver programs and dynamic dependency libraries. If drivers depend on third-party libraries, you must compress dynamic libraries and driver programs into the driver packages.

  • SDKs for the Node.js programming language

    If you use these SDKs to develop a driver and the driver depends on a third-party library, you must develop the driver in the runtime environment of Link IoT Edge. In the runtime environment, you must run the following command to install the dependencies:

    Npm install <Third-party library name>
  • SDKs for the Python programming language

    If you use these SDKs to develop a driver and the driver depends on a third-party library, you must develop the driver in the runtime environment of Link IoT Edge. In the runtime environment, you must run the following command to install the dependencies:

    
    pip3 install -t . <Third-party library name>

Driver package considerations

After you develop drivers by using the SDKs provided by Link IoT Edge and debug the drivers, you must create .zip files for the drivers. The driver binaries or index source files must be stored in the first-level directories of the .zip files.

You must comply with the following rules when you create .zip files for drivers. The rules vary according to the SDKs that you use to develop drivers.

  • SDKs for the C programming language
    The packages of drivers that are developed by using the SDKs for the C programming language may contain driver programs and dynamic dependency libraries. If driver packages contain third-party libraries, you must store the libraries in the lib folder of the driver directory. The procedure is described as follows:
    1. Specify the name of the driver program as main.
    2. Create the lib folder in the current directory of the main driver program.
    3. Copy the dynamic libraries that the main driver program depends on to the lib folder.
    4. Run the zip command to compress the main driver program and lib folder into a package.
      zip -r your_driver_name.zip main lib
  • SDKs for the Python programming language

    The packages of drivers that are developed by using the SDKs for the Python programming language must contain index.py files. The handler functions must be defined in the index.py files. Drivers are functions that run continuously on the engine of the edge applications that are created by using Function Compute. Therefore, driver packages must contain index.py files where handler functions are defined.

    The index.py files are loaded to the Python runtime environment when drivers run. The drivers do not call the handler functions that are stored in the index.py files and defined by Function Compute-based edge applications. Therefore, the driver code cannot be contained in the handler functions. This ensures that you can run the driver code when the index.py files are loaded. For more information, see SDK for Python.

  • SDKs for the Node.js programming language

    The packages of drivers that are developed by using the SDKs for the Node.js programming language must contain index.js files. The handler functions must be defined in the index.py files.

    The index.js files are loaded to the Node.js runtime environment when drivers run. The drivers do not call the handler functions that are stored in the index.py files and defined by Function Compute-based edge applications. Therefore, the driver code cannot be contained in the handler functions. This ensures that you can run the driver code when the index.js files are loaded. For more information, see SDK for Node.js.