The operations, administration, and management (OAM) tool lectl is a command-line tool provided by Link IoT Edge to manage resources. It allows you to use Link IoT Edge efficiently.

You can find the lectl tool in the {LINKEDGE_ROOT}/gateway/build/bin directory.
Note {LINKEDGE_ROOT} indicates the root directory of the Link IoT Edge software package. Typically, the root directory is /linkedge/.

Help

You can add the --help section to the lectl command or a lectl subcommand to retrieve help information. The following code shows the top-level help information:
$ lectl --help

Usage:    lectl [OPTIONS] COMMAND

Manage Link IoT Edge services and facilitate troubleshooting.

Options:
  -v, --version   Print version information and quit

Commands:
  completion  Output shell completion code
  config      Manage configs
  dbus        Manage D-Bus message bus
  deployment  Manage deployments
  device      Manage devices
  diagnose    Check if requirements meet
  driver      Manage drivers
  fc          Manage function compute
  logger      Manage logger service and logs
  mqtt        Manage MQTT service
  ota         Manage OTA service
  rom         Manage remote operations and maintenance
  router      Manage message routing
  sc          Manage stream compute
  scene       Manage scenes

Run 'lectl COMMAND --help' for more information on a command.

Autocomplete

lectl supports the autocomplete feature of the bash and zsh shells to improve input efficiency.

  • bash

    Run the lectl completion bash command on the gateway to generate the bash autocomplete script. Then, import the script to the current shell.

    The bash autocomplete script depends on the bash-completion package. Different package management systems provide different bash-completion packages. Perform the following steps to enable the autocomplete feature for lectl.

    1. Run the type _init_completion command on the gateway to check whether the bash-completion package has been installed.
      • If the package has been installed, go to step 4.
      • If the package has not been installed, go to step 2.
    2. Use the package management system to install the bash-completion package.
      • If you are using Red Hat Linux operating systems, run the yum install bash-completion command.
      • If you are using Debian Linux operating systems, run the apt-get install bash-completion command.

      For more information about bash-completion packages that are provided by different package management systems, see bash-completion.

    3. Add the content of the generated /usr/share/bash-completion/bash_completion file to the .bashrc file.
      source /usr/share/bash-completion/bash_completion
    4. Enable the autocomplete feature.
      You can use either of the following methods:
      • Import the bash autocomplete script to the current shell. (Recommended)
        source <(lectl completion bash)
        Note If you use this method, the autocomplete feature is invalid after you exit the shell. If you want the autocomplete feature to take effect all the time, run the echo 'source <(lectl completion bash)' >> ~/.bashrc command to add the source <(lectl completion bash) command to the .bashrc file.
      • Add the bash autocomplete script to the bash_completion.d directory.
        lectl completion bash > /etc/bash_completion.d/lectl
  • zsh

    Run the lectl completion zsh command to generate the zsh autocomplete script. Then, import the generated script to the current shell.

    You can also run the following command on the gateway to generate the zsh autocomplete script and enable the autocomplete feature for lectl.
    source <(lectl completion zsh)
    Note If the complete:13: command not found: compdef error occurs, copy and paste the following command into the .zshrc file.
    autoload -Uz compinit
    compinit

Connection diagnosis

If the Link IoT Edge gateway fails to connect to IoT Platform, you can run the diagnose command in the lectl tool for preliminary diagnosis.
lectl diagnose
The system returns the running status of the gateway. The following section provides an example:
$ lectl diagnose

....................................................

  Get Gateway Triple ***************************[ OK ]
  Get IoT Region *******************************[ OK ]
  Check Network ********************************[ OK ]
  Check DNS Service ****************************[ OK ]
  Check MQTT Port ******************************[ OK ]
  Check MQTT Cert ******************************[ OK ]
Warning: Inspection of MQTT connection will offline edge-gateway(y or n)y 

  Gateway Produck Key     : a17p****0p0
  Gateway Device Name     : TASN_******_LinkEdge_Core
  Gateway Device Secret   : 9ygH*************vZqfv
  MQTT Service Host       : a17p****0p0.iot-as-mqtt.cn-shanghai.aliyuncs.com
  MQTT Service Port       : 1883

  Check MQTT Connection ************************[ OK ]
