Docs › Quick start › Quick start guide

Quick start guide

This guide shows you how to get started with Pelion Edge. 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 18.04 operating system with Docker installed.

Before you can begin using this guide, you must:

Set up the required building tools:
- Docker.
- build-essential.
- repo.
- Manifest tool v1.5.2.

Execute the following commands to install these prerequisites:

sudo apt-get install -y build-essential repo python-pip && pip install manifest-tool==1.5.2

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

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

Generate your build machine's SSH key and add it to your GitHub account because the recipes of various metalayers refer to [email protected] during cloning and you will get a permission denied message if your SSH key is not properly configured.

Pelion configuration

Create a folder to store Pelion-specific configuration files:
```
$ mkdir edge-build && cd edge-build
```
Create the credentials required to allow the edge gateway to connect to your Pelion account:
- In developer mode:
  1. In the Pelion Device Management Portal, go to Device Identity > Certificates.
  2. Create a developer certificate.
  3. Download the mbed_cloud_dev_credentials.c certificate and save it in the edge-build folder.
- In production mode, you need to create your own credentials. For testing purposes, you can do this using OpenSSL as described on the Pelion factory provisioning documentation site.
Initialize the manifest tool to create the corresponding update_default_resources.c file. This enables firmware updates to be applied to the gateway device:
```
manifest-tool init -m "<product model identifier>" -V 42fa7b48-1a65-43aa-890f-8c704daade54 -q
```
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 at Arm to request they enable Edge gateway features in your Pelion web Portal account. By default, the features are not enabled.

Build

After the prerequisites are set up, start the Yocto build process:

$ mkdir build; cd build
$ repo init -u ssh://[email protected]/armpelionedge/manifest-pelion-edge.git
$ repo sync -j8
$ cd build-env
$ cp ../../mbed_cloud_dev_credentials.c .
$ cp ../../manifest-tool/update_default_resources.c .
$ make

Detailed steps

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 ssh://[email protected]/armpelionedge/manifest-pelion-edge.git
```
Your directory now contains a .repo directory.
Fetch all the repositories:
```
$ repo sync -j8
```
Enter the build-env directory, and copy the Pelion configuration files to it:
```
$ cd build-env
$ cp ../../mbed_cloud_dev_credentials.c .
$ cp ../../manifest-tool/update_default_resources.c .
```
During the build, the Makefile puts these certificates in the correct spots as long as they are in build-env.
Start the build with make:
```
$ make
```
The built image is in the build directory under poky/build/tmp/deploy/images/raspberrypi3/.
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
```
After you flash, the built image is in the build directory under poky/build/tmp/deploy/images/raspberrypi3/ with a file name console-image-raspberrypi3-<timestamp>.SOMETHING. The ending varies based on the value of IMAGE_FSTYPES in your local.conf.
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

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

Documentation