EdgeScale Documentation · GETTING STARTED 2.1Basic Concept 2.1.1Bootstrap and Operational Image Bootstrap image is the “golden” image used to authenticate device with EdgeScale

EdgeScale DocumentationRelease 0.5

EdgeScale

Revision: a5f2fd1

CONTENTS

1 EdgeScale Overview 11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Supported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Supported Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Getting Started 32.1 Basic Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Quick Start Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Bootstrap & OTA 133.1 Bootstrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2 OTA update procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 User Management 194.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.2 Apply Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.3 Create Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.4 Set User Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.5 Check Detail Information Of User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5 OEM Config 235.1 CA Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.2 Service Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 Device Management 276.1 Device Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.2 Create a New Device Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.3 Create and Enroll Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296.4 Inactivate a Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296.5 Activate a Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306.6 Device Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316.7 Delete Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326.8 Monitor Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.9 Erasing Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.10 Device Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

7 Device Groups 377.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377.2 Bulk Device Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8 Application Management 41

i

8.1 APP Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418.2 Application Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

9 Solution Management 579.1 Solution Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

10 Monitor 6510.1 Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6510.2 Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6510.3 Task Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

11 Builder Management (Experimental) 6911.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6911.2 Write a buildspec.yaml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6911.3 Create Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7211.4 Manage Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

12 Connect to EdgeScale 7912.1 Build EdgeScale Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7912.2 OTA: Auto Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7912.3 non-OTA: Manual Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

13 Secure Solution 8313.1 Prepare secure bootstrap image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8313.2 Prepare secure solution image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8413.3 Create device and bootup in secure mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8413.4 Enforce the secure boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8413.5 Read pub key from device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8413.6 Upload device db to cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

14 Container Security 8714.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8714.2 Setup a secure Private Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8814.3 Use a trusted registry and image on EdgeScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

15 ESCLI Usage 9715.1 ESCLI Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9715.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9715.3 Common Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

16 Connect Public Cloud 10716.1 Azure IoT Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10716.2 Ali-Cloud IoT Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10916.3 AWS Greengrass Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11216.4 Google IoT Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11216.5 IBM Watson IoT Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

17 Bring your board to EdgeScale 11517.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11517.2 Software dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11517.3 Enable the OTA feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

18 Application Notes 11718.1 Enable AI framework: TensorFlow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11718.2 Connect to Secure Element chip: A71CH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

ii

19 Frequently Asked Questions (FAQ) 11919.1 How to access EdgeScale? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11919.2 I have one container app, how to deploy it to my device? . . . . . . . . . . . . . . . . . . . . . . . . 11919.3 I have one system image, how to deploy it to my device? . . . . . . . . . . . . . . . . . . . . . . . . 12019.4 My software image is stored at other place, how to connect it with EdgeScale service? . . . . . . . . 12019.5 Which platforms are supported with EdgeScale? Does it support x86? . . . . . . . . . . . . . . . . . 12019.6 Is EdgeScale open-source? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12019.7 What’s the difference of facial recognition APPs in store? . . . . . . . . . . . . . . . . . . . . . . . 12019.8 How to fix the following issue when board is boot up with ubuntu rootfs? . . . . . . . . . . . . . . . 12019.9 How to create a device and enroll it with escli? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12119.10 How to make Docker image size small? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

iii

CHAPTER

ONE

EDGESCALE OVERVIEW

1.1 Overview

EdgeScale is a unified, scalable, and secure device management solution for Edge Computing applications. It en-ables OEMs and developers to leverage cloud compute frameworks like AWS Greengrass, Azure IoT, and Aliyun onLayerscape devices.

EdgeScale provides the missing piece of device security and management needed for customers to securely deployand manage many Edge computing devices from the cloud. End-users and developers can use the EdgeScale clouddashboard to securely enroll Edge devices, monitor their health, attest, and deploy container applications and firmwareupdates.

EdgeScale can also be used as a development environment to build containers and generate firmware.

1.2 Supported Features

• EdgeScale dashboard for users

• EdgeScale command line tool for users

• EdgeScale Restful APIs for developers

• Secure device enrollment

• Secure key/certificate provisioning

• OTA: firmware update

• Device status monitoring on the cloud

• Dynamic deployment of container-based applications

1.3 Supported Devices

• LS1012A: QorIQ Layerscape LS1012A Low Power Communication Processor

• LS1021A: QorIQ Layerscape LS1021A Dual-Core Communications Processor with LCD Controller

• LS1043A: QorIQ Layerscape LS1043A Multicore Communications Processors




1

EdgeScale Documentation, Release 0.5

• LX2160A: QorIQ Layerscape LX2160A Multicore Communications Processors

• LS1012A-FRWY: Lowcost LS1012A derivatives

2 Chapter 1. EdgeScale Overview

CHAPTER

TWO

GETTING STARTED

2.1 Basic Concept

2.1.1 Bootstrap and Operational Image

Bootstrap image is the “golden” image used to authenticate device with EdgeScale cloud and update new version ofsoftware image which is called operational image. The bootstrap image is a small stable flash booted image withminimal software packages which connects to EdgeScale cloud. It is seldom updated. The operational image isusually a full functional SD card booted image which has docker engine built-in and support container based apps. Ifthe device does not support SD boot, the boot loader is supposed at flash and the root file system is stored at SD card.

2.1.2 Identification and Certificate

The identification info is a device specific private key generated at the cloud. It will be used as the initial credentialto connect EdgeScale cloud by the device. During the device on-boarding, this private key will be used to sign devicemeta data and cloud can verify this feature by the corresponding public key. After this step, EdgeScale will issue acertificate for this device used for device to cloud communications.

Note: This private key is only generated for device has not been provisioned by the secure manufacturing. For secureprovisioning, please check the “secure solution” section

Currently this kind of data is taking the form of a shell script and downloaded from the dashboard while creatingdevice. Sometimes it is also called identification image.

2.1.3 Device Model

The device model describes the metadata and management characteristics of a device. It determines which version ofsoftware image will be installed on the device automatically.

2.2 Quick Start Guide

2.2.1 Register and Sign-in

• Register an account: open a web browser and connect to EdgeScale Portal

3

https://console.edgescale.org


It will send email to admin: [email protected]

After approval, you will get an email with a random password, please login and set a new passwd for you.

• When the account is available, you can sign in

• Follow the account setting and reset password

2.2.2 Prepare Device

1. Create Device

• Go to SmartConnect -> My Devices and Create

4 Chapter 2. Getting Started

mailto:[email protected]


2. Download & Provision Device Identity

• Fill in the form with SN number and device model info (select from suggested data)

• click Submit will register the device and a popup window prompts you to download the device credential.

• Download the device identity info

bootstrap-enroll--iot.gateway.ls1043ardb.nxp.sh

• Check device is created

2.2. Quick Start Guide 5


• Copy the script file to your Linux host

• Execute the script file (linux bash script) on the Linux host, with the SD card inserted

