Mistake on this page? Email us

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 a Raspberry Pi 3, use the Raspberry Pi 3 tutorial.

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.2.0 or higher:

      pip install --upgrade manifest-tool
      
    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.