Quick start with Debian

This guide shows you how to get started with Pelion Edge and Debian. You can obtain Pelion Edge .deb (Debian) packages through two methods:

• Installing prebuilt packages from Pelion's official Advanced Package Tool (APT) repository.
  • This method saves time, requires less knowledge and reduces the risk of making mistakes because it doesn't require setting up a build environment.
• Building the packages from source.
  • With this method, you can install mbed-edge-core-devmode, which is Edge Core built specifically with your Pelion Device Management developer credentials, so it doesn't require additional provisioning after installation.

Install prebuilt packages

At the end of this tutorial, you will have installed Pelion Edge packages on the Debian 10 operating system from Pelion's official APT repository.

Prerequisites

Before you install the packages, you need a Pelion Device Management account.

Install

1. Add the Pelion Edge APT repository to your list of package repositories:

   sudo sh -c 'echo "deb http://apt.edge.pelion.com/debian/ <distro> main" >/etc/apt/sources.list.d/pelion-edge.list'
   

   Note: We support both Debian 10 Buster and Debian 11 Bullseye. Replace with either 'buster' or 'bullseye'.

2. Import the public GPG key to verify the integrity of the Pelion Edge debian packages:

   curl http://apt.edge.pelion.com/apt.edge.pelion.com.gpg.key | sudo apt-key add -
   

3. Update the APT package index, so the Pelion Edge packages are available for installation:

   sudo apt update
   

4. Install the Pelion Edge packages:

   sudo apt install pelion-edge
   

At this point, Pelion Edge packages are installed on your system. However, if you have not yet provisioned Edge Core with a Pelion Edge client certificate, the Pelion Edge edge-core service will be in a failed state. To provision a certificate to Edge Core, please see the provisioning documentation, or use the Edge pep tool to automate the provisioning process.

Additional steps for Debian 11 Bullseye

Pelion container orchestration services require cgroupv1 for proper operation. Because Debian 11 uses cgroupv2 by default, you must configure the Debian 11 kernel to override the default and use a hybrid cgroup heirarchy:

1. Add the parameters systemd.unified_cgroup_hierarchy=false and systemd.legacy_systemd_cgroup_controller=false to the kernel command-line.

   For example, if using grub, add this line to a new file /etc/default/grub.d/pelion.cfg:

   GRUB_CMDLINE_LINUX_DEFAULT="${GRUB_CMDLINE_LINUX_DEFAULT} systemd.unified_cgroup_hierarchy=false systemd.legacy_systemd_cgroup_controller=false"
   

2. Regenerate the grub config file and reboot the system:

   sudo update-grub
   sudo reboot
   

Build packages from source

This guide builds Pelion Edge on the Debian 10 operating system. At the end of this tutorial, you will have built Pelion Edge packages ready to be installed on Debian Buster AMD64.

Prerequisites

Before you can build this package, you must have:

• A Pelion Device Management account with which you have:

  • Created and downloaded the developer certificate credentials file mbed_cloud_dev_credentials.c.
  • Created an application access key.

• Docker and git installed to your build machine.

• Manifest tool v1.5.2.

Build

1. Clone distro-pelion-edge, and change the directory to the root of the repository:

   git clone https://github.com/PelionIoT/distro-pelion-edge
   cd distro-pelion-edge
   

2. Copy the mbed_cloud_dev_credentials.c file in place, so the Edge developer mode package builds with your developer credentials:

   cp ~/Downloads/mbed_cloud_dev_credentials.c .
   

3. Use the manifest tool to create update_default_resources.c:

   manifest-tool init -a <access-key> --vendor-id 42fa7b48-1a65-43aa-890f-8c704daade54 --class-id 42fa7b48-1a65-43aa-890f-8c704daade54 --force
   

   Note: Firmware-over-the-air update behavior is currently not defined.

4. Copy the generated update_default_resources.c into place:

   cp /path/to/update_default_resources.c .
   

5. Build all the Debian 10 packages for AMD64 using Docker:

   ./build-env/bin/docker-run-env.sh buster ./build-env/bin/build-all.sh --deps --install --build --source --arch=amd64
   

   Debian packages are available in ./build/deploy/deb/buster/main/

6. (Optional) To rebuild an individual package (for example, mbed-edge-core-devmode):

   ./build-env/bin/docker-run-env.sh buster ./mbed-edge-core-devmode/deb/build.sh --install --build --source --arch=amd64
   

Troubleshooting

Please see the distro-pelion-edge README for more information and GitHub issues for solutions to common build errors.