Documentation

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

Quick start with snapcraft

This guide shows you how to get started with Izuma Edge and snapcraft packaging. At the end of this tutorial, you will have built and installed Izuma Edge and viewed its logs.

Note: If you are building behind a proxy (with no direct Internet access), you need to follow additional steps.

Prerequisites

  1. Install Kubectl.
  2. Verify you have snap running in the target system.
    • Run snap --version.
    • Ubuntu 18.04 LTS for example does not have it by default.
    • You can install it with sudo apt install snap.
  3. An Izuma Cloud account.
    • If you do not have an Izuma Cloud account, please contact us.
    • If you have an account - go to the Izuma Portal where you:
  4. Docker and git installed to your build machine.
  5. Your logged-in user added to the Docker group.

Note: For updates you need a brand dedicated Snap Store.

Build Izuma Edge

  1. Clone the snap-pelion-edge repository:

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

  2. Decide whether you will use production or developer mode when building your snap. You can find documentation on the choices for certificate configuration modes at Configuring Edge Build.

    • [Developer Mode] Generate a device certificate from the Device Management Portal:

      1. Change the definitions of DEVELOPER_MODE and FACTORY_MODE in snap/snapcraft.yaml to DEVELOPER_MODE=ON and FACTORY_MODE=OFF

      2. Log in to the Device Management Portal, and select Device identity > Certificates.

      3. If you don't have a certificate, select New certificate > Create a developer certificate.

      4. When you have a certificate, open its panel.

      5. On this panel, click Download Developer C file to receive mbed_cloud_dev_credentials.c.

      6. Copy mbed_cloud_dev_crendentials.c to /path/to/snap-pelion-edge/:

        cp /path/to/mbed_cloud_dev_credentials.c /path/to/snap-pelion-edge/

    • [Production Mode] Do not use the device certificate from the Device Management Portal. Turn off by:

      1. Change the definitions of DEVELOPER_MODE and FACTORY_MODE in snap/snapcraft.yaml to DEVELOPER_MODE=OFF and FACTORY_MODE=ON

  3. Generate additional certificates using the manifest-tool.

    1. Install the manifest-tool.

    Create a Python virtual environment for pelion-build, activate it, check Python version again and install Manifest tool v1.5.2.

    Manifest-tool v1.5.2 works with Python 3.6, 3.8 and 3.8, so you might have to install also a compatible version of Python.

    python3 -m venv ~/edge-venv
source ~/edge-venv/bin/activate
python --version
pip install wheel
pip install manifest-tool==1.5.2

    1. Obtain an access key from the Izuma Edge Access Management Portal.

    2. Run the manifest-tool:

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

      This step creates several files, including .manifest_tool.json and update_default_resources.c.

      This step also creates the update certificate and private key, which you must keep safe and secure. The files are called:

      • .update-certificates/default.der (certificate).
      • .update-certificates/default.key.pem (matching private key).

    3. Copy the update_default_resources.c file to /path/to/snap-pelion-edge/.

    Note: This step is only for use in developer mode. Production mode does not require the update_default_resources.c file.

  4. Build with the snapcraft Docker image:

    docker build --no-cache -f Dockerfile --label snapcore/snapcraft --tag ${USER}/snapcraft:latest .
docker run --rm -v "$PWD":/build -w /build ${USER}/snapcraft:latest bash -c "sudo apt-get update && snapcraft --debug"

    Note: Running the build in Docker may contaminate your project folders with files owned by root and causes a permission denied error when you run the build outside of Docker. Run sudo chown --changes --recursive $USER:$USER _project_folder_ to fix it.

Install Izuma Edge

  1. Copy the pelion-edge_<version>_<arch>.snap package to the device.

  2. Use the snap utility to install the snap package:

    sudo snap install --dangerous pelion-edge_<version>_<arch>.snap

  3. Disable devicedb:

    sudo systemctl stop snap.pelion-edge.devicedb.service
sudo systemctl disable snap.pelion-edge.devicedb.service

  4. When installing on Ubuntu 18.04, run:

    sudo snap install network-manager
sudo snap install modem-manager

  5. Hook up these connections with the connect.sh script:

    1. Copy connect.sh to the device.
    2. On the device, run chmod +x connect.sh; ./connect.sh.

  6. Reboot the device:

sudo reboot

Run Izuma Edge

After the snap is installed, Izuma Edge starts automatically. To view its status, run:

systemctl status snap.pelion-edge.edge-core

  • If Izuma Edge does not run automatically, use one of these commands to manually start Izuma Edge:

    snap start pelion-edge

    or

    systemctl start snap.pelion-edge.edge-core

  • Use one of the following commands to stop Izuma Edge:

    snap stop pelion-edge

    or

    systemctl stop snap.pelion-edge.edge-core

These are just convenient snap commands that run the binaries. The actual binaries are at /snap/pelion-edge/current/.

View Izuma Edge logs

Log files are captured by snap and are available with the following commands:

(Do not copy and paste the line. It will likely not work)

  • To dump the whole log:

    snap logs -n=all pelion-edge.edge-core

  • To follow the log (print new lines as they come in):

    snap logs -f pelion-edge.edge-core

    Alternatively, you can use journalctl.

  • To dump the whole log:

    journalctl -u snap.pelion-edge.edge-core -a

  • To follow the log (print new lines as they come in):

    journalctl -u snap.pelion-edge.edge-core -f

Runtime configuration

  1. You may configure the Maestro service over its local API or with Maestro Shell.

  2. You can configure some aspects of Izuma Edge with snap configurations:

    snap get pelion-edge

