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 Pelion 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 Pelion Edge software that is ready to be deployed on NXP i.MX 8M Mini EVK or Avnet UltraZed-EG.

Prerequisites

Building the Pelion Edge image has been verified to work on Ubuntu 18.04 operating system.

  1. Verify you comply with the Yocto 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 \
android-sdk-ext4-utils ca-certificates whiptail

  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. Check your default Python version:

    python --version

    If your default Python version is earlier than 3.6, 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.1.1:

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

    After you have activated the Python 3 virtual enviroment, a python command that starts python3.

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

    git config --global user.name "Mona Lisa"
git config --global user.email "[email protected]"

  7. Decide to build a Production (factory) or a Developer mode image:

    • Production mode results in a build that only contains bootstrap credentials against the Pelion Cloud. This enables you to use the FCU/FCC process to pair the gateway to any Pelion Cloud 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 Pelion Cloud account.

    You can read more about Production or Developer mode on the configuring mbed-edge github page.

Developer mode prerequisites

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

    mkdir ~/Pelion_Edge_Credentials
cd ~/Pelion_Edge_Credentials

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

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

    1. In the Pelion Device Management Portal, go to Device Identity > Certificates.
    2. Create a developer certificate.
    3. Download the certificate mbed_cloud_dev_credentials.c
    4. Place this file into ~/Pelion_Edge_Credentials.

  3. Create the corresponding update_default_resources.c file to enable firmware updates to be applied to the gateway device:

    1. In the Pelion Device Management Portal, go to Access Management > API keys.
    2. Create an API key and save it.
    3. Run following command
    manifest-dev-tool init -a <api key>
    1. Copy the generated update_default_resources.c to ~/Pelion_Edge_Credentials For more information, please refer to the manifest tool README.

    Note: To unlock the rich node features, such as gateway logs and the gateway terminal in the Pelion web Portal, pass the command-line parameter --vendor-id 42fa7b48-1a65-43aa-890f-8c704daade54 to the manifest tool. Contact the service continuity team to request they enable Edge gateway features in your Pelion web Portal account. By default, the features are not enabled.

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-lmp-pelion-edge.git -m pelion.xml

      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. Determine whether you're running in Production mode or Developer mode:

    • 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 ~/Pelion_Edge_Credentials/mbed_cloud_dev_credentials.c layers/meta-mbed-edge/recipes-connectivity/mbed-edge-core/files/
cp ~/Pelion_Edge_Credentials/update_default_resources.c layers/meta-mbed-edge/recipes-connectivity/mbed-edge-core/files/

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

      echo -e "\n" >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = "ON"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_FOTA_ENABLE = "ON"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_CURL_DYNAMIC_LINK = "ON"' >> .repo/manifests/conf/local.conf

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

      echo -e "\n" >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_FACTORY_MODE = "ON"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = "OFF"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_BYOC_MODE = "OFF"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_FOTA_ENABLE = "ON"' >> .repo/manifests/conf/local.conf
echo 'MBED_EDGE_CORE_CONFIG_CURL_DYNAMIC_LINK = "ON"' >> .repo/manifests/conf/local.conf

  4. Set up the build environment variables:

    • For i.MX 8M Mini, run:

      MACHINE=imx8mmevk source setup-environment

    • For Avnet UltraZed, run:

      MACHINE=uz3eg-iocc source setup-environment

  5. Start the build with bitbake:

    bitbake console-image-lmp

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

  6. Prepare the device for booting from the SD card

    • For i.MX 8M Mini, check the positions of the boot switches. You can see the required positions of the switches printed on the silkscreen of the PCB.

    • For Avnet UltraZed, check the position of the boot switches. You can find the required positions of the switches from the user guide of your board.

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

    • 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 console-image-lmp-<MACHINE_NAME>-<timestamp>.rootfs.wic.gz | sudo dd bs=4m of=/dev/diskX conv=sync

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

        1. Choose the file to flash.
        2. Choose the destination SD card.
        3. Click Flash.

    • 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 console-image-lmp-<MACHINE_NAME>-<timestamp>.rootfs.wic.gz | sudo dd bs=4M of=/dev/mmcblkX conv=fsync status=progress iflag=fullblock oflag=direct

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. Copy the earlier built image to the new build directory:

    cp ../build-lmp/deploy/images/imx8mmevk/console-image-lmp-imx8mmevk.wic deploy/images/imx8mmevk/

  4. Navigate to the mfgtools-directory, and change the flashed image name in the full_image.uuu file:

    cd deploy/images/imx8mmevk/mfgtool-files
sed -i 's/lmp-base-console-image-imx8mmevk.wic/console-image-lmp-imx8mmevk.wic/' full_image.uuu
# Ensure that the new image name was written
grep "console-image-lmp-imx8mmevk.wic" full_image.uuu

  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 Pelion Edge

After preparing the SD card (and flashing the device in the case of i.MX 8M Mini EVK), you are ready to run Pelion 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.

Troubleshooting

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

Previous Next