Getting Started

Basic Concept

Bootstrap and Operational Image

Bootstrap image is the “golden” image used to authenticate device with EdgeScale cloud and update new version of software images, namely operational images. The bootstrap image is a small stable flash booted image with minimal software packages connected to EdgeScale cloud. It is seldom updated. The operational image is usually a full functional SD card booted image with a built-in docker engine and supports container-based apps. If the device does not support SD boot, the boot loader is supposed at flash and the root file system is stored on the SD card.

Identification and Certificate

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

Note

This private key is only generated for devices not provisioned by secure manufacturing. For secure provisioning, please check the “secure solution” section.

Currently this data is created as a shell script and can be downloaded from the dashboard while creating a device. Sometimes it is also called identification image.

Device Model

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

Quick Start Guide

Register and Sign-in

_images/register-account.png

It will send an email to the admin: esadmin@NXP1.onmicrosoft.com

After approval, you will get an email with a random password. Please log in and set a new passwd.

  • When the account is available, you can sign in.
_images/sign-in.png
  • Follow the account setting and reset password.
_images/passwd-reset.png

Prepare Device

1. Create Device

  • Go to SmartConnect -> My Devices and Create
_images/qs-device1.png

2. Download & Provision Device Identity

  • Fill in the form with SN number and device model info (select from suggested data).
  • Click Submit to register the device. A popup window will prompt you to download the device credential.
  • Download the device identity info.
bootstrap-enroll-<device ID>-iot.gateway.ls1043ardb.nxp.sh
_images/qs-device2.png
  • Check that the device is created.
_images/qs-device3.png
  • Copy the script file to your Linux host.
  • In Terminal, change directory to where the scipt file located, and execute the script file (Linux bash script) on the Linux host with the SD card inserted. Line started with $ indicates commands typed in Terminal.
$ sudo fdisk -l #find the location of the sd card in the form of dev/<sdx>
$ sudo ./bootstrap-enroll-2f63c75eaa50535087e623c5c0f22721.iot.gateway.ls1043ardb.nxp.sh đev/<sdx>
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
  • Note: If you encounter error “command not found” when executing the shell script, try to change access permission chmod u+x <filename> before running it. Be aware that running the script will erase the device, so check the name carefully before doing so.

After this step, the device identity information is saved on some reserved area of the SD card. Next, we need to prepare the software image for the device, which includes building and installing 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 is preferred, please refer to the “secure solution” section.

  • Preconditions

EdgeScale client depends on golang 1.9 environment. If the system is installed with an older version, please update it to 1.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 flexbuild
$ source setup.env

$ vi configs/build_lsdk.cfg
# change the below line from n to y:
CONFIG_BUILD_QORIQ_EDGESCALE=y
  • Build the images:
$ flex-builder clean
$ flex-builder -m <machine>
  • Note: The autobuild takes considerable amount of time to complete. Please make sure that your computer has stable Internet connection during this process.
3.2 Install pre-built pkg on the device

Note

Currently, only Debian pkg is supported.

This package could be used for:

  1. LSDK1909 image without built-in EdgeScale agents.
  2. Any ODM/OEM board derived from LSDK rootfs after LSDK1909.

Note

Due to the change of SD card layout after LSDK1906, we broke the backward compatibility. At present,the Debian package only works with LSDK1906/1909

Download the Debian package according to the following table.

Version Platform package
v1909 ARM64 EdgeScale Agents 64bit
v1909 ARM32 EdgeScale agents 32bit
  • You can use commands to get the Debian package, such as wget <website_above>.
  • Use the following command to run the Debian package:
=> dpkg -i edgescale-agents_1909_arm64.deb

4. Manually deploy the image to the SD card

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

  • Insert the SD card into x86 host Identify the physical device with fdisk -l or cat /proc/partitions. The SD card will be identified as /dev/sdx, where x could typically be a, b, c.
  • Unmount the SD card if auto mounted
sudo umount /dev/<sdx>
  • Install the solution image

    The required images that were assembled in the previous step will be available under “flexbuild_<version>” directory on the host machine.

    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/<sdx>
  • Note: please mount the second and third partition of the SD card and check that bootpartition_LS_arm64_edgescale_lts_4.9.tgz and rootfs_ubuntu_bionic_LS_arm64.tgz are installed to the SD card successfully. If the second partition is empty, please run the following command to install:
$ cd build/images
$ mount the second partition to <p2-dest-dir>
$ tar zxvf bootpartition_LS_arm64_edgescale_lts_4.9.tgz -C <p2-dest-dir>
$ umount <p2-dest-dir>
  • Insert the SD card into the target board and boot.

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

5. Bring the Device On-line

  • Cleanly unmount the SD card from the host, and insert it in the target platform.
  • Power up the target and stop in u-boot (CTRL-C). Help regarding starting the board or troubleshooting can be found in the board’s Getting Started Guide.
  • Reset to boot from the 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
_images/qs-device4.png

Deploy APP

1. Deploy APP to device

  • Follow Edge Software Store -> App Store -> App Market, select one APP (filtered by tag) and add to My App
_images/qs-app1.png
  • Click Deploy in My app
_images/qs-app2.png
  • Select device(s) and then click Deploy App
_images/qs-app3.png

2. Monitor APP task

  • Click Task to check deployment task status, click taskname to check app status.
_images/qs-app4.png

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

_images/qs-app5.png