Module development quick reference

Owned by Former user (Deleted)
Last updated: Aug 06, 2021
3 min read

Update omg utility
omg update or npm i -g @ombori/ga-cli

Create a module
omg module create <orgName>.<moduleName>

A new directory will be created containing a template for a new module (in you language of choice: JS, C# and Python are currently supported). A new git repository will be initialised unless parent directory already a part of existing git repo.

orgName is an identifier of your organisation, moduleName is unique module identifier, a container name will have the same name (without orgName. prefix)

NOTE: even though module names are only unique within an organisation, you cannot have 2 modules with the same moduleName installed on a single device, e.g. acme.test-module and evilcorp.test-module cannot be installed together

Build a module

yarn build

The module image will be built. A working docker installation is required to build the module. The image will have registry.hostname/orgName.moduleName:version-platform format. registry.hostname, orgName.moduleName and version are taken from package.json. platform is taken from Dockerfile suffix.

Publish the new version of a module

omg module publish [--overwrite]

The module image will be published in the module library. The module must be build beforehand. Registry credentials are taken from .env file.

If no module exists in the library, it will be created automatically. If the version already exists in the library, the operation will fail. If old version must be overridden, a --overwrite flag may be used.

NOTE: If you overwrite a module version that is already installed on a device, the device will not re-download it.

After the module version is published, it can be installed on the device via “Modules” tab of device settings page.

Directly deploy a module to a device

omg module deploy <orgName>.<deviceName> [-w --watch]

The module image will be rebuilt (a temporary version number will be used) and installed on the device. This feature is to be used for development purposes only.

NOTE: Before a module can be deployed to the device, it must be installed to the device via ‘Modules’ tab. That also means that for a new module you need to have at least one version published.

NOTE: When device settings are saved on device page in Grid Console, the device will revert to a module version specified in settings.

NOTE: Two modules cannot be deployed to a device at the same time. Imagine having a device with 2 modules: test.one v.1.0 and test.two v.1.0 If we deploy a development version of the fist one, the versions on the device will be test.one v.20210501.1122 and test.two v.1.0. Now, if we deploy the second module, the first one will be reverted to the version in settings: test.one v.1.0 and test.two v.20210501.2233.

If a --watch option is specified, the module will be re-built and re-deployed after every file is changed in the repository.

List devices in my organisation

omg dev list <orgName> [--long]

Lists a devices you have access to. --long option shows more information.

List modules installed on a device

omg dev modules <orgName>.<deviceName>

Shows module ids installed on the devices, their statuses and versions. If a module is about to be updated, two versions will be shown for it.

Show module logs

omg dev logs <orgName>.<deviceName> <moduleName> [-t --timestamps] [-f --follow]

Displays last 100 lines of logs for a given module. If --follow option is specified, realtime logs will be streamed from the device.

Restart a module

omg dev invoke <orgName>.<deviceName> <moduleName> restart

Restarts a module

Module methods

module.settings - settings object for a module.

on_settings(callback) - registers a handler for settings update. When any value have changed for a running module, a callback will be invoked.

on_method(name, callback) - registers a handler for a direct module method. When method is invoked by omg utility or the cloud, a callback will be executed, receiving parameters as a first argument. if the handler function throws an exception, a result code 500 will be returned to calling party. Otherwise a result code 200 will be returned, with a function return value as a result.

broadcast(type, payload) - broadcasts a message via message bus. The message could be received by screen application and other devices.

on_event(type, callback) - registers a handler for an incoming message. The handler receives arguments of (type, payload). Messages can be sent from screen application or other devices.

publish(topic, payload) - writes to a specified MQTT topic. NOTE: that only topics with names starting with public/ are currently accessible.

subscribe(topic, handler) - subscribes for messages on a specified MQTT topic. Wildcards are supported. NOTE: that only topics with names starting with public/ are currently accessible.