@signageos/front-applet 8.0.1 → 8.0.3

package/docs/fpath/index.md

@@ -1,6 +1,12 @@
+---
+sidebar_position: 99
+---
+
 # fpath
 
-fpath utility mirrors node path module, but accepts IFilePath type instead of strings.
+fpath utility mirrors node [path](https://nodejs.org/docs/latest/api/path.html)
+module, but accepts IFilePath type instead of strings. It is useful when
+working with [sos.fileSystem](/sdk/sos/fileSystem).
 
 Not implemented functions:
 - format
@@ -8,6 +14,21 @@ Not implemented functions:
 - parse
 - relative
 
+```ts
+import { sos, fpath } from "@signageos/front-applet";
+
+const [internal] = await sos.fileSystem.listInternalStorageUnits();
+const rootPath = {
+	filePath: '', // Empty string is used as an absolute path instead of "/"
+	storageUnit: internal
+};
+
+// list saved files in videos/2025-05-19/ directory
+const videos = await sos.fileSystem.listFiles(
+ fpath.join(rootPath, "videos", "2025-05-19"),
+);
+```
+
 ## Properties
 
 ### path

package/docs/sos/browser.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # browser
 
 The `sos.browser` API groups together methods for working with the integrated web browser.
@@ -157,7 +161,7 @@ sos.browser.open('https://www.signageos.io', {
 
 ### ~openLink()~
 
-:::danger
+:::danger Deprecated
 
 This method was deprecated. use `sos.browser.open()` instead
 
@@ -207,4 +211,30 @@ type ITheme = {
     };
 };
 
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	await sos.browser.open('https://www.signageos.io', {
+		aclDomains: ['google.com', 'yahoo.com'],
+		aclMode: 'blacklist', // or 'whitelist'
+		readOnlyAddressBar: true,
+		coordinates: {
+			// Supported only on Linux and Android
+			x: 0,
+			y: 0,
+			height: 500,
+			width: 500,
+		},
+		// theme: { ... } // supported only on Android
+		headlessMode: false, // supported only on Android
+	});
+
+	await sos.browser.close(); // Close the browser
+});
+
 ```

package/docs/sos/command.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # command
 
 The `sos.command` API groups together methods for sending logs and receiving commands from signageOS.
@@ -65,4 +69,24 @@ interface ICommand {
 
 - [Receiving commands](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/receiving)
 
-:::
+:::
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	/* 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
+	});
+
+	sos.command.onCommand((command) => {
+		console.log(`new command ${command.type} received, with data:`, command.command);
+	});
+});
+
+```

package/docs/sos/debug.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # debug
 
 The `sos.debug` API groups together methods for checking the state of remote debug mode.
@@ -22,4 +26,21 @@ The `onRemoteDebugChanged()` method sets up a listener, which is called whenever
 onRemoteDebugChanged(listener: (data: {
     enabled: boolean;
 }) => void): void;
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	if (await sos.debug.isRemoteDebugEnabled()) {
+		console.log('Remote debug is turned on');
+	}
+
+	sos.debug.onRemoteDebugChanged((enabled) => {
+		console.log('Weinre debug is', { enabled });
+	});
+});
+
 ```

package/docs/sos/deviceInfo.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # deviceInfo
 
 The `sos.deviceInfo` API groups together methods for retrieving information about the device set in the CloudControl, such as location or
@@ -46,4 +50,30 @@ interface IOrganizationTag {
     name: string;
 }
 
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	await printLocation();
+	await printTags();
+});
+
+const printLocation = async () => {
+	const { name, customId, description } = (await sos.deviceInfo.getLocation()) ?? {};
+
+	console.log('Location: ', { name, customId, description });
+};
+
+const printTags = async () => {
+	const tags = await sos.deviceInfo.getOrganizationTags();
+
+	for (const { name } of tags) {
+		console.log('Tag: ', name);
+	}
+};
+
 ```

package/docs/sos/display.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # display
 
 The `sos.display` API groups together methods for getting information about the device. Primarily to find out which
