ESCLI Usage

ESCLI Overview

CLI is the acronym for command-line interface. EdgeScale CLI (ESCLI) is used to maximize productivity. CLI offers greater capability than a dashboard, exposing more, finer-grained commands, especially when the task must be done repeatedly. Such scenario would likely occur if a company manages thousands or millions of nodes. For example, CLI helps developers build a firmware image and push it out to multiple devices with only a few commands.

Installation

ESCLI is verified with Ubuntu 16.04 Linux system and python 2.7.

$ git clone https://github.com/NXP/escli
$ cd escli
$ sudo python setup.py install

Common Usage

The usage of EdgeScale CLI is:

$ escli

  Usage: escli [OPTIONS] COMMAND [ARGS]...

  CLI to interact with EdgeScale server and execute your commands, default
  config file is  ~/.edgescale/cli_conf.ini

  Options:
    -H, --host TEXT  EdgeScale host server address
    --debug          enable debug mode, default False
    -h, --help       Show this message and exit.

  Commands:
    app       applications management
    device    device register and management.
    instance  docker or application instances management
    login     login to EdgeScale
    logout    Logout from EdgeScale
    model     model of device management.
    repo      docker's repository registry.
    solution  solution image management.
    task      service to deploy application or solution.
    vendor    manufacturer vendor management.

Login to EdgeScale

There are two ways to log in to the EdgeScale server as shown by the two commands below. Please use only one of them to log in to the EdgeScale system. Once logging in successfully, a token file will be generated and the user’s token will be saved in file “~/.edgescale/token.txt”. Simultaneously, a configuration file is generated with the default EdgeScale API server name and API version defined in this file (~/.edgescale/cli_conf.ini). You can edit it if needed.

$ escli login          Input user’s name and password according the prompt.
$ escli login -u <username> -p <password>

Device commands

With the device related commands, users can create new devices, and check and query the device status.

Device command help usage

$ escli device
  Usage: escli device [OPTIONS] COMMAND [ARGS]...

  device register and management.

  Options:
    -h, --help  Show this message and exit.

  Commands:
    create    create a new device.
    delete    Remove device by id or name
    get-cert  Get device private key & certification by...
    list      List your Devices
    show      show device information.

Create new device

$ escli device create -h
  Usage: escli device create [OPTIONS]

  Create a new device.

  Options:
    -d, --description TEXT  Description
    --fuid TEXT             device's fuid  [required]
    --model_id INTEGER      device model's id  [required]
    -h, --help              Show this message and exit.
  Parameters notes:
    fuid:      factory uuid, here we can type some string or number instead
    mode_id:  device’s model ID, can be get by command “escli model list”

Query the device list

$ escli device list
+-----+----------------------------------------------------------+---------+----------------------------+---------+
| id  |                       Device name                        | Status  |        Create time         | IP addr |
+=====+==========================================================+=========+============================+=========+
| 663 | 13d3ddee9bda56ae84e8ab578f625e3e.iot.gateway.ls1046a.nxp | offline | 2018-05-31 06:03:57.123579 | None    |
|     |                                                          |         |                            |

$ escli device list --id 663
----------------------------------------------------------------------
  id:                  663
  name:                13d3ddee9bda56ae84e8ab578f625e3e.iot.gateway.ls1046a.nxp
  created_at:          2018-05-31T06:03:57.123Z
  last_report:         None
  mode                 {"platform": "ls1046a", "model": "iot", "vendor": "nxp", "type": "gateway"}
  certname:            13d3ddee9bda56ae84e8ab578f625e3e.iot.gateway.ls1046a.nxp
  uid:                 13d3ddee9bda56ae84e8ab578f625e3e
  cpu_usage:           None
  mem_usage:           None
  es_version:          None
  app_num:             None
  mac:                 00:00:00:00:00:00

Delete device

$ escli device delete --id=xxx

Upload device metadata to cloud

With this command, users can upload the device metadata to the cloud in batches. An example metadata file is “example/dev_db.csv”. It contains device fuid, OEM_DI, SK_PUB_X, and SK_PUB_Y.

$ escli device upload-db -f dev_data.csv.

Application commands

With the application commands, users can create new Apps, deploy Apps to devices, query the App status, and check instance status.

Help usage

