Documentation

Mistake on this page? Email us
Docs › Quick start › Quick start with Linux microPlatform (LmP)

Quick start with Linux microPlatform (LmP)

This guide shows you how to get started with Izuma Edge and Linux microPlatform (LmP). LmP is a Yocto-built distribution maintained by Foundries.io. At the end of this tutorial, you will have built an LmP image that contains the Izuma Edge software that is ready to be deployed on the supported targets.

Prerequisites

Building the Izuma Edge image has been verified to work on Ubuntu 22.04 operating system.

  1. Verify you comply with the build machine requirements.

  2. Install the build requirements:

     sudo apt-get install coreutils curl gawk wget git diffstat unzip \
 texinfo g++ gcc-multilib build-essential chrpath socat cpio \
 openjdk-11-jre python3 python3-pip python3-venv python3-pexpect \
 xz-utils debianutils iputils-ping libsdl1.2-dev xterm libssl-dev \
 libelf-dev file lz4 ca-certificates whiptail xxd \
 libtinfo5 zstd libncurses5-dev

  3. Set up the required building tools:

    1. Install repo. You can install repo on Linux with this command:

      mkdir ~/bin && PATH=~/bin:$PATH && curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo && chmod a+x ~/bin/repo

  4. Create a Python virtual environment for pelion-build, activate it, check Python version again and install Manifest tool v2.5.1:

    If your default Python version is earlier than 3.8, you need to install a newer Python version.

  5. Create a Python virtual environment for pelion-build, activate it, check Python version again and install Manifest tool v2.5.1:

    python3 -m venv ~/edge-venv
source ~/edge-venv/bin/activate
python --version
pip install wheel
pip install manifest-tool

    After you have activated the Python 3 virtual environment, python command starts python3.

    Note: If your host system Python version is 3.6, use manifest-tool version 2.4.1. Use version 2.5.1 (or newer) for a more up-to-date system. You can specify the version via: pip install manifest-tool==2.4.1.

  6. Configure user.name and user.email because the repo tool is built on top of Git:

    git config --global user.name "Firstname LastName"
git config --global user.email "[email protected]"

  7. Decide to build a Production (factory), a Developer or a Bring your own certificate (BYOC) mode image:

    • Production mode results in a build that only contains bootstrap credentials against Izuma Device Management, so you can use the FCU/FCC process to pair the gateway to any Izuma Device Management account. Look at the PEP tool to learn about automating your factory floor in a production environment.
    • Developer mode results in a build that automatically pairs to a specific Izuma Device Management account. You need to provide the Izuma Device Management configuration files at build time, and they are compiled within the program binary.
    • BYOC mode results in a developer build and is similar to the developer mode except the Izuma Device Management configuration is provided at runtime rather than at build time. This creates a generic developer build you can distribute for development or testing purposes.

    You can learn more about how to configure Izuma Edge build options for the different modes in the mbed-edge GitHub.

Build machine requirements

Building an LmP image means building a whole Linux distribution. To successfully build such images, you must:

  • Have a build machine capable of building an LmP image:

    • A CPU with a minimum of eight cores.

    • A minimum of 100GB of free disk space per target. We highly recommend a fast solid state drive (SSD or NVMe) disk.

    • A minimum of 16GB of RAM available. Our recommendation is 32GB.

      Tip: Logs with signal 9 or Killed signal terminated program indicate a lack of memory. You can decrease parallel memory use by building clang and rust separately. Run bitbake clang && bitbake rust-native before starting the image build.

  • Have the required unhindered connectivity to internet:

    Yocto builds consist of more than 1,500 components spread around the internet. Invasive man-in-the-middle proxies can prevent the builds from working by interfering with the end-to-end security built into some of the tooling (such as curl or git). If you have such an environment, please work with your local IT support staff for solutions because these will be specific to the network infrastructure your IT has chosen. We also recommend you read Yocto documentation on working with proxies.

    Errors that indicate issues caused by proxies include:

    • fatal: unable to connect to github.com: github.com[0: 140.82.121.3]: errno=Connection timed out.
    • do_fetch. Failed to fetch URL.
    • fatal: unable to connect to git.yoctoproject.org:git.yoctoproject.org[0: 44.225.90.102]: errno=Connection timed out.

    You can also test for this:

    curl -L https://dl.google.com/go/go1.14.4.linux-amd64.tar.gz >go1.14.4.tar.gz

    If that fails with curl: (60) server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt, a proxy is being used.

  • Log into the build machine as a non-root user. If you are a root user:

    1. Add another user.
    2. Log in as the non-root user before proceeding further. The user may be in the sudoers group.

Developer mode prerequisites

  1. Create a folder to store Izuma-specific configuration files:

    mkdir ~/Edge_Credentials
