Documentation

Mistake on this page? Email us
Docs › Quick start › Quick start with Yocto

Quick start with Yocto

This guide shows you how to get started with Pelion Edge and Yocto. At the end of this tutorial, you will have built a Yocto image that contains the Pelion Edge software that is ready to be deployed on a Raspberry Pi 3B+.

Prerequisites

Building the Pelion Edge image has been verified to work on Ubuntu 20.04 operating system with Docker installed.

Before you can begin using this guide, you must:

  1. Verify you comply with the Yocto build machine requirements.

  2. Be sure to log in to the build machine as a non-root user. If you are a root user:

    1. Add another user:

      adduser <username>

    2. Add the new user to the sudo group:

      usermod -aG sudo <username>

    3. Log in as the non-root user:

      su <username>

  3. To install these prerequisites, execute this command:

    sudo apt-get install -y build-essential python3-pip python3-venv

  4. Check the default Python version:

    python --version

    If the default Python version is before 3.6, you must install a newer Python version.

  5. Set up the required building tools:

  6. Create a Python virtual environment, activate it, check the Python version again and install Manifest tool v2.1.1:

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

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

  7. Be sure your logged-in user is added to the Docker group.

  8. 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]"

  9. 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 folder.

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

    manifest-dev-tool init --vendor-id 42fa7b48-1a65-43aa-890f-8c704daade54

    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 -V 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-pelion-edge.git

    Your directory now contains a .repo directory.

  2. Fetch all the repositories:

    $ repo sync -j8

  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. Enter the build-env directory, and copy the Pelion configuration credentials to it. During the build, the Makefile puts these certificates in the correct spots as long as they are in build-env.

        $ cd build-env
$ cp ~/Pelion_Edge_Credentials/mbed_cloud_dev_credentials.c .
$ cp ~/Pelion_Edge_Credentials/update_default_resources.c .
$ make conf
$ echo -e "\n" >> ../poky/build/conf/local.conf
$ echo 'MBED_EDGE_CORE_CONFIG_FACTORY_MODE = "OFF"' >> ../poky/build/conf/local.conf
$ echo 'MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = "ON"' >> ../poky/build/conf/local.conf
$ echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> ../poky/build/conf/local.conf

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

      $ cd build-env
$ make conf
$ echo -e "\n" >> ../poky/build/conf/local.conf
$ echo "MBED_EDGE_CORE_CONFIG_FACTORY_MODE = \"ON\"" >> ../poky/build/conf/local.conf
$ echo "MBED_EDGE_CORE_CONFIG_DEVELOPER_MODE = \"OFF\"" >> ../poky/build/conf/local.conf
$ echo 'MBED_EDGE_CORE_CONFIG_FIRMWARE_UPDATE = "ON"' >> ../poky/build/conf/local.conf

  4. Start the build with make:

    $ make

    The built image is in the build directory under poky/build/tmp/deploy/images/raspberrypi3/ with a file name console-image-raspberrypi3-<timestamp>.<VALUE>. The ending varies based on the value of IMAGE_FSTYPES in local.conf.

  5. Flash the image console-image-raspberrypi3-<timestamp>.rootfs.wic.gz:

    • 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-raspberrypi3-<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 the following command:

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

      2. Use dd:

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

  6. Modify the login credentials:

    There is only one login user by default, root. The default password is set to redmbed. To modify that, follow these instructions.

Troubleshooting

Command repo init fails with SyntaxError

The repo command no longer supports Python 2. This can cause the repo init command to fail:

$ repo init -u https://github.com/PelionIoT/manifest-pelion-edge.git
repo: warning: Python 2 is no longer supported; Please upgrade to Python 3.6+.
Downloading Repo source from https://gerrit.googlesource.com/git-repo
remote: Counting objects: 1, done
remote: Finding sources: 100% (39/39)
remote: Total 39 (delta 13), reused 39 (delta 13)
  File "/xtra/.repo/repo/main.py", line 79
    file=sys.stderr)
        ^
SyntaxError: invalid syntax

To fix this, start the python commmand with Python version 3.6 or later. Use python --version to determine the Python version.

Additional information

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

Previous Next