Skip to main content

Using Custom Scripts, Plugins and Runners

The signageOS platform offers several ways to extend its native functionality and customize device behavior to fit your specific needs. The three primary tools for this are Custom Scripts, Plugins, and Runners. Each has a different operating model and is suited for different purposes.

This page will help you understand the key differences and decide which tool is right for your use case.

FeatureCustom ScriptPluginRunner
Execution model

|

One-off, on-demand

|

Periodic, automated

|

Continuous, background

| |

Primary purpose

|

Simple remote commands

|

Extending native features

|

Persistent background services

| |

Persistence

|

No (Executed from cloud)

|

Yes (Installed on device)

|

Yes (Installed on device)

| |

Policy integration

|

None

|

Full (Behaves like a native setting)

|

Deployment & Configuration only

| |

Health monitoring

|

No

|

No

|

Yes (Status reported to Box)

|

Custom Scripts​

Custom Scripts are the most straightforward way to execute a specific, one-off command remotely on a device. They are ideal for actions that do not need to run repeatedly or be permanently present on the device. The script is executed from the cloud, performs its task, and then terminates.

When to use them?

  • You need to perform a device-specific action that is not natively supported by signageOS.
  • You need to retrieve a custom telemetry value immediately, which is not reported by default or you need an instant reading.

Practical examples:

  1. Install Linux drivers: You have specific hardware (e.g., an external sensor) connected to a Linux player that requires custom drivers. Using a Custom Script, you can remotely execute terminal commands (e.g., apt-get install, dpkg -i) to install the necessary drivers.
  2. Retrieve custom telemetry: You need to instantly check if all linked Linux repositories on a device are correctly configured and accessible. A Custom Script can run a command that returns their current state without you having to wait for a standard telemetry report.

Learn more about Custom Scripts here

Plugins​

Plugins are used to extend the native features of signageOS and integrate them directly into system policies. Once installed, a Plugin behaves like a standard part of the system. It is executed periodically and automatically, ensuring its configuration is consistently enforced on the device.

When to use them?

  • You want to add a new configuration option that behaves like a native signageOS setting.
  • You need to apply a specific setting to the device regularly and automatically.

Practical Example:

  • Setting an S-curve for smooth transitions: Some displays support advanced image settings like an "S-curve" to optimize contrast and the smoothness of transitions. This feature might not be controllable via native signageOS settings. You can create a Plugin that periodically sets this value (e.g., via an RS232 command). In the Box, a new option like "S-curve Setting" would appear, which you could then manage within standard policies, just like volume or brightness.

Learn more about Plugins here

Runners​

Runners are designed to operate as continuous and persistent background services. They are essentially standalone applications running alongside the signageOS Core App. Their health is actively monitored and reported to the Box, so you always have an overview of their operational status.

When to use them?

  • You need to run complex logic on the device that must be active at all times.
  • Your service requires its own health monitoring.
  • You need to manage a configuration that is too complex for a simple Plugin.

Practical Example:

  • Advanced Wi-Fi Network Configuration: You need to connect a device to an enterprise Wi-Fi network that requires a complex setup (e.g., EAP-TLS with client certificates and a private key). A Runner can operate as a background service that:
    1. Receives the secure configuration from Box (SSID, authentication type, certificates).
    2. Manages the device's network profiles and ensures a stable connection.
    3. Continuously monitors the connection status and can attempt to reconnect if the connection drops.
    4. Reports its status (e.g., "Connected to SSID," "Authentication Failed") back to the Box for easy monitoring and troubleshooting.

Learn more about Runners here