cd ~/Edge_Credentials

    Note: You can reuse this folder in further tutorials, such as when using the Izuma Edge Provisioner. Store it in a safe location.

  2. Create and download a developer certificate to allow the edge gateway to connect to your Izuma account:

    1. Go to the Izuma Device Management Portal for your region:

    2. Go to Device Identity > Certificates.

    3. Create a developer certificate.

    4. Download the certificate mbed_cloud_dev_credentials.c.

    5. Place this file into ~/Edge_Credentials.

  3. Create the corresponding update_default_resources.c file, so you can apply firmware updates to the gateway device:

    1. In the Izuma Device Management Portal, go to Access Management > Access keys.

    2. Create an access key and save it.

    3. Run this command:

      manifest-dev-tool init -a <access key>

    4. Copy the generated update_default_resources.c to ~/Edge_Credentials.

      For more information, please refer to the manifest tool README.

Build

  1. Initialize a repository client:

    1. Create an empty directory to hold the build directory:

      mkdir ~/build
cd ~/build

    2. Download the Yocto manifest file in this repository:

      repo init -u https://github.com/PelionIoT/manifest-edge.git -m edge.xml -b refs/tags/v2.6.0

      Note: If you use two-factor authentication, you need to generate a personal access token and use it as password.

    Your directory now contains a .repo directory.

  2. Fetch all the repositories:

    repo sync -j"$(nproc)"

  3. Set up the build environment variables:

    • Izuma Edge has no dependency on hardware/board - you can build it against any MACHINE LmP supports.

    • For i.MX 8M Mini EVK, run:

      MACHINE=imx8mmevk source setup-environment

    • For Raspberry Pi 3, run:

      MACHINE=raspberrypi3-64 source setup-environment

    • For Raspberry Pi 4, run:

      MACHINE=raspberrypi4-64 source setup-environment

      Note: Izuma Edge has no machine specific implementations, it should run in any target supported by LmP.

      After this command you will be in build-lmp -folder.

Select provisioning mode

  1. Determine whether you're running in Production mode, Developer mode or BYOC mode:

    • If running in BYOC mode, inform the build system about BYOC mode, and update:

      export LOCALCONF="conf/local.conf"
echo -e "\n" >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_BYOC_MODE = "ON"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = "OFF"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FOTA_ENABLE = "ON"' >> "$LOCALCONF"

    • If running in Developer mode:

      1. Ensure you followed the Developer mode prerequsites above.

      2. Copy the mbed_cloud_dev_credentials.c and update_default_resources.c to the edge-core recipe folder.

        cp ~/Edge_Credentials/mbed_cloud_dev_credentials.c layers/meta-edge/recipes-edge/mbed-edge-core/files/
cp ~/Edge_Credentials/update_default_resources.c layers/meta-edge/recipes-edge/mbed-edge-core/files/

      3. Inform the build system about developer mode and update:

        export LOCALCONF="conf/local.conf"
echo -e "\n" >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = "ON"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FOTA_ENABLE = "ON"' >> "$LOCALCONF"

    • If running in Production mode, inform the build system that this is not a developer mode build (which is the default):

      export LOCALCONF="conf/local.conf"
echo -e "\n" >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FACTORY_MODE = "ON"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = "OFF"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> "$LOCALCONF"
echo 'MBED_EDGE_CORE_CONFIG_FOTA_ENABLE = "ON"' >> "$LOCALCONF"

      To securely run Izuma Edge with the Trusted Platform Module (TPM) v2.0, add this flag:

      echo 'MBED_EDGE_CORE_CONFIG_PARSEC_TPM_SE_SUPPORT = "ON"' >> "$LOCALCONF"

      Note: You can only work with Izuma Edge in production mode when you use a TPM. For more details, please see the documentation about securing Izuma Edge with a TPM.

      To speed up subsequent builds, set up your SSTATE_CACHE (or SSTATE_MIRRORS) and DL_DIR for BitBake. Modify the path according to your needs and username:

      echo 'SSTATE_DIR = "/home/username/SSTATE_CACHE"' >> "$LOCALCONF"
