@signageos/front-applet 8.2.0 → 8.2.2

package/docs/sos_management/debug.md

@@ -4,7 +4,20 @@ sidebar_position: 0
 
 # debug
 
-The `sos.management.debug` API groups together method for working with native debug mode.
+The `sos.management.debug` API groups together methods for working with native debug mode.
+
+:::note
+Some modern systems might require additional steps to enable the native debug mode. Please refer to the [native debug documentation](https://docs.signageos.io/hc/en-us/articles/4413935787154-Applet-Native-Device-Debug) for more information.
+:::
+
+<details>
+    <summary>Debug Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `SET_DEBUG` | If the device can enable or disable the native debug mode. |
+
+		If you want to check if the device supports this capability, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
 
 ## Methods
 
@@ -16,6 +29,16 @@ The `enable()` method disables the [native debug](https://docs.signageos.io/hc/e
 disable(): Promise<void>;
 ```
 
+#### Return value
+
+A promise that resolves when the debug mode is disabled.
+
+#### Example
+
+```ts
+await sos.management.debug.disable();
+```
+
 <Separator />
 
 ### enable()
@@ -26,6 +49,22 @@ The `enable()` method enables the [native debug](https://docs.signageos.io/hc/en
 enable(): Promise<void>;
 ```
 
+#### Return value
+
+A promise that resolves when the debug mode is enabled.
+
+#### Example
+
+```ts
+await sos.management.debug.enable();
+```
+
+:::note[GitHub Example]
+
+- [ Example applet with activating debug mode](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/debug)
+
+:::
+
 <Separator />
 
 ### isEnabled()
@@ -34,4 +73,48 @@ The `isEnabled()` method returns whether the [native debug](https://docs.signage
 
 ```ts expandable
 isEnabled(): Promise<boolean>;
+```
+
+#### Return value
+
+A promise that resolves to `true` if the debug mode is enabled, otherwise `false`.
+
+#### Example
+
+```ts
+const isDebugEnabled = await sos.management.debug.isEnabled();
+console.log(`Native debug mode is ${isDebugEnabled ? 'enabled' : 'disabled'}.`);
+```
+
+<Separator />
+
+### setDebug()
+
+The `setDebug(enabled)` method sets the native debug mode to the specified state.
+
+```ts expandable
+setDebug(enabled: boolean): Promise<void>;
+```
+
+#### Params
+
+| Name      | Type      | Required         | Description                                             |
+|-----------|-----------|------------------|---------------------------------------------------------|
+| `enabled` | `boolean` |  <div>Yes</div>  | `true` to enable the debug mode, `false` to disable it. |
+
+#### Return value
+
+A promise that resolves when the debug mode is set.
+
+#### Possible errors
+
+If the `enabled` parameter is not a boolean.
+
+#### Example
+
+```ts
+const enabled = await sos.management.debug.isEnabled();
+if (!enabled) {
+ await sos.management.debug.setDebug(true);
+}
 ```

package/docs/sos_management/firmware.md

@@ -6,6 +6,25 @@ sidebar_position: 0
 
 The `sos.management.firmware` API groups together methods for working with the firmware of the device.
 
+:::warning
+Always check if your absolute firmware URL ends with a firmware file. Example: `https://cnd.your-cms.com/brightsign/fw/brightsign-update.bsfw`
+:::
+
+:::info
+For BrightSign firmware upgrade, please ensure that you have a text file with the SHA1 hash of that firmware file.
+- Firmware file path: `https://cnd.your-cms.com/brightsign/fw/brightsign-update.bsfw`
+- SHA1 txt file: `https://cnd.your-cms.com/brightsign/fw/brightsign-update.bsfw.sha1.txt`
+:::
+
+<details>
+    <summary>Firmware Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `FIRMWARE_UPGRADE` | If device can upgrade firmware version |
+
+		If you want to check if the device supports this capability, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
+
 ## Methods
 
 ### getType()
@@ -14,10 +33,26 @@ The `getType()` method returns the type of the firmware currently installed on t
 
 This information, when combined with firmware version, can be used to identify a correct firmware image to install on the current device.
 
+<details>
+    <summary>Linux and Android prefixes</summary>
+		| Type | Description |
+		|:------------|:-------------|
+		| `rpi` | Any Raspberry Pi 3 or Compute Module 3 |
+		| `rpi4` | Any Raspberry Pi 4 or Compute Module 4 |
+		| `benq-` | Any Benq display |
+		| `philips-` | Any Philips display |
+		| `sharp-` | Any Sharp display |
+		| `elo-` | Any Elo display |
+</details>
+
 ```ts expandable
 getType(): Promise<string>;
 ```
 
+#### Return value
+
+A promise that resolves to the current firmware type.
+
 #### Example
 
 ```ts
@@ -35,6 +70,10 @@ The `getVersion()` method returns the version of the firmware currently installe
 getVersion(): Promise<string>;
 ```
 
+#### Return value
+
+A promise that resolves to the current firmware version.
+
 #### Example
 
 ```ts
@@ -59,6 +98,10 @@ upgrade(baseUrl: string, version: string): Promise<void>;
 | `baseUrl` | `string` |  <div>Yes</div>  | The server URL where firmware files are located. |
 | `version` | `string` |  <div>Yes</div>  | The version of the firmware being installed.     |
 
+#### Return value
+
+A promise that resolves when the firmware upgrade is initiated.
+
 #### Example
 
 ```ts
@@ -90,12 +133,22 @@ upgrade(fwUri: string): Promise<void>;
 |---------|----------|------------------|--------------------------------------------------|
 | `fwUri` | `string` |  <div>Yes</div>  | FQN uri where the firmware main file is located. |
 
+#### Return value
+
+A promise that resolves when the firmware upgrade is initiated.
+
 #### Example
 
 ```ts
 await sos.management.firmware.upgrade('https://cdn.your-cms.com/tizen/pmf/fw/2080_4.bem');
 ```
 
+:::note[GitHub Example]
+
+- [ Example applet with firmware upgrade](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/firmware)
+
+:::
+
 <Separator />
 
 ### upgrade(version, baseUrl)
@@ -113,4 +166,14 @@ upgrade(version: string, baseUrl?: string): Promise<void>;
 | Name      | Type     | Required         | Description                                                                                           |
 |-----------|----------|------------------|-------------------------------------------------------------------------------------------------------|
 | `version` | `string` |  <div>Yes</div>  | The version of the firmware being installed.                                                          |
-| `baseUrl` | `string` |  <div>No</div>   | Optional server URL where firmware files are located.<br/>(Default value: `"https://2.signageos.io"`) |
+| `baseUrl` | `string` |  <div>No</div>   | Optional server URL where firmware files are located.<br/>(Default value: `"https://2.signageos.io"`) |
+
+#### Return value
+
+A promise that resolves when the firmware upgrade is initiated.
+
+#### Example
+
+```ts
+await sos.management.firmware.upgrade('T-HKMLAKUC-2080.4');
+```

package/docs/sos_management/index.md

@@ -4,8 +4,30 @@ sidebar_position: 0
 
 # sos.management
 
-The `sos.management` API group provides methods for managing the device. Through this API things like device firmware,
-battery status, brightness, network information, remote control, power, time or volume can be monitored.
+The `sos.management` API group provides methods for managing the device. Through this API, things like device firmware,
+battery status, brightness, network information, remote control, power, time, or volume can be monitored.
+
+:::note GitHub Example
+- [Basic usage of the Management API](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/basics)
+- [Getting basic management data](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/js-management-getters)
+- [Setting management data](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/js-management-setters)
+:::
+
+<details>
+    <summary>Management Capabilities</summary>
+		| Capability | Description |
+		|:------------|:-------------|
+		| `MODEL` | If device can return proper model name |
+		| `SERIAL_NUMBER` | If device can return serial number |
+		| `BATTERY_STATUS` | If device can return battery status |
+		| `TEMPERATURE` | If device can return current temperature |
+		| `BRAND` | If device can return manufacturer brand |
+		| `FACTORY_RESET` | If device can perform factory reset |
+		| `EXTENDED_MANAGEMENT` | If device can return or set extended management URL |
+		| `HARDWARE_ACCELERATION` | If device can turn hardware acceleration on or off |
+
+		If you want to check if the device supports those capabilities, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
+</details>
 
 ## Methods
 
@@ -17,12 +39,24 @@ The `factoryReset()` method initializes the factory reset of the device.
 factoryReset(): Promise<void>;
 ```
 
+#### Return value
+
+A promise that resolves when the factory reset is initiated.
+
+#### Possible errors
+
+If the device does not support factory reset.
+
 <Separator />
 
 ### getBatteryStatus()
 
 The `getBatteryStatus()` method returns information about the battery of the device.
 
+:::note
+- Emulator has mocked this method and will always return a battery status with 100% charge.
+:::
+
 ```ts expandable
 getBatteryStatus(): Promise<IBatteryStatus>;
 // show-more
@@ -36,6 +70,21 @@ interface IBatteryStatus {
 
 ```
 
+#### Return value
+
+A promise that resolves to an object containing the battery status.
+
+#### Possible errors
+
+If the device does not support battery status monitoring.
+
+#### Example
+
+```ts
+const batteryStatus = await sos.management.getBatteryStatus();
+console.log(`Battery status: ${batteryStatus.percentage}% charged`);
+```
+
 <Separator />
 
 ### getBrand()
@@ -46,22 +95,43 @@ The `getBrand()` method returns the manufacturer brand of the device.
 getBrand(): Promise<string>;
 ```
 
+#### Return value
+
+A promise that resolves to the brand name of the device.
+
+#### Possible errors
+
+If the device does not support brand information.
+
+#### Example
+
+```ts
+const brand = await sos.management.getBrand();
+console.log(`Device brand is: ${brand}`); // e.g., 'Samsung', 'LG', BrightSign, etc.
+```
+
 <Separator />
 
 ### getExtendedManagementUrl()
 
-The `getExtendedManagementUrl()` method returns the management url of the device.
+The `getExtendedManagementUrl()` method returns the management URL of the device.
 
 :::info
-
-This is currently only implemented for the MagicInfo on Tizen platform.
-
+This is currently only implemented for the MagicInfo on the Tizen platform.
 :::
 
 ```ts expandable
 getExtendedManagementUrl(): Promise<string | null>;
 ```
 
+#### Return value
+
+A promise that resolves to the management URL of the device, or `null` if not set.
+
+#### Possible errors
+
+If the device does not support the extended management URL.
+
 <Separator />
 
 ### getModel()
@@ -72,6 +142,17 @@ The `getModel()` method returns the model of the device.
 getModel(): Promise<string>;
 ```
 
+#### Return value
+
+A promise that resolves to the model name of the device.
+
+#### Example
+
+```ts
+const model = await sos.management.getModel();
+console.log(`Device model is: ${model}`); // e.g. 'XC4055' (BrightSign)
+```
+
 <Separator />
 
 ### getSerialNumber()
@@ -82,16 +163,42 @@ The `getSerialNumber()` method returns the serial number of the device.
 getSerialNumber(): Promise<string>;
 ```
 
+#### Return value
+
+A promise that resolves to the serial number of the device.
+
+#### Example
+
+```ts
+const serialNumber = await sos.management.getSerialNumber();
+console.log(`Device serial number is: ${serialNumber}`); // e.g. '1234567890'
+```
+
 <Separator />
 
 ### getTemperature()
 
-The `getTemperature()` method returns the temperature of the device (in 0-100 range of degrees Celsius).
+The `getTemperature()` method returns the temperature of the device (in the 0-100 range of degrees Celsius).
 
 ```ts expandable
 getTemperature(): Promise<number>;
 ```
 
+#### Return value
+
+A promise that resolves to the current temperature of the device.
+
+#### Possible errors
+
+If the device does not support temperature monitoring.
+
+#### Example
+
+```ts
+const temperature = await sos.management.getTemperature();
+console.log(`Current device temperature is: ${temperature}°C`); // e.g. 25°C
+```
+
 <Separator />
 
 ### isHardwareAccelerationEnabled()
@@ -102,32 +209,51 @@ The `isHardwareAccelerationEnabled()` method returns whether hardware accelerati
 isHardwareAccelerationEnabled(): Promise<boolean>;
 ```
 
+#### Return value
+
+A promise that resolves to `true` if hardware acceleration is enabled, otherwise `false`.
+
+#### Possible errors
+
+If the device does not support hardware acceleration management.
+
+#### Example
+
+```ts
+const isEnabled = await sos.management.isHardwareAccelerationEnabled();
+console.log(`Hardware acceleration is ${isEnabled ? 'enabled' : 'disabled'}.`);
+```
+
 <Separator />
 
 ### resetSettings()
 
 The `resetSettings()` method initializes the reset of the specific device settings.
 
-:::info
-
-This is currently only implemented on Linux platform.
-
+:::warning
+This is currently only implemented on the Linux platform.
 :::
 
 ```ts expandable
 resetSettings(): Promise<void>;
 ```
 
+#### Return value
+
+A promise that resolves when the settings are reset.
+
+#### Possible errors
+
+If the device does not support settings reset.
+
 <Separator />
 
 ### setExtendedManagementUrl()
 
-The `getExtendedManagementUrl()` set the management url of the device.
+The `getExtendedManagementUrl()` sets the management URL of the device.
 
 :::info
-
-This is currently only implemented for the MagicInfo on Tizen platform.
-
+This is currently only implemented for the MagicInfo on the Tizen platform.
 :::
 
 ```ts expandable
@@ -136,15 +262,39 @@ setExtendedManagementUrl(url: string | null): Promise<void>;
 
 #### Params
 
-| Name  | Type             | Required         | Description                |
-|-------|------------------|------------------|----------------------------|
-| `url` | `string \| null` |  <div>Yes</div>  | The management URL to set. |
+| Name  | Type             | Required         | Description                                                           |
+|-------|------------------|------------------|-----------------------------------------------------------------------|
+| `url` | `string \| null` |  <div>Yes</div>  | The management URL to set. If `null`, it will remove the current URL. |
+
+#### Return value
+
+A promise that resolves when the URL is set.
+
+#### Possible errors
+
+
+- If the URL is not a valid string or if the device
+- If the device does not support the extended management URL.
+
+#### Example
+
+```ts
+await sos.management.setExtendedManagementUrl('https://example.com/management');
+// later
+const url = await sos.management.getExtendedManagementUrl();
+console.log(`Extended management URL is: ${url}`); // e.g. 'https://example.com/management'
+```
 
 <Separator />
 
 ### setHardwareAcceleration()
 
-The `setHardwareAcceleration()` method enables or disables hardware acceleration.
+The `setHardwareAcceleration()` method turns hardware acceleration on or off.
+
+:::note
+- This is currently only implemented for the BrightSign platform.
+- Device must always be rebooted for the changes to take effect.
+:::
 
 ```ts expandable
 setHardwareAcceleration(enabled: boolean): Promise<void>;
@@ -156,12 +306,45 @@ setHardwareAcceleration(enabled: boolean): Promise<void>;
 |-----------|-----------|------------------|--------------------------------------------------|
 | `enabled` | `boolean` |  <div>Yes</div>  | Whether hardware acceleration should be enabled. |
 
+#### Return value
+
+A promise that resolves when the hardware acceleration setting is applied.
+
+#### Possible errors
+
+
+- If the `enabled` parameter is not a boolean.
+- If the device does not support hardware acceleration management.
+
+#### Example
+
+```ts
+await sos.management.setHardwareAcceleration(true).then(async () => {
+	console.log('Hardware acceleration enabled.');
+	await sos.management.reboot();
+}).catch((error) => {
+	console.error('Failed to set hardware acceleration:', error);
+});
+```
+
 <Separator />
 
 ### supports()
 
 The `supports()` method determines whether a queried capability is supported.
 
+#### What are capabilities?
+Capabilities are features or functionalities that a device can support. We divided those capabilities into `front` and `management` capabilities.
+This section is about management capabilities, which include features to manage the device, receive information about the device, or change its settings.
+
+On the other hand, the `front` capabilities are features that are related to the application running on the device, such as displaying content, handling user input, etc.
+To check `front` capabilities, refer to the `sos.display.supports()` method or [this section](https://developers.signageos.io/sdk/sos/display#supports).
+
+:::tip
+If you want to check specific capabilities, refer to the sidebar for the selected management section. Every section has its capabilities written in the description,
+or check the **ManagementCapability** type in `supports()` method. It has a list of all available capabilities for all platforms.
+:::
+
 ```ts expandable
 supports(capability: ManagementCapability): Promise<boolean>;
 // show-more
@@ -177,6 +360,21 @@ type AnyString = string & {};
 |--------------|------------------------|------------------|--------------------------------------|
 | `capability` | `ManagementCapability` |  <div>Yes</div>  | The capability to check for support. |
 
+#### Return value
+
+A promise that resolves to `true` if the capability is supported, otherwise `false`.
+
+#### Possible errors
+
+If the capability is not a valid string.
+
+#### Example
+
+```ts
+const isSupported = await sos.management.supports('OS_VERSION');
+console.log(`Is OS_VERSION supported? ${isSupported}`);
+```
+
 <Separator />
 
 ### ~getNetworkInfo()~