@signageos/front-applet 8.1.2 → 8.1.4

package/docs/sos/hardware/barcodeScanner.md

@@ -4,36 +4,39 @@ sidebar_position: 0
 
 # barcodeScanner
 
-## Methods
+The `sos.hardware.barcodeScanner` API provides methods for working with barcode scanners.
+It allows starting and stopping the scanner, as well as listening for scanned data and errors.
 
-### getVersion()
+:::note
+This API is experimental and may change in the future.
+:::
 
-:::warning
+## Methods
 
-This API is experimental and may change in the future.
+### getVersion()
 
-:::
+The `getVersion()` method returns the version of the barcode scanner.
 
 ```ts expandable
 getVersion(): Promise<string>;
 ```
 
-<Separator />
+#### Return value
 
-### start()
+Returns a promise that resolves to the version of the barcode scanner.
 
-:::warning
+#### Possible errors
 
-This API is experimental and may change in the future.
+If the version cannot be retrieved.
 
-:::
+<Separator />
+
+### start()
+
+The `start()` starts the barcode scanner and starts listening for scanned data.
 
 ```ts expandable
-start(userOptions?: Omit<IBarcodeScannerOptions, 'scannerId'>): Promise<{
-    stop: () => Promise<void>;
-    onData: (listener: (data: string) => void) => void;
-    onError: (listener: (error: Error) => void) => void;
-}>;
+start(userOptions?: Omit<IBarcodeScannerOptions, 'scannerId'>): Promise<IBarcodeScannerResponse>;
 // show-more
 interface IBarcodeScannerOptions {
     timeout?: number;
@@ -41,4 +44,44 @@ interface IBarcodeScannerOptions {
     scannerId?: number;
 }
 
+interface IBarcodeScannerResponse {
+    stop: () => Promise<void>;
+    onData: (listener: (data: string) => void) => void;
+    onError: (listener: (error: Error) => void) => void;
+}
+
+```
+
+#### Params
+
+| Name                         | Type                                        | Required        | Description                                                                               |
+|------------------------------|---------------------------------------------|-----------------|-------------------------------------------------------------------------------------------|
+| `userOptions`                | `Omit<IBarcodeScannerOptions, "scannerId">` |  <div>No</div>  | User options to configure the scanner.                                                    |
+| `userOptions.timeout`        | `number`                                    |  <div>No</div>  | The maximum time to wait for a scan before timing out.                                    |
+| `userOptions.cancelPrevious` | `boolean`                                   |  <div>No</div>  | If set to `true`, it will cancel any previous scanner instance with the same `scannerId`. |
+
+#### Return value
+
+Returns a promise that resolves to an object with methods to stop the scanner and listen for scanned data and errors.
+
+#### Possible errors
+
+
+- If the scanner cannot be started.
+- If the scanner is already running and `cancelPrevious` option is not set to `true`.
+- If any other error occurs while starting the scanner.
+
+#### Example
+
+```ts
+// Start the barcode scanner with default options
+const scanner = await sos.hardware.barcodeScanner.start();
+// Listen for scanned data
+scanner.onData((data) => {
+	console.log(`Scanned data: ${data}`);
+});
+// Listen for errors
+scanner.onError((error) => {
+	console.error(`Scanner error: ${error.message}`);
+});
 ```

package/docs/sos/hardware/index.md