echo 'DL_DIR = "/home/username/DL_DIR"' >> "$LOCALCONF"

  2. Start the build with bitbake:

    bitbake lmp-base-console-image

    The built image is in the build directory under deploy/images/<MACHINE_NAME>/ with a file name lmp-base-console-image-<MACHINE_NAME>-<timestamp>.rootfs.wic.

    If limited memory is available, you can build in two stages: bitbake nodejs && bitbake lmp-base-console-image.

  3. Prepare the device for booting from the SD card:

    Check the positions of the boot switches:

    • For i.MX 8M Mini you can see the required positions of the switches printed on the silkscreen of the PCB.

  4. Flash the image lmp-base-console-image-<MACHINE_NAME>-<timestamp>.rootfs.wic.gz to an SD card:

    • Move the folder where the image is:
    cd deploy/images/<MACHINE ID>

    • macOS:

      1. Be sure to verify your device's path. This example assumes the SD card is enumerated as /dev/diskX.

      2. Make sure the SD card drive and its partitions, if any, are unmounted. To unmount all partitions, run the following command:

        ls /dev/diskX?* | xargs -n1 diskutil umount

      3. Use dd:

        gunzip -c lmp-base-console-image-<MACHINE_NAME>.rootfs.wic.gz | sudo dd bs=4m of=/dev/diskX conv=sync

        Alternatively, you can use the Etcher app or bmaptools, which can result in significant time savings over using dd:

    • Linux:

      1. Make sure the SD card drive and its partitions, if any, are unmounted. You can use lsblk to find the name of your SD card block device. To unmount all partitions, run:

        ls /dev/mmcblkX?* | xargs -n1 umount -l

      2. Use dd:

        gunzip -c lmp-base-console-image-<MACHINE_NAME>.rootfs.wic.gz | sudo dd bs=4M of=/dev/mmcblkX conv=fsync status=progress iflag=fullblock oflag=direct

        or with bmaptools:

        sudo bmaptool copy lmp-base-console-image-<MACHINE_NAME>.rootfs.wic /dev/<sd card device>

Flash the i.MX 8M Mini eMMC

If you are using the i.MX 8M Mini, you must flash the device with the built image. This writes the internal boot tools to the device. You only need to do this once:

  1. Navigate to the root of your work directory (one folder above the build-folder).

  2. Build the mfgtool-files for flashing:

    DISTRO=lmp-mfgtool MACHINE=imx8mmevk source setup-environment build-mfgtool
bitbake mfgtool-files

  3. Navigate to the mfgtools directory:

    cd deploy/images/imx8mmevk/mfgtool-files

  4. Update file paths in full_image.uuu:

    ...
FB: flash -raw2sparse all ../../../../../build-lmp/deploy/images/imx8mmevk/lmp-base-console-image-imx8mmevk.wic
FB: flash bootloader ../../../../../build-lmp/deploy/images/imx8mmevk/imx-boot-imx8mmevk
FB: flash bootloader2 ../../../../../build-lmp/deploy/images/imx8mmevk/u-boot-imx8mmevk.itb
FB: flash bootloader_s ../../../../../build-lmp/deploy/images/imx8mmevk/imx-boot-imx8mmevk
FB: flash bootloader2_s ../../../../../build-lmp/deploy/images/imx8mmevk/u-boot-imx8mmevk.itb
FB: flash sit ../../../../../build-lmp/deploy/images/imx8mmevk/sit-imx8mmevk.bin
...

  5. Set your i.MX 8M Mini EVK board to a download mode, and turn it on. Please consult your user guide on how to do this.

  6. Flash the eMMC of the board using uuu:

    sudo ./uuu full_image.uuu

  7. Set your i.MX 8M Mini EVK back to the SD card boot mode.

Running Izuma Edge

After preparing the SD card (and flashing the device in the case of i.MX 8M Mini EVK), you are ready to run Izuma Edge:

  1. Insert the prepared SD card.

  2. Power on the device.

  3. Use the serial connection of your board to communicate with the device. Please consult the user's guide of your board on how to do this.

  4. Modify the login credentials:

    The default login user for the system is fio. The default password is set to fio. The user has sudo-permissions. To modify the default password, use the passwd command after login.

BYOC mode provisioning steps

If you are using BYOC mode, after you boot the device and log in, you must provision the device with certificates:

  1. Create and download a developer certificate to allow the edge gateway to connect to your Izuma account:

    1. Go to the Izuma Device Management Portal for your region:

    2. Go to Device Identity > Certificates.

    3. Create a developer certificate.

    4. Download the certificate:

      mbed_cloud_dev_credentials.c

    Note: The downloaded developer certificate is confidential to your account. Store it securely in a place where unauthorized users can't access or use it.

  2. Create the corresponding update_default_resources.c file, so you can apply firmware updates to the gateway device:

    manifest-dev-tool init

    For more information, please refer to the manifest tool README.

  3. Securely copy the above files to the gateway, and place them at /userdata/mbed/:

    scp mbed_cloud_dev_credentials.c update_default_resources.c fio@<gw-ip-address>:~/
ssh fio@<gw-ip-address>
sudo mv *.c /userdata/mbed/

    The gateway is now connected to Izuma Device Management.

  4. Run sudo edge-info on the gateway to validate the gateway's connection to Device Management and find the gateway's Device ID. You can view and access the gateway through the Izuma Device Management Portal for your region:

