Custom modules development

Prerequisites

Before we start, make sure you have everything installed. You’re going to need:

node js
ombori grid client command-line utility
docker
a credentials to your own docker image registry
a grid-os device up and running

Creating a project

Now, let’s bootstrap our module. Run this command in terminal

omg module create hello

This will create a new folder named hello with basic nodejs module structure in it.

Let’s have a look at file structure:

package.json - a nodejs module file description in JSON format. A name field from this file will be used as a module name.
settings.json - container settings file, a settings.createOptions field from this file will be used to set up the container. This can be used to specify container port binding, volumes and other container options.
module.json - module settings file, an image.repository field from this file specifies the repository where the module image will be stored. Also image.tag.version stores the current image version. This value will be auto-increased when doing image build (see “Building” section below)
Dockerfile.amd64 - a dockerfile with instructions on how to build module image for amd64 platform
Dockerfile.arm32v7 - a dockerfile with instructions on how to build module image for arm32 platform
schema.ts - schema file for settings that will be displayed for this module on a device configuration page
src/app.js - module entry point

Before building our image we need to specify a correct docker image name and repository. Assuming you image will be stored at my-docker-repo.azurecr.io/my-image and credentials for this container registry are “username” and “password”, you’ll need to do the following:

Update repository value in the module.json file

{ 
   "$schema-version": "0.0.1",
   "description": "",
   "image": {
       "repository": "my-docker-repo.azurecr.io/my-image",
       "tag": {
           "version": "0.0.1",
           "platforms": {
               "amd64": "./Dockerfile.amd64",
               "arm32v7": "./Dockerfile.arm32v7"
           }
       },
       "buildOptions": []
   },
   "language": "javascript"
}

Now create a file with the name .env in the repo root folder:

my-docker-repo_azurecr_io_USERNAME=username
my-docker-repo_azurecr_io_PASSWORD=password

Please note that you need to replace dots (.) with underscores (_) in the hostname of the respository in the .env file

This file will contain credentials for your container registry. Note that this file is not saved in .git to prevent credentials being stored in version control.

You also need to login to docker repo if you haven’t done it already:

docker login my-docker-repo.azurecr.io -u username -p password

Now your module is ready to be built.

Building and deploying

To build the module just run yarn build in your terminal. This command does the following:

it checks if a local image is created for this module
if the repo contains any commits newer than the local image, a minor version of the module will be bumped and a new docker image will be built.
otherwise if the repo contains any uncommitted changes, newer than local image, a patch version of the module will be bumped and a new docker image will be built.
if the repo does not contain any changes, nothing will be done

In other words, for each change in your local files, a new image will be built and a patch version of the image will be increased: 0.0.1 -> 0.0.2 -> 0.0.3 etc. After you commit your changes, a minor version will be bumped instead: 0.0.3->0.1.0.

Now, what you’ll need next is your device name. Device names have org-name.device-name format. To see all devices that are available for you, just run omg dev list. Lets assume your device name is acme.my-device.

Lets deploy your module by running this command:

yarn deploy acme.my-device

The module is now saved in the device configuration, along with its configuration files and settings schema.

Note that the module is not yet being installed on the device because it is not enabled yet. To enable the module, go to your device page in the grid console, find an entry for your new module, and click the ‘enabled’ checkbox. You can also specify additional parameters for the module. List of parameters and their type are defined by settings schema in schema.ts file.

Monitoring

Now, after you have enabled the module, it will be downloaded and started on the device. To monitor current status of the module run omg dev modules <devicename>.

After the module has started you can see its logs using omg dev logs <devicename> <modulename>.

You can also invoke module methods using omg dev invoke <devicename> <modulename> <method> ‘<payload>’.