$ sudo ./bootstrap-enroll-2f63c75eaa50535087e623c5c0f22721.iot.gateway.ls1043ardb.nxp.→˓sh d̄ev/Install EdgeScale AAA service Private key to Disk /dev/sdd: 7.4 GiB, 7948206080 bytes,→˓ 15523840 sectors- Yes|No ---Yes[...]048576 bytes (1.0 MB, 1.0 MiB) copied, 0.00334797 s, 313 MB/s[...]048576 bytes (1.0 MB, 1.0 MiB) copied, 0.00155437 s, 675 MB/s

After this step, the device identity information is saved on some reserved area of SD card. Next, we need to preparethe software image for the device which includes building and install the image on the SD card.

3. Deploy EdgeScale agents on the device

There are two ways to install the EdgeScale agents on the device.

3.1 Build EdgeScale agents from source

Below is an example for enabling EdgeScale client in LSDK based image. Please check LSDK and the building tool:flex-builder for more information. This is for non-secure mode, if booting device with secure boot checking, pleaserefer the “secure solution” section.

• Preconditions

EdgeScale client depends on golang 1.9 environment. If the system is installed with old version, please update it to1.9

# rm -rf ~/go && curl -L https://redirector.gvt1.com/edgedl/go/go1.9.4.linux-amd64.→˓tar.gz | tar xz -C ~/

• Enable the EdgeScale components in LSDK

cd flexbuildsource setup.env

# vi configs/build_lsdk.cfgCONFIG_BUILD_QORIQ_EDGESCALE=y


https://lsdk.github.iohttps://lsdk.github.io


• Build the images

# flex-builder clean# flex-builder -m

3.2 Install pre-built pkg on the device

Note: Currently, only debian pkg supported

This package could be used:

1. LSDK1903 image without EdgeScale agents builtin.

2. Legacy LSDK images, verified with LSDK1806/1809/1812.

3. Any ODM/OEM board derived from LSDK rootfs.

Download the Debian package according to the following table.

Version Platform packagev1903 ARM64 Debian packagev1903 ARM32 Debian package

• You can use the command to get the debian package. Such as wget

• Use the following commands to run the debian package

=> dpkg -i edgescale-agents_1903_arm64.deb

4. Manually deploy the image to SD card

In this mode, the image is installed manually on SD card, not support deploying image from cloud dashboard.

• insert the SD card into x86 host Identify the physical device with dmesg or sudo gparted, such as /dev/sdx

• umount the SD card if auto mounted

sudo umount /dev/sdx

• install the solution image

assume the solution image components are stored in build/images

$ cd build/images$ flex-installer -b bootpartition_LS_arm64_edgescale_lts_4.9.tgz -r rootfs_ubuntu_→˓bionic_LS_arm64_edgescale.tgz

-f firmware_[ls1043ardb|ls1046ardb]_uboot_sdboot.img -s 8 -d /dev/→˓

• Note: please mount the second and third partition of SD card and check bootparti-tion_LS_arm64_edgescale_lts_4.9.tgz and rootfs_ubuntu_bionic_LS_arm64.tgz are installed in SD cardsuccessfully. if the second partition is empty, please run the following command to install:


https://image.edgescale.org/1903/debian-pkg/edgescale-agents_1903_arm64.debhttps://image.edgescale.org/1903/debian-pkg/edgescale-agents_1903_arm32.deb


$ cd build/images$ mount the second partition to $ tar zxvf bootpartition_LS_arm64_edgescale_lts_4.9.tgz -C $ umount

• insert the SD card into target board and boot.

For OTA (automatically deploy image from cloud), please refer Bootstrap.

5. Bringing the Device On-line

• Cleanly umount the SD card from the host, and insert it in the target platform

• Power up the target and stop in u-boot (CTRL-C)

• Reset to boot from SD card

=> cpld reset sd

• Platform will start up, connect to the Internet, and register with the cloud infrastructure.

• Verify Device Certificate Enrollment with dmesg

[ 30.159672] Checking for ethernet port fm1-mac3[ 40.242777] Link detected: yes[ 45.000582] network ethernet port is fm1-mac3[ 45.004823] fm1-mac3 Link encap:Ethernet HWaddr 00:04:9f:04:1e:3c[ 45.005105] inet addr:192.168.147.137 Bcast:192.168.147.255 Mask:255.→˓255.255.0

...

[ 45.010835] Setting time from www.baidu.com[ 47.349473] Tue Apr 24 12:43:18 UTC 2018[ 47.629792] No valid certificate found, starting 3 Phases Certificate Enrollment[ 47.630061] starting Phase1[ 61.902924] starting Phase2[ 66.152794] starting Phase3[ 67.629686] create PKCS10 request[ 72.118433] Starting E-EST certificate Enrollment[ 73.265688] set Hostname to 2f63c75eaa50535087e623c5c0f22721.iot.gateway.→˓ls1043ardb.nxp

...

