@signageos/front-applet 4.11.0

package/docs/js-api/js-offline-cache-media-files.md

@@ -0,0 +1,314 @@
+---
+title:  Offline Cache for media files
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] File API allows files (video files, media files etc.) to be stored for offline usage."
+---
+
+# Offline Cache for media files (File API)
+File API allows files (video files, media files etc.) to be stored for offline usage.
+
+## All methods
+
+::: table-responsive
+| Methods | Description | Supported since |
+| ------ | -------- | ----- | :-------------: |
+| `listFiles()` | Return list of files of existing directory | 2.0.0 |
+| `saveFile()` | Download file to selected directory | 1.0.3 |
+| `loadFile()` | Load file from cache | 1.0.3 |
+| `loadOrSaveFile()` | Download and load file from directory | 1.0.9 |
+| `deleteFile()` | Delete file from directory | 2.0.0  |
+| `getChecksumFile()` | Get checksum of a file | 2.0.0  |
+| `validateChecksumFile()` | Validate that file's checksum matches expected value | 2.0.0  |
+| `decompressFile()` | Decompress a compressed file or archive | 2.1.0  |
+:::
+
+::: alert alert--warning
+Emulator has certain limitations while handling offline files. [Read more here](/knowledge-base/box-emulator-limitations)
+:::
+
+## listFiles() 
+This method is used to get a list of uids of all files, saved by the current applet.
+
+### Javascript example
+```javascript
+// List uids of all files
+await sos.offline.cache.listFiles().then((fileUids) => {
+    console.log("Loaded", fileUids); 
+}).catch((error) => { console.error(error); });
+```
+### Returns
+```javascript
+["video-3", "video-2", "video-1", "image-9", "image-8", "image-7", "image-6", "image-5", "image-4", "image-3", "image-2", "image-13", "image-12", "image-11", "image-10", "image-1"]
+```
+
+
+## saveFile()
+Method `saveFile()` is used to save files from remote a destination into the device internal memory.
+
+### Parameters
+
+::: table-responsive
+|      Param       | Type                  | Required | Description                  					|
+| ---------------- | --------------------- | :------: |---------------------------------------------- |
+| `uid`              | string                | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters, slash / is supported since Front-display version 6.0.0 |
+| `uri`              | string                | <div class="red">Yes</div> | URL address to retrieve the file				|
+| `headers`         | object                | <div class="yellow">No</div> | Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any other specific headers are needed to access it.                                   			|
+:::
+
+::: alert alert--warning
+`headers` has to be a JSON object. If you are passing the value, make sure you use `JSON.parse()`.
+:::
+
+::: alert alert--warning
+`uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file.
+:::
+
+### Javascript example
+```javascript
+// Example saving files into internal memory, unique id could be salted md5 hash, uri directs to our CDN
+await sos.offline.cache.saveFile('9d66725ba2105f1833731ade5b7f334e.mp4', 'https://cdn.my-cms.com/files/video.mp4', { "Authorization": "Basic Zm9vOmJhcg==" })
+.then(() => { console.log('Saved'); })
+.catch((error) => { console.error(error); });
+```
+
+::: alert alert--info
+Local device file path differs from device to device. It can point to file:// or http://localhost etc.
+:::
+
+## loadFile()
+Method `loadFile()` is used for individual file retrieval from internal memory.
+
+### Parameters
+
+| Param | Type | Required | Description |
+| --------- | ------------ | :---------: | --------------- |
+| `uid` | string | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |
+
+::: alert alert--warning
+`uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file.
+:::
+
+### Javascript Example
+```javascript
+await sos.offline.cache.loadFile('9d66725ba2105f1833731ade5b7f334e.mp4')
+.then((file) => { console.log('Loaded', file); })
+.catch((error) => { console.error(error); });
+ 
+// Logs into console
+{
+  filePath: '/real/device/path/to/file/9d66725ba2105f1833731ade5b7f334e.mp4',
+}
+```
+
+::: alert alert--info
+Local device file path differs from device to device. It can point to file:// or http://localhost etc.
+:::
+
+### Returns
+* SUCCESS: File object
+* FAIL: No file of such uid is available, it throws error into promise
+
+## loadOrSaveFile()
+Method `loadOrSaveFile()` is used for individual file retrieval & save in case when file is not saved in local storage yet.
+To get file from internal memory & save it when not yet exists we prepared `loadOrSaveFile()` method:
+
+::: alert alert--info
+* The file URI has to return the file. If your URI leads to a 303 redirect (e.g. from http to http**s**), the API will not work.
+* Emulator has certain limitations while handling offline files. [Read more here](knowledge-base/box-emulator-limitations) 
+:::
+
+### Parameters
+
+|      Param      | Type           | Required | Description                  					|
+| --------------- | -------------- | :-------: |---------------------------------------------- |
+| `uid`             | string         | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |
+| `uri`             | string         | <div class="red">Yes</div> | URL address where to get the file             |
+| `headers`        | object         | <div class="yellow">No</div> | Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any other specific headers are needed to access it.                                   			|
+
+::: alert alert--warning
+`uid` should have the same file extension (e.g.: mp4, svg, jpg) as the original file.
+:::
+
+### Javascript Example
+```javascript
+await sos.offline.cache.loadOrSaveFile('9d66725ba2105f1833731ade5b7f334e.mp4', 'https://cdn.my-cms.com/files/video.mp4', { "Authorization": "Basic Zm9vOmJhcg==" })
+.then((file) => { console.log('Loaded or Saved', file); })
+.catch((error) => { console.error(error); });
+ 
+// Logs into console
+{
+  filePath: '/real/device/path/to/file/9d66725ba2105f1833731ade5b7f334e.mp4',
+}
+```
+
+::: alert alert--info
+Local device file path differs from device to device. It can point to file:// or http://localhost etc.
+:::
+
+### Returns
+* SUCCESS: File object
+* FAIL: No file of such uid is available, it will download it to local storage & then return saved file.
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/offline-files">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of managing offline files</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+<div class="row d-flex align-content-stretch force-padding-10">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/video-loop-offline">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of playing video in loop</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## deleteFile()
+Method `deleteFile()` is used for deleting previously saved file from internal memory.
+
+### Parameters
+
+|      Param     | Type         | Required  | Description                  					|
+| -------------- | -------------| :-------: |-------------------------------------------- |
+| `uid`            | string       | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |
+
+### Javascript example
+```javascript
+await sos.offline.cache.deleteFile('9d66725ba2105f1833731ade5b7f334e.mp4')
+.then(() => { console.log('Deleted'); })
+.catch((error) => { console.error(error); });
+```
+
+## getChecksumFile()
+Method `getChecksumFile()` is used for getting the checksum of file from internal memory.
+
+### Parameters:
+|      Param     | Type            | Required  | Description                  					|
+| -------------- | ----------------| :-------: |-------------------------------------------- |
+| `uid`            | string          | <div class="red">Yes</div> |Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |
+| `hashType`       | string          | <div class="red">Yes</div> |Type of checksum has. Currently supported hashType is just md5 |
+
+### Javascript example
+```javascript
+await sos.offline.cache.getChecksumFile('9d66725ba2105f1833731ade5b7f334e.mp4', 'md5')
+.then((checksum) => { console.log('MD5 checksum is ' + checksum); })
+.catch((error) => { console.error(error); });
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/md5-checksum">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of checking checksum of file</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## validateChecksumFile()
+Method `validateChecksumFile()` is used for validating the checksum of the previously saved file in from internal memory.
+
+### Parameters:
+
+|      Param     | Type             | Required  | Description                  					|
+| -------------- | -----------------| :-------: |-------------------------------------------- |
+| `uid`            | string           | <div class="red">Yes</div> |Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |
+| `hash`           | string           | <div class="red">Yes</div> |Hexa decimal representation of file checksum to be validated against |
+| `hashType`       | string           | <div class="red">Yes</div> |Type of checksum hash. Currently supported hashType is just md5 |
+
+### Javascript example
+```javascript
+// validate file checksum against internal memory
+await sos.offline.cache.validateChecksumFile(uid, '23dc936691f46d2bbef631f18a02f94f', 'md5')
+.then((valid) => { console.log('MD5 checksum is ' + (valid ? 'valid' : 'not valid')); })
+.catch((error) => { console.error(error); });
+```
+
+## decompressFile() (ZIP)
+Method `decompressFile()` is used to decompress (extract ZIP) file previously saved to internal memory.
+
+### Parameters
+
+|      Param      | Type         | Required  | Description                  					                     |
+| --------------- | ------------ | :-------: |----------------------------------------------------------------- |
+| `zipUid`          | string       | <div class="red">Yes</div> | Unique file identifier of a previously downloaded ZIP file          |
+| `destinationUid`  | string       | <div class="red">Yes</div> | Unique directory identifier (prefix of file) to extract ZIP file to |
+| `method`          | string       | <div class="red">Yes</div> | Method of compression algorithm, currently only zip is supported    |
+
+### Javascript example
+```javascript
+// validate file checksum against internal memory
+await sos.offline.cache.decompressFile(zipUid, destinationDirectoryUid, 'zip')
+    .then(() => { console.log('ZIP file extracted'); })
+    .catch((error) => { console.error(error); });
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/offline-zip-decompress">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of decompressing ZIP files</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## More examples
+
+* [Managing files](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/file-system)
+* [Sample applet from Box](https://github.com/signageos/applet-examples/blob/master/index.html)
+* All other examples are available in Knowledge Base under [Applet Examples](/knowledge-base/applet-examples)
+
+## Errors
+Although we are doing our best, following errors may occur when working with the offline cache.
+
+| Code | Type | Message |
+| ---- | ---- | ------- |
+| 40105 | AppletResourceError | Already loading file: `$$FILE_NAME$$` |
+|^^|^^| Please, check your code for multiple occurrences of addFile/s methods. |
+| 40106 | AppletResourceError | Already existing file: `$$FILE_NAME$$` |
+|^^|^^| Please, check your code for occurrences of addFile/s methods on lines before this error. |
+| 49902 | FileNotFoundError | File was not found `$$FILE_ID$$` |
+| 40901 | AppletOfflineCacheError | Uid contains invalid characters, allowed: `$$ALLOWED_CHARS$$`, got `$$ACTUAL_UID$$` |
+|^^|^^| Please, check if the used URL is correct. |
+| 40902 | AppletOfflineCacheError | Invalid headers `$$HEADERS$$` |
+| 50901 | InternalOfflineCacheError | Couldn't not read the files from the offline cache. |
+| 50902 | InternalOfflineCacheError | File wasn't saved correctly. |
+| 50903 | InternalOfflineCacheError | Reading the file from the offline cache failed. |

package/docs/js-api/js-offline-cache-simple-data.md

@@ -0,0 +1,134 @@
+---
+title:  Offline Cache for storing data
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] This API provides you with approach similar to the HTML5's Local Storage, but implemented internally via native device API and completely device agnostic."
+---
+
+# Offline Cache for storing simple data
+
+Use when you need to save some data into local memory. 
+This API provides you with approach similar to the HTML5's Local Storage, but implemented internally via native device API and completely device agnostic. 
+We do not recommend using a different storage type then Offline Cache or full featured [File System API](/api/js/content/js-file-system) that will provide you with more low-level methods.
+
+## All methods
+::: table-responsive
+| Method | Description | Supported Since |
+| ------ | -------- | ----- | :--------: |
+| `loadContent()` | Loads content from internal storage | 1.0.3 |
+| `saveContent()` | Saves content to internal storage | 1.0.3 |
+| `listContents()` | List all content items saved previously to internal storage | 2.0.0 |
+| `deleteContent()` | Delete content item previously saved to internal storage	 | 2.0.0 |
+:::
+
+::: alert alert--warning
+Emulator has certain limitations while handling offline files. [Read more here](/knowledge-base/box-emulator-limitations)
+:::
+
+## loadContent()
+Method `loadContent()` loads content from internal storage.
+
+### Parameters
+::: table-responsive
+|      Param     | Type   | Required | Description  |
+| -------------- | ------ | :-------: | ----------- |
+| `uid` | string | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |             				  |
+:::
+
+### Javascript example
+```javascript
+await sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash');
+```
+
+## saveContent()
+Method for saving content into internal storage. 
+
+### Parameters
+::: table-responsive
+|      Param     | Type   | Required | Description  |
+| -------------- | ------ | :-------: | ----------- |
+| `uid` | string | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |
+| `content` | string | <div class="red">Yes</div> | Only string variables enabled. For JSON values use `JSON.Stringify()`               				  |
+:::
+
+### Javascript Example
+```javascript
+sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash')
+.then(() => {
+    //Content was successfully saved, retrieve it. 
+    return sos.offline.cache.loadContent('ApplicationSecret');
+})
+.then((content) => {
+    console.log('Loaded', content); // print 123SuperSecretHash
+})
+```
+
+## listContents()
+List all content items saved previously to internal storage
+
+### Javascript example
+```javascript
+await sos.offline.cache.listContents();
+```
+
+## deleteContent()
+Delete content item previously saved to internal storage.
+
+### Parameters
+::: table-responsive
+|      Param     | Type   | Required | Description  |
+| -------------- | ------ | :-------: | ----------- |
+| `uid` | string | <div class="red">Yes</div> | Unique file identifier is used for later file retrieval, must contain a-z,A-Z,0-9 and . characters |             				  |
+:::
+
+### Javascript example
+```javascript
+//Store
+sos.offline.cache.saveContent('ApplicationSecret', '123SuperSecretHash')
+.then(() => {
+    //Content was successfully saved, retrieve it. 
+    return sos.offline.cache.loadContent('ApplicationSecret');
+})
+.then((content) => {
+    console.log('Loaded', content); // print 123SuperSecretHash
+ 
+    // Let's delete the content now
+    return sos.offline.cache.deleteContent('ApplicationSecret')
+})
+.then(() => {
+    console.log("Deleted");
+})
+.catch((error) => { console.error(error); });
+```
+
+## Usage with Typescript
+You can also use all these methods with [signageOS TypeScript](/knowledge-base/dev-tools-cli-typescript).
+
+```typescript
+loadContent(uid: string): Promise<string>;
+saveContent(uid: string, content: string): Promise<void>;
+
+listContents(): Promise<string[]>;
+deleteContent(uid: string): Promise<void>;
+```
+
+## Errors
+Although we are doing our best, following errors may occur when working with the offline cache.
+
+::: table-responsive
+| Code | Type | Message |
+| ---- | ---- | ------- |
+| 41001 | AppletNativeCacheError | Already saving the file with UID: ```uid``` |
+| 51001 | InternalNativeCacheError | Couldn't not read the files from the offline cache. |
+| 51001 | InternalNativeCacheError | Couldn\'t load the file from offline cache. |
+| 51001 | InternalNativeCacheError | Couldn\'t load the file before deleting it. |
+| 51002 | InternalNativeCacheError | Couldn\'t save the file to the offline cache. |
+| 51003 | InternalNativeCacheError | File wasn\'t deleted correctly. |
+| 40901 | AppletOfflineCacheError | Uid contains invalid characters, allowed: $$ALLOWED_CHARS$$, got $$ACTUAL_UID$$ |
+:::