$ escli app
  Usage: escli app [OPTIONS] COMMAND [ARGS]...

  applications management

  Options:
    -h, --help  Show this message and exit.

  Commands:
    create        create a new application
    del-instance  delete the docker instance
    delete        Remove a application
    deploy        Deploy one application to device
    instance      query and list the docker instances of user
    list          List your Applications
    show          query and show specific application (id...

Create application

$ escli app create -h
  Usage: escli app create [OPTIONS]

  Create a new Application.

  Options:
    --name TEXT          application name to be created  [required]
    --image_name TEXT    docker image name, e.g., media_server:latest  [required]
    --vendor_id INTEGER  vendor_id default null
    --commands TEXT      docker application command default null
    --args TEXT          args of application command default null
    --pic TEXT           application skin picture file default null
    --description TEXT   Description, default null
    -h, --help           Show this message and exit.

Query application

$ escli app list
+-----+------------------------+--------------------+-----------+--------------+
| id  |          name          |    display_name    | is_public | description  |
+=====+========================+====================+===========+==============+
| 398 | edgerepos-aiwebapp     | edgerepos-aiwebapp | 0         |              |
| 391 | testname1              | display1           | 0         | description1 |
| 385 | LSDK1806-New-feature-  | New-feature-LS1046 | 0         |              |
|     | LS1046                 |                    |           |              |

Deploy application to device

$ escli app deploy -h
  Usage: escli app deploy [OPTIONS]

  Deploy one application to device

  Options:
    --device TEXT     device's name  [required]
    --app_id INTEGER  application's id  [required]
    -h, --help        Show this message and exit.

Check instance status

$ escli app instance
+---------------+--------+-----------------+-------------+---------+
| instance_name | status | deployed_device | create_time | message |
+===============+========+=================+=============+=========+
+---------------+--------+-----------------+-------------+---------+

Delete Application

$ escli app delete -h
  Usage: escli app delete [OPTIONS]

  Remove a application

  Options:
    --id INTEGER  delete according to application id  [required]
    -h, --help    Show this message and exit.

Instance commands

With the instance commands, users can reboot a docker instance, check instance log, and deploy/delete an instance to/from devices.

Help usage

$ escli instance
  Usage: escli instance [OPTIONS] COMMAND [ARGS]...

    docker or application instances management

  Options:
    -h, --help  Show this message and exit.

  Commands:
    delete    delete the docker instance
    deploy    Deploy one application to device, same as...
    describe  show history and event for docker instance
    list      query and list the docker instances of user
    logs      show the docker instance log
    reboot    reboot the docker instance, remember to backup your instance data

Check instance description

$ escli instance describe --name face-recognition-3e333ca6f8274f

  2019-01-23T07:42:59Z: pending 35d07fcae2d1538ebb5f8972e1ddc523.lsdk.generic.ls1046ardb.nxp Wait to schedule and launch
  2019-01-23T07:43:15Z: creating 0%: aa2cf31b9627: Verifying Checksum
  2019-01-23T07:43:16Z: creating 50%: aa2cf31b9627: Download complete
  2019-01-23T07:43:16Z: creating 100%: aa2cf31b9627: Pull complete
  2019-01-23T07:43:17Z: creating 100%: Digest: sha256:edf26fe09753cd52dfcf9fdbdd7ad88205722d14fa74f2618dcd3d6cf835d774
  2019-01-23T07:43:18Z: starting Download image done, app is starting.
  2019-01-23T07:43:19Z: starting Download image done, app is starting.
  2019-01-23T07:44:18Z: running running

Check instance logs

$ escli instance logs --name face-recognition-3e333ca6f8274f

  92.120.166.93 - - [09/Jan/2019 02:32:20] "GET /phpmyadmin/ HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:32:20] "GET /console/faces/com_sun_web_ui/jsp/version/version_30.jsp HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:32:21] "GET /console/faces/com_sun_web_ui/jsp/version/version_4.jsp HTTP/1.1" 404 -
  1547001185: New connection from 92.120.166.93 on port 1883.
  1547001185: Socket error on client <unknown>, disconnecting.
  1547001245: New connection from 92.120.166.93 on port 1883.
  1547001245: Socket error on client <unknown>, disconnecting.
  92.120.166.93 - - [09/Jan/2019 02:34:23] "GET /cgi-bin/htsearch?Exclude=%60/etc/passwd%60 HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:34:23] "POST /xmlrpc.php HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:34:23] "GET /jkstatus/ HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:34:23] "GET /CFIDE/administrator/enter.cfm?locale=../../../../../../../lib/password.properties%00en HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:34:23] "GET /cgi-bin/php.ini HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:34:23] "POST /cgi-bin/home.tcl HTTP/1.1" 404 -
  92.120.166.93 - - [09/Jan/2019 02:34:23] "POST /cgi-bin/test-cgi HTTP/1.1" 404 -

Reboot an instance

$ escli instance reboot --name ibm-iot-3e333ca6f8274f069a10aa45bb32ebf7
  +-----------------------------------------+-----------+-----------------------------------------+----------------------+-----------------------------+
  |              instance_name              |  status   |             deployed_device             |     create_time      |           message           |
  +=========================================+===========+=========================================+======================+=============================+
  | ibm-iot-                                | rebooting | 3aad486f5ed75dd7815d26637f106840.lsdk.g | 2019-03-06T02:00:33Z |                             |
  | 3e333ca6f8274f069a10aa45bb32ebf7        |           | eneric.ls2088ardb.nxp                   |                      | Wait to schedule and launch |
  |                                         |           |                                         |                      |                             |
  +-----------------------------------------+-----------+-----------------------------------------+----------------------+-----------------------------+