@@ -4,21 +4,39 @@ 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.
+The `sos.hardware` API groups together methods for working with hardware. It allows opening serial ports, using bar scanner or controlling LEDs.
+
+:::warning
+- Before using this API, ensure that the display [supports](/sdk/sos/display#supports) serial via `sos.display.supports("SERIAL")`.
+- Samsung Kiosk serial connection only works over serial ports, not over USB ports.
+:::
+
+### List of supported serial ports
+Bellow is example list of serial ports that can be used with `sos.hardware.openSerialPort()` method.
+
+| Device type | Default value | Other available values |
+|:----|:-----|:------|
+| RaspberryPi / Linux | `/dev/ttyS0` | `/dev/ttyS1`, `/dev/ttyUSB0`, `/dev/ttyUSB1` |
+| Windows | `COM3` | `COM1`, `COM2`, `COM4` etc. Usually it's always `COM3` |
+| Samsung Kiosk | `PORT1` | `PORT2`, `PORT3`, `PORT4` |
+| Android | `/dev/ttyusb0` | `/dev/ttyusb1`, `/dev/ttyusb2` |
+| BrightSign | `0` | `0` (Serial Jack as `/dev/ttyS0`), `1` (GPIO port as `/dev/ttyS1`), `USB:A/0` (USB-to-serial as `/dev/ttyUSB0`) |
 
 ## Methods
 
 ### 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.
+The `openSerialPort()` method opens a serial port for reading/writing. After the port is opened the method returns 
 
 ```ts expandable
 openSerialPort(options: ISerialPortOptions): Promise<ISerialPort>;
 // show-more
+/**
+ * Options for opening a serial port used by the `sos.hardware.openSerialPort()` method.
+ *
+ * @remarks
+ * All properties are optional except `baudRate`.
+ */
 interface ISerialPortOptions {
     device?: string;
     baudRate: number;
@@ -36,14 +54,27 @@ enum Parity {
     SPACE = "space"
 }
 
+/**
+ * Returned by sos.hardware.openSerialPort() method.
+ * This interface provides methods to read/write data from/to the serial port.
+ */
 interface ISerialPort {
     /**
      * The `onData()` method sets up a listener, which is called whenever new data are received. The listener will stop after the serial port
      * is closed.
+     *
+     * @param listener A function that will be called with the received data as a Uint8Array.
+     * @returns {void} Returns when the listener is set up.
      */
     onData(listener: (data: Uint8Array) => void): void;
     /**
-     * The `write()` method writes data to the serial port. The data can be a string of hexadecimal digits, array of numbers or Uint8Array
+     * The `write()` method writes data to the serial port. The data can be a string of hexadecimal digits, array of numbers or Uint8Array.
+     *
+     * @param data The data to write to the serial port.
+     * @returns {Promise<void>} Returns a promise that resolves when the data is successfully written to the serial port.
+     * @throws {Error} If the data cannot be written to the serial port.
+     * @throws {Error} If the serial port is not open.
+     * @throws {Error} If any other error occurs while writing to the serial port.
      *
      * @example
      * // serial port instance previously created via sos.hardware.openSerialPort()
@@ -54,6 +85,9 @@ interface ISerialPort {
     write(data: string | number[] | Uint8Array): Promise<void>;
     /**
      * The `close()` method closes the serial port.
+     *
+     * @returns {Promise<void>} Returns a promise that resolves when the serial port is successfully closed.
+     * @throws {Error} If the serial port cannot be closed.
      */
     close(): Promise<void>;
 }
@@ -62,14 +96,37 @@ interface ISerialPort {
 
 #### Params
 
-| Name                            | Type      | Description                                                                                                         |
-|---------------------------------|-----------|---------------------------------------------------------------------------------------------------------------------|
-| `options.device` *(optional)*   | `string`  | Specifies the address of the external device.                                                                       |
-| `options.baudRate`              | `number`  | Specifies the data transmission speed in bits per second.                                                           |
-| `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. |
+| Name               | Type      | Required         | Description                                                                                                         |
+|--------------------|-----------|------------------|---------------------------------------------------------------------------------------------------------------------|
+| `options.device`   | `string`  |  <div>No</div>   | Specifies the address of the external device, check the table above for ports.                                      |
+| `options.baudRate` | `number`  |  <div>Yes</div>  | Specifies the data transmission speed in bits per second.                                                           |
+| `options.parity`   | `Parity`  |  <div>No</div>   | Specifies the form of error checking, whether (or what) extra bits are added to a byte.                             |
+| `options.databits` | `number`  |  <div>No</div>   | Specifies the number of bits in a byte.                                                                             |
+| `options.stopbits` | `number`  |  <div>No</div>   | Specifies the number of bits used to signal the end of a communication packet.                                      |
+| `options.rtscts`   | `boolean` |  <div>No</div>   | Enables or disables RTS/CTS handshaking over the serial port. Currently supported by selected models of BrightSign. |
+
+#### Return value
+
+Returns a promise that resolves to an instance of 
+
+#### Possible errors
+
+
+- If the serial port cannot be opened.
+- If the device address is not supported by the platform.
+- If the device fails to process the data.
+- If any other error occurs while opening the serial port.
+
+#### Example
+
+```ts
+// Open serial port on BrightSign with default settings
+const serialPort = await sos.hardware.openSerialPort({
+	device: '0',
+	baudRate: 9600,
+});
+serialPort.write('68656c6c6f'); // Write "hello" in hexadecimal
+```
 
 ## API Example
 

package/docs/sos/hardware/led.md

@@ -4,19 +4,48 @@ 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
-devices.**
+The `sos.hardware.led` API groups together methods for controlling LEDs of the device.
+
+:::warning
+This is currently only supported by Phillips devices.
+:::
 
 ## Methods
 
 ### setColor()
 
-The `setColor()` methods sets the LED color (if string is passed) or disabled (if null is passed).
+The `setColor()` methods sets the LED color.
 
 ```ts expandable
 setColor(color: string | null): Promise<void>;
 ```
 
+#### Params
+
+| Name    | Type             | Required         | Description                                                                                                       |
+|---------|------------------|------------------|-------------------------------------------------------------------------------------------------------------------|
+| `color` | `string \| null` |  <div>Yes</div>  | The color to set the LED to, in hexadecimal format (e.g. `#FF0000` for red). If `null`, it will turn off the LED. |
+
+#### Return value
+
+Returns a promise that resolves when the color is successfully set.
+
+#### Possible errors
+
+
+- If the color is not a valid hexadecimal string or is not a string at all.
+- If the LED cannot be controlled by the device.
+- If any other error occurs while setting the color.
+
+#### Example
+
+```ts
+// Set the LED color to red
+await sos.hardware.led.setColor('#FF0000');
+// Turn off the LED
+await sos.hardware.led.setColor(null);
+```
+
 ## API Example
 
 ```ts

package/docs/sos/index.md

@@ -69,9 +69,9 @@ onReady(listener?: () => void): Promise<void>;
 
 #### Params
 
-| Name                    | Type         | Description                                                  |
-|-------------------------|--------------|--------------------------------------------------------------|
-| `listener` *(optional)* | `() => void` | Optional listener which is called when the sos API is ready. |
+| Name       | Type         | Required        | Description                                                  |
+|------------|--------------|-----------------|--------------------------------------------------------------|
+| `listener` | `() => void` |  <div>No</div>  | Optional listener which is called when the sos API is ready. |
 
 #### Return value
 

package/docs/sos/input.md

@@ -4,25 +4,39 @@ sidebar_position: 0
 
 # input
 
+The `sos.input` API groups together all input-related functionality, such as remote control key events. With this API, you can
+listen to key events from the remote control and handle them in your application.
+
 ## Methods
 
 ### onKeyUp()
 
-The `onKeyUp` method sets up a listeners, which is called on every key stroke of the remote controller. For the specific logic of an
+The `onKeyUp` method sets up a listeners, which is called on every keystroke of the remote controller. For the specific logic of an
 application (games for example), binding the remote control inputs can be helpful. Only a subset of all remote control keys is
 supported on the specific device. Only numerical digits are guaranteed to be supported.
 
+:::note
 This feature must be tested by users on real devices.
+:::
 
 ```ts expandable
 onKeyUp(listener: (event: IKeyUpEvent) => void): void;
 // show-more
+/**
+ * KeyUp event interface for handling key release events.
+ */
 interface IKeyUpEvent {
     type: 'keyup';
     keyCode: KeyUpEventMap;
     keyName: keyof typeof KeyUpEventMap;
 }
 
+/**
+ * Enum of supported key codes for KeyUp events.
+ *
+ * @remarks
+ * If a key is not listed here, it will show warning in the console.
+ */
 enum KeyUpEventMap {
     UNKNOWN = 0,
     NUM_0 = 1,
@@ -56,6 +70,22 @@ enum KeyUpEventMap {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Required         | Description                                                      |
+|------------|--------------------------------|------------------|------------------------------------------------------------------|
+| `listener` | `(event: IKeyUpEvent) => void` |  <div>Yes</div>  | The listener function that will be called on every key up event. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Possible errors
+
+
+- If listener is not valid function.
+- If listener is unregistered.
+
 <Separator />
 
 ### removeEventListener()
@@ -66,6 +96,17 @@ The `removeEventListener()` method removes all event listeners for a specific ev
 removeEventListener(event: 'keyup', listener: (...args: any[]) => void): void;
 ```
 
+#### Params
+
+| Name       | Type                       | Required         | Description                                                                             |
+|------------|----------------------------|------------------|-----------------------------------------------------------------------------------------|
+| `event`    | `"keyup"`                  |  <div>Yes</div>  | The name of the event to remove the listener for. Currently, only `keyup` is supported. |
+| `listener` | `(...args: any[]) => void` |  <div>Yes</div>  | The listener function to remove.                                                        |
+
+#### Return value
+
+Resolves when the listener is successfully removed.
+
 <Separator />
 
 ### removeEventListeners()

package/docs/sos/monitors.md

@@ -6,6 +6,10 @@ sidebar_position: 0
 
 The `sos.monitors` API groups together methods for providing information about monitors connected to the device.
 
+:::note
+This API is available only on Linux devices.
+:::
+
 ## Methods
 
 ### getList()
@@ -24,6 +28,10 @@ interface IConnectedMonitor {
 
 ```
 
+#### Return value
+
+A promise that resolves to an array of connected monitors.
+
 ## API Example
 
 ```ts

package/docs/sos/native/mdc.md

@@ -7,15 +7,11 @@ sidebar_position: 0
 The `sos.native.mdc` API groups together methods for controlling Tizen devices using MDC commands.
 
 :::warning
-
 This API is currently available on Tizen devices only.
-
 :::
 
 :::info
-
 You can ensure that the device supports MDC commands via `sos.management.supports("NATIVE_COMMANDS_MDC")`.
-
 :::
 
 ## Methods
@@ -27,6 +23,26 @@ The `sendOne()` method sends an MDC command to another Tizen device on the same
 ```ts expandable
 sendOne(ipAddress: IpAddressType, command: CodesMDC, data?: number[]): Promise<IMDCResponse>;
 // show-more
+/**
+ * Response object returned by Tizen Core App.
+ */
+interface IMDCResponse {
+    /**
+     * The type of the response, either 'ACK' for acknowledgment or 'NACK' for negative acknowledgment.
+     */
+    type: 'ACK' | 'NACK';
+    /**
+     * The command type that was executed, represented as a number.
+     * Should match the command number in {@link CodesMDC}.
+     */
+    commandType: number;
+    /**
+     * The result of the command execution, represented as a number.
+     * This value can vary depending on the command executed.
+     */
+    result: number;
+}
+
 /**
  * This enum contains valid command codes for Tizen MDC communication.
  */
@@ -177,31 +193,36 @@ enum CodesMDC {
     REPLY = 255
 }
 
-interface IMDCResponse {
-    type: 'ACK' | 'NACK';
-    commandType: number;
-    result: number;
-}
-
 ```
 
 #### Params
 
-| Name                | Type       | Description                                          |
-|---------------------|------------|------------------------------------------------------|
-| `ipAddress`         | `string`   | The IP address of the device to send the command to. |
-| `command`           | `CodesMDC` | The MDC command to send.                             |
-| `data` *(optional)* | `number[]` | The optional data to send with the command.          |
+| Name        | Type       | Required         | Description                                          |
+|-------------|------------|------------------|------------------------------------------------------|
+| `ipAddress` | `string`   |  <div>Yes</div>  | The IP address of the device to send the command to. |
+| `command`   | `CodesMDC` |  <div>Yes</div>  | The MDC command to send                              |
+| `data`      | `number[]` |  <div>No</div>   | The optional data to send with the command.          |
+
+#### Return value
+
+MDC response object containing the result of the command execution.
+
+#### Possible errors
+
+
+- If the `ipAddress` is not a valid string or if the `command` is not a valid number.
+- If the `data` is not an array of numbers.
+- If any error occurs during the command execution.
 
 #### Example
 
 ```ts
-await sos.native.mdc.sendOne('localhost', CodesMDC.BRIGHTNESS_CONTROL); // Promise<IMDCResponse>
-await sos.native.mdc.sendOne('192.168.0.10', CodesMDC.VOLUME_CONTROL, [50]); // Promise<IMDCResponse>
-await sos.native.mdc.sendOne('192.168.0.10', CodesMDC.PICTURE_CONTROL, [0x54, 0x03]); // Promise<IMDCResponse>
+await sos.native.mdc.sendOne('localhost', CodesMDC.BRIGHTNESS_CONTROL);
+await sos.native.mdc.sendOne('192.168.0.10', CodesMDC.VOLUME_CONTROL, [50]);
+await sos.native.mdc.sendOne('192.168.0.10', CodesMDC.PICTURE_CONTROL, [0x54, 0x03]);
 
 // You can also send custom number if we don't have predefined command in our enum
-await sos.native.mdc.sendOne('192.168.0.10', 0x01, []); // Promise<IMDCResponse>
+await sos.native.mdc.sendOne('192.168.0.10', 0x01, []);
 ```
 
 <Separator />
@@ -215,9 +236,23 @@ but without explicitly specifying the command.
 sendOneRaw(ipAddress: IpAddressType, data: number[] | [
 ]): Promise<IMDCResponse>;
 // show-more
+/**
+ * Response object returned by Tizen Core App.
+ */
 interface IMDCResponse {
+    /**
+     * The type of the response, either 'ACK' for acknowledgment or 'NACK' for negative acknowledgment.
+     */
     type: 'ACK' | 'NACK';
+    /**
+     * The command type that was executed, represented as a number.
+     * Should match the command number in {@link CodesMDC}.
+     */
     commandType: number;
+    /**
+     * The result of the command execution, represented as a number.
+     * This value can vary depending on the command executed.
+     */
     result: number;
 }
 
@@ -225,10 +260,21 @@ interface IMDCResponse {
 
 #### Params
 
-| Name        | Type             | Description                                          |
-|-------------|------------------|------------------------------------------------------|
-| `ipAddress` | `string`         | The IP address of the device to send the command to. |
-| `data`      | `number[] \| []` | The data to send with the command.                   |
+| Name        | Type             | Required         | Description                                                                        |
+|-------------|------------------|------------------|------------------------------------------------------------------------------------|
+| `ipAddress` | `string`         |  <div>Yes</div>  | The IP address of the device to send the command to.                               |
+| `data`      | `number[] \| []` |  <div>Yes</div>  | The data as array of numbers to send with the command. It can be also empty array. |
+
+#### Return value
+
+MDC response object containing the result of the command execution.
+
+#### Possible errors
+
+
+- If the `ipAddress` is not a valid string or if the `command` is not a valid number.
+- If the `data` is not an array of numbers.
+- If any error occurs during the command execution.
 
 #### Example