This is an expert-level functionality

Misuse of Runners can cause issues, including device misconfiguration, device disconnection, or other unforeseeable situations.

Use this feature wisely and always test your runners in lab before running them on production devices.

Introduction

A Runner is designed for continuous execution. Once activated, it starts and runs indefinitely as a background process on the device. To ensure stability, signageOS actively monitors the health of each Runner and reports its status back to Box. If a Runner fails, the system can be configured to automatically restart it.

Prerequisites

• signageOS CLI - version 2.6.0-rc.0 and newer
• Minimal Core App version per platform that supports Runners:

Core App	Minimal Version
Tizen	2.10.2-runners-plugins.5520
webOS	2.10.0-runners-plugins.4373
BrightSign	coming soon
Linux	coming soon
Windows	coming soon
Android	coming soon
ChromeOS	coming soon
Emulator	14.21.3-plugins-runners.9762

Runners allow users to send its implementation in operating-system-specific programming languages. The runner can use device-specific native APIs.

Operating system	Runner type
Tizen	HTML + JS + Tizen APIs
webOS	HTML + JS + webOS APIs

Create a new project

Generate boilerplate project with signageOS CLI:

sos runner generate

Alternatively, copy the boilerplate code from signageOS/runners-boilerplate.

You will have a project with the following structure:

.
├── README.md
├── schema.json
├── .sosconfig.json
├── .gitignore
├── default
│   └── setBrightness.js
├── tizen
│   └── setBrightness.js

var sosRunner = {
	/**
	 * Required runner daemon function
	 */
	run: function () {
		setInterval(function () {
			console.log('Running SOS Runner...');
			sos.management.network.listInterfaces().then(function(interfaces){addTelemetry(interfaces)})
			// Your code
		}, 60e3);
	},

	/**
	 * Required for settings, policy and bulk.
	 */
	set: function (data) {
		return new Promise(function (resolve, reject) {
			// Your code
		});
	},
	/**
	 * Required for telemetry.
	 */
	get: function () {
		return new Promise(function (resolve, reject) {
			// Your code
		});
	}
};

The structure of the runner is similar to the plugin, with the main difference being the continuous run method.

How it works

Schema file

Contains the schema definition for the runner. Input is for set parameters and output is for get return values. Telemetry is custom telemetry from runner which is used through addTelemetry(your telemetry data)

{
	"input": [
		{
        "name": "myBaseUrl",
        "valueType": "url",
        "description": "A base URL to My cloud. No slash at the end required.",
        "placeholder": "https://api.signageos.io"
      },
      {
        "name": "refreshIntervalMs",
        "valueType": "number",
        "description": "Frequency of trying to generate new playlist from My cloud in milliseconds.",
        "placeholder": "65000",
        "min": 60000,
        "max": 70000
      }
	],
	"output": [
		{
			"name": "resolution",
			"description": "Resolution output",
			"valueType": "string"
		}
	],
    "telemetry": [
        {
            "name": "saturation",
            "description": "Saturation telemetry",
            "valueType": "number"
        },
        {
            "name": "brightness",
            "description": "Brightness telemetry",
            "valueType": "number"
        }
    ]
}

Config file

When calling sos runner upload, it reads the .sosconfig.json file. This file contains several fields:

• name - Runner will be created and displayed using this name
• description - Short description of the Runner that will be displayed in Runner detail. It should help the user to understand what the Runner does.
• version - Used for version control. Must follow the semantic versioning format. Each time the Runner Version changes, it should be incremented, however it's possible to overwrite the same version as long as its not published.
• platforms - List of platforms and their files that will be uploaded to the signageOS platform.
• configDefinition - list of accepted configuration parameters. It's a mandatory item, keep it empty if you do not need any variables ("configDefinition": [])

Platforms

The general structure of the platforms field is as follows:

{
	"{platform}": {
		"rootDir": "{rootDir}",
		"mainFile": "{mainFile}",
		"runtime": "{runtime}"
	}
}

• {platform} - name of the platform. It should be one of:
  • default, tizen, webos
• {rootDir} - relative path to the platform implementation. This is where the platform-specific files are located in this repository.
• {mainFile} - entry point of the platform implementation. This file will be executed
• {runtime} - runtime of the platform. It should be one of:
  • browser

Platforms and supported runtimes matrix:

Platform	Available Runtimes
Samsung Tizen	browser
LG webOS	browser
Windows	coming soon
Linux	coming soon
Android	coming soon
BrightSign	coming soon
ChromeOS	coming soon
Emulator (default)	browser

Config Definition

configDefinition is a list of accepted configuration parameters. It's a mandatory item, keep it empty if you do not need any variables ("configDefinition": []).

Config Definition item has the following options (same as Applet configuration):

Key	Value type	Description
name	string	name of the configuration
valueType	string | url | enum | number | secret | encrypted	expected value type
list	array of strings | numbers	only for valueType enum, list of predefined options
mandatory	boolean	required to be filled before executing runner
description	string	description shown in the UI to guide user
placeholder	string	field placeholder in the UI to guide user; placeholder is never used as default value
min	number	minimum number value user can fill in to the field
max	number	maximum number value user can fill in to the field

secret and encrypted type in configuration

Runner configuration is often used to pass sensitive data, such as tokens, credentials, and passwords. To protect these values, use the Runner configuration with one of these value types.

• secret value type

  Use this type if you want to mask the value in the Box UI. It is suitable for less sensitive data. The value is stored in the database in its raw form and may be visible, for example, in device history.

• encrypted value type:

  This type provides stronger protection. The value is encrypted using asymmetric encryption with a provided public key, which is generated for your company on demand. It is stored in encrypted form in the database and cannot be read anywhere.

Full example

.sosconfig.json with defined configDefinition

{
	// ... .sosconfig.json
	"configDefinition": [
		{
			"name": "wifiSSID",
			"valueType": "secret",
			"mandatory": true,
			"description": "An SSID for the WiFi network."
		},
		{
			"name": "myBaseUrl",
			"valueType": "URL",
			"description": "A base URL to My cloud. No slash at the end required.",
			"placeholder": "https://api.signageos.io"
		},
		{
			"name": "playerDuration",
			"valueType": "string",
			"description": "A length of generated playlist in '##s' format (seconds).",
			"placeholder": "172800s"
		},
		{
			"name": "refreshIntervalMs",
			"valueType": "number",
			"description": "Frequency of trying to generate new playlist from My cloud in milliseconds.",
			"placeholder": "65000",
			"min": 60000,
			"max": 70000
		},
		{
			"name": "playerId",
			"valueType": "string",
			"description": "An identifier for the device used to identifying against cloud. E.g. platform: SSSP, WEBOS, BRIGHTSIGN, ANDROID, WINDOWS, LINUX",
			"placeholder": "{PLATFORM}_{SERIAL_NUMBER}"
		},
		{
			"name": "proxyUrl",
			"valueType": "URL",
			"description": "A prefix for all HTTP(s) requests done by My player to My cloud. Default is no proxy.",
			"placeholder": "https://cors-anywhere.herokuapp.com/"
		}
	]
}

Or leave empty when not using configDefinition.

.sosconfig.json when not using configDefinition

{
	// ... .sosconfig.json
	"configDefinition": []
}

Upload runner

Run the following command to upload your runner to signageOS

sos runner upload

When calling sos runner upload, it reads the .sosconfig.json file. After the upload is completed, you will get runnerUid in the uid field in .sosconfig.json file.