Link IoT Edge:Debug drivers

Step 1: Compile a driver and create a driver package

For information about how to create a driver package, see the Notes for creating a driver package section 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 compile the driver.

   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 is compiled and a driver package is created.

   

Step 2: Upload and publish the driver

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

1. Log on to the Link IoT Edge console. In the left-side navigation pane, click Drivers. On the Drivers page, click the Custom Drivers tab.
2. On the Custom Drivers tab, click Create Driver.
   On the Create Driver page, set the driver parameters. For more information, see Publish cloud-hosted drivers.

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

3. After you set the parameters and upload a driver package, click Confirm. On the Custom Drivers tab, you can view the created driver.

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

Before you deploy the driver, you must create an edge instance to provide a runtime environment for the driver. For more information, see Prerequisites.

1. In the left-side navigation pane, click Edge Instances. On the Edge Instances page, find the edge instance that you want to use and click View in the Actions column.
2. On the Instance Details page, click the Devices & Drivers tab and click the + icon next to All Drivers.
3. In the Assign Driver panel, select Custom Drivers from the drop-down list, find the custom driver that you created, and then click Assign in the Actions column. Then, click Close.
   
4. In the All Drivers section, click the demo_driver driver that was assigned to the edge instance. Then, click Assign Sub-device. In the demo_driver settings, perform the following steps to assign a device to the edge instance:
   1. In the Assign Sub-device panel, click Add Sub-device.
      
   2. In the Add Device dialog box, click Create Product and create a product.
      
   3. In the Create Product dialog box, set the parameters as required and click OK.

      Table 1. Parameter description

      Parameter	Description
      Product Name	The name of the product. The product name must be unique within the current Alibaba Cloud account. The name must be 4 to 30 characters in length and can contain letters, digits, underscores (_), hyphens (-), at signs (@), and parentheses ().
      Gateway Connection Protocol	The communication 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 devices. For more information, see Authenticate devices.
      Product Description	The description of the product. This parameter is optional.

   4. You are navigated to the Add Device dialog box. In the dialog box, click Configure. Then, define custom features for the product.
      

      You are navigated to the Product Details page of the IoT Platform console. On the Define Feature tab, click Edit Draft and then Add Self-defined Feature. In the Add Self-defined Feature dialog box, you can define properties and events for the product. For more information, see Add a TSL feature.

      • Define a property
      • Define an event

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

        
   5. Go back to the Add Device dialog box and create a device.
      
   6. In the Assign Sub-device panel, find the device that you created and click Assign in the Actions column.
5. After the device is assigned to the edge instance, find the device on the Devices & Drivers tab and click Device Configurations in the Actions column. In the Device Configurations panel, configure the device information.
   

   The configuration content must be in the JSON format and cannot exceed 1 KB in size. Click Validation Format to verify the format of the configuration content. After the configuration content passes the verification, 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 status of device connection and execution. You can view the device information in the IoT Platform console or from the driver operations logs in the runtime environment of the edge gateway.

   • View device information in the IoT Platform console
     1. Go to the Instance Details page, click the Devices & Drivers tab, and then click the demo_driver custom driver. In the Devices section, you can view the status of device connection.
     2. Find the device that you want to view and click View in the Actions column. You are navigated to the Device Details page of the IoT Platform console.
     3. To view the data that is reported by the device, click the TSL Data tab and then the Status tab.
   • View device information from the driver operations logs
     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 an example of command output.

        Table 2. Parameter description

        Parameter	Description
        DriverName	The name of the driver, which 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 execution status of the driver from its driver operations logs. The driver operations logs record the execution information about the driver. 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 package.

        cd /linkedge/run/logger/fc-base/demo_driver && ls -l

        The following figure shows an example of command output.
        Driver operations logs allow you to check the execution status of drivers in most cases. 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 file for troubleshooting.

        cd /linkedge/run/logger/dimu
        ls -l

        The following figure shows an example of command output.
        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 file for troubleshooting.

        cd /linkedge/run/logger/cloud-proxy
        ls -l

        The following figure shows an example of command output.

Step 5: Check data transmission between devices and the cloud

After the device is published, you can debug drivers and devices on the Online Debug page of the IoT Platform console. On this page, you can view the data that is 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. Select the features and services for debugging. You can also view the real-time operations logs of the device.
   

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 need only to locally replace the faulty driver with the new driver that is compiled.

1. Find the location of the driver. You can run the fctl command to find the location. For information about the parameter description, see the "View the debugging information" section in this topic.

   cd /linkedge/gateway/build/bin/
   ./fctl show

   
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 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, you can publish the new driver to the IoT Platform console. For more information, see Step 2: Upload and publish the driver.

After you perform the preceding steps, the driver is debugged and published.

Notes for using driver dependencies

To meet the requirements for various communication 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 SDK for C, Node.js, or Python to develop drivers:

• SDK for C

  The C programming language is a type of compiled language. If the compilation environment is different from the runtime environment, execution errors may occur. If you use the SDK for C to develop a driver, you must make sure 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 driver packages.

• SDK for Node.js

  If you use the SDK for Node.js 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

• SDK for Python

  If you use the SDK for Python 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

Notes for creating a driver package

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

You must comply with the following rules when you create .zip packages for drivers. The rules vary based on the programming languages of the SDKs that you use to develop drivers.

• Drivers developed by using the SDK for C
  The packages of drivers that are developed by using the SDK for C 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. To do so, perform the following steps:

  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 on which the main driver program depends 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

• Drivers developed by using the SDK for Python

  The packages of drivers that are developed by using the SDK for Python must contain index.py files. The handler functions must be defined in the index.py files. Drivers are functions that continuously run 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 invoke 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.

• Drivers developed by using the SDK for Node.js

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

  The index.js files are loaded to the Node.js runtime environment when drivers run. The drivers do not invoke the handler functions that are stored in the index.js 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.