@@ -18,4 +22,21 @@ type DisplayCapability = 'FILE_SYSTEM_INTERNAL_STORAGE' | 'FILE_SYSTEM_EXTERNAL_
 
 type AnyString = string & {};
 
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	const supports = await sos.display.supports('SERIAL');
+
+	if (supports) {
+		console.log('This device supports serial port.');
+	} else {
+		console.log('This device does NOT support serial port.');
+	}
+});
+
 ```

package/docs/sos/fileSystem.md

@@ -1,5 +1,13 @@
+---
+sidebar_position: 0
+---
+
 # fileSystem
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/offline-content#storing-files-permanently)
+</Admonition>
+
 The `sos.fileSystem` API groups together methods for low-level access to the file system. The File System API supports both internal and
 external storage.
 
@@ -591,4 +599,50 @@ interface IStorageUnit {
 
 #### Possible errors
 
-The method throws an error if the parent directory does not exist or the `filePath` is a directory.
+The method throws an error if the parent directory does not exist or the `filePath` is a directory.
+
+## API Example
+
+```ts
+import { sos, fpath } from '@signageos/front-applet';
+import { IFilePath } from '@signageos/front-applet/es6/FrontApplet/FileSystem/types';
+
+void sos.onReady(async () => {
+	const [internal] = await sos.fileSystem.listInternalStorageUnits();
+
+	const root: IFilePath = {
+		storageUnit: internal,
+		filePath: '', // empty string points to root directory
+	};
+
+	// list files in the root directory
+	const contents = await sos.fileSystem.listFiles(root);
+
+	// print files from the root directory
+	for (const entries of contents) {
+		if (await sos.fileSystem.isDirectory(entries)) {
+			console.log(`${entries.filePath} (directory)`);
+		} else {
+			console.log(`${entries.filePath} (file)`);
+		}
+	}
+
+	// write data into a file
+	const writePath = fpath.join(root, 'value.json');
+	await sos.fileSystem.writeFile(writePath, JSON.stringify({ data: 'Lorem ipsum dolor sit amet' }));
+
+	// download a file from the internet and play it
+	const downloadPath = fpath.join(root, 'video.mp4');
+	await sos.fileSystem.downloadFile(
+		downloadPath,
+		'https://static.signageos.io/assets/test-videos-03_AME/video-test-03_15s_1920x1080_2fe7b039750a134aeac1c0a515710007.mp4',
+	);
+	const file = await sos.fileSystem.getFile(downloadPath);
+
+	if (file) {
+		await sos.video.prepare(file.filePath, 0, 0, 1920, 1080);
+		await sos.video.play(file.filePath, 0, 0, 1920, 1080);
+	}
+});
+
+```

package/docs/sos/hardware/barcodeScanner.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # barcodeScanner
 
 ## Methods

package/docs/sos/hardware/index.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # hardware
 
 The `sos.hardware` API groups together methods for working with hardware. It allows opening serials ports, using bar scanner or controlling LEDs.
@@ -6,6 +10,10 @@ The `sos.hardware` API groups together methods for working with hardware. It all
 
 ### openSerialPort()
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/serial-port)
+</Admonition>
+
 The `openSerialPort()` method opens a serial port for reading/writing. After the port is opened the method returns ISerialPort interface.
 
 ```ts expandable