Table 1. Fields
Field Description
Get Gateway Triple Queries the device certificate of the gateway.
Get IoT Region Queries the region of the IoT service.
Check Network Checks the network connection status.
Check DNS Service Checks the DNS service status.
Check MQTT Port Checks the port that the MQTT protocol uses.
Check MQTT Cert Checks the certificate for the MQTT client.
Check MQTT Connection Checks the MQTT connection.

Manage logs

You can use the lectl tool to package logs or temporarily change Log Service behaviors. This allows you to upload logs or troubleshoot errors.

  • Package logs
    Run the following command to package logs:
    lectl logger pack
    Note By default, log files are packaged into the current directory and the package is named logs.zip. You can use the -n or --name option to specify the output file name, and the -o or --output option to specify the output path.
  • Manage Log Service

    lectl allows you to retrieve Log Service configurations and temporarily change Log Service behaviors. For example, if errors occur on Link IoT Edge, you can change the global log level to debug to view more details.

    Run the following command to retrieve Log Service configurations or temporarily change Log Service behaviors:
    lectl logger config [OPTIONS]
    Note You can use the lectl logger config command to configure multiple logging options at a time.
    Table 2. Options
    Option Description
    -d, --disable Disables the logging system, log level, module logging, module log level, logging destination, or display format. You can disable only one feature at a time.
    -e, --enable Enables the logging system, log level, module logging, module log level, logging destination, or display format. You can enable only one feature at a time.
    --show Displays all or specified configurations. Syntax: --show=.

    You can specify the following configuration items:

    • dir: the log file path.
    • level: the global log level.
    • module: the module log configurations.
    • format: the log display format.
    • target: the logging destination.
    • size: the log file size.
    -g, --single-file-mb Sets the size of a single log file. Unit: MB.
    -t, --total-files-mb Sets the overall log file size. Unit: MB.

    The following examples show common commands that are used to manage Log Service:

    $ lectl logger config --show
    $ lectl logger config --show=level
    $ lectl logger config -g 10
    $ lectl logger config -t 1024
    $ lectl logger config -e system
    $ lectl logger config -e warn
    $ lectl logger config -e credential
    $ lectl logger config -e credential:info
    $ lectl logger config -e stdout
    $ lectl logger config -e full
    $ lectl logger config -d warn

Manage Link IoT Edge configurations

You can use the config subcommand to manage Link IoT Edge configurations.

  • Retrieve configurations
    Run the following command to retrieve configurations:
    lectl config get [OPTIONS] [ARG]

    By default, the [ARG] parameter specifies the key of the value to be retrieved and changes based on the [OPTIONS] parameter. The following table lists the valid options.

    Table 3. Options
    Option Description
    -d, --d3 Retrieves the certificate information of all devices. You do not need to specify the [ARG] parameter.
    -v, --driver Retrieves the configurations of a specified driver. [ARG] specifies the driver name.
    -g, --g3 Retrieves the certificate information of the gateway device. You do not need to specify the [ARG] parameter.
    -s, --tsl Retrieves the TSL of a specified product. [ARG] specifies the product key.
    The following examples show common commands that are used to retrieve configurations:
    $ lectl config get foo
    $ lectl config get -g
    $ lectl config get -d
    $ lectl config get -s foo
    $ lectl config get -v foo
  • Configure devices
    Run the following command to configure devices:
    lectl config set [OPTIONS] [ARG...]

    By default, the [ARG...] parameter includes the ARG1, ARG2, and ARG3 parameters that specify the key, value, and timestamp, respectively. The timestamp is optional. The [ARG...] parameter changes based on the [OPTIONS] parameter. The following table lists the valid options.

    Table 4. Options
    Option Description
    -d, --d3 Configures the device certificate. The ARG1, ARG2, and ARG3 parameters specify the product key, device name, and device secret, respectively.
    -p, --d3f Reads a specified file to configure the device certificate. The ARG1 parameter specifies the file path. You do not need to specify the ARG2 and ARG3 parameters.
    -v, --driver Configures the driver. The ARG1 and ARG2 parameters specify the driver name and driver configurations, respectively. You do not need to specify the ARG3 parameter.
    -f, --file Reads a specified file to configure key-value pairs. The ARG1 and ARG2 parameters specify the key and file path, respectively. You do not need to specify the ARG3 parameter.
    -g, --g3 Configures the device certificate of the gateway. The ARG1, ARG2, and ARG3 parameters specify the product key, device name, and device secret, respectively.
    -s, --tsl Configures the TSL of the product. The ARG1 and ARG2 parameters specify the product key and file path, respectively.
    The following examples show common commands that are used to configure devices:
    $ lectl config set foo bar
    $ lectl config set foo bar 1555483052
    $ lectl config set -f foo /path/to/bar
    $ lectl config set -g foo bar baz
    $ lectl config set -d foo bar baz
    $ lectl config set -p /path/to/foo
    $ lectl config set -s foo /path/to/bar
    $ lectl config set -v foo bar
  • Remove configurations
    Run the following command to remove configurations:
    lectl config unset KEY
  • Force to write configurations
    To ensure successful configuration, you can force the system to write configurations and save the configurations to a disk. Run the following command:
    lectl config flush