[ 83.353776] Start kubelet[ 83.998282] 1+0 records in[ 83.998558] 1+0 records out[ 83.998766] 512 bytes copied, 0.00045336 s, 1.1 MB/s[ 84.030918] ./ota-statuscheck: 17: [: x: unexpected operator[ 84.031286] ./ota-statuscheck: 21: [: x: unexpected operator[ 84.033247] 0+1 records in[ 84.033499] 1+0 records out[ 84.033741] 512 bytes copied, 0.00041832 s, 1.2 MB/s

• It is recommended to update local time zone of the device:

$ dpkg-reconfigure tzdata

• Refresh My Devices will show the device as online



2.2.3 Deploy APP

1. Deploy APP to device

• Follow Edge Software Store -> App Store -> App Market, select one APP (filter by tag) and addto My App

• Click Deploy in My app



• Select device(s) and then click Deploy App

2. Monitor APP task

• Click Task to check deployment task status, click taskname to check app status.



3. Running APP

Find the APP running card and click top-right icon to check App Log

• find the IP address to open the related service

For example, Image Classification APP


CHAPTER

THREE

BOOTSTRAP & OTA

3.1 Bootstrap

To enroll your device in EdgeScale, the bootstrap image needs to be programmed firstly, and then reboot the board,the OTA process will start to install corresponding solution image which is associated with selected model, finally theenrollment will be done.

The guide will introduce how to get and flash the images to finish enrollment in EdgeScale.

3.1.1 Image Download

Download the bootstrap images according to the following table. Only work with LSDK1903 solution image, can notbootup with previous LSDK release versions.

3.1.2 Images

Version Platform Imagesv1903 LS1012ARDB qspi_ls1012ardb.imgv1903 LS1043ARDB nor_ls1043ardb.imgv1903 LS1046ARDB qspi_ls1046ardb.imgv1903 LS1088ARDB_PB qspi_ls1088ardb_pb.imgv1903 LS2088ARDB nor_ls2088ardb.imgv1903 LS1021ATWR nor_ls1021atwr.imgv1903 LX2160ARDB xspi_lx2160ardb.img

3.1.3 Precondition

• Setup the tftp server

• Copy the bootstrap image to tftp server

• Configure network for board to ensure it can connect to tftp server

3.1.4 Flash Image

LS1012ARDB/LS1046ARDB/LS1088ARDB/LX2160ARDB

• Create device in the EdgeScale dashboard and download the identification image

13

https://image.edgescale.org/1903/non-secure/ls1012ardb/qspi_ls1012ardb.imghttps://image.edgescale.org/1903/non-secure/ls1043ardb/nor_ls1043ardb.imghttps://image.edgescale.org/1903/non-secure/ls1046ardb/qspi_ls1046ardb.imghttps://image.edgescale.org/1903/non-secure/ls1088ardb_pb/qspi_ls1088ardb_pb.imghttps://image.edgescale.org/1903/non-secure/ls2088ardb/nor_ls2088ardb.imghttps://image.edgescale.org/1903/non-secure/ls1021atwr/nor_ls1021atwr.imghttps://image.edgescale.org/1903/non-secure/lx2160ardb/xspi_lx2160ardb.img


• Program the identification image to SD on a Linux PC

$ sudo fdisk -l # find the /dev/sdx for the SD card e.g. /dev/sdb$ sudo umount /dev/sdx$ sudo bootstrap-enroll-.sh /dev/sdx

• Insert SD card to the board then boot the board to enter u-boot prompt

• Run the following command to flash the bootstrap image

=> tftp 0xa0000000 /tftpboot/qspi_/xspi_lx2160ardb.→˓img=> sf probe 0:0=> sf erase 0 +$filesize=> sf write 0xa0000000 0 $filesize

• Run the following command in u-boot environment to start the OTA process

=> reset

LS1043ARDB/LS1021ATWR






=> tftp 0xa0000000 /tftpboot/nor_.img=> pro off all=> erase 0x60000000 +$filesize=> cp.b 0xa0000000 0x60000000 $filesize


=> reset

LS2088ARDB






14 Chapter 3. Bootstrap & OTA


=> tftp 0xa0000000 /tftpboot/nor_ls2088ardb.img=> pro off all=> erase 0x580000000 +$filesize=> cp.b 0xa0000000 0x580000000 $filesize


=> reset

3.2 OTA update procedure

3.2.1 Precondition

The SD storage range of 63M~64M is reserved to store OTA status information. This area is accessed both by thebootstrap image and the new SD image.

3.2.2 OTA process

• When first time start the board, the bootstrap image will be started from flash. Then it will get latest SD cardimage from cloud and install it on the SD card.

• The OS will be started from SD card normally. OTA script will check if there is a new version of image for thedevice periodically.

• If update failed, the bootstrap image will be started from flash and roll back to old SD card image.

3.2.3 Procedure

To automatically deploy the solution image to device, please refer below work flow:

3.2. OTA update procedure 15


• Create device, bind model and build the solution image with EdgeScale agents

Please refer Quick Start Guide.

• Compress all the software images as a tgz file

tar czvf edgescale_lsdk1903-ls1046_image_sdboot.tgz \bootpartition_LS_arm64_edgescale_lts_4.14.tgz \firmware_ls1046ardb_uboot_sdboot.img \rootfs_ubuntu_bionic_LS_arm64_edgescale.tgz

• Upload the compressed solution image to a storage server and get the downloading URL link

Currently, EdgeScale will NOT host user’s binary image. Assume user has his own public storage.

• Create the solution image via EdgeScale dashboard

click Create button and go to the solution create page

Model name, solution name and version are required.

Model Name: Chose a model for solution

Solution Name: The name for solution

Version: The version for solution

• Specify solution permission and tag

private: Can’t be seen by others



public: Can be seen by others

tags: Add tags to the solution

• Specify solution image location (URL link)

Specify Firmware Location An specific firmware address(Image URL)

Upload Firmware Image User can upload a local firmware image

• Click submit button and finish creating solution.

• Download and flash bootstrap image to device as previous “Bootstrap” section

3.2. OTA update procedure 17

CHAPTER

FOUR

USER MANAGEMENT

4.1 Introduction

User management includes Apply Account, Audit Account and Create Account. Before user login the system, theyshould apply account first. The administrator will check the application and create an account for user.

4.2 Apply Account

• click Apply Now button on the login page, go to apply account page. (First Name, Last Name, Email, AccountType, Company Name) these items are required.

19


• After click Apply Now button, there will be a new data(marked with red box) on Auth > Auth list page.

Administrator can audit users’ application (only administrator can see this):

• Approved: application will be passed and administrator will create an account, then send the account informationto user’s email. User can change the password according the email.

• Rejected: application will be rejected and administrator will send the reject information to user’s email.

4.3 Create Account

• click Manage > User on left banner, go to user list page.

• click Create button(marked with red frame) to go to create user page.

20 Chapter 4. User Management


• After click submit button, there will be a new data(marked with red box) on user list page.

4.4 Set User Limit

• click the setting button(marked with red box), can open the setting limit dialog:

• Device: set the max number devices that user can create

• Deploy: set the max number solution that user can deploy

4.4. Set User Limit 21


4.5 Check Detail Information Of User

• click the name on the table, go to user detail page On this page, administrator can check user’s basic informationand device, model, solution, application information of the user

22 Chapter 4. User Management

CHAPTER

FIVE

OEM CONFIG

5.1 CA Config

Click Portal -> Config on the left navigation. The Config page has two items, one is for CA and the other is forservice:

5.1.1 CA Config

Fill in the field with Root CA and Private Key from your certificates bundle package.

• Root CA: OEM CA, used to protect OEM specific service.

• Private Key: used for issuing the secondary certificate.

• Trust chain: verify secondary or more level certificate.

Once the CA is updated by this config, the communication between the device and the OEM specific service isprotected by this CA.

5.2 Service Config

Click Create button.

23


5.2.1 Service Config

Add Private Registry Service

• Service Name: a readable name for this service.

• URL: service URL, like https://service.oem.com.

• Port: service port, like 80 for web.

• Token: private docker repo access token Optional field, current only support dockerrepo service.

24 Chapter 5. OEM Config

https://service.oem.com


5.2. Service Config 25


26 Chapter 5. OEM Config

CHAPTER

SIX

DEVICE MANAGEMENT

6.1 Device Model

The device model describes the metadata and management characteristics of a device. This metadata determines the version of firmware or solution software which will be run on the device. Currently the model composes of the following fields:

vendor.platform.type.model

• vendor is the manufacture of the device

• platform is the main CPU used on the device

• type defines the general functionality of the device, such as gateway, l2switch, firewall.

• model is the device’s model number. On most devices, it can be usually found in the label located on thefront, back, side or bottom.

For example, a reference board made by NXP could take the model string as: nxp.ls1043a.gateway.rdb

6.2 Create a New Device Model

• Click Devices -> Device Model -> Create

27


• Input the device model arguments, select from pull down box or provide new data

If this device model is only used by yourself, make sure private is selected

• Get back to device model list and check the new model is generated

28 Chapter 6. Device Management


6.3 Create and Enroll Device

Click Devices -> Device List -> Create

• Fill in the SN number and device model (select from the drop-down list) in the following form.

• Please refer the Quick Start Guide and Bootstrap to enroll device manually or automatically (OTA process).

6.4 Inactivate a Device

Inactivating a device means to disable the device functionality from the cloud. After the instruction is sent to device,the device will erase the identification and certificate and disconnect from the cloud.Anyway, the bootstrap image willnot be erased and the device can go through the enroll process as a new device.

6.3. Create and Enroll Device 29


6.5 Activate a Device

When the device is in “Inactive” state, click the Active button at the device page, the bootscript download windowwill pop up. The bootscript contains the device identity and device specific private key. The device can go through theenroll process again with the script and connect to the cloud.



6.6 Device Detail

Device detail page displays more information of the device running status: App Number: number of runningAPPs on the device

CPU Usage: percentage of CPU load

Mem Usage: percentage of memory used

EdgeScale Version: EdgeScale agents version.

Device Logs: including system log and EdgeScale agents logs

Statistics: Including CPU Usage, Mem Usage and Disk Usage

6.6. Device Detail 31


6.7 Delete Device

To delete a device, click Delete button of the corresponding device in the “DeviceList” page. It will ask for user’sconfirmation before it is deleted.



6.8 Monitor Device

When user starts a device, then a start time will send to the database, EdgeScale will receive the start time and showan mark(marked with red box) on device list page to show that the device is online. when user turns off the device, themark will be offline.

6.9 Erasing Device

When user click the Destroy button on device detail page, There will be a pop up window. If you click Yes, All thedata on the device will be erased.

6.8. Monitor Device 33


6.10 Device Group

6.10.1 Create a device group

Click Devices -> Device Group -> Create

After click Submit button, there will be a new group item in the list



6.10.2 Check group detail information

Click group id, page will link to group detail page

6.10.3 Bind and Remove devices

Click Add button, bind devices to current device group

6.10. Device Group 35


Click Bind to Group, all devices you select will be bind to current group. On Group List page, select devices,and remove button can be used, click it, and all devices you select will be removed from current group.

6.10.4 Deploy group

Click deploy icon (red box content), deploy dialog will show

On deploy dialog, customers can select deploy app or solution, select the target app or solution.

• click deploy button, target apps or solution will be deployed to device in this group, and create a task.

• click Save as template button, current deploy setting will be save as a template, and create a tem-plate.


CHAPTER

SEVEN

DEVICE GROUPS

7.1 Overview

For effective and quick device management, EdgeScale allows users to manage several devices at once by categorizingthem into groups. EdgeScale supports both dynamic groups and static groups, system groups and custom groups.

7.1.1 Device Group Types

System Groups Default groups created by EdgeScale

1. Model: device group(s) per device model.

2. Customer: device group(s) per customer.

Custom Groups Created by the user for specific requirements. Users can view, edit, and delete group.

1. Static Groups: Manually created by the user by adding specific devices to a group. Thesegroups change only when a user manually changes the devices in the group.

2. Dynamic Groups: Groups that are dynamically defined by matching user-specified criteria.Devices in the group change based on the result of devices that are discovered by using criteria.

Here are the things users can do with device groups:

• Create, describe or delete a static device group.

• Add device(s) into a static device group.

• Remove device(s) from a static device group.

• List the dynamic device groups created by system and static groups created by user.

• List the devices in a group.

• Add, delete or update the attributes of a static group.

7.2 Bulk Device Management

EdgeScale supports several bulk operations on device groups.

• Manufacture service could generate config file for a production or sales batch

• Bulk provisioning per device group

• Bulk deployment per device group

37


7.2.1 Manufacture

• Project name: input the project name

• Model: select device model

• Number: input the device number of this production or sales batch

• Customer: select customer name

Each manufacture project provides a general config file per the device batch. This file needs to be saved to thefilesystem of device during factory manufacture.

For example:

api: https://api.edgescale.org/v1mft:

keyID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxoemID: "xxx"key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can perform the following actions on user’s historical manufacture projects

1. check the project details

2. download the config file

3. delete the project

38 Chapter 7. Device Groups


When the devices with the config file embedded in file system are powered on, they will be registerred automaticallyto EdgeScale.

7.2.2 Manage Device Group

Refer to

• Create a device group

• Check group detail information

• Deploy group

7.2. Bulk Device Management 39


40 Chapter 7. Device Groups

CHAPTER

EIGHT

APPLICATION MANAGEMENT

8.1 APP Store

8.1.1 Introduction

APP store is the digital distribution platform for the dockerized application running on devices, it supports the appli-cation view, search, deploy and monitor on the end devices.

The following is the major function modules:

• create

• delete

• view

• update

• deploy

8.1.2 Public & Private APP

Private: The APP is only visible to the owner, it is maintained by the owner.

Public: The APP is visible to every user.

If a private APP needs to be public, the owner should be responsible for the quality assurance.

8.2 Application Management

8.2.1 Get available APPs

Click Edgescale Software Store on the top navigation bar.

• Click App Market to view public APPs list page.

• Click My App to my APPs list page.

41


8.2.2 Add App in Market into My App

Click App Market > Add to My APP to add one APP from Market to My APP.

8.2.3 View and edit APP

Click APP’s name to view the details of the APP in Market, or edit the APP in My APP.

42 Chapter 8. Application Management


• click App permission to configure if the APP is visible to other users.

8.2. Application Management 43


Apply for a public store: Enroll the APP into EdgeScale public app store with justification.

• Click App Documents to edit the APP documents

• Click Edit to update the basic configuration of APP

• Click Add to add more docker run arguments



8.2.4 Create APP

Click Create App button to create a new APP.

All the fields marked with “*” are mandatory.

Step1: input the basic info.

• App Name (mandatory): the name for APP

• Description: the description for APP

• Upload Icon: upload APP icon

Step2 : input the configuration info.

• Registry (mandatory): select the registry for APP container

• Image Name (mandatory): the image name for APP container

• Version (mandatory): the version for APP container



• Commands: shell commands, like “/bin/bash -c”, etc.

• Arguments: command arguments.

• Host Network: Connect a container to a network

• Host Port: Container host port

• Container Port: Container port

• Host Path: Container host path

• Mount Path: Container host path

• Cap Add: add Linux capabilities

Click submit button to create the APP.



8.2.5 Delete APP

Click My APP > Delete to remove An App out of My APP

8.2.6 Deploy APP

1. Deploy an APP to device

Click Edge Software Store > App Store > My App > Deploy.

Step:

• App Version: Choose the APP version

• More Arguments: Specify the “docker run” command arguments for deployment

• Devices: Choose devices

• Deploy App: Deploy APP to devices



Click Deploy button to begin the deployment, and then go to the task page.

2. Deploy an APP to group devices

Click Smart Connect > Device > Device Group



Select one or more apps. Click Deploy, then apps selected will be deployed to every device in this group.

3. Deploy APPs from task template

Click Smart Connect > Task > Task Template.



In this new page, we can preview and edit the template.

Click Deploy to create a new deployment task, then swith to task page to view the latest deployment status.



8.2.7 Arguments for APP

1. arguments setting of creating APP



2. argument of deployment



3. docker run command



4. application argument


CHAPTER

NINE

SOLUTION MANAGEMENT

9.1 Solution Store

9.1.1 Introduction

Solution store is a visual solution control system. It is designed as a tool for users to manage solution software.

The major components compose of:

• create

• delete

• view

• update

• deploy

9.1.2 Get Solution List

• Click Software > Solution in the left navigation bar

• Click the solutions title to open solution detail page:

57


9.1.3 Deploy Solution Image

If automatic OTA is configured, the device accepts solution image update command from the cloud. User can select asolution image in the store and deploy it to device(s).

Click Deploy button to deploy solution to devices:

Step1: Filter devices (According Location, Platform and Tag, system will find target devices)

58 Chapter 9. Solution Management


Step2: Select devices to deploy solution

Step3: Review deploy configuration to make sure all information is correct, and then deploy.

9.1. Solution Store 59


9.1.4 Upload a solution image

Click the Edge Software Store at the top of the page and the Solution Store in the left navigation bar.

Click Create button to open the “solution create” page.

All the fields marked with “*” are mandatory.

Step1: Input basic information:

Model Name: choose a model for solution Solution Name: specify the name of solution Version: specify the versionof solution

Step2: Define the permission of solution:

Permission: private solution is visible to the solution owner; public solution is visible to all the users. Tags: applytags to solution



Step3: Configure firmware settings

• Specify the firmware location(Image URL), assume this image is uploaded in a public file storage.

• Upload Firmware Image - user can upload a local firmware image (NOT supported yet)

Step4: Enable trusted solution image (Optional)

• If the image is signed by a private key, please upload the corresponding public key.

Click submit button to create the new solution.

9.1.5 Solution component update

This section introduces how to update the system software component such as firmware, uboot, kernel, dtb, rootfs, etc.

Warning: Update the system software component is riskful. Please make sure the software component is com-patible with the software image on the device. Otherwise, it may cause the system can not boot or functional asnormal.

1. Pecondition:



• Device is online

• Device is already deployed with the full solution image. Keep the component version is same as the full solutionimage.

2. Prepare components that need to be upgraded (u-boot; boot partition) and install.sh

Step1: Provide the install script on how to deploy the software component image on the device.

Note: The install script must be named as “install.sh”. Below example is only working with lsdk solution image. Youshould adapt the install script to the target device and software system.

For example, update component on ls1012ardb with lsdk image

• The install script for uboot should looks like below:

#!/bin/bash

download_path=/run/media/mmcblk0p3/updateImagesif [ -e ${download_path}/firmware*.img ];then

update_file=`ls ${download_path}/*firmware*.img`flex-installer -f $update_file -d /dev/mmcblk0

fi

• The install script for kernel looks like below:

#!/bin/bash

download_path=/run/media/mmcblk0p3/updateImages

if [ -e ${download_path}/boot*.tgz ];thenupdate_file=`ls ${download_path}/*boot*.tgz`ls | grep -v lost+found | xargs rm -rf {}tar zxf $update_file -C /run/media/mmcblk0p2

fi

Step2: Tar components that need to be upgraded with install script.

#packaging the uboot image with install script$tar czvf install.tgz firmware_ls1012ardb_uboot_qspiboot.img install.sh

#packaging the bootpartition image with install script$tar czvf install.tgz bootpartition_LS_arm64_lts_4.14.tgz install.sh

Step3: Create solution component image.

Please refer Upload a solution image



Note: When updaing solution component image, the checkbox ‘Have the installer in solution’ must be marked.

Fill in the image url in the solution and submit

Step4: Deploy component image.

Please refer Deploy Solution Image

Select the solution component image you create for deploy


CHAPTER

TEN

MONITOR

10.1 Devices

Click Here to see more device monitor

10.2 Task

10.2.1 Introduction

Task is designed as a tool for users to monitor the status of APPs/solutions deployment (including delete, view).

10.2.2 Get Task List

Click Task > Task List on the left navigation bar

Click task’s id to open the task detail page:

65

https://doc.edgescale.org/device.html


10.3 Task Template

10.3.1 Introduction

Task template is designed as a tool for users to save already exists task into a template (including delete, view).

10.3.2 Get Task Template List

Click Task > Task Template on the left navigation bar

Click task’s Save As Template icon to save current task into a template:

Click Submit button, there will be a template item in template list

66 Chapter 10. Monitor


Click template id (red box content), the page will link to template detail page

Click deploy icon (green box content), the page will link to edit and deploy page

10.3. Task Template 67


After finished editing, click deploy button, this changed template will be deployed. If you click save button, all changeswill be saved without deploy.

68 Chapter 10. Monitor

CHAPTER

ELEVEN

BUILDER MANAGEMENT (EXPERIMENTAL)

This feature is an experimental feature. Currently it is only accessible for approved users. Contact admin torequest the permission.

11.1 Overview

Builder leverages AWS CodeBuild currently.

The steps to use it:

1. Write a build spec file named buildspec.yaml, and put it in your source directory

2. Save your source in either of the below ways:

• Push to github.com repository

• Push to a AWS CodeCommit repository

• Create a zip file, and put it into a version-enabled AWS S3 bucket

3. Create build project

4. Start build manually or automatically

11.2 Write a buildspec.yaml

A build spec is a collection of build commands and related settings, in YAML format, that Builder uses to run a build.By default, the build spec file must be named buildspec.yml and be placed in the root of your source directory.

11.2.1 Syntax

The build spec has the following syntax:

version: 0.2

env:variables:key: "value"key: "value"

parameter-store:key: "value"key: "value"

(continues on next page)

69

https://aws.amazon.com/codebuild/https://aws.amazon.com/codecommit/https://aws.amazon.com/s3/http://yaml.org/


(continued from previous page)

phases:install:commands:

- command- command

pre_build:commands:

- command- command

build:commands:

- command- command

post_build:commands:

- command- command

artifacts:files:- location- location

discard-paths: yesbase-directory: location

cache:paths:- path- path

For details, please refer to AWS CodeBuild Manual.

11.2.2 Examples

Building Docker images

To build Docker images, Docker daemon needs to be installed and started in the build environment. Otherwise, allassociated builds that attempt to interact with the Docker daemon will fail. One way to do this is to initialize the Dockerdaemon in the install phase of your build spec by running the following build commands. (Do not run the followingbuild commands if you chose a build environment image provided by AWS CodeBuild with Docker support.)

- nohup dockerd --host=unix:///var/run/docker.sock --host=tcp://0.0.0.0:2375 --→˓storage-driver=overlay&- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"

Directory structure::

(root directory)|-- buildspec.yml|-- hello_world.go`-- Dockerfile

buildspec.yml:

70 Chapter 11. Builder Management (Experimental)

https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax


version: 0.2

phases:pre_build:commands:

- echo Logging in to Docker Hub...# Type the command to log in to your Docker Hub account here.

install:commands:

# install and start Docker daemon if needed- timeout 15 sh -c "until docker info; do echo .; sleep 1; done"

build:commands:

- echo Build started on `date`- echo Building the Docker image...- docker build -t hello_world:v1 .


- echo Build completed on `date`- echo Pushing the Docker image...- docker push hello_world:v1

Dockerfile:

FROM golang:1.9 as builderWORKDIR /COPY hello_world.go .RUN GOOS=linux go build hello_world.go

FROM ubuntu:16.04WORKDIR /root/COPY --from=builder /hello_world .CMD ["./hello_world"]

hello_world.go:

package main

import "fmt"

func main() {fmt.Println("hello world")

}

Building Non-Docker images

Directory structure:

(root directory)|-- buildspec.yml`-- hello_world.go

buildspec.yml:

11.2. Write a buildspec.yaml 71


version: 0.2

phases:build:commands:

- echo Build started on `date`- GOOS=linux go build hello_world.go


- echo Build completed on `date`

artifacts:files:- 'hello_world'

hello_world.go:

package main

import "fmt"

func main() {fmt.Println("hello world")

}

11.3 Create Project

Click Builder -> Projects -> Create on the Builder project list page. There are three steps to create a builderproject:

• Project basic information

• The source code of project

• The build environment of project

11.3.1 Basic Information

• Project Name: the name of the project

• Description: the description of the project



11.3.2 Source Code

• Source Provider:

– CodeCommit

– Amazon S3

– GitHub

• Repository: The URL of source code

• Branch: The branch of source code

• check periodically for changes

11.3. Create Project 73


11.3.3 Build Environment

• Environment: the environment of the project

• Image: the image of the project

• Compute Type:

– 3GB memory 2 vCPU



• Timeout



11.4 Manage Project

Click Builder -> Projects on the left navigation

11.4.1 Start/Edit/Delete

• Click start the first button on the Action column, then you can start this project, the status will changeto Running

• Click edit the second button on the Action column, page will link to edit page, the same with create page

• Click delete the third button on the Action column, then you can delete this project

11.4.2 View Project Detail

• Click Name column, then you can check the detail information about this project

11.4. Manage Project 75


11.4.3 View Project Log

• Click Log column, then you can check the log information about this project



11.4. Manage Project 77

CHAPTER

TWELVE

CONNECT TO EDGESCALE

12.1 Build EdgeScale Client

Currently only support building EdgeScale client with flex-builder on LSDK based images. Please refer 3. DeployEdgeScale agents on the device for building instructions.

12.2 OTA: Auto Deployment

12.2.1 Introduction

A solution image can be deployed to one or more devices from the EdgeScale web page . this guide will introducehow to deploy one solution to one device.

1. Click Software > Solution on the left navigation to go to solution page.

2. Click Deploy button of selected solution (e.g. edgescalecli001-test) to go to ‘Filter’ page.

79


3. Fill in the device filter conditions and click Query Devices button to go to ‘Select devices’ page.

4. Select one device and click Next Step: Preview button to go to the ‘Preview’ Page.

80 Chapter 12. Connect to EdgeScale


5. Click Next Step: Deploy button to go to the ‘Status Monitor’ Page.

12.3 non-OTA: Manual Deployment

In this mode, the image built by flex-builder is manually installed on SD/USB/SATA storage. After this, the dockerbased application can be deployed from cloud. for more details about how to manually build and deploy the LSDKdistro with EdgeScale client to storage. please refer the LSDK doc: https://lsdk.github.io/.

1. Login EdgeScale, create device, bind device model at the dashboard and download the identification imagelike:bootstrap-enroll-.sh

2. Boot up the board using the LSDK tiny itb image, format and create new partition on storage, then deploy theLSDK bootpartition and rootfs into the storage. e.g. for ls1046a: In u-boot:

=> setenv bootargs root=/dev/ram0 rw console=ttyS0,115200 earlycon=uart8250,mmio,→˓0x21c0500 ramdisk_size=0x10000000=> tftp a0000000 lsdk_linux_arm64_tiny.itb=> bootm 0xa0000000#ls1046ardb

In Linux:

$ flex-installer -i pf -d sd$ cd /run/media/mmcblk0p3 # then download the bootpartition and rootfs you generated→˓using LSDK into this partition.$ flex-installer -i install -b -r -m ls1046ardb -d sd$ reboot

3. Boot up the board form storage. e.g. for ls1046ardb In u-boot:

=> cpld reset sd

4. After booting up board form storage. copy and run the identification image and start the enrollment process.

$ bash bootstrap-enroll-.sh /dev/mmcblk0$ startup.sh

12.3. non-OTA: Manual Deployment 81

https://lsdk.github.io/


82 Chapter 12. Connect to EdgeScale

CHAPTER

THIRTEEN

SECURE SOLUTION

This section is very platform dependent and Strongly suggest reading the security chapter of the LSDK document firstbefore running any real instructions on the device.

In order to build secure solution, you need to boot the board securely. Steps to do so can be found in LSDK document“security chapter”.

13.1 Prepare secure bootstrap image

• Generate key pair using CST tool

CST tool could be built from source and key pair generation is one of the functionality. Generally, the key pairshould be generated once and keep safe. The private key will be used to sign images and the public keywill be fused into device to verify the image signature.

# build cst tool from source$ flex-builder -c cst

$ cd /packages/apps/cst

# generate RSA key pair: srk.pub and srk.pri, 1024bit$ ./gen_keys 1024

• Download secure bootstrap image: secure-ota-.tar from EdgeScale

Version Platform Imagev1903 LS1012A secure-ota-ls1012a.tarv1903 LS1043A secure-ota-ls1043a.tarv1903 LS1046A secure-ota-ls1046a.tar

• Signing the bootstrap image with gen-ota-image.sh

untar the downloaded file will find gen-ota-image.sh

$ export SRK_PUB=/srk.pub$ export SRK_PRI=/srk.pri$ export CST_PATH=/cst$ bash gen-ota-image.sh

83

https://image.edgescale.org/1903/secure/ls1012ardb/secure-ota-ls1012a.tarhttps://image.edgescale.org/1903/secure/ls1043ardb/secure-ota-ls1043a.tarhttps://image.edgescale.org/1903/secure/ls1046ardb/secure-ota-ls1046a.tar


13.2 Prepare secure solution image

• Specify the keys pair for secure boot in configs/build_lsdk.cfg

SECURE_PRI_KEY=/home/xx/path/srk.priSECURE_PUB_KEY=/home/xx/path/srk.pub

• Building EdgeScale agents as LSDK user guide see more at 3. Deploy EdgeScale agents on the device.

13.3 Create device and bootup in secure mode

• Create device via EdgeScale dashboard or escli command line tools.

• Program secure bootstrap image into device, see more at Bootstrap.

13.4 Enforce the secure boot

In production systems, secure boot is enforced via blowing the ITS fuse.

In development environment, if you are booting the board securely using SB_EN bit, you need to ensure that ITS bitis set. This can be done via code-warrior (ccs). For this you would need to put the core in boot hold-off by setting thecorresponding bit in RCW.

• Set the ITS bit through CCS when the system is in boot hold off state.

#Boot up the system

#Connect CodeWarrior/ccs

#Set the ITS bit if ITS not fused$ ccs::write_mem 0x1e80200 4 0 0x00000004

#Get the Core Out of Boot Hold-Off$ ccs::write_mem 0x1ee00e4 4 0 0x1

13.5 Read pub key from device

This public key is derived from srk.pub generated by CST tool and used for device authentication. mp_app ispart of secure object library and integrated with LSDK rootfs.

• Get MP public key:

– boot up system with secure mode

– Get public key in device with tool mp_app:

mp_app -p

Public key x part = 671fe89daca42004d648b2ad7ddeb2a0ca7e47556e73f376aab45061fca74603

Public key y part = 9519e09aab4da3a972511d3ca7e842e8bb1d02e744cc85ff4e65c0ca6fbb7376

Public key in form of x followed by y is saved in pub_key file

84 Chapter 13. Secure Solution


13.6 Upload device db to cloud

For secure enrollment of this device to the cloud, some data from the device needs to be uploaded to the cloud. Thisdata includes :

1. Manufacturing Protection Public key - Public part of the ECC key pair generated after secure boot process.Steps given in the Section “Read pub key from device”

2. Factory UID or FUID

3. OEM UID (For reading 2 and 3, please refer to the SoC SFP block memory map from the Reference Manual)

#csv file schema: FUID, OEMID, SK_PUB_X, SK_PUB_Y, MODEL_ID

$ escli device upload-db -f

13.6. Upload device db to cloud 85


86 Chapter 13. Secure Solution

CHAPTER

FOURTEEN

CONTAINER SECURITY

14.1 Overview

14.1.1 Introduction

We use the following features to ensure the docker security when reviewing container and image security onEdgeScale:

• Kernel namespaces

• control groups

• Docker daemon attack surface

• Linux kernel capabilities

• Use trusted docker private registry

• Use trusted images(signature and verification)

• Vulnerability Static Analysis for Containers

14.1.2 Illustrated

Container security on EdgeScale illustrated

87


The steps to use it:

• 1. Setup a secure Private Registry

• 2. Use a trusted registry and image on EdgeScale

14.2 Setup a secure Private Registry

14.2.1 Components

• Docker CE client

• Notary

• Docker private Registry

• Nginx

• Harbor

14.2.2 Installation the Trusted Private Docker Registry - Harbor

Installation Docker CLI and Docker compose

What’s Harbor

Harbor is an open source trusted cloud native registry project that stores, signs, and scans content. Harbor extendsthe open source Docker Distribution by adding the functionalities usually required by users such as security, identityand management. Having a registry closer to the build and run environment can improve the image transfer efficiency.Harbor supports replication of images between registries, and also offers advanced security features such as usermanagement, access control and activity auditing.

88 Chapter 14. Container Security

https://docs.docker.com/installhttps://github.com/theupdateframework/notaryhttps://github.com/docker/docker-registryhttps://www.nginx.com/https://github.com/goharbor/harbor


Prerequisites for the target host

Harbor is deployed as several Docker containers, and, therefore, can be deployed on any Linux distribution thatsupports Docker. The target host requires Python, Docker, and Docker Compose to be installed.

• Hardware

Resource Capacity DescriptionCPU minimal 2 CPU 4 CPU is preferredMem minimal 4GB 8GB is preferredDisk minimal 40GB 160GB is preferred

• Software

Software Version DescriptionPython version 2.7

or higherNote that you may have to install Python on Linux distributions (Gentoo, Arch) thatdo not come with a Python interpreter installed by default

Dockerengine

version 1.10or higher

For installation instructions, please refer to: https://docs.docker.com/engine/installation/

DockerCompose

version 1.6.0or higher

For installation instructions, please refer to: https://docs.docker.com/compose/install/

Openssl latest is pre-ferred

Generate certificate and keys for Harbor

• Network ports

Port Proto-col

Description

443 HTTPS Harbor UI and API will accept requests on this port for https protocol443 HTTPS Connections to the Docker Content Trust service for Harbor, only needed when Notary is en-

abled80 HTTP Harbor UI and API will accept requests on this port for http protocol

Downloading installer package

We offer two installation methods to setup Harbor. by default, we recommend offline installation.

Package Platform Image URLoffline Linux harbor-offline-installer.tgzonline Linux harbor-online-installer.tgz

Installation Steps

Download installer package and decompress

$ tar xvf harbor-offline-installer.tgz$ cd harbor-offline-installer$ mkdir /root/cert && cd harbor-installer

Get a certificate

• You can request a new certificate with trusted certificate provider.

14.2. Setup a secure Private Registry 89

https://docs.docker.com/engine/installation/https://docs.docker.com/engine/installation/https://docs.docker.com/compose/install/https://docs.docker.com/compose/install/https://image.edgescale.org/container/harbor-offline-installer.tgzhttps://image.edgescale.org/container/harbor-online-installer.tgz


• The certificate usually contains a .crt file and a .key file, for example, regisrty.edgescale.org.crt and reg-istry.edgescale.org.key.

• About the certificate conventions, please refer to the chapter Use a trusted registry and imageon EdgeScale -> Remarks.

Install by https

• edit file harbor.cfg, replace field ssl_cert, ssl_cert_key and hostname with your domain name.

• for example

$ cp cert/registry.edgescale.org.key /root/cert/$ cp cert/registry.edgescale.org.crt /root/cert/$ ./install.sh --with-notary --with-clair

Login and push

$ cp registry.edgescale.org-CA.crt /usr/local/share/ca-certificates/$ update-ca-certificates$ service docker restart$ docker login -u admin -p Harbor12345 registry.edgescale.org$ docker pull hello-world$ docker tag hello-world registry.edgescale.org/library/hello-world$ docker push registry.edgescale.org/library/hello-world

14.3 Use a trusted registry and image on EdgeScale

14.3.1 Enable Trusted Container for EdgeScale

Add OEM information to EdgeScale

Click Portal -> Config

• Fill in the field Root CA and Private Key from your certificates bundle package.

• Root CA - verify the security of the external connection.

• Private Key - issued to the secondary certificate.

• Trust Chain - verify secondary or more level certificate.



If you Filled, you can update a new certificates package.

• fill example.

Add Private Registry Service

Click Create button to add your private registry.

• Service Name: Current support service can be added.

• URL: filling your service URL.

• Port: filling your service port.

14.3. Use a trusted registry and image on EdgeScale 91


• Token: docker login token content. Optional field, current only support docker reposervice.

• fill example.

• get the token content, see below example.



Add Trust Container Service

Click Create button to add your trusted server address.

• fill example.

List all Services

If you need all service, you can found by below.



14.3.2 Pushing trusted container image on target host

Download Private Registry Certificate

$ cp registry.edgescale.org-CA.crt /usr/local/share/ca-certificates/$ update-ca-certificates$ service docker restart$ docker login -u admin -p Harbor12345 registry.edgescale.org

Enable content trust on your target host

$ export DOCKER_CONTENT_TRUST=1$ export DOCKER_CONTENT_TRUST_SERVER="https://trust.edgescale.org"

Pushing an singed image to Private Registry

$ docker tag debian registry.edgescale.org/library/debian$ docker push registry.edgescale.org/library/debian:latestThe push refers to repository [registry.edgescale.org/library/debian]dd60b611baaa: Pushed1.0: digest: sha256:6d8fda39c2eb8fdc7b18c27f53fb6c01ac7721e7d55e7d6ae4cf6b1f3f0109fb→˓size: 529Signing and pushing trust metadataEnter passphrase for root key with ID 83320be:Enter passphrase for new repository key with ID 7411b4b:Repeat passphrase for new repository key with ID 7411b4b:Enter passphrase for new repository key with ID 7411b4b:Repeat passphrase for new repository key with ID 7411b4b:Enter passphrase for new repository key with ID 7411b4b:Repeat passphrase for new repository key with ID 7411b4b:Finished initializing "registry.edgescale.org/library/debian"Successfully signed registry.edgescale.org/library/debian:latest

14.3.3 Create Trusted APP on EdgeScale

Next, you need create a trusted app on EdgeScale.

Click Software -> APP -> Create App

• fill the App Name, Description and Upload app logo.



• Choose you added registry server address, fill other basic info

• Click submit, Click My App, you can see created App



More details please see the chapter Application Management.

14.3.4 Deployed Trusted APP from EdgeScale

Regarding the deploy app, please see the chapter Application Management -> Deploy App.

14.3.5 Remarks

• We recommend naming your private registry and trusted service by the following naming conventions.

– Private Registry domain name - registry.A.B

– Trust Server domain name - trust.A.B

• Regarding the domain certificate issued, below condition must be followed.

– The domain name *.A.B issued by CA provider.


CHAPTER

FIFTEEN

ESCLI USAGE

15.1 ESCLI Overview

CLI is the acronym of command-line interface. EdgeScale CLI (ESCLI) is used to maximize productivity. CLI offersgreater capability than a dashboard, exposing more, finer-grained commands, especially when the task must be donerepeatedly. Such is likely to be the case if a company manages thousands or millions of nodes. For example, CLI helpdeveloper build a firmware image and push it out to multiple devices with a few commands.

15.2 Installation

ESCLI is verified with ubuntu 16.04 Linux system, python version is 2.7.

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

15.3 Common Usage

The usage of EdgeScale CLI is:

$ escli

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

CLI to interact with EdgeScale server and execute your commands, defaultconfig 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 managementdevice device register and management.instance docker or application instances managementlogin login to EdgeScalelogout Logout from EdgeScalemodel model of device management.


97



repo docker's repository registry.solution solution image management.task service to deploy application or solution.vendor manufacturer vendor management.

15.3.1 Login to EdgeScale

There are two ways to login to the EdgeScale server, see below two commands, please use only one of them to loginthe EdgeScale system. Once login successfully, one token file will be generated and the user’s token will be saved infile “~/.edgescale/token.txt”. And at same time, a configuration file is generated too, the default EdgeScale API servername and API version is 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 -p

15.3.2 Device commands

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

Device command help usage

$ escli deviceUsage: 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 nameget-cert Get device private key & certification by...list List your Devicesshow show device information.

Create one new device

$ escli device create -hUsage: 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:


98 Chapter 15. ESCLI Usage



fuid: factory uuid, here we can type some string or number insteadmode_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: 663name: 13d3ddee9bda56ae84e8ab578f625e3e.iot.gateway.ls1046a.nxpcreated_at: 2018-05-31T06:03:57.123Zlast_report: Nonemode {"platform": "ls1046a", "model": "iot", "vendor": "nxp", "type

→˓": "gateway"}certname: 13d3ddee9bda56ae84e8ab578f625e3e.iot.gateway.ls1046a.nxpuid: 13d3ddee9bda56ae84e8ab578f625e3ecpu_usage: Nonemem_usage: Nonees_version: Noneapp_num: Nonemac: 00:00:00:00:00:00

Delete device

$ escli device delete --id=xxx

Upload device meta data to cloud

With this command, we can upload device meta data to cloud in batches. A example meta data file is “exam-ple/dev_db.csv”, it contains device fuid, OEM_DI, SK_PUB_X, SK_PUB_Y.

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

15.3.3 Application commands

With the application commands, we can create new app, deploy apps to device, query the app status and check instancestatus.

15.3. Common Usage 99


Help usage

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

applications management


Commands:create create a new applicationdel-instance delete the docker instancedelete Remove a applicationdeploy Deploy one application to deviceinstance query and list the docker instances of userlist List your Applicationsshow query and show specific application (id...

Create Application

$ escli app create -hUsage: 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 -hUsage: escli app deploy [OPTIONS]





Deploy one application to device

Options:--device TEXT device's name [required]--app_id INTEGER applicastion'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 -hUsage: escli app delete [OPTIONS]

Remove a application

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

15.3.4 Instance commands

With the instance commands, we can reboot a docker instance, check instance log, and deploy(delete) and instanceto(from) device.

Help usage

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

docker or application instances management


Commands:delete delete the docker instancedeploy Deploy one application to device, same as...describe show history and event for docker instancelist query and list the docker instances of userlogs show the docker instance logreboot 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 launch2019-01-23T07:43:15Z: creating 0%: aa2cf31b9627: Verifying Checksum2019-01-23T07:43:16Z: creating 50%: aa2cf31b9627: Download complete2019-01-23T07:43:16Z: creating 100%: aa2cf31b9627: Pull complete2019-01-23T07:43:17Z: creating 100%: Digest:

→˓sha256:edf26fe09753cd52dfcf9fdbdd7ad88205722d14fa74f2618dcd3d6cf835d7742019-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 , disconnecting.1547001245: New connection from 92.120.166.93 on port 1883.1547001245: Socket error on client , 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 a 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 || | |

→˓ | | |





+-----------------------------------------+-----------+-----------------------------→˓------------+----------------------+-----------------------------+

15.3.5 Solution commands

With the solution commands, we can upload new solution, deploy solution to device, and edit the solution image.

Help usage

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

solution image management.


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

Create new solution

$ escli solution create -hUsage: 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 -hUsage: 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.

15.3.6 Task commands

With the commands, we can deploy application or solution images to device, and check each task status.

Deploy one application to a device

$ escli task deploy-app -hUsage: 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 -hUsage: 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 |+-----+-----------------+---------+------------------------------------------+



15.3.7 Docker repository commands

With the repo commands, we can get the docker repository list, get command to login edgescale repository.

Help usage

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

docker's repository registry.


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 login 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

15.3.8 Other commands

model

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

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

model of device management.


Commands:create Create new model name, e.g, yun-ls1043a-gateway-nxpdelete Delete model by IDlist query and show the available model listupdate Update model with a new name

vendor

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



$ escli vendor -hUsage: escli vendor [OPTIONS] COMMAND [ARGS]...

manufacturer vendor management.


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


CHAPTER

SIXTEEN

CONNECT PUBLIC CLOUD

This section will introduce how to integrate public cloud service provider’s IoT SDK with EdgeScale.

16.1 Azure IoT Setup

16.1.1 Overall picture of the Azure setup

16.1.2 Hardware logistics

• Extra Ethernet cable

• Ethernet Router

• Power Strip

• SD card (8 or 32GB)

107


• Connect LS1012ARDB to a Linux PC by serial port. The port device can be found as device /dev/ttyACMx (xcan be 0, 1 etc).

16.1.3 Steps for cloud

• Register a free user account: free account.

• Follow up the setup in the iot-edge quick-start

1. Create an IoT hub with Azure CLI

2. Register an IoT Edge device

• After the device registration, a connection string will be seen

16.1.4 Steps for board

$ iotedgectl setup --edge-host