Documentation

Mistake on this page? Email us
Docs › Connecting devices › Device Management Client tutorials › Linux on PC › Connect a Linux device

Connect a Linux device

Securely connect a Linux device to Device Management over an IP connection.

Note: These instructions explain how to connect a generic Linux device. If you want to connect using embedded Linux (Yocto / LmP), refer to Edge documentation.

Requirements

This requires a Linux PC (64-bit Ubuntu/XUbuntu OS desktop environment).

For all other requirements, see the tools and account section. See also the Mbed CLI instructions.

Connecting the device

  1. Open a terminal, and clone the example repository to a convenient location on your development environment:

    git clone https://github.com/PelionIoT/mbed-cloud-client-example
cd mbed-cloud-client-example

    Note: If you want to speed up mbed deploy, you can remove unnecessary Linux components, such as mbed-os.lib and the drivers/ folder.

  2. Deploy the example repository:

    mbed deploy

  3. Download the developer certificates from the Device Management Portal:

    1. Log in to the portal for your region with your credentials:

    2. Navigate to Device identity > Certificates.

    3. Click New certificate.

    4. Add a name and an optional description for the certificate, and click Create certificate.

    5. Go to Device identity > Certificates again.

    6. Click on your new certificate.

    7. Click Download developer C file to download the file mbed_cloud_dev_credentials.c.

  4. Copy the mbed_cloud_dev_credentials.c file to the root folder of the example.

  5. Create update-related configuration and credentials using the manifest-tool python package:

    1. Upgrade to manifest-tool version 2.4.1 or higher:

      pip install --upgrade manifest-tool

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

    2. Initialize the developer environment using an application access key:

      manifest-dev-tool init --access-key <Device Management access key>

  6. Deploy Linux dependencies:

    python pal-platform/pal-platform.py deploy --target=x86_x64_NativeLinux_mbedtls generate
cd __x86_x64_NativeLinux_mbedtls

  7. Generate cmake files based on your configuration and build profile (Release or Debug and PSA or non-PSA):

    • For the Release profile:

      • For non-PSA targets:

        cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define.txt

    • For PSA targets:

      cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define_linux_psa.txt

    • For the Debug profile:

      • For non-PSA targets:

        cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define.txt

      • For PSA targets:

        cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=./../pal-platform/Toolchain/GCC/GCC.cmake -DEXTERNAL_DEFINE_FILE=./../define_linux_psa.txt

  8. Compile the application:

    make mbedCloudClientExample.elf

    Note: To compile Device Management Client with KCM over RAM, add the PAL_SIMULATOR_FILE_SYSTEM_OVER_RAM compilation flag. Read more about KCM over RAM mode.

  9. The build creates binaries under mbed-cloud-client-example/__x86_x64_NativeLinux_mbedtls. In both cases, there are subdirectories Debug and Release respectively created for the two profiles.

    Note: If you experience build problems, refer to the Troubleshooting section for potential issues and workarounds.

  10. Set the Entropy source:

    export ENTROPYSOURCE=<file-name>

    For example:

    export ENTROPYSOURCE=/dev/urandom

    Note: The ENTROPYSOURCE environment variable is optional. If you do not use it, Device Management uses a default entropy source, which is Linux-platform-dependent.

  11. Run the application (at the respective path, see above):

    ./mbedCloudClientExample.elf

    You should see a message when the device connects to Device Management:

    Client registered
Endpoint Name: 013584750b3400000000000100100051
Device Id: 013584750b3400000000000100100051

    For development devices, the Endpoint Name and Device ID are identical.

  12. To verify the connection:

    1. Log in to Device Management Portal for your region:

    2. Select Device directory from the menu on the left.

      If your device is connected, it should appear on the Devices page.

Updating the firmware

Note: For a Linux PC, we demonstrate the firmware-over-the-air (FOTA) update feature by replacing Device Management Client's *.elf file. This is a single file replacement that we use for demo purposes.

To update the firmware on your device, run:

manifest-dev-tool update \
    --payload-path mbedCloudClientExample.elf \
    --device-id <Device ID>
    --wait-for-completion

During the update flow, the client tracing log shows:

Firmware download requested
Authorization granted
Downloading: [++++++++++++++++++++++++++++++++++++++++++++++++++] 100 %
Download completed
Firmware install requested
Authorization granted

After this, the device reboots automatically and registers to Device Management.

Previous Next