Management D-Bus

Internal components of Link IoT Edge use the D-Bus message bus to communicate with each other. You can use the dbus subcommand to manage Link IoT Edge D-Bus.

Run the following command to monitor messages in D-Bus:

lectl dbus monitor

Manage deployment

You can use the deployment subcommand to manage the deployment of edge instances.

You can use the lectl deployment show command to view the deployment information of edge instances.

Manage drivers

You can use the driver subcommand to manage Link IoT Edge drivers.

Run the following command to view driver details:

Note Whether the command returns information depends on the managed driver. If the driver does not provide the API, related information cannot be retrieved.
lectl driver show [OPTIONS] DRIVER
Table 5. Parameters
Parameter Description
[OPTIONS] For information about this parameter, see the following table.
DRIVER The ID of the driver.
Table 6. Options
Option Description
-c, --connections If you specify this option, only the driver connection information is displayed. If you do not specify this option, all driver information is displayed.
--devices If you specify this option, only the device information is displayed. If you do not specify this option, all driver information is displayed. You can specify the product key and device name to filter devices.

The following examples show common commands that are used to manage drivers:

$ lectl driver show 44c0****78204641a4b9bcf1024176c2
$ lectl driver show -c 44c0****78204641a4b9bcf1024176c2
$ lectl driver show --devices 44c0****78204641a4b9bcf1024176c2
$ lectl driver show --devices=a1t8****n42K/GjCb****gcKYaluGJLN 44c0****78204641a4b9bcf1024176c2

Manage devices

