screen

The sos.management.screen API groups together methods for controlling the screen of the device. It allows for manipulating the screen resolution or orientation, set brightness, retrieve the current brightness of the display, and manipulate the power mode.

warning

This method only turns on/off the display/backlight. It will not set any power-saving mode. We also strongly recommend rebooting any device once a day.

info

There is a specific behavior based on the device type you operate: On SoC displays (e.g., Samsung Tizen, LG webOS, Android-based SoC displays from Sony, Vestel Philips,...)

• powerOn() and powerOff() are turning the display backlight and the panel off On external media players (e.g., BrightSign, Windows PC, Android players, Raspberry Pi)
• powerOn() and powerOff() are turning off the video output (typically HDMI-out); this functionality does not manage the connected display backlight and needs to be controlled via RS232 or another way.

Screen Management Capabilities

Capability	Description
SET_BRIGHTNESS	If device can brightness.
GET_BRIGHTNESS	If device can return current brightness.
SCREEN_RESIZE	If the device can change screen resolution and orientation.
ORIENTATION_LANDSCAPE	If device supports landscape orientation.
ORIENTATION_PORTRAIT	If device supports portrait orientation.
ORIENTATION_LANDSCAPE_FLIPPED	If device supports flipped landscape orientation.
ORIENTATION_PORTRAIT_FLIPPED	If device supports flipped portrait orientation.
ORIENTATION_AUTO	If device supports auto orientation.

If you want to check if the device supports those capabilities, use sos.management.supports().

Methods

getBrightness()

The getBrightness() method returns information about the currently set brightness values.

getBrightness(): Promise<IBrightness>;

Return value

A promise that resolves to the current brightness settings.

Possible errors

If the brightness cannot be retrieved.

getOrientation()

The getOrientation() method returns the current orientation of the screen.

getOrientation(): Promise<IOrientation>;

Return value

A promise that resolves to the current screen orientation.

Possible errors

If the orientation cannot be retrieved.

Example

const orientation = (await sos.management.screen.getOrientation()).screenOrientation;
console.log(`Current screen orientation is: ${orientation}`);

isPoweredOn()

The isPoweredOn() method returns whether the screen is on.

isPoweredOn(): Promise<boolean>;

Return value

A promise that resolves to a boolean indicating whether the screen is powered on.

Possible errors

If the power state cannot be retrieved.

powerOff()

The powerOff() method turns the screen off. It will turn off the display backlight and the panel, and it will also disable the applet.

warning

On Android devices, powerOff() also shuts down the webview and the Applet. It's the default Android behavior that cannot be changed. Once the Applet is off, you cannot call powerOn() to resume the playback.

To manage the display On/Off state, use REST API Power Actions instead.

powerOff(): Promise<void>;

Return value

A promise that resolves when the screen is successfully turned off.

Possible errors

If the screen cannot be turned off.

powerOn()

The powerOn() method turns the screen on.

powerOn(): Promise<void>;

Return value

A promise that resolves when the screen is successfully turned on.

Possible errors

If the screen cannot be turned on.

resize()

The resize() method changes the resolution and orientation of the display.

info

For Tizen, you have to provide baseUrl which points to the Core App for Tizen, which will be downloaded to the device Read more on how to upload your Core Apps here..

resize(baseUrl: string, orientation: string, resolution: string, currentVersion: string, videoOrientation?: string): Promise<void>;

Params

Name	Type	Required	Description
baseUrl	string	Yes	SSSP & Tizen devices require installing an orientation-specific Core App if you want to switch orientation to portrait or landscape.
orientation	string	Yes	Screen orientation
resolution	string	Yes	Where it applies (mainly SSSP 2/3)
currentVersion	string	Yes	Core App version
videoOrientation	string	No	If the video has a different orientation than the HTML5 content

Return value

A promise that resolves when the screen is successfully resized.

Possible errors

• If baseUrl is not a valid URL
• If orientation is not a valid orientation
• If resolution is not a valid resolution
• If currentVersion is not a valid string
• If videoOrientation is not a valid video orientation

Example

// for Tizen
await sos.management.screen.resize(
    "https://cdn.your-cms.com/tizen/1.0.4",
    "PORTRAIT",
    "FULL_READY",
    "1.0.4"
);

// for all other supported devices
await sos.management.screen.resize(
    "",
    "PORTRAIT",
    "HD_READY",
    ""
);

GitHub Example

• How to resize screen on device

setBrightness()

The setBrightness() method sets the brightness of the screen. It supports two different brightness values for 2 time points in the day.

setBrightness(timeFrom1: string, brightness1: number, timeFrom2: string, brightness2: number): Promise<void>;

Params

Name	Type	Required	Description
timeFrom1	string	Yes	Time in the XX:XX format
brightness1	number	Yes	Brightness value between 0 and 100
timeFrom2	string	Yes	Time in the XX:XX format
brightness2	number	Yes	Brightness value between 0 and 100

Return value

A promise that resolves when the brightness is successfully set.

Possible errors

• If timeFrom1 is not a valid time in the XX:XX format
• If brightness1 is not a number between 0 and 100
• If timeFrom2 is not a valid time in the XX:XX format
• If brightness2 is not a number between 0 and 100

Example

// Set brightness to 10% between 00:00 and 17:00, and to 30% between 17:00 and 23:59
await sos.management.screen.setBrightness(
    '00:00',
    '10',
    '17:00',
    '30'
);

// Set brightness to 50% all day
await sos.management.screen.setBrightness(
   00:00,
   50,
   23:59,
   50
);

GitHub Example

• Applet Example with Brightness setup

takeAndUploadScreenshot(uploadBaseUrl, computeHash)

The takeAndUploadScreenshot() method takes a screenshot and uploads it to a specified URL. This can be either a signageOS upload URL (https://upload.signageos.io) or a dedicated server URL for uploading screenshots. The format in which the screenshot is uploaded may be different for every platform.

To implement a custom screenshot upload server, it needs to implement these endpoints:

• POST /upload/file?prefix=screenshot/ - Endpoint for receiving screenshot using form data, with the image set to the file field.
• POST /upload/raw?prefix=screenshot/ - Endpoint for receiving screenshots as raw data.
• POST /upload/image-data-uri?prefix=screenshot/ - Endpoint for receiving screenshots encoded as a data URL.

signageOS provides a standalone server that implements all of those methods. It is offered to all of our partners through the support ticketing system.

takeAndUploadScreenshot(uploadBaseUrl: string, computeHash?: boolean): Promise<{
    screenshotUrl: string;
    aHash?: string;
}>;

Params

Name	Type	Required	Description
uploadBaseUrl	string	Yes	URL to which the screenshot will be uploaded. It can be either a signageOS upload URL or a custom server URL.
computeHash	boolean	No	Whether to compute a hash of the screenshot and return it in the response.

Return value

A promise that resolves to an object containing the screenshot URL and optionally a hash of the screenshot.

Possible errors

• If uploadBaseUrl is not a valid URL
• If computeHash is not a boolean
• If the screenshot cannot be taken or uploaded.

Example

const { screenshotUrl, aHash } = await sos.management.screen.takeAndUploadScreenshot(
   'https://your.upload.server/upload/file?prefix=screenshot/',
   true,
);

GitHub Example

• Applet Example with Screenshot Upload

takeAndUploadScreenshot(uploadBaseUrl)

Deprecated

This method was deprecated. Use takeAndUploadScreenshot(uploadBaseUrl: string, computeHash?: boolean): Promise<{ screenshotUrl: string; aHash?: string }> instead.

takeAndUploadScreenshot(uploadBaseUrl: string): Promise<string>;