Key         Value
edge-core   {...}
edge-proxy  {...}

Edge-proxy snap configuration

You can see edge-proxy snap configuration with:

```
snap get pelion-edge edge-proxy

Key                                 Value
edge-proxy.debug                    false
edge-proxy.extern-http-proxy-uri
```

  • edge-proxy.debug

    The default is false. Setting the flag to true sends edge-proxy log messages to the systemd journal. Setting the flag to false redirects edge-proxy log messages to /dev/null.

  • edge-proxy.extern-http-proxy-uri

    The default is an empty string. Set the value to the URL of an HTTP proxy server to cause the edge-proxy service to forward network traffic through the specified proxy rather than directly to the Izuma cloud. If the proxy requires authentication, specify the username and password within the URL:

    snap set pelion-edge edge-proxy.extern-http-proxy-uri=https://webproxy.myorg.com:8443
snap set pelion-edge edge-proxy.extern-http-proxy-uri=https://username:[email protected]:8444

Edge Core snap configuration

You can view the edge-core snap configuration with:

```
snap get pelion-edge edge-core

Key                 Value
edge-core.proxy
```

  • edge-core.proxy

    The default is an empty string. Set the value to the URL of an HTTP proxy server to cause Edge Core to connect to the Izuma cloud through the specified proxy rather than attempting to connect directly. If the proxy requires authentication, specify the username and password within the URL:

    snap set pelion-edge edge-core.proxy=http://webproxy.myorg.com:8080
snap set pelion-edge edge-core.proxy=http://username:[email protected]:8081

    Note: Edge Core does not support HTTPS proxy addresses at this time.

Update Izuma Edge

See the snap update guide for information about updating the Izuma Edge snap.

Known issues and troubleshooting

Can't use CoAP ports - using port 443

To use port 443 for the for Pelion-Cloud connection:

  1. Open snap/snapcraft.yaml, and set COAP_PORT_OVERRIDE_443 to true in the Edge Core part.
  2. Do a clean build following the instructions.

Edge service errors

If you see this error:

2018-09-13 18:14:13.771 tid:   6932 [ERR ][esfs]: esfs_create() - pal_fsFopen() for working dir file failed
2018-09-13 18:14:13.772 tid:   6932 [ERR ][fcc ]: storage.c:283:storage_file_create:File already exist in ESFS (esfs_status 5)
2018-09-13 18:14:13.773 tid:   6932 [ERR ][fcc ]: storage.c:131:storage_file_write:<=== Failed to create new file
2018-09-13 18:14:13.774 tid:   6932 [ERR ][fcc ]: key_config_manager.c:206:kcm_item_store:Failed writing file to storage
2018-09-13 18:14:13.775 tid:   6932 [ERR ][fcc ]: fcc_dev_flow.c:96:fcc_developer_flow:<=== Store status: 8, Failed to store mbed.UseBootstrap
2018-09-13 18:14:13.958 tid:   6932 [ERR ][esfs]: esfs_close() failed with bad parameters
2018-09-13 18:14:13.961 tid:   6932 [ERR ][fcc ]: storage.c:366:storage_file_close:<=== Failed closing file (esfs_status 1)
2018-09-13 18:14:14.002 tid:   6932 [ERR ][fcc ]: storage.c:434:storage_file_read_with_ctx:<=== Buffer too small
2018-09-13 18:14:14.003 tid:   6932 [ERR ][fcc ]: key_config_manager.c:309:kcm_item_get_data:Failed reading file from storage (3)

Please reset your credentials and restart pelion-edge:

sudo rm -rf /var/snap/pelion-edge/current/userdata/mbed/mcc_config
sudo rm -rf /var/snap/pelion-edge/current/userdata/edge_gw_identity
sudo snap restart pelion-edge

Edge startup errors

If you see the following error when starting Edge core, you are probably attempting to start Edge core while running on a LiveUSB or LiveCD Ubuntu system:

    /snap/core/current/usr/lib/snapd/snap-confine: error while loading shared libraries:

    libudev.so.1: cannot open shared object file: No such file or directory

This is known to not work. The remedy is to install Ubuntu onto the system or use a virtual machine.

kubelet not displaying ID

  1. Check that kubelet is running:

    sudo systemctl status snap.pelion-edge.kubelet.service

  2. Check kubelet logs:

    sudo journalctl –u snap.pelion-edge.kubelet -f

    Note: Attempting to register node ... indicates you can't connect.

  3. Check fp-edge:

    sudo journalctl –u snap.pelion-edge.fp-edge –f

Most likely, the hosts file on the gateway is not populated. To fix this, revisit the Install Izuma Edge section.

Docker fails with strange networking issue

Docker can sometimes get into a bad state:

   docker build --no-cache -f Dockerfile --label snapcore/snapcraft --tag ${USER}/snapcraft:latest .

   Sending build context to Docker daemon  6.144kB
   Step 1/7 : FROM snapcore/  snapcraft@sha256:6d771575c134569e28a590f173f7efae8bf7f4d1746ad8a474c98e02f4a3f627
    ---> 8a45de234ac8
   Step 2/7 : RUN apt-get update && apt-get install -y  curl jq squashfs-tools openssh-client git gosu
    ---> Running in 91ef6bfc81dd
   failed to create endpoint pensive_banach on network bridge: adding interface veth8b822d4 to bridge   docker0 failed: could not find bridge docker0: route ip+net: no such network interface

You can usually recover by restarting the Docker service: systemctl restart docker. If that does not help, a full device reboot might be required.

Further reading

To verify the gateway is now available in Izuma Portal, please see our device onboarding documentation.

Previous Next