You can use the device subcommand to manage Link IoT Edge devices.

  • View device information

    Run the lectl device show subcommand to view the status of the current device.

    The following example shows the device information:
    lectl device show
    {
        "DeviceStats": [
            {
                "ProductKey": "a1t9****42K",
                "DeviceName": "GjCb****gcKXeluGJLNp",
                "LocalId": "GjCb9****cKXeluGJLNp",
                "IsLocal": false,
                "DriverId": "e0bb****964e4519b4a52f9b719e1dd3",
                "Activation": "activated",
                "LocalState": "online",
                "CloudState": "online",
                "LastSeenTime": "2020-02-27T14:16:52+08:00",
                "LastRequestOnlineTime": "2020-02-27T14:16:52+08:00",
                "LastLocalOnlineTime": "2020-02-27T14:16:52+08:00",
                "LastCloudOnlineTime": "2020-02-27T14:16:52+08:00",
                "LastCloudOnlineFinishTime": "2020-02-27T14:16:52+08:00",
                "LastRequestOfflineTime": "2020-02-26T12:04:45+08:00",
                "LastLocalOfflineTime": "2020-02-26T12:04:45+08:00",
                "LastCloudOfflineTime": "2020-02-26T12:04:45+08:00",
                "LastCloudOfflineFinishTime": "2020-02-26T12:04:45+08:00",
                "RequestOnlineTimes": 17,
                "LocalOnlineTimes": 17,
                "CloudOnlineTimes": 252,
                "RequestOfflineTimes": 1,
                "LocalOfflineTimes": 1,
                "CloudOfflineTimes": 1
            }      
        ]
    }
    Table 7. Fields
    Field Description
    ProductKey The unique identifier of the product.
    DeviceName The name of the device.
    DriverId The ID of the driver to which the device is associated.
    Activation Indicates whether the device is activated.
    LocalState The connection status between the device and the gateway.
    CloudState The connection status between the device and IoT Platform.
  • Retrieve device properties

    You can use the getproperties subcommand to retrieve the property values of a specified device.

    lectl device getproperties [OPTIONS]
    Table 8. Options
    Option Required Description
    -i, --identifier Yes Identifies the device to be queried. Syntax: ProductKey/DeviceName.
    --key Yes Identifies the keys of the properties. You must specify a JSON string array.

    The following example shows a common command that is used to retrieve device properties:

    lectl device getproperties --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --keys='["foo"]'
  • Configure device properties

    You can use the setproperties subcommand to configure the property values of a specified device.

    lectl device setproperties [OPTIONS]
    Table 9. Options
    Option Required Description
    -i, --identifier Yes Identifies the device to be queried. Syntax: ProductKey/DeviceName.
    --properties Yes Identifies the keys of the properties. You must specify a JSON string array.

    The following example shows a common command that is used to configure device properties:

    $ lectl device setproperties --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --properties='["foo": "bar"]'
  • Call device services

    You can use the callservices subcommand to call the services of a specified device.

    lectl device callservice [OPTIONS]
    Table 10. Options
    Option Required Description
    -i, --identifier Yes Identifies the device to be queried. Syntax: ProductKey/DeviceName.
    --name Yes Identifies the name of the service to be called.
    --args No Identifies the input parameters of the service to be called. The data format of parameters is defined by the service.

    The following examples show common commands that are used to call device services:

    $ lectl device callservice --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --name=foo
    $ lectl device callservice --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --name=foo --args=bar
    $ lectl device callservice --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --name=foo --args='["bar"]'

Manage scene orchestrations

You can use lectl to manage scene orchestrations in Link IoT Edge. lectl allows you to view, enable, disable, and trigger scene orchestrations.

  • View scene orchestrations

    Run the lectl scene show command to view the basic information, execution information, statistics, and deployment information of scene orchestrations.

    The following example shows the result of running this command:

    lectl scene show
    {
        "Scenes": [
            {
                "Times": 8,
                "FailureTimes": 0,
                "LastState": {
                    "State": "success",
                    "Cause": "",
                    "Time": "2020-02-27T14:25:00+08:00",
                    "Duration": 3
                },
                "Id": "d141****2aaf4d1d8e3259637e489528",
                "Name": "scene_test_types",
                "Running": true,
                "Time": "2020-02-27T14:17:53+08:00",
                "Uptime": 466184,
                "Actions": {
                    "Times": 8,
                    "FailureTimes": 0,
                    "LastState": {
                        "State": "success",
                        "Cause": "",
                        "Time": "2020-02-27T14:25:00+08:00",
                        "Duration": 2
                    }
                },
                "Conditions": {
                    "Times": 8,
                    "FailureTimes": 0,
                    "LastState": {
                        "State": "success",
                        "Cause": "",
                        "Time": "2020-02-27T14:25:00+08:00",
                        "Duration": 0
                    }
                }
            }
        ],
        "Deployment": null
    }
  • Enable scene orchestrations

    Run the following command to enable one or more scene orchestrations:

    lectl scene enable SCENE [SCENE...]

    The SCENE parameter specifies the IDs of the scene orchestrations. Multiple IDs must be separated with spaces.

  • Disable scene orchestrations

    Run the following command to disable one or more scene orchestrations:

    lectl scene disable SCENE [SCENE...]

    The SCENE parameter specifies the IDs of the scene orchestrations. Multiple IDs must be separated with spaces.

  • Trigger scene orchestrations

    Run the following command to trigger one or more scene orchestrations:

    lectl scene invoke SCENE [SCENE...]

    The SCENE parameter specifies the IDs of the scene orchestrations. Multiple IDs must be separated with spaces.

  • Reset scene orchestrations

    Run the following command to remove all scene orchestrations on the current gateway:

    lectl scene reset