package/docs/js-api/js-sensors.md

@@ -0,0 +1,70 @@
+---
+title:  Sensors
+author: Michal Artazov
+date:   28.9.2020
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+- sensors
+description: "[Content JS API] We don't directly provide any sensors API but we provide a set of tools to implement your own integration of the hardware that you want to use."
+---
+
+# Sensors
+
+We don't directly provide any sensors API but we provide a set of tools to implement your own integration of
+the hardware that you want to use.
+
+## Sensors interfaces
+
+We provide a set of interfaces, that any integration should implement.
+If every implementation implements the same set of interfaces, it's easy to swap it for a different implementation.
+It also requires less code to be written to use various types of hardware.
+If possible, you should always implement these interfaces.
+
+::: alert alert--info
+Right now, the list of interfaces is very short. We will be adding more types soon.
+If there's any particular type of interfaces you'd like, kindly let us know.
+:::
+
+### Button
+
+A regular button, that can be pressed or released.
+
+```typescript
+interface IButton {
+    isPressed(): Promise<boolean>;
+    on(event: 'pressed' | 'released', listener: () => void): void;
+}
+```
+
+### RFID Antenna
+
+Antenna that detects presence of RFID tags. An RFID tag is simply a number.
+Whenever a tag is placed at close proximity to the antenna, it will emit a `placed` event.
+Whenever a tag is picked and is no longer detected by the antenna, it will emit a `picked` event.
+
+```typescript
+interface IRfidAntenna {
+	getPlacedTags(): Promise<number[]>;
+	on(event: 'picked' | 'placed', listener: (rfidTag: number) => void): void;
+}
+```
+
+## Ready to use integrations
+
+We already did the hard work for you and implemented some of the popular hardware. All you have to do is use it in your project.
+For more information read [this article](/knowledge-base/sensors-supported-sensors).
+
+## Writing your own implementation
+
+Sometimes you might want to use hardware that we don't support out of the box yet.
+
+Firstly, you will need to read the documentation for the [serial API](/api/js/content/js-hardware-serial).
+Most often, the hardware you will decide to use connects to the device via USB and internally uses a serial communication, like RS232.
+In that case you will use the serial API.
+
+You can approach this any way you like, but remember that you should always implement the [interfaces defined by us](/api/js/content/js-sensors#sensors-interfaces).
+That will allow for greater code reusability and readability.