Extending the Losant Gateway Edge Agent

If you need to include custom dependencies or script in the same environment as the edge agent, this tutorial is for you. We ship our Losant Gateway Edge Agent using Docker to ensure a consistent environment. Since the agent runs in a container, it’s best to think of it as an entirely separate environment. Dependencies and custom scripts are not automatically available inside the container, even if you’ve installed them in the host OS. This tutorial will walk you through accomplishing this.

Using an Edge Workflow, you can run a script or process locally using the Run Executable Node. Depending on the script or process, it may require certain things to be installed within the edge agent container. This is useful if you have custom logic, or need to use custom protocols, systems, etc.

Let’s get started.

Prerequisites

Extending the edge agent is a very powerful feature, but doing so does require deeper knowledge in things like Linux and Docker. Throughout the article, I'll be sure to link to resources that could fill some knowledge gaps. This tutorial assumes that you have the edge agent installed and running somewhere. Here are helpful articles:

• Gateway Edge Agent Walkthrough
• Gateway Edge Agent Installation
• Gateway Edge Agent Usage

Keep in mind that you can install the edge agent on your local machine to test everything we are about to cover.

Custom Dependencies

Currently, when you install and run the edge agent, you are using the image that Losant made for you. Actually, you download said image when you run this command:

$ sudo docker pull losant/edge-agent

To install our custom dependencies, we need to extend this image. This is one of the advantages of using Docker, which gives us the capabilities to easily do this. There is a wealth of information online about Docker. It’s a very popular tool. So, instead of explaining Docker, and how it works here are some helpful resources:

• https://docs.docker.com/get-started/part2/
• https://docs.docker.com/develop/develop-images/dockerfile_best-practices/

Create a Dockerfile

We need to create a new Dockerfile. This file will allow us to include any custom dependency we need.

$ mkdir custom-losant-edge-agent
$ cd custom-losant-edge-agent
$ touch Dockerfile

The RUN command in the Docker file lets you execute shell commands.  Here is a base Dockerfile for you to start with:

FROM losant/edge-agent:1.6.1
USER root 

# Install additional dependencies

RUN echo "Hello from my custom agent image"

Best Practice: You can specify the agent image as losant/edge-agent:latest. But, it’s wise to lock down the version in production to avoid unintended upgrades. You can see the latest version of the agent here.

This Dockerfile will then allow you to build a new image that includes anything you’ve added.

Building Your New Image

Now we need to build your new image with your new dependencies. In Docker, the build command packages everything up so we can run it in a container (More on Docker build).

This command needs to run inside of the folder with the Dockerfile in it. Above, we called it custom-losant-edge-agent.

docker build -t custom-losant-edge-agent .

After running this command, you should see output similar to:

Running Your New Image

We provide instructions for running the Losant Gateway Edge Agent. But, since you have a custom image now, your run image command will look like this:

docker run -d --restart always --name custom-losant-edge-agent \
  -v /your/path/to/data:/data \
  -v /your/path/to/config.toml:/etc/losant/losant-edge-agent-config.toml \
  custom-losant-edge-agent

On line 1, we can give our image a custom name. I’ll name this one custom-losant-edge-agent.

On line 4, instead of telling Docker to run the losant/edge-agent image, we can run our custom-losant-edge-agent image we just built.

Also, be sure to correct the proper data and config.toml paths in the command above (more info).

Once you run this, you should be able to see your edge device — using your new extended agent image — connected within Losant!

Examples:

Installing Python 3

This example shows how to have a custom edge agent image with Python 3 installed.

Dockerfile:

FROM losant/edge-agent:latest
USER root

# install debian packages
ENV DEBIAN_FRONTEND noninteractive
RUN apt-get update -qq \
 && apt-get install --no-install-recommends -y \
 # install essentials
 build-essential \
 g++ \
 git \
 openssh-client \
 # install python 3
 python3 \
 python3-dev \
 python3-pip \
 python3-setuptools \
 python3-virtualenv \
 python3-wheel \
 pkg-config \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/*

Usage:

Custom Scripts

Adding custom scripts to your edge agent image simply builds upon what we did when adding dependencies. But, we also include a script within the custom image.

Example Script:

# numpy is a custom dependency I need to install
import numpy as np

# assume this is really hard and complex math :) 
a = np.array([[1, 2, 3], [4, 5, 6]])

# this will go to sdtout in the workflow engine
# this will output (2/3)
print(a.shape)

Dockerfile:

FROM losant/edge-agent:latest
USER root

# install debian packages
ENV DEBIAN_FRONTEND noninteractive
RUN apt-get update -qq \
 && apt-get install --no-install-recommends -y \
 # install essentials
 build-essential \
 g++ \
 git \
 openssh-client \
 # install python 3
 python3 \
 python3-dev \
 python3-pip \
 python3-setuptools \
 python3-virtualenv \
 python3-wheel \
 pkg-config \
 # requirements for numpy
 libopenblas-base \
 python3-numpy \
 python3-scipy \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/*

RUN pip3 install --upgrade pip
RUN pip3 install --ignore-installed numpy

# move our script into the image
COPY ./myScript.py /opt/custom-scripts/

Usage:

Custom NPM Module to Use in Edge Function Node

Unlike in an Application Workflow, in an Edge Workflow, you have access to Node’s require. This means you can install custom modules with your image and use them within an Edge Function Node.

Dockerfile:

FROM losant/edge-agent:1.6.1
USER root

# install npm package
# npm is already in the base image
RUN npm i -g moment

Usage:

The End

Extending the Losant Gateway Edge Agent is a very powerful feature that allows for some very interesting use cases. If you have any questions, reach out in the Losant Forums.