Enabling more detailed logs in edge-core

By default edge-core (found in repo mbed-edge) is doing WARN-level logs. You can increase the log level by adding the following to your local.conf.

MBED_EDGE_CORE_CONFIG_TRACE_LEVEL = "DEBUG"

The file edge-core.bb has list of other definitions you could be interested in.

Licenses

Each LmP (and Yocto) build includes a large list of third-party IP (TPIP). Each build produces a license manifest file as part of the build process. This file is human readable but difficult to create summaries of. It is also difficult to compare changes between license manifest files in different builds or releases.

We recommend you use the open-source tool licensetool to convert the license manifest files into .csv and .xlsx formats and highlight the changes between two different license manifest files.

Troubleshooting

Please see the meta-pelion-edge GitHub issues for solutions to common build errors.

fatal error: ld terminated with signal 9 [Killed]

If you see "signal 9" in the logs, it means your build machine has run out RAM memory, such as in this example log:

| collect2: fatal error: ld terminated with signal 9 [Killed]
| compilation terminated.
| cctest.target.mk:187: recipe for target 'Release/cctest' failed
| make[1]: *** [Release/cctest] Error 1
| make[1]: *** Waiting for unfinished jobs....
| collect2: fatal error: ld terminated with signal 9 [Killed]
| compilation terminated.
| mkcodecache.target.mk:163: recipe for target 'Release/mkcodecache' failed
| make[1]: *** [Release/mkcodecache] Error 1
| rm 512ddb6f206424ba3727f48e2a88c3e2a07f1f7a.intermediate 2717ed055cefa06f0c281328677fc46980107d50.intermediate 86dcd984228c4d2848091aaa2f7c778b4720a32a.intermediate
| Makefile:101: recipe for target 'node' failed
| make: *** [node] Error 2
| WARNING: /home/user/poky/build/tmp/work/cortexa7t2hf-neon-vfpv4-poky-linux-gnueabi/nodejs/12.14.1-r0/temp/run.do_compile.2301077:1 exit 1 from 'exit 1'

autoconf fails

The Yocto build system doesn't support work areas behind symbolic links. You likely have a symbolic link to your work area if you see an error like this:

/2.69-r11/autoconf-2.69/man/autoupdate' | sed 's,.*/,,'`
/bin/bash: line 3: help2man: command not found
Makefile:460: recipe for target '../../../../../../../../../../home/tappuh01/workspace/disk2/abb_ngww_master/build-lmp/tmp-lmp/work/x86_64-linux/autoconf-native/2.69-r11/autoconf-2.69/man/config.sub.1' failed
make[2]: *** [../../../../../../../../../../home/tappuh01/workspace/disk2/abb_ngww_master/build-lmp/tmp-lmp/work/x86_64-linux/autoconf-native/2.69-r11/autoconf-2.69/man/config.sub.1] Error 127
make[2]: *** Waiting for unfinished jobs....
/bin/bash: line 3: help2man: command not found
Makefile:460: recipe for target '.

upstream 'master' -> 'main' branch renaming causing fetch failures

Upstream recipe maintainers are slowly transitioning primary branches from being named master to main. However, when bitbake is fetching sources, the tool by default only checks one branch, even if the reference exists in the remote repository.

This workaround is only required for packages with the following output failure pattern (with go-systemd used as an example):

WARNING: go-systemd-4+gitAUTOINC+b4a58d9518-r0 do_fetch: Failed to fetch URL git://github.com/coreos/go-systemd.git, attempting MIRRORS if available
ERROR: go-systemd-4+gitAUTOINC+b4a58d9518-r0 do_fetch: Fetcher failure: Unable to find revision b4a58d95188dd092ae20072bac14cece0e67c388 in branch master even from upstream
ERROR: go-systemd-4+gitAUTOINC+b4a58d9518-r0 do_fetch: Fetcher failure for URL: 'git://github.com/coreos/go-systemd.git'. Unable to fetch URL from any source.
ERROR: Logfile of failure stored in: /ws/build/tmp/work/cortexa7t2hf-neon-vfpv4-poky-linux-gnueabi/go-systemd/4+gitAUTOINC+b4a58d9518-r0/temp/log.do_fetch.81
ERROR: Task (/ws/meta-virtualization/recipes-devtools/go/go-systemd_git.bb:do_fetch) failed with exit code '1'

To fix locally:

  1. Locate and open the recipe that failed.

    In the above example, this is /ws/meta-virtualization/recipes-devtools/go/go-systemd_git.bb.

  2. Locate the line starting with SRC_URI =. Immediately after that line, add a new line:

    SRC_URI.=;branch=main

  3. Restart the build by running:

    bitbake lmp-base-console-image --continue

Previous