Command

In some cases, you might be interested in a complete log of what the device was doing during its operation. All of your business or technical logs can be stored in our storage for later usage. You can identify which events happened or even trigger self-repairing logic.

All commands will be available in Applet Command REST API and can be downloaded historically as CSV export.

All methods

Methods	Description	Supported since
dispatch()	Dispatch method for sending logs and data from device	1.0.3
onCommand()	Event listener for incoming commands from server	1.0.3

dispatch()

Dispatch() is used for sending your custom logs or data from device to signageOS.

Throttling in place

The maximum allowed frequency for dispatching commands is 30 commands per 30 seconds. Any commands sent that exceed this frequency will be discarded.

Parameters

Parameter	Type	Required	Description
type	String	Yes	Event type; can be any string up to 100 characters
custom parameter	String	No	Custom parameters and values that you need to be dispatched

Javascript example

/*
Example of dispatching information about file download
*/
await sos.command.dispatch({
  type: 'Files.StartLoading', // mandatory *type* with custom value
  fileName: 'my-file', // custom parameter and value
  fileType: 'txt' // custom parameter and value
});

/*
Example of dispatching applet heartbeat
*/
await sos.command.dispatch({
  type: 'Heartbeat' // mandatory *type* with custom value
});

/*
Example of dispatching applet new data
*/
const myCMSJSON = {playlist: "myPlaylist", items: [...]};

await sos.command.dispatch({
  type: 'Content.update', // mandatory *type* with custom value
  content: JSON.stringify(myCMSJSON) // custom parameter and value
});

GitHub Example

Sending commands

Errors

Code	Type	Message
40401	AppletCommandTypeError	Type contains invalid characters.
40402	AppletCommandTypeError	Type is longer then 100 characters.
40403	AppletCommandTypeError	Command type must be a string.

Usage with Typescript

interface ICommand {
  type: string;
}
dispatch(command: ICommand): void;

GitHub Example

Rest API: Get Commands

Receiving your data dispatched from devices

GitHub Example

Rest API: Monitoring/Device Reports

Receiving historical data

onCommand()

Used for sending custom messages to online connected devices. This can be done through the REST API by POST new applet command. The command will be dispatched to the device & the applet can set up the logic by subscribing onCommand method.

Parameters:

Param	Type	Required	Description
command	object	Yes	Any JS object with required property type.
append	HTMLElement	Yes	Type property must be string not longer then 50 characters and must contain only characters a-zA-Z0-9_- and .

Javascript

sos.command.onCommand((command) => {
   // ... logic
});

GitHub Example

Receiving commands

Usage with Typescript

interface ICommand {
  type: string;
}
onCommand(listener: (command: ICommand) => void): void;

GitHub Example

Rest API: Monitoring

Creating monitoring data

Errors

Although we are doing our best, following errors may occur when working with the commands.

Code	Type	Message
40401	AppletCommandTypeError	Type contains invalid characters, allowed are /^[a-zA-Z0-9\.\-_]+$/g
40402	AppletCommandTypeError	Type is longer then 100 characters.
40403	AppletCommandTypeError	Command type must be a string.