Manage functions

You can use lectl to manage functions in Link IoT Edge. lectl allows you to view, deploy, remove, reset, call, and restart functions.

  • View function information

    If exceptions occur during function execution, you can run the lectl fc show command to view the statuses and statistics of functions.

    The following example shows the result of running this command:

    $ lectl fc show
    {
        "Functions": [        
            {
                "FunctionId": "90fe****d2a5466993117e58c1ae3f7f",
                "ServiceName": "helloworld",
                "FunctionName": "helloworld",
                "Runtime": "nodejs8",
                "MemorySize": 1073741824,
                "Timeout": 5,
                "RunMode": "OnDemand",
                "Status": "Running",
                "InvocationTimes": 157,
                "ProcessStats": {
                    "Pid": 254,
                    "MemoryUsage": 32988,
                    "StartTime": "2020-02-27 14:17:14.412906 ",
                    "LastStopTime": "1970-01-01 08:00:00.000000 ",
                    "LastInvokeTime": "2020-02-27 14:22:26.547315 ",
                    "ExitTimes": 0
                },
                "TaskStats": {
                    "HandledTimes": 157,
                    "HandledErrorTimes": 0,
                    "UnhandledTimes": 0,
                    "HandledAverageDuration": 3025,
                    "WaitingAverageDuration": 0,
                    "LastHandledDuration": 2006
                },
                "RuntimeStats": {
                    "RequestUnhandledTimes": 0,
                    "RequestHandledTimes": 0,
                    "RequestHandledErrorTimes": 0,
                    "RequestHandledAverageDuration": 0
                },
                "DeploymentStats": {
                    "State": "Success"
                }
            }
        ]
    }
  • Call a function

    Run the following command to call a function:

    lectl fc invoke [OPTIONS] FUNCTION
    Table 11. Parameters
    Parameter Description
    [OPTIONS] The options. The following options are available:

    -p, --payload: specifies the base64-encoded parameter value. The parameter value is left intact before being passed to the function.

    FUNCTION The ID or Alibaba Resource Name (ARN) of the function. The syntax of a function ARN: acs:fc:<Region>:<AccountId>:service:<ServiceName>:function:<FunctionName>.
  • Restart functions
    Run the following command to restart one or more functions:
    lectl fc restart FUNCTION [FUNCTION...]

    The FUNCTION parameter specifies the IDs of the functions. Multiple function IDs must be separated with spaces.

  • Remove functions
    Run the following command to remove one or more functions:
    lectl fc remove FUNCTION [FUNCTION...]

    The FUNCTION parameter specifies the IDs of the functions. Multiple function IDs must be separated with spaces.

  • Reset deployment
    Run the following command to reset the deployment:
    lectl fc reset

Manage remote services

You can use the rom subcommand to manage remote services in Link IoT Edge.

Run the following command to view the statuses of the current remote services:

lectl rom show
Table 12. Fields
Field Description
ChannelState The status of the channel connection.
ThreadState The status of the thread.
Services The list of remote services and their statuses.

Manage MQTT messaging

You can use the mqtt subcommand to manage MQTT-based message subscriptions of Link IoT Edge components.

Run the following command to view the message subscriptions of Link IoT Edge components:

lectl mqtt show
Table 13. Fields
Field Description
Topic The topic whose messages are subscribed.
QoS The Quality of Service (QoS) level that is defined in the MQTT protocol.
Subscriber The subscriber of the message.
State The status of the message subscription.
Time The time when the message was subscribed.