Solution commands

With the solution commands, users can upload new solutions, deploy solution to devices, and edit the solution images.

Help usage

$ escli solution
  Usage: escli solution [OPTIONS] COMMAND [ARGS]...

  solution image management.

  Options:
    -h, --help  Show this message and exit.

  Commands:
    create  create a solution image
    delete  Remove solution by id or name
    deploy  Deploy solution image to board, use "escli...
    list    List your solution items
    show    show a specific solution information (id...
    update  update solution image_url and permission

Create new solution

$ escli solution create -h
  Usage: escli solution create [OPTIONS]

  Create and upload a solution.

  Options:
    --name TEXT         solution name and version, e.g.,
                        lsdk_solutionname1:version2  [required]
    --image_url TEXT    solution image URL, e.g.,
                        http://sun.ap.testhost/testpath/testimgage.tgz
                        [required]
    --model_id INTEGER  model's id, escli model list  [required]
    --public_key TEXT   image signed public key default null
    --private           make the image as private, default False
    -h, --help          Show this message and exit.

Edit the solution image

$ escli solution update -h
  Usage: escli solution update [OPTIONS]

  update solution image_url and permission

  Options:
    --id INTEGER      solution id  [required]
    --image_url TEXT  solution image URL, e.g.,
                      http://sun.ap.testhost/testpath/testimgage.tgz  [required]
    --private         make the image as private, default False
    -h, --help        Show this message and exit.

Task commands

With the task commands, users can deploy applications or solution images to devices, and check each task status.

Deploy one application to a device

$ escli task deploy-app -h
  Usage: escli task deploy-app [OPTIONS]

  Create task to deploy application.

  Options:
   --device_id TEXT    device id list  [required]
   --id INTEGER        application's id  [required]
   --app_version TEXT  application's version default 1806
   -h, --help          Show this message and exit.

Deploy one solution image to a device

$ escli task deploy-solution -h
  Usage: escli task deploy-solution [OPTIONS]

  Create task to deploy solution image to a board given.

  Options:
   --device_id TEXT  device id list  [required]
   --id INTEGER      solution's id  [required]
   -h, --help        Show this message and exit.

Check task status

$ escli task list
+-----+-----------------+---------+------------------------------------------+
| id  |      type       | status  |                 metadata                 |
+=====+=================+=========+==========================================+
| 478 | deploy_solution | Running | lsdk1806-ls1046-test-tc1;model_id:4      |
| 477 | deploy_solution | Running | lsdk1806-ls1046-test-tc1;model_id:4      |
| 474 | deploy_solution | Running | lsdk-1803;model_id:4                     |
| 473 | deploy_solution | Running | LSDK1806-newFeature-1046-1806;model_id:4 |
| 472 | deploy_solution | Running | LSDK1806-newFeature-1046-1806;model_id:4 |
| 470 | deploy_solution | Running | LSDK1806-newFeature-1046-1806;model_id:4 |
+-----+-----------------+---------+------------------------------------------+

Docker repository commands

With the repo commands, users can get the docker repository list and get command to log in to EdgeScale repository.

Help usage

$ escli repo
  Usage: escli repo [OPTIONS] COMMAND [ARGS]...

    docker's repository registry.

  Options:
    -h, --help  Show this message and exit.

  Commands:
    get-login  get a docker command to login EdgeScale...
    list       query and show the docker registry list

get-login

The command is used to get token to log in to EdgeScale docker repository.

$ escli repo get-login
  *** The previous docker login token will be expired.
  *** Do you want to continue? [y/N]: y
  *** Command to login EdgeScale registry:
         docker login -u xxxx -p 6964e3953ad4bb5b registry.edgescale.org/xxxx

Other commands

Model

The command is used to create, delete, or edit the device model.

$ escli model
  Usage: escli model [OPTIONS] COMMAND [ARGS]...

  model of device management.

  Options:
    -h, --help  Show this message and exit.

  Commands:
    create  Create new model name, e.g, yun-ls1043a-gateway-nxp
    delete  Delete model by ID
    list    query and show the available model list
    update  Update model with a new name

Vendor

The command is used to create or check device vendor list.

$ escli vendor -h
  Usage: escli vendor [OPTIONS] COMMAND [ARGS]...

  manufacturer vendor management.

  Options:
    -h, --help  Show this message and exit.

  Commands:
    create  create a new manufacturer vendor, admin is required
    delete  Remove a vendor by vendor id, admin is required
    list    query and show the vendor list