mirrors/flipperzero-firmware
1
Fork 0
mirror of https://github.com/flipperdevices/flipperzero-firmware.git synced 2025-12-12 12:51:22 +04:00
Code Issues Activity

Documentation: new doc on Storage module and JS cleanup (#4161)

Browse Source 
- Add new doc on Storage module
- Improve formatting in the JS section for better readability
This commit is contained in:
knrn64
2025-03-26 17:29:26 +03:00
committed by GitHub
parent 02dedd60f3
commit 54adc38b3a
17 changed files with 898 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
documentation/doxygen/js.dox
View File

@@ -16,12 +16,13 @@ Flipper Zero's built-in JavaScript engine enables you to run lightweight scripts
## JavaScript modules {#js_modules} ## JavaScript modules {#js_modules}
- @subpage js_badusb — This module allows you to emulate a standard USB keyboard - @subpage js_badusb — This module allows you to emulate a standard USB keyboard
- @subpage js_serial — The module for interaction with external devices via UART
- @subpage js_math — This module contains mathematical methods and constants
- @subpage js_notification — This module allows you to use LED, speaker and vibro for notifications
- @subpage js_event_loop — The module for easy event-based developing - @subpage js_event_loop — The module for easy event-based developing
- @subpage js_gpio — This module allows you to control GPIO pins - @subpage js_gpio — This module allows you to control GPIO pins
- @subpage js_gui — This module allows you to use GUI (graphical user interface) - @subpage js_gui — This module allows you to use GUI (graphical user interface)
- @subpage js_math — This module contains mathematical methods and constants
- @subpage js_notification — This module allows you to use LED, speaker and vibro for notifications
- @subpage js_serial — The module for interaction with external devices via UART
- @subpage js_storage — The module for accessing the filesystem
## Examples {#js_examples} ## Examples {#js_examples}

64
documentation/js/js_badusb.md
View File

@@ -4,16 +4,17 @@
let badusb = require("badusb"); let badusb = require("badusb");
``` ```
# Methods # Methods
## setup ## setup()
Start USB HID with optional parameters. Should be called before all other methods. Start USB HID with optional parameters. Should be called before all other methods.
### Parameters **Parameters**
Configuration object (optional):
Configuration object *(optional)*:
- vid, pid (number): VID and PID values, both are mandatory - vid, pid (number): VID and PID values, both are mandatory
- mfr_name (string): Manufacturer name (32 ASCII characters max), optional - mfr_name (string): Manufacturer name (32 ASCII characters max), optional
- prod_name (string): Product name (32 ASCII characters max), optional - prod_name (string): Product name (32 ASCII characters max), optional
### Examples: **Examples**
```js ```js
// Start USB HID with default parameters // Start USB HID with default parameters
badusb.setup(); badusb.setup();
@@ -23,10 +24,12 @@ badusb.setup({ vid: 0xAAAA, pid: 0xBBBB });
badusb.setup({ vid: 0xAAAA, pid: 0xBBBB, mfr_name: "Flipper Devices", prod_name: "Flipper Zero" }); badusb.setup({ vid: 0xAAAA, pid: 0xBBBB, mfr_name: "Flipper Devices", prod_name: "Flipper Zero" });
``` ```
## isConnected <br>
## isConnected()
Returns USB connection state. Returns USB connection state.
### Example: **Example**
```js ```js
if (badusb.isConnected()) { if (badusb.isConnected()) {
// Do something // Do something
@@ -35,15 +38,18 @@ if (badusb.isConnected()) {
} }
``` ```
## press <br>
## press()
Press and release a key. Press and release a key.
### Parameters **Parameters**
Key or modifier name, key code. Key or modifier name, key code.
See a list of key names below. See a [list of key names below](#js_badusb_keynames).
### Examples: **Examples**
```js ```js
badusb.press("a"); // Press "a" key badusb.press("a"); // Press "a" key
badusb.press("A"); // SHIFT + "a" badusb.press("A"); // SHIFT + "a"
@@ -53,58 +59,70 @@ 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) badusb.press(0x47); // Press key with HID code (hex) 0x47 (Scroll lock)
``` ```
## hold <br>
## hold()
Hold a key. Up to 5 keys (excluding modifiers) can be held simultaneously. Hold a key. Up to 5 keys (excluding modifiers) can be held simultaneously.
### Parameters **Parameters**
Same as `press`. Same as `press`.
### Examples: **Examples**
```js ```js
badusb.hold("a"); // Press and hold "a" key badusb.hold("a"); // Press and hold "a" key
badusb.hold("CTRL", "v"); // Press and hold CTRL + "v" combo badusb.hold("CTRL", "v"); // Press and hold CTRL + "v" combo
``` ```
## release <br>
## release()
Release a previously held key. Release a previously held key.
### Parameters **Parameters**
Same as `press`. Same as `press`.
Release all keys if called without parameters. Release all keys if called without parameters.
### Examples: **Examples**
```js ```js
badusb.release(); // Release all keys badusb.release(); // Release all keys
badusb.release("a"); // Release "a" key badusb.release("a"); // Release "a" key
``` ```
## print <br>
## print()
Print a string. Print a string.
### Parameters **Parameters**
- A string to print - A string to print
- *(optional)* Delay between key presses - *(optional)* Delay between key presses
### Examples: **Examples**
```js ```js
badusb.print("Hello, world!"); // print "Hello, world!" badusb.print("Hello, world!"); // print "Hello, world!"
badusb.print("Hello, world!", 100); // Add 100ms delay between key presses badusb.print("Hello, world!", 100); // Add 100ms delay between key presses
``` ```
<br>
## println ## println()
Same as `print` but ended with "ENTER" press. Same as `print` but ended with "ENTER" press.
### Parameters **Parameters**
- A string to print - A string to print
- *(optional)* Delay between key presses - *(optional)* Delay between key presses
### Examples: **Examples**
```js ```js
badusb.println("Hello, world!"); // print "Hello, world!" and press "ENTER" badusb.println("Hello, world!"); // print "Hello, world!" and press "ENTER"
``` ```
<br>
# Key names list # Key names list {#js_badusb_keynames}
## Modifier keys ## Modifier keys

46
documentation/js/js_builtin.md
View File

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

63
documentation/js/js_event_loop.md
View File

@@ -1,27 +1,28 @@
# Event Loop module {#js_event_loop} # Event Loop module {#js_event_loop}
```js
let eventLoop = require("event_loop");
```
The event loop is central to event-based programming in many frameworks, and our The event loop is central to event-based programming in many frameworks, and our
JS subsystem is no exception. It is a good idea to familiarize yourself with the JS subsystem is no exception. It is a good idea to familiarize yourself with the
event loop first before using any of the advanced modules (e.g. GPIO and GUI). event loop first before using any of the advanced modules (e.g. GPIO and GUI).
```js
let eventLoop = require("event_loop");
```
## Conceptualizing the event loop ## Conceptualizing the event loop
If you ever wrote JavaScript before, you have definitely seen callbacks. It's If you've ever written JavaScript code before, you've definitely seen callbacks. It's
when a function accepts another function (usually an anonymous one) as one of when a function takes another function (usually an anonymous one) as one of
the arguments, which it will call later on, e.g. when an event happens or when the arguments, which it will call later, e.g. when an event happens or when
data becomes ready: data becomes ready:
```js ```js
setTimeout(function() { console.log("Hello, World!") }, 1000); setTimeout(function() { console.log("Hello, World!") }, 1000);
``` ```
Many JavaScript engines employ a queue that the runtime fetches events from as Many JavaScript engines employ a queue from which the runtime fetches events as
they occur, subsequently calling the corresponding callbacks. This is done in a they occur, subsequently calling the corresponding callbacks. This is done in a
long-running loop, hence the name "event loop". Here's the pseudocode for a long-running loop, hence the name "event loop". Here's the pseudocode for a
typical event loop: typical event loop:
```js
\code{.js}
while(loop_is_running()) { while(loop_is_running()) {
if(event_available_in_queue()) { if(event_available_in_queue()) {
let event = fetch_event_from_queue(); let event = fetch_event_from_queue();
@@ -33,12 +34,14 @@ while(loop_is_running()) {
sleep_until_any_event_becomes_available(); sleep_until_any_event_becomes_available();
} }
} }
``` \endcode
Most JS runtimes enclose the event loop within themselves, so that most JS Most JS runtimes enclose the event loop within themselves, so that most JS
programmers does not even need to be aware of its existence. This is not the programmers don't even need to be aware of its existence. This is not the
case with our JS subsystem. case with our JS subsystem.
---
# Example # Example
This is how one would write something similar to the `setTimeout` example above: This is how one would write something similar to the `setTimeout` example above:
```js ```js
@@ -87,14 +90,18 @@ The first two arguments that get passed to our callback are:
- The event item, used for events that have extra data. Timer events do not, - The event item, used for events that have extra data. Timer events do not,
they just produce `undefined`. they just produce `undefined`.
---
# API reference # API reference
## `run` ## run()
Runs the event loop until it is stopped with `stop`. Runs the event loop until it is stopped with `stop`.
## `subscribe` <br>
## subscribe()
Subscribes a function to an event. Subscribes a function to an event.
### Parameters **Parameters**
- `contract`: an event source identifier - `contract`: an event source identifier
- `callback`: the function to call when the event happens - `callback`: the function to call when the event happens
- extra arguments: will be passed as extra arguments to the callback - extra arguments: will be passed as extra arguments to the callback
@@ -107,35 +114,45 @@ to `undefined`. The callback may return an array of the same length as the count
of the extra arguments to modify them for the next time that the event handler of the extra arguments to modify them for the next time that the event handler
is called. Any other returns values are discarded. is called. Any other returns values are discarded.
### Returns **Returns**
A `SubscriptionManager` object: A `SubscriptionManager` object:
- `SubscriptionManager.cancel()`: unsubscribes the callback from the event - `SubscriptionManager.cancel()`: unsubscribes the callback from the event
### Warning **Warning**
Each event source may only have one callback associated with it. Each event source may only have one callback associated with it.
## `stop` <br>
## stop()
Stops the event loop. Stops the event loop.
## `timer` <br>
## timer()
Produces an event source that fires with a constant interval either once or Produces an event source that fires with a constant interval either once or
indefinitely. indefinitely.
### Parameters **Parameters**
- `mode`: either `"oneshot"` or `"periodic"` - `mode`: either `"oneshot"` or `"periodic"`
- `interval`: the timeout (for `"oneshot"`) timers or the period (for - `interval`: the timeout (for `"oneshot"`) timers or the period (for
`"periodic"` timers) `"periodic"` timers)
### Returns **Returns**
A `Contract` object, as expected by `subscribe`'s first parameter. A `Contract` object, as expected by `subscribe`'s first parameter.
## `queue` <br>
## queue()
Produces a queue that can be used to exchange messages. Produces a queue that can be used to exchange messages.
### Parameters **Parameters**
- `length`: the maximum number of items that the queue may contain - `length`: the maximum number of items that the queue may contain
### Returns **Returns**
A `Queue` object: A `Queue` object:
- `Queue.send(message)`: - `Queue.send(message)`:
- `message`: a value of any type that will be placed at the end of the queue - `message`: a value of any type that will be placed at the end of the queue

46
documentation/js/js_gpio.md
View File

@@ -21,21 +21,26 @@ led.write(false);
delay(1000); delay(1000);
``` ```
---
# API reference # API reference
## `get` ## get
Gets a `Pin` object that can be used to manage a pin. Gets a `Pin` object that can be used to manage a pin.
### Parameters **Parameters**
- `pin`: pin identifier (examples: `"pc3"`, `7`, `"pa6"`, `3`) - `pin`: pin identifier (examples: `"pc3"`, `7`, `"pa6"`, `3`)
### Returns **Returns**
A `Pin` object. A `Pin` object.
## `Pin` object <br>
### `Pin.init()`
## Pin object
### Pin.init()
Configures a pin. Configures a pin.
#### Parameters **Parameters**
- `mode`: `Mode` object: - `mode`: `Mode` object:
- `direction` (required): either `"in"` or `"out"` - `direction` (required): either `"in"` or `"out"`
- `outMode` (required for `direction: "out"`): either `"open_drain"` or - `outMode` (required for `direction: "out"`): either `"open_drain"` or
@@ -46,30 +51,41 @@ Configures a pin.
`"rising"`, `"falling"` or `"both"` `"rising"`, `"falling"` or `"both"`
- `pull` (optional): either `"up"`, `"down"` or unset - `pull` (optional): either `"up"`, `"down"` or unset
### `Pin.write()` <br>
### Pin.write()
Writes a digital value to a pin configured with `direction: "out"`. Writes a digital value to a pin configured with `direction: "out"`.
#### Parameters **Parameters**
- `value`: boolean logic level to write - `value`: boolean logic level to write
### `Pin.read()` <br>
### Pin.read()
Reads a digital value from a pin configured with `direction: "in"` and any Reads a digital value from a pin configured with `direction: "in"` and any
`inMode` except `"analog"`. `inMode` except `"analog"`.
#### Returns **Returns**
Boolean logic level
### `Pin.readAnalog()` Boolean logic level.
<br>
### Pin.readAnalog()
Reads an analog voltage level in millivolts from a pin configured with Reads an analog voltage level in millivolts from a pin configured with
`direction: "in"` and `inMode: "analog"`. `direction: "in"` and `inMode: "analog"`.
#### Returns **Returns**
Voltage on pin in millivolts. Voltage on pin in millivolts.
### `Pin.interrupt()` <br>
### Pin.interrupt()
Attaches an interrupt to a pin configured with `direction: "in"` and Attaches an interrupt to a pin configured with `direction: "in"` and
`inMode: "interrupt"` or `"event"`. `inMode: "interrupt"` or `"event"`.
#### Returns **Returns**
An event loop `Contract` object that identifies the interrupt event source. The An event loop `Contract` object that identifies the interrupt event source. The
event does not produce any extra data. event does not produce any extra data.

54
documentation/js/js_gui.md
View File

@@ -18,6 +18,8 @@ GUI module has several submodules:
- @subpage js_gui__dialog — Dialog with up to 3 options - @subpage js_gui__dialog — Dialog with up to 3 options
- @subpage js_gui__widget — Displays a combination of custom elements on one screen - @subpage js_gui__widget — Displays a combination of custom elements on one screen
---
## Conceptualizing GUI ## Conceptualizing GUI
### Event loop ### Event loop
It is highly recommended to familiarize yourself with the event loop first It is highly recommended to familiarize yourself with the event loop first
@@ -78,7 +80,9 @@ a GUI application:
| ViewDispatcher | Common UI elements that fit with the overall look of the system | ✅ | | ViewDispatcher | Common UI elements that fit with the overall look of the system | ✅ |
| SceneManager | Additional navigation flow management for complex applications | ❌ | | SceneManager | Additional navigation flow management for complex applications | ❌ |
# Example ---
## Example
An example with three different views using the ViewDispatcher approach: An example with three different views using the ViewDispatcher approach:
```js ```js
let eventLoop = require("event_loop"); let eventLoop = require("event_loop");
@@ -123,48 +127,64 @@ gui.viewDispatcher.switchTo(views.demos);
eventLoop.run(); eventLoop.run();
``` ```
---
# API reference # API reference
## `viewDispatcher` ## viewDispatcher
The `viewDispatcher` constant holds the `ViewDispatcher` singleton. The `viewDispatcher` constant holds the `ViewDispatcher` singleton.
### `viewDispatcher.switchTo(view)` <br>
### viewDispatcher.switchTo(view)
Switches to a view, giving it control over the display and input. Switches to a view, giving it control over the display and input.
#### Parameters **Parameters**
- `view`: the `View` to switch to - `view`: the `View` to switch to
### `viewDispatcher.sendTo(direction)` <br>
### viewDispatcher.sendTo(direction)
Sends the viewport that the dispatcher manages to the front of the stackup Sends the viewport that the dispatcher manages to the front of the stackup
(effectively making it visible), or to the back (effectively making it (effectively making it visible), or to the back (effectively making it
invisible). invisible).
#### Parameters **Parameters**
- `direction`: either `"front"` or `"back"` - `direction`: either `"front"` or `"back"`
### `viewDispatcher.sendCustom(event)` <br>
### viewDispatcher.sendCustom(event)
Sends a custom number to the `custom` event handler. Sends a custom number to the `custom` event handler.
#### Parameters **Parameters**
- `event`: number to send - `event`: number to send
### `viewDispatcher.custom` <br>
### viewDispatcher.custom
An event loop `Contract` object that identifies the custom event source, An event loop `Contract` object that identifies the custom event source,
triggered by `ViewDispatcher.sendCustom(event)`. triggered by `ViewDispatcher.sendCustom(event)`.
### `viewDispatcher.navigation` <br>
### viewDispatcher.navigation
An event loop `Contract` object that identifies the navigation event source, An event loop `Contract` object that identifies the navigation event source,
triggered when the back key is pressed. triggered when the back key is pressed.
## `ViewFactory` <br>
When you import a module implementing a view, a `ViewFactory` is instantiated.
For example, in the example above, `loadingView`, `submenuView` and `emptyView`
are view factories.
### `ViewFactory.make()` ## ViewFactory
When you import a module implementing a view, a `ViewFactory` is instantiated. For example, in the example above, `loadingView`, `submenuView` and `emptyView` are view factories.
<br>
### ViewFactory.make()
Creates an instance of a `View`. Creates an instance of a `View`.
### `ViewFactory.make(props)` <br>
### ViewFactory.make(props)
Creates an instance of a `View` and assigns initial properties from `props`. Creates an instance of a `View` and assigns initial properties from `props`.
#### Parameters **Parameters**
- `props`: simple key-value object, e.g. `{ header: "Header" }` - `props`: simple key-value object, e.g. `{ header: "Header" }`

40
documentation/js/js_gui__dialog.md
View File

@@ -11,42 +11,24 @@ let dialogView = require("gui/dialog");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example # Example
For an example, refer to the `gui.js` example script. For an example, refer to the `gui.js` example script.
# View props # View props
## `header`
Text that appears in bold at the top of the screen.
Type: `string` | **Prop** | **Type** | **Description** |
|------------|-----------|----------------------------------------------------------------|
## `text` | `header` | string | Text that appears in bold at the top of the screen. |
Text that appears in the middle of the screen. | `text` | string | Text that appears in the middle of the screen. |
| `left` | string | Text for the left button. If unset, the left button does not show up. |
Type: `string` | `center` | string | Text for the center button. If unset, the center button does not show up. |
| `right` | string | Text for the right button. If unset, the right button does not show up. |
## `left`
Text for the left button. If unset, the left button does not show up.
Type: `string`
## `center`
Text for the center button. If unset, the center button does not show up.
Type: `string`
## `right`
Text for the right button. If unset, the right button does not show up.
Type: `string`
# View events # View events
## `input`
Fires when the user presses on either of the three possible buttons. The item
contains one of the strings `"left"`, `"center"` or `"right"` depending on the
button.
Item type: `string` | Item | Type | Description |
|----------|--------|-----------------------------------------------------------------------------|
| `input` | `string`| Fires when the user presses on either of the three possible buttons. The item contains one of the strings `"left"`, `"center"`, or `"right"` depending on the button. |

2
documentation/js/js_gui__empty_screen.md
View File

@@ -11,7 +11,7 @@ let emptyView = require("gui/empty_screen");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example # Example

2
documentation/js/js_gui__loading.md
View File

@@ -11,7 +11,7 @@ let loadingView = require("gui/loading");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example # Example

27
documentation/js/js_gui__submenu.md
View File

@@ -11,26 +11,19 @@ let submenuView = require("gui/submenu");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example ## View props
For an example, refer to the GUI example.
# View props | Property | Type | Description |
## `header` |----------|-----------|-------------------------------------------|
A single line of text that appears above the list. | `header` | `string` | A single line of text that appears above the list. |
| `items` | `string[]`| The list of options. |
Type: `string`
## `items` ## View events
The list of options.
Type: `string[]` | Item | Type | Description |
|----------|---------|---------------------------------------------------------------|
# View events | `chosen` | `number`| Fires when an entry has been chosen by the user. The item contains the index of the entry. |
## `chosen`
Fires when an entry has been chosen by the user. The item contains the index of
the entry.
Item type: `number`

12
documentation/js/js_gui__text_box.md
View File

@@ -11,14 +11,14 @@ let textBoxView = require("gui/text_box");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example ## Example
For an example, refer to the `gui.js` example script. For an example, refer to the `gui.js` example script.
# View props ## View props
## `text`
Text to show in the text box.
Type: `string` | Prop | Type | Description |
|----------|---------|------------------------------------|
| `text` | `string`| Text to show in the text box. |

35
documentation/js/js_gui__text_input.md
View File

@@ -11,33 +11,22 @@ let textInputView = require("gui/text_input");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example ## Example
For an example, refer to the `gui.js` example script. For an example, refer to the `gui.js` example script.
# View props ## View props
## `minLength`
The shortest allowed text length.
Type: `number` | Prop | Type | Description |
|-------------|--------|--------------------------------------------------|
| `minLength` | `number` | The shortest allowed text length. |
| `maxLength` | `number` | The longest allowed text length. <br> Default: `32` |
| `header` | `string` | A single line of text that appears above the keyboard. |
## `maxLength` ## View events
The longest allowed text length.
Type: `number` | Item | Type | Description |
|-------------|--------|--------------------------------------------------|
Default: `32` | `input` | `string` | Fires when the user selects the "Save" button and the text matches the length constrained by `minLength` and `maxLength`. |
## `header`
A single line of text that appears above the keyboard.
Type: `string`
# View events
## `input`
Fires when the user selects the "Save" button and the text matches the length
constrained by `minLength` and `maxLength`.
Item type: `string`

8
documentation/js/js_gui__widget.md
View File

@@ -11,14 +11,14 @@ let widgetView = require("gui/widget");
``` ```
This module depends on the `gui` module, which in turn depends on the This module depends on the `gui` module, which in turn depends on the
`event_loop` module, so they _must_ be imported in this order. It is also `event_loop` module, so they **must** be imported in this order. It is also
recommended to conceptualize these modules first before using this one. recommended to conceptualize these modules first before using this one.
# Example ## Example
For an example, refer to the `gui.js` example script. For an example, refer to the `gui.js` example script.
# View props ## View props
This view does not have any props. This view does not have any props.
# Children ## Children
This view has the elements as its children. This view has the elements as its children.

255
documentation/js/js_math.md
View File

@@ -5,6 +5,7 @@ The module contains mathematical methods and constants. Call the `require` funct
```js ```js
let math = require("math"); let math = require("math");
``` ```
# Constants # Constants
## PI ## PI
@@ -17,204 +18,248 @@ The number e (Euler's number) = 2.71828182845904523536028747135266250.
The smallest number that satisfies the condition: 1.0 + EPSILON != 1.0. The smallest number that satisfies the condition: 1.0 + EPSILON != 1.0.
EPSILON = 2.2204460492503131e-16. EPSILON = 2.2204460492503131e-16.
<br>
---
# Methods # Methods
## abs ## abs()
Return the absolute value of a number. Return the absolute value of a number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The absolute value of `x`. If `x` is negative (including -0), returns `-x`. Otherwise, returns `x`. The result is therefore always a positive number or 0. The absolute value of `x`. If `x` is negative (including -0), returns `-x`. Otherwise, returns `x`. The result is therefore always a positive number or 0.
### Example **Example**
```js ```js
math.abs(-5); // 5 math.abs(-5); // 5
``` ```
## acos <br>
## acos()
Return the inverse cosine (in radians) of a number. Return the inverse cosine (in radians) of a number.
### Parameters **Parameters**
- x: A number between -1 and 1, inclusive, representing the angle's cosine value - x: A number between -1 and 1, inclusive, representing the angle's cosine value
### Returns **Returns**
The inverse cosine (angle in radians between 0 and π, inclusive) of `x`. If `x` is less than -1 or greater than 1, returns `NaN`. The inverse cosine (angle in radians between 0 and π, inclusive) of `x`. If `x` is less than -1 or greater than 1, returns `NaN`.
### Example **Example**
```js ```js
math.acos(-1); // 3.141592653589793 math.acos(-1); // 3.141592653589793
``` ```
## acosh <br>
## acosh()
Return the inverse hyperbolic cosine of a number. Return the inverse hyperbolic cosine of a number.
### Parameters **Parameters**
- x: A number greater than or equal to 1 - x: A number greater than or equal to 1
### Returns **Returns**
The inverse hyperbolic cosine of `x`. The inverse hyperbolic cosine of `x`.
### Example **Example**
```js ```js
math.acosh(1); // 0 math.acosh(1); // 0
``` ```
## asin <br>
## asin()
Return the inverse sine (in radians) of a number. Return the inverse sine (in radians) of a number.
### Parameters **Parameters**
- x: A number between -1 and 1, inclusive, representing the angle's sine value - x: A number between -1 and 1, inclusive, representing the angle's sine value
### Returns **Returns**
The inverse sine (angle in radians between -𝜋/2 and 𝜋/2, inclusive) of `x`. The inverse sine (angle in radians between -𝜋/2 and 𝜋/2, inclusive) of `x`.
### Example **Example**
```js ```js
math.asin(0.5); // 0.5235987755982989 math.asin(0.5); // 0.5235987755982989
``` ```
## asinh <br>
## asinh()
Return the inverse hyperbolic sine of a number. Return the inverse hyperbolic sine of a number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The inverse hyperbolic sine of `x`. The inverse hyperbolic sine of `x`.
### Example **Example**
```js ```js
math.asinh(1); // 0.881373587019543 math.asinh(1); // 0.881373587019543
``` ```
## atan <br>
## atan()
Return the inverse tangent (in radians) of a number. Return the inverse tangent (in radians) of a number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The inverse tangent (angle in radians between -𝜋/2 and 𝜋/2, inclusive) of `x`. The inverse tangent (angle in radians between -𝜋/2 and 𝜋/2, inclusive) of `x`.
### Example **Example**
```js ```js
math.atan(1); // 0.7853981633974483 math.atan(1); // 0.7853981633974483
``` ```
## atan2 <br>
## atan2()
Return the angle in the plane (in radians) between the positive x-axis and the ray from (0, 0) to the point (x, y), for math.atan2(y, x). Return the angle in the plane (in radians) between the positive x-axis and the ray from (0, 0) to the point (x, y), for math.atan2(y, x).
### Parameters **Parameters**
- y: The y coordinate of the point - y: The y coordinate of the point
- x: The x coordinate of the point - x: The x coordinate of the point
### Returns **Returns**
The angle in radians (between -π and π, inclusive) between the positive x-axis and the ray from (0, 0) to the point (x, y). The angle in radians (between -π and π, inclusive) between the positive x-axis and the ray from (0, 0) to the point (x, y).
### Example **Example**
```js ```js
math.atan2(90, 15); // 1.4056476493802699 math.atan2(90, 15); // 1.4056476493802699
``` ```
## atanh <br>
## atanh()
The method returns the inverse hyperbolic tangent of a number. The method returns the inverse hyperbolic tangent of a number.
### Parameters **Parameters**
- x: A number between -1 and 1, inclusive - x: A number between -1 and 1, inclusive
### Returns **Returns**
The inverse hyperbolic tangent of `x`. The inverse hyperbolic tangent of `x`.
### Example **Example**
```js ```js
math.atanh(0.5); // 0.5493061443340548 math.atanh(0.5); // 0.5493061443340548
``` ```
## cbrt <br>
## cbrt()
Return the cube root of a number. Return the cube root of a number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The cube root of `x`. The cube root of `x`.
### Example **Example**
```js ```js
math.cbrt(2); // 1.2599210498948732 math.cbrt(2); // 1.2599210498948732
``` ```
## ceil <br>
## ceil()
Round up and return the smallest integer greater than or equal to a given number. Round up and return the smallest integer greater than or equal to a given number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The smallest integer greater than or equal to `x`. It's the same value as `-math.floor(-x)`. The smallest integer greater than or equal to `x`. It's the same value as `-math.floor(-x)`.
### Example **Example**
```js ```js
math.ceil(-7.004); // -7 math.ceil(-7.004); // -7
math.ceil(7.004); // 8 math.ceil(7.004); // 8
``` ```
## clz32 <br>
## clz32()
Return the number of leading zero bits in the 32-bit binary representation of a number. Return the number of leading zero bits in the 32-bit binary representation of a number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The number of leading zero bits in the 32-bit binary representation of `x`. The number of leading zero bits in the 32-bit binary representation of `x`.
### Example **Example**
```js ```js
math.clz32(1); // 31 math.clz32(1); // 31
math.clz32(1000); // 22 math.clz32(1000); // 22
``` ```
## cos <br>
## cos()
Return the cosine of a number in radians. Return the cosine of a number in radians.
### Parameters **Parameters**
- x: A number representing an angle in radians - x: A number representing an angle in radians
### Returns **Returns**
The cosine of `x`, between -1 and 1, inclusive. The cosine of `x`, between -1 and 1, inclusive.
### Example **Example**
```js ```js
math.cos(math.PI); // -1 math.cos(math.PI); // -1
``` ```
## exp <br>
## exp()
Return e raised to the power of a number. Return e raised to the power of a number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
A nonnegative number representing `e^x`, where `e` is the base of the natural logarithm. A nonnegative number representing `e^x`, where `e` is the base of the natural logarithm.
### Example **Example**
```js ```js
math.exp(0); // 1 math.exp(0); // 1
math.exp(1); // 2.718281828459045 math.exp(1); // 2.718281828459045
``` ```
## floor <br>
## floor()
Round down and return the largest integer less than or equal to a given number. Round down and return the largest integer less than or equal to a given number.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The largest integer smaller than or equal to `x`. It's the same value as `-math.ceil(-x)`. The largest integer smaller than or equal to `x`. It's the same value as `-math.ceil(-x)`.
### Example **Example**
```js ```js
math.floor(-45.95); // -46 math.floor(-45.95); // -46
math.floor(-45.05); // -46 math.floor(-45.05); // -46
@@ -224,137 +269,165 @@ math.floor(45.05); // 45
math.floor(45.95); // 45 math.floor(45.95); // 45
``` ```
## isEqual <br>
## isEqual()
Return true if the difference between numbers `a` and `b` is less than the specified parameter `e`. Return true if the difference between numbers `a` and `b` is less than the specified parameter `e`.
### Parameters **Parameters**
- a: A number a - a: A number a
- b: A number b - b: A number b
- e: An epsilon parameter - e: An epsilon parameter
### Returns **Returns**
True if the difference between numbers `a` and `b` is less than the specified parameter `e`. Otherwise, false. True if the difference between numbers `a` and `b` is less than the specified parameter `e`. Otherwise, false.
### Example **Example**
```js ```js
math.isEqual(1.4, 1.6, 0.2); // false math.isEqual(1.4, 1.6, 0.2); // false
math.isEqual(3.556, 3.555, 0.01); // true math.isEqual(3.556, 3.555, 0.01); // true
``` ```
## max <br>
## max()
Return the largest of two numbers given as input parameters. Return the largest of two numbers given as input parameters.
### Parameters **Parameters**
- a: A number a - a: A number a
- b: A number b - b: A number b
### Returns **Returns**
The largest of the given numbers. The largest of the given numbers.
### Example **Example**
```js ```js
math.max(10, 20); // 20 math.max(10, 20); // 20
math.max(-10, -20); // -10 math.max(-10, -20); // -10
``` ```
## min <br>
## min()
Return the smallest of two numbers given as input parameters. Return the smallest of two numbers given as input parameters.
### Parameters **Parameters**
- a: A number a - a: A number a
- b: A number b - b: A number b
### Returns **Returns**
The smallest of the given numbers. The smallest of the given numbers.
### Example **Example**
```js ```js
math.min(10, 20); // 10 math.min(10, 20); // 10
math.min(-10, -20); // -20 math.min(-10, -20); // -20
``` ```
## pow <br>
## pow()
Return the value of a base raised to a power. Return the value of a base raised to a power.
### Parameters **Parameters**
- base: The base number - base: The base number
- exponent: The exponent number - exponent: The exponent number
### Returns **Returns**
A number representing base taken to the power of exponent. A number representing base taken to the power of exponent.
### Example **Example**
```js ```js
math.pow(7, 2); // 49 math.pow(7, 2); // 49
math.pow(7, 3); // 343 math.pow(7, 3); // 343
math.pow(2, 10); // 1024 math.pow(2, 10); // 1024
``` ```
## random <br>
## random()
Return a floating-point, pseudo-random number that's greater than or equal to 0 and less than 1, with approximately uniform distribution over that range — which you can then scale to your desired range. Return a floating-point, pseudo-random number that's greater than or equal to 0 and less than 1, with approximately uniform distribution over that range — which you can then scale to your desired range.
### Returns **Returns**
A floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive). A floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive).
### Example **Example**
```js ```js
let num = math.random(); let num = math.random();
``` ```
## sign <br>
## sign()
Return 1 or -1, indicating the sign of the number passed as argument. Return 1 or -1, indicating the sign of the number passed as argument.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
-1 if the number is less than 0, and 1 otherwise. -1 if the number is less than 0, and 1 otherwise.
### Example **Example**
```js ```js
math.sign(3); // 1 math.sign(3); // 1
math.sign(0); // 1 math.sign(0); // 1
math.sign(-3); // -1 math.sign(-3); // -1
``` ```
## sin <br>
## sin()
Return the sine of a number in radians. Return the sine of a number in radians.
### Parameters **Parameters**
- x: A number representing an angle in radians - x: A number representing an angle in radians
### Returns **Returns**
The sine of `x`, between -1 and 1, inclusive. The sine of `x`, between -1 and 1, inclusive.
### Example **Example**
```js ```js
math.sin(math.PI / 2); // 1 math.sin(math.PI / 2); // 1
``` ```
## sqrt <br>
## sqrt()
Return the square root of a number. Return the square root of a number.
### Parameters **Parameters**
- x: A number greater than or equal to 0 - x: A number greater than or equal to 0
### Returns **Returns**
The square root of `x`, a nonnegative number. If `x` < 0, script will fail with an error. The square root of `x`, a nonnegative number. If `x` < 0, script will fail with an error.
### Example **Example**
```js ```js
math.sqrt(25); // 5 math.sqrt(25); // 5
``` ```
## trunc <br>
## trunc()
Return the integer part of a number by removing any fractional digits. Return the integer part of a number by removing any fractional digits.
### Parameters **Parameters**
- x: A number - x: A number
### Returns **Returns**
The integer part of `x`. The integer part of `x`.
### Example **Example**
```js ```js
math.trunc(-1.123); // -1 math.trunc(-1.123); // -1
math.trunc(0.123); // 0 math.trunc(0.123); // 0

20
documentation/js/js_notification.md
View File

@@ -3,32 +3,36 @@
```js ```js
let notify = require("notification"); let notify = require("notification");
``` ```
# Methods ## Methods
## success ### success()
"Success" flipper notification message. "Success" flipper notification message.
### Examples: **Example**
```js ```js
notify.success(); notify.success();
``` ```
## error <br>
### error()
"Error" flipper notification message. "Error" flipper notification message.
### Examples: **Example**
```js ```js
notify.error(); notify.error();
``` ```
## blink <br>
### blink()
Blink notification LED. Blink notification LED.
### Parameters **Parameters**
- Blink color (blue/red/green/yellow/cyan/magenta) - Blink color (blue/red/green/yellow/cyan/magenta)
- Blink type (short/long) - Blink type (short/long)
### Examples: **Examples**
```js ```js
notify.blink("red", "short"); // Short blink of red LED notify.blink("red", "short"); // Short blink of red LED
notify.blink("green", "short"); // Long blink of green LED notify.blink("green", "short"); // Long blink of green LED

70
documentation/js/js_serial.md
View File

@@ -5,78 +5,99 @@ let serial = require("serial");
``` ```
# Methods # Methods
## setup ## setup()
Configure serial port. Should be called before all other methods. Configure serial port. Should be called before all other methods.
### Parameters **Parameters**
- Serial port name (usart, lpuart) - Serial port name (usart, lpuart)
- Baudrate - Baudrate
### Examples: **Example**
```js ```js
// Configure LPUART port with baudrate = 115200 // Configure LPUART port with baudrate = 115200
serial.setup("lpuart", 115200); serial.setup("lpuart", 115200);
``` ```
## write <br>
## write()
Write data to serial port. Write data to serial port.
### Parameters **Parameters**
One or more arguments of the following types: One or more arguments of the following types:
- A string - A string
- Single number, each number is interpreted as a byte - Single number, each number is interpreted as a byte
- Array of numbers, each number is interpreted as a byte - Array of numbers, each number is interpreted as a byte
- ArrayBuffer or DataView - ArrayBuffer or DataView
### Examples: **Example**
```js ```js
serial.write(0x0a); // Write a single byte 0x0A serial.write(0x0a); // Write a single byte 0x0A
serial.write("Hello, world!"); // Write a string serial.write("Hello, world!"); // Write a string
serial.write("Hello, world!", [0x0d, 0x0a]); // Write a string followed by two bytes serial.write("Hello, world!", [0x0d, 0x0a]); // Write a string followed by two bytes
``` ```
## read <br>
## read()
Read a fixed number of characters from serial port. Read a fixed number of characters from serial port.
### Parameters **Parameters**
- Number of bytes to read - Number of bytes to read
- *(optional)* Timeout value in ms - *(optional)* Timeout value in ms
### Returns **Returns**
A sting of received characters or undefined if nothing was received before timeout. A sting of received characters or undefined if nothing was received before timeout.
### Examples: **Example**
```js ```js
serial.read(1); // Read a single byte, without timeout serial.read(1); // Read a single byte, without timeout
serial.read(10, 5000); // Read 10 bytes, with 5s timeout serial.read(10, 5000); // Read 10 bytes, with 5s timeout
``` ```
## readln <br>
## readln()
Read from serial port until line break character. Read from serial port until line break character.
### Parameters **Parameters**
*(optional)* Timeout value in ms. *(optional)* Timeout value in ms.
### Returns **Returns**
A sting of received characters or undefined if nothing was received before timeout. A sting of received characters or undefined if nothing was received before timeout.
### Examples: **Example**
```js ```js
serial.readln(); // Read without timeout serial.readln(); // Read without timeout
serial.readln(5000); // Read with 5s timeout serial.readln(5000); // Read with 5s timeout
``` ```
## readBytes <br>
## readBytes()
Read from serial port until line break character. Read from serial port until line break character.
### Parameters **Parameters**
- Number of bytes to read - Number of bytes to read
- *(optional)* Timeout value in ms - *(optional)* Timeout value in ms
### Returns **Returns**
ArrayBuffer with received data or undefined if nothing was received before timeout. ArrayBuffer with received data or undefined if nothing was received before timeout.
### Examples: **Example**
```js ```js
serial.readBytes(4); // Read 4 bytes, without timeout serial.readBytes(4); // Read 4 bytes, without timeout
@@ -84,19 +105,24 @@ serial.readBytes(4); // Read 4 bytes, without timeout
serial.readBytes(1, 0); serial.readBytes(1, 0);
``` ```
## expect <br>
## expect()
Search for a string pattern in received data stream. Search for a string pattern in received data stream.
### Parameters **Parameters**
- Single argument or array of the following types: - Single argument or array of the following types:
- A string - A string
- Array of numbers, each number is interpreted as a byte - Array of numbers, each number is interpreted as a byte
- *(optional)* Timeout value in ms - *(optional)* Timeout value in ms
### Returns **Returns**
Index of matched pattern in input patterns list, undefined if nothing was found. Index of matched pattern in input patterns list, undefined if nothing was found.
### Examples: **Example**
```js ```js
// Wait for root shell prompt with 1s timeout, returns 0 if it was received before timeout, undefined if not // Wait for root shell prompt with 1s timeout, returns 0 if it was received before timeout, undefined if not
serial.expect("# ", 1000); serial.expect("# ", 1000);

445
documentation/js/js_storage.md Normal file
View File

@@ -0,0 +1,445 @@
# Storage module {#js_storage}
The module allows you to access files and directories on the Flipper Zero filesystems. Call the `require` function to load the module before first using its methods:
```js
let storage = require("storage");
```
## Paths
To work with files and folders, you'll need to specify paths to them. File paths have the following structure:
```
/ext/example_subdir_1/example_subdir_2/example_file.txt
\____________________________________/ \__________/ \_/
dirPath fileName fileExt
```
* **dirPath** — directory path starting with `/int/` (small storage in the MCU's flash memory) or `/ext/` (microSD card storage). Specify the sub-directories containing the file using `/` as a separator between directory names.
* **fileName** — file name.
* **fileExt** — file extension (separated from the file name by a period).
---
# Structures
## FsInfo
Filesystem information structure.
**Fields**
- totalSpace: Total size of the filesystem, in bytes
- freeSpace: Free space in the filesystem, in bytes
<br>
## FileInfo
File information structure.
**Fields**
- path: Full path (e.g. "/ext/test", returned by `stat`) or file name (e.g. "test", returned by `readDirectory`)
- isDirectory: Returns `true` if path leads to a directory (not a file)
- size: File size in bytes, or 0 in the case of directories
- accessTime: Time of last access as a UNIX timestamp
---
# Classes
## File
This class implements methods for working with file. To get an object of the File class, use the `OpenFile` method.
<br>
### close()
Closes the file. After this method is called, all other operations related to this file become unavailable.
**Returns**
`true` on success, `false` on failure.
<br>
### isOpen()
**Returns**
`true` if file is currently opened, `false` otherwise.
<br>
### read()
Reads bytes from a file opened in read-only or read-write mode.
**Parameters**
- mode: The data type to interpret the bytes as: a `string` decoded from ASCII data (`"ascii"`), or an `ArrayBuf` (`"binary"`)
- bytes: How many bytes to read from the file
**Returns**
An `ArrayBuf` if the mode is `"binary"`, a `string` if the mode is `ascii`. The number of bytes that was actually read may be fewer than requested.
<br>
### write()
Writes bytes to a file opened in write-only or read-write mode.
**Parameters**
- data: The data to write: a string that will be ASCII-encoded, or an ArrayBuf
**Returns**
The amount of bytes that was actually written.
<br>
### seekRelative()
Moves the R/W pointer forward.
**Parameters**
- bytes: How many bytes to move the pointer forward by
**Returns**
`true` on success, `false` on failure.
<br>
### seekAbsolute()
Moves the R/W pointer to an absolute position inside the file.
**Parameters**
- bytes: The position inside the file
**Returns**
`true` on success, `false` on failure.
<br>
### tell()
Gets the absolute position of the R/W pointer in bytes.
**Returns**
The absolute current position in the file.
<br>
### truncate()
Discards the data after the current position of the R/W pointer in a file opened in either write-only or read-write mode.
**Returns**
`true` on success, `false` on failure.
<br>
### size()
**Returns**
The total size of the file in bytes.
<br>
### eof()
Detects whether the R/W pointer has reached the end of the file.
**Returns**
`true` if end of file reached, `false` otherwise.
<br>
### copyTo()
Copies bytes from the R/W pointer in the current file to the R/W pointer in another file.
**Parameters**
- dest: The file to copy the bytes into
- bytes: The number of bytes to copy
**Returns**
`true` on success, `false` on failure.
---
# Methods
## arePathsEqual()
Determines whether the two paths are equivalent. Respects filesystem-defined path equivalence rules.
**Parameters**
- path1: The first path for comparison
- path2: The second path for comparison
**Returns**
`true` if path1 and path2 are equals, `false` otherwise.
<br>
## isSubpathOf()
Determines whether a path is a subpath of another path. Respects filesystem-defined path equivalence rules.
**Parameters**
- parentPath: The parent path
- childPath: The child path
**Returns**
`true` if path1 and path2 are equals, `false` otherwise.
<br>
## fileOrDirExists()
Detects whether a file or a directory exists.
**Parameters**
- path: The path to the file or directory
**Returns**
`true` if file/directory exists, `false` otherwise.
**Example**
```js
if (storage.fileOrDirExists("/ext/test_dir")) {
print("Test directory exists");
}
```
<br>
## fsInfo()
Fetches generic information about a filesystem.
**Parameters**
- filesystem: The path to the filesystem (e.g. `"/ext"` or `"/int"`)
**Returns**
A `fsInfo` structure or `undefined` on failure.
**Example**
```js
let fsinfo = storage.fsInfo("/ext");
if (fsinfo === undefined) {
print("Filesystem access error");
} else {
print("Free space on the /ext filesystem:", fsinfo.freeSpace);
}
```
<br>
## stat()
Acquires metadata about a file or directory.
**Parameters**
- path: The path to the file or directory
**Returns**
A `FileInfo` structure or `undefined` on failure.
**Example**
```js
let finfo = storage.stat("/ext/test_file.txt");
if (finfo === undefined) {
print("File not found");
} else {
print("File size:", finfo.size);
}
```
<br>
## directoryExists()
Detects whether a directory exists.
**Parameters**
- path: The path to the directory
**Returns**
`true` if directory exists, `false` otherwise.
<br>
## makeDirectory()
Creates an empty directory.
**Parameters**
- path: The path to the new directory
**Returns**
`true` on success, `false` on failure.
<br>
## readDirectory()
Reads the list of files in a directory.
**Parameters**
- path: The path to the directory
**Returns**
Array of `FileInfo` structures with directory entries, or `undefined` on failure.
<br>
## nextAvailableFilename()
Chooses the next available filename with a numeric suffix in a directory.
```
/ext/example_dir/example_file123.txt
\______________/ \__________/\_/ \_/
dirPath fileName | |
| +--- fileExt
+------- suffix selected by this function
```
**Parameters**
- dirPath: The directory to look in
- fileName: The base of the filename (the part before the numeric suffix)
- fileExt: The extension of the filename (the part after the numeric suffix)
- maxLen: The maximum length of the filename with the numeric suffix
**Returns**
The base of the filename with the next available numeric suffix, without the extension or the base directory.
<br>
## copy()
Copies a file or recursively copies a possibly non-empty directory.
**Parameters**
- oldPath: The original path to the file or directory
- newPath: The new path that the copy of the file or directory will be accessible under
**Returns**
`true` on success, `false` on failure.
**Example**
```js
if (storage.copy("/ext/src_file.txt", "/ext/dst_file.txt")) {
print("File copied");
}
```
<br>
## rename()
Renames or moves a file or directory.
**Parameters**
- oldPath: The old path to the file or directory
- newPath: The new path that the file or directory will become accessible
**Returns**
`true` on success, `false` on failure.
**Example**
```js
if (storage.rename("/ext/src_file.txt", "/ext/dst_file.txt")) {
print("File moved");
}
```
<br>
## remove()
Removes a file or an empty directory.
**Parameters**
- path: The path to the file or directory
**Returns**
`true` on success, `false` on failure.
**Example**
```js
let path = "/ext/test_file.txt";
file = storage.openFile(path, "w", "create_always");
file.write("Test");
file.close();
print("File created");
if (storage.remove(path)) {
print("File removed");
}
```
<br>
## rmrf()
Removes a file or recursively removes a possibly non-empty directory.
**Parameters**
- path: The path to the file or directory
**Returns**
`true` on success, `false` on failure.
**Example**
```js
let path = "/ext/test_dir";
if (storage.rmrf(path)) {
print("Directory removed");
}
```