JS Documentation (#3535)

* Initial JS documentation
* Spelling fix

Co-authored-by: あく <alleteam@gmail.com>

documentation/doxygen/index.dox

@@ -15,6 +15,7 @@ The documentation is divided into several sections, with all of them accessible
 - @ref dev_tools - Hardware and software tools for all kinds of programming
 - @ref expansion - Additional modules to expand Flipper's consciousness
 - @ref misc - Various useful pieces of information
+- @ref js - JS-based scripting engine documentation
 
 Aside from the manually-written documentation files, there's also a few automatically-generated ones at the bottom of the sidebar:
 

documentation/doxygen/js.dox

@@ -0,0 +1,18 @@
+/**
+@page js JavaScript
+
+This page contains some information on the Flipper Zero scripting engine, which is based on a modified mJS library
+
+- [Brief mJS description](https://github.com/cesanta/mjs/blob/master/README.md)
+- @subpage js_data_types
+- @subpage js_builtin
+
+JavaScript Modules
+JS modules use the Flipper app plugin system. Each module is compiled into a .fal library file and is located on a microSD card. Here is a list of implemented modules:
+
+- @subpage js_badusb - BadUSB module
+- @subpage js_serial - Serial module
+- @subpage js_dialog - Dialog module
+- @subpage js_notification - Notifications module
+
+*/

documentation/js/js_badusb.md

@@ -0,0 +1,144 @@
+# js_badusb {#js_badusb}
+
+# BadUSB module
+```js
+let badusb = require("badusb");
+```
+# Methods
+## setup
+Start USB HID with optional parameters. Should be called before all other methods.
+
+### Parameters
+Configuration object (optional):
+- vid, pid (number): VID and PID values, both are mandatory
+- mfr_name (string): Manufacturer name (32  ASCII characters max), optional
+- prod_name (string): Product name (32  ASCII characters max), optional
+
+### Examples:
+```js
+// Start USB HID with default parameters
+badusb.setup();
+// Start USB HID with custom vid:pid = AAAA:BBBB, manufacturer and product strings not defined
+badusb.setup({ vid: 0xAAAA, pid: 0xBBBB }); 
+// Start USB HID with custom vid:pid = AAAA:BBBB, manufacturer string = "Flipper Devices", product string = "Flipper Zero"
+badusb.setup({ vid: 0xAAAA, pid: 0xBBBB, mfr_name: "Flipper Devices", prod_name: "Flipper Zero" });
+```
+
+## isConnected
+Returns USB connection state.
+
+### Example:
+```js
+if (badusb.isConnected()) {
+    // Do something
+} else {
+    // Show an error
+}
+```
+
+## press
+Press and release a key.
+
+### Parameters
+Key or modifier name, key code.
+
+See a list of key names below.
+
+### Examples:
+```js
+badusb.press("a"); // Press "a" key
+badusb.press("A"); // SHIFT + "a"
+badusb.press("CTRL", "a"); // CTRL + "a"
+badusb.press("CTRL", "SHIFT", "ESC"); // CTRL + SHIFT + ESC combo
+badusb.press(98); // Press key with HID code (dec) 98 (Numpad 0 / Insert)
+badusb.press(0x47); // Press key with HID code (hex) 0x47 (Scroll lock)
+```
+
+## hold
+Hold a key. Up to 5 keys (excluding modifiers) can be held simultaneously.
+
+### Parameters
+Same as `press`
+
+### Examples:
+```js
+badusb.hold("a"); // Press and hold "a" key
+badusb.hold("CTRL", "v"); // Press and hold CTRL + "v" combo
+```
+
+## release
+Release a previously hold key.
+
+### Parameters
+Same as `press`
+
+Release all keys if called without parameters
+
+### Examples:
+```js
+badusb.release(); // Release all keys
+badusb.release("a"); // Release "a" key
+```
+
+## print
+Print a string.
+
+### Parameters
+- A string to print
+- (optional) delay between key presses
+
+### Examples:
+```js
+badusb.print("Hello, world!"); // print "Hello, world!"
+badusb.print("Hello, world!", 100); // Add 100ms delay between key presses
+```
+
+## println
+Same as `print` but ended with "ENTER" press.
+
+### Parameters
+- A string to print
+- (optional) delay between key presses
+
+### Examples:
+```js
+badusb.println("Hello, world!");  // print "Hello, world!" and press "ENTER"
+```
+
+# Key names list
+
+## Modifier keys
+
+| Name          |
+| ------------- |
+| CTRL          |            
+| SHIFT         |  
+| ALT           |
+| GUI           |          
+
+## Special keys
+
+| Name               | Notes            |
+| ------------------ | ---------------- |
+| DOWN               | Down arrow       |
+| LEFT               | Left arrow       |
+| RIGHT              | Right arrow      |
+| UP                 | Up arrow         |
+| ENTER              |                  |
+| DELETE             |                  |
+| BACKSPACE          |                  |
+| END                |                  |
+| HOME               |                  |
+| ESC                |                  |
+| INSERT             |                  |
+| PAGEUP             |                  |
+| PAGEDOWN           |                  |
+| CAPSLOCK           |                  |
+| NUMLOCK            |                  |
+| SCROLLLOCK         |                  |
+| PRINTSCREEN        |                  |
+| PAUSE              | Pause/Break key  |
+| SPACE              |                  |
+| TAB                |                  |
+| MENU               | Context menu key |
+| Fx                 | F1-F24 keys      |

documentation/js/js_builtin.md

@@ -0,0 +1,56 @@
+# Built-in methods {#js_builtin}
+
+## require
+Load a module plugin.
+
+### Parameters
+- Module name
+
+### Examples:
+```js
+let serial = require("serial"); // Load "serial" module
+```
+
+## delay
+### Parameters
+- Delay value in ms
+
+### Examples:
+```js
+delay(500); // Delay for 500ms
+```
+## print
+Print a message on a screen console.
+
+### Parameters
+The following argument types are supported:
+- String
+- Number
+- Bool
+- undefined
+
+### Examples:
+```js
+print("string1", "string2", 123);
+```
+
+## console.log
+## console.warn
+## console.error
+## console.debug
+Same as `print`, but output to serial console only, with corresponding log level.
+
+## to_string
+Convert a number to string.
+
+### Examples:
+```js
+to_string(123)
+```
+## to_hex_string
+Convert a number to string(hex format).
+
+### Examples:
+```js
+to_hex_string(0xFF)
+```

documentation/js/js_data_types.md

@@ -0,0 +1,13 @@
+# Data types {#js_data_types}
+
+Here is a list of common data types used by mJS.
+- string - sequence of single byte characters, no UTF8 support
+- number
+- boolean
+- foreign - C function or data pointer
+- undefined
+- null
+- object - a data structure with named fields
+- array - special type of object, all items have indexes and equal types
+- ArrayBuffer - raw data buffer
+- DataView - provides interface for accessing ArrayBuffer contents

documentation/js/js_dialog.md

@@ -0,0 +1,49 @@
+# js_dialog {#js_dialog}
+
+# Dialog module
+```js
+let dialog = require("dialog");
+```
+# Methods
+
+## message
+Show a simple message dialog with header, text and "OK" button.
+
+### Parameters
+- Dialog header text
+- Dialog text
+
+### Retuns
+true if central button was pressed, false if the dialog was closed by back key press
+
+### Examples:
+```js
+dialog.message("Dialog demo", "Press OK to start");
+```
+
+## custom
+More complex dialog with configurable buttons
+
+### Parameters
+Configuration object with the following fileds:
+- header: Dialog header text
+- text: Dialog text
+- button_left: (optional) left button name
+- button_right: (optional) right button name
+- button_center: (optional) central button name
+
+### Retuns
+Name of pressed button or empty string if the dialog was closed by back key press
+
+### Examples:
+```js
+let dialog_params = ({
+    header: "Dialog header",
+    text: "Dialog text",
+    button_left: "Left",
+    button_right: "Right",
+    button_center: "OK"
+});
+
+dialog.custom(dialog_params);
+```

documentation/js/js_notification.md

@@ -0,0 +1,36 @@
+# js_notification {#js_notification}
+
+# Notification module
+```js
+let notify = require("notification");
+```
+# Methods
+
+## success
+"Success" flipper notification message
+
+### Examples:
+```js
+notify.success();
+```
+
+## error
+"Error" flipper notification message
+
+### Examples:
+```js
+notify.error();
+```
+
+## blink
+Blink notification LED
+
+### Parameters
+- Blink color (blue/red/green/yellow/cyan/magenta)
+- Blink type (short/long)
+
+### Examples:
+```js
+notify.blink("red", "short"); // Short blink of red LED
+notify.blink("green", "short"); // Long blink of green LED
+```

documentation/js/js_serial.md

@@ -0,0 +1,107 @@
+# js_serial {#js_serial}
+
+# Serial module
+```js
+let serial = require("serial");
+```
+# Methods
+
+## setup
+Configure serial port. Should be called before all other methods.
+
+### Parameters
+- Serial port name (usart, lpuart)
+- Baudrate
+
+### Examples:
+```js
+// Configure LPUART port with baudrate = 115200
+serial.setup("lpuart", 115200);
+```
+
+## write
+Write data to serial port
+
+### Parameters
+One or more arguments of the following types:
+- A string
+- Single number, each number is interpreted as a byte
+- Array of numbers, each number is interpreted as a byte
+- ArrayBuffer or DataView
+
+### Examples:
+```js
+serial.write(0x0a); // Write a single byte 0x0A
+serial.write("Hello, world!"); // Write a string
+serial.write("Hello, world!", [0x0d, 0x0a]); // Write a string followed by two bytes
+```
+
+## read
+Read a fixed number of characters from serial port.
+
+### Parameters
+- Number of bytes to read
+- (optional) Timeout value in ms
+
+### Returns
+A sting of received characters or undefined if nothing was received before timeout.
+
+### Examples:
+```js
+serial.read(1); // Read a single byte, without timeout
+serial.read(10, 5000); // Read 10 bytes, with 5s timeout
+```
+
+## readln
+Read from serial port untill line break character
+
+### Parameters
+(optional) Timeout value in ms
+
+### Returns
+A sting of received characters or undefined if nothing was received before timeout.
+
+### Examples:
+```js
+serial.readln(); // Read without timeout
+serial.readln(5000); // Read with 5s timeout
+```
+
+## readBytes
+Read from serial port untill line break character
+
+### Parameters
+- Number of bytes to read
+- (optional) Timeout value in ms
+
+### Returns
+ArrayBuffer with received data or undefined if nothing was received before timeout.
+
+### Examples:
+```js
+serial.readBytes(4); // Read 4 bytes, without timeout
+
+// Read one byte from receive buffer with zero timeout, returns UNDEFINED if Rx bufer is empty
+serial.readBytes(1, 0);
+```
+
+## expect
+Search for a string pattern in received data stream
+
+### Parameters
+- Single argument or array of the following types:
+    - A string
+    - Array of numbers, each number is interpreted as a byte
+- (optional) Timeout value in ms
+
+### Returns
+Index of matched pattern in input patterns list, undefined if nothing was found.
+
+### Examples:
+```js
+// Wait for root shell prompt with 1s timeout, returns 0 if it was received before timeout, undefined if not
+serial.expect("# ", 1000); 
+
+// Infinitely wait for one of two strings, should return 0 if the first string got matched, 1 if the second one
+serial.expect([": not found", "Usage: "]);
+```