@@ -61,4 +69,39 @@ interface ISerialPort {
 | `options.parity` *(optional)*   | `Parity`  | Specifies the form of error checking, whether (or what) extra bits are added to a byte.                             |
 | `options.databits` *(optional)* | `number`  | Specifies the number of bits in a byte.                                                                             |
 | `options.stopbits` *(optional)* | `number`  | Specifies the number of bits used to signal the end of a communication packet.                                      |
-| `options.rtscts` *(optional)*   | `boolean` | Enables or disables RTS/CTS handshaking over the serial port. Currently supported by selected models of BrightSign. |
+| `options.rtscts` *(optional)*   | `boolean` | Enables or disables RTS/CTS handshaking over the serial port. Currently supported by selected models of BrightSign. |
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	// Open default serial port based platform
+	const serialPort = await sos.hardware.openSerialPort({
+		baudRate: 115200,
+	});
+
+	await serialPort.close();
+});
+
+void sos.onReady(async () => {
+	// Open specific serial port
+	const serialPort = await sos.hardware.openSerialPort({
+		device: '/dev/ttyUSB0',
+		baudRate: 115200,
+	});
+
+	serialPort.onData((data) => {
+		const dataString = [...data].map((char) => String.fromCharCode(char)).join('');
+		console.log(dataString);
+	});
+
+	await serialPort.write('68656c6c6f'); // hexadecimal string
+	await serialPort.write([10, 20, 30, 40]); // array of numbers
+	await serialPort.write(Uint8Array.from([10, 20, 30, 40])); // Uint8Array
+
+	await serialPort.close();
+});
+
+```

package/docs/sos/hardware/led.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # led
 
 The `sos.hardware.led` API groups together methods for controlling LEDs of the device. **This is currently only supported by Phillips
@@ -11,4 +15,15 @@ The `setColor()` methods sets the LED color (if string is passed) or disabled (i
 
 ```ts expandable
 setColor(color: string | null): Promise<void>;
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	await sos.hardware.led.setColor('#00FF00'); // For GREEN light
+});
+
 ```

package/docs/sos/index.md

@@ -1,6 +1,14 @@
+---
+sidebar_position: 0
+---
+
 # sos
 
-The `sos` API groups together all functionality the
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/getting-started/#using-the-sos-sdk)
+</Admonition>
+
+The `sos` API groups together all functionality the \@signageos/front-applet offers.
 
 ## Properties
 
@@ -14,6 +22,10 @@ readonly appletVersion: string;
 
 ### authHash
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/device-identification)
+</Admonition>
+
 The `authHash` property is an alternative device identifier, which is designed for secure pairing and locating devices through
 the REST API.
 
@@ -27,6 +39,10 @@ readonly authHash: string;
 
 ### config
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/configuration/)
+</Admonition>
+
 The `config` property is a Key-value dictionary of the applet configuration.
 
 ```ts expandable
@@ -66,6 +82,12 @@ The `refresh()` method initializes refresh of the applet. Similar to window.loca
 refresh(): Promise<void>;
 ```
 
+#### Example
+
+```ts
+await sos.refresh();
+```
+
 <Separator />
 
 ### restore()
@@ -74,9 +96,15 @@ The `restore()` method clears all previously played videos, streams, clear displ
 is playing a loop with some specified duration. This method should be called always when the loop is changed. It will clear all
 previously played videos, streams, clear display views, and notify for garbage collection.
 
- It stops all video playback and clears out the memory. The following function should be triggered only in a case the whole playback
+It stops all video playback and clears out the memory. The following function should be triggered only in a case the whole playback
 needs to be restarted as it's completely switching the playback 'loop/playlist'.
 
 ```ts expandable
 restore(): void;
+```
+
+#### Example
+
+```ts
+sos.restore();
 ```

package/docs/sos/input.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # input
 
 ## Methods
@@ -70,4 +74,17 @@ The `removeEventListeners()` method removes all event listeners bind on `sos.inp
 
 ```ts expandable
 removeEventListeners(): void;
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	sos.input.onKeyUp((keyUpEvent) => {
+		console.log(`Pressed: ${keyUpEvent.keyCode} (${keyUpEvent.keyName})`);
+	});
+});
+
 ```

package/docs/sos/monitors.md

@@ -1,6 +1,10 @@
+---
+sidebar_position: 0
+---
+
 # monitors
 
-The `sos.management.monitors` API groups together methods for providing information about monitors connected to the device.
+The `sos.monitors` API groups together methods for providing information about monitors connected to the device.
 
 ## Methods
 
@@ -18,4 +22,19 @@ interface IConnectedMonitor {
     firmware?: string;
 }
 
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	const monitors = await sos.monitors.getList();
+
+	for (const { model, manufacturer, serial } of monitors) {
+		console.log('Connected monitor: ', { model, manufacturer, serial });
+	}
+});
+
 ```

package/docs/sos/native/index.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # native
 
 The `sos.native` API groups together methods for controlling the device using native commands.

package/docs/sos/native/mdc.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # mdc
 
 The `sos.native.mdc` API groups together methods for controlling Tizen devices using MDC commands.

package/docs/sos/offline/cache.md

@@ -1,5 +1,13 @@
+---
+sidebar_position: 0
+---
+
 # cache
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/offline-content#caching-audio-visual-content-or-arbitrary-data-sosofflinecache)
+</Admonition>
+
 The `sos.offline` API groups together methods used to download and save arbitrary files, which can be accessed even if the device is offline.
 
 :::warning
@@ -26,6 +34,10 @@ The method throws an error if the uid does not exist.
 
 ### deleteContent()
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/key-value-storage)
+</Admonition>
+
 The `deleteContent() method removes the value specified by `uid` key.
 
 ```ts expandable
@@ -69,6 +81,10 @@ The method throws an error if the uid does not exist or the hashing algorithm is
 
 ### listContents()
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/key-value-storage)
+</Admonition>
+
 The `listContent()` method lists all values saved by `saveContent()` method.
 
 ```ts expandable
@@ -89,6 +105,10 @@ listFiles(): Promise<string[]>;
 
 ### loadContent()
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/key-value-storage)
+</Admonition>
+
 The `loadContent()` method gets the value specified by `uid`, which was previously saved by `saveContent()`.
 
 ```ts expandable
@@ -135,6 +155,10 @@ interface IFile {
 
 ### saveContent()
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/key-value-storage)
+</Admonition>
+
 The `saveContent()` method saves a string value to the cache.
 
 ```ts expandable

package/docs/sos/offline/index.md

@@ -1,5 +1,13 @@
+---
+sidebar_position: 0
+---
+
 # offline
 
+<Admonition type="info" icon="" title="">
+  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/offline-content#caching-css--javascript-sosoffline)
+</Admonition>
+
 The `sos.offline` API groups together methods for storing and using JS, CSS and font files.
 
 :::warning

package/docs/sos/osd.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # osd
 
 The `sos.osd` API groups together methods for working with the OSD (On Screen Display).
@@ -10,4 +14,19 @@ The `showOSD()` method opens the OSD without typing the pin.
 
 ```ts expandable
 showOSD(): Promise<void>;
+```
+
+## API Example
+
+```ts
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(() => {
+	sos.input.onKeyUp(async (e) => {
+		if (e.keyName === 'BLUE') {
+			await sos.osd.showOSD();
+		}
+	});
+});
+
 ```

package/docs/sos/proofOfPlay.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # proofOfPlay
 
 ## Methods
@@ -22,16 +26,21 @@ interface IRecordItemOptions {
 
 ```
 
-#### Example
+## API Example
 
 ```ts
-await sos.proofOfPlay.recordItemPlayed({
-  name: 'generic-brand-christmas-coffee-ad',
-  customId: 'dBE43bFB3312VFfvd34bgGHJVV334cd2',
-  type: 'video',
-  tags: ['generic-brand', 'christmas'],
-  fileName: 'coffee.mp4',
-  playbackSuccess: false,
-  errorMessage: 'Unsupported framerate 60fps',
+import { sos } from '@signageos/front-applet';
+
+void sos.onReady(async () => {
+	await sos.proofOfPlay.recordItemPlayed({
+		name: 'generic-brand-christmas-coffee-ad',
+		customId: 'dBE43bFB3312VFfvd34bgGHJVV334cd2',
+		type: 'video',
+		tags: ['generic-brand', 'christmas'],
+		fileName: 'coffee.mp4',
+		playbackSuccess: false,
+		errorMessage: 'Unsupported framerate 60fps',
+	});
 });
+
 ```

package/docs/sos/stream.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 0
+---
+
 # stream
 
 The `sos.video` API groups together methods for streaming videos.