mirrors/unleashed-firmware
1
Fork 0
mirror of https://github.com/DarkFlippers/unleashed-firmware.git synced 2025-12-12 12:42:30 +04:00
Code Issues Activity

Merge remote-tracking branch 'OFW/dev' into dev

Browse Source
This commit is contained in:
MX
2024-10-15 00:08:47 +03:00
parent 2f102e61a9
commit 4b9b1769f7
54 changed files with 1357 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
documentation/js/js_builtin.md
View File

@@ -41,16 +41,10 @@ print("string1", "string2", 123);
Same as `print`, but output to serial console only, with corresponding log level.
## to_string
Convert a number to string.
Convert a number to string with an optional base.
### Examples:
```js
to_string(123)
```
## to_hex_string
Convert a number to string(hex format).
### Examples:
```js
to_hex_string(0xFF)
to_string(123) // "123"
to_string(123, 16) // "0x7b"
```

49
documentation/js/js_dialog.md
View File

@@ -1,49 +0,0 @@
# 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
### Returns
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 fields:
- 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
### Returns
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);
```

144
documentation/js/js_event_loop.md Normal file
View File

@@ -0,0 +1,144 @@
# js_event_loop {#js_event_loop}
# Event Loop module
```js
let eventLoop = require("event_loop");
```
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
event loop first before using any of the advanced modules (e.g. GPIO and GUI).
## Conceptualizing the event loop
If you ever wrote JavaScript before, you have definitely seen callbacks. It's
when a function accepts 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
data becomes ready:
```js
setTimeout(function() { console.log("Hello, World!") }, 1000);
```
Many JavaScript engines employ a queue that the runtime fetches events from as
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
typical event loop:
```js
while(loop_is_running()) {
if(event_available_in_queue()) {
let event = fetch_event_from_queue();
let callback = get_callback_associated_with(event);
if(callback)
callback(get_extra_data_for(event));
} else {
// avoid wasting CPU time
sleep_until_any_event_becomes_available();
}
}
```
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
case with our JS subsystem.
# Example
This is how one would write something similar to the `setTimeout` example above:
```js
// import module
let eventLoop = require("event_loop");
// create an event source that will fire once 1 second after it has been created
let timer = eventLoop.timer("oneshot", 1000);
// subscribe a callback to the event source
eventLoop.subscribe(timer, function(_subscription, _item, eventLoop) {
print("Hello, World!");
eventLoop.stop();
}, eventLoop); // notice this extra argument. we'll come back to this later
// run the loop until it is stopped
eventLoop.run();
// the previous line will only finish executing once `.stop()` is called, hence
// the following line will execute only after "Hello, World!" is printed
print("Stopped");
```
I promised you that we'll come back to the extra argument after the callback
function. Our JavaScript engine does not support closures (anonymous functions
that access values outside of their arguments), so we ask `subscribe` to pass an
outside value (namely, `eventLoop`) as an argument to the callback so that we
can access it. We can modify this extra state:
```js
// this timer will fire every second
let timer = eventLoop.timer("periodic", 1000);
eventLoop.subscribe(timer, function(_subscription, _item, counter, eventLoop) {
print("Counter is at:", counter);
if(counter === 10)
eventLoop.stop();
// modify the extra arguments that will be passed to us the next time
return [counter + 1, eventLoop];
}, 0, eventLoop);
```
Because we have two extra arguments, if we return anything other than an array
of length 2, the arguments will be kept as-is for the next call.
The first two arguments that get passed to our callback are:
- The subscription manager that lets us `.cancel()` our subscription
- The event item, used for events that have extra data. Timer events do not,
they just produce `undefined`.
# API reference
## `run`
Runs the event loop until it is stopped with `stop`.
## `subscribe`
Subscribes a function to an event.
### Parameters
- `contract`: an event source identifier
- `callback`: the function to call when the event happens
- extra arguments: will be passed as extra arguments to the callback
The callback will be called with at least two arguments, plus however many were
passed as extra arguments to `subscribe`. The first argument is the subscription
manager (the same one that `subscribe` itself returns). The second argument is
the event item for events that produce extra data; the ones that don't set this
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
is called. Any other returns values are discarded.
### Returns
A `SubscriptionManager` object:
- `SubscriptionManager.cancel()`: unsubscribes the callback from the event
### Warning
Each event source may only have one callback associated with it.
## `stop`
Stops the event loop.
## `timer`
Produces an event source that fires with a constant interval either once or
indefinitely.
### Parameters
- `mode`: either `"oneshot"` or `"periodic"`
- `interval`: the timeout (for `"oneshot"`) timers or the period (for
`"periodic"` timers)
### Returns
A `Contract` object, as expected by `subscribe`'s first parameter.
## `queue`
Produces a queue that can be used to exchange messages.
### Parameters
- `length`: the maximum number of items that the queue may contain
### Returns
A `Queue` object:
- `Queue.send(message)`:
- `message`: a value of any type that will be placed at the end of the queue
- `input`: a `Contract` (event source) that pops items from the front of the
queue

77
documentation/js/js_gpio.md Normal file
View File

@@ -0,0 +1,77 @@
# js_gpio {#js_gpio}
# GPIO module
```js
let eventLoop = require("event_loop");
let gpio = require("gpio");
```
This module depends on the `event_loop` module, so it _must_ only be imported
after `event_loop` is imported.
# Example
```js
let eventLoop = require("event_loop");
let gpio = require("gpio");
let led = gpio.get("pc3");
led.init({ direction: "out", outMode: "push_pull" });
led.write(true);
delay(1000);
led.write(false);
delay(1000);
```
# API reference
## `get`
Gets a `Pin` object that can be used to manage a pin.
### Parameters
- `pin`: pin identifier (examples: `"pc3"`, `7`, `"pa6"`, `3`)
### Returns
A `Pin` object
## `Pin` object
### `Pin.init()`
Configures a pin
#### Parameters
- `mode`: `Mode` object:
- `direction` (required): either `"in"` or `"out"`
- `outMode` (required for `direction: "out"`): either `"open_drain"` or
`"push_pull"`
- `inMode` (required for `direction: "in"`): either `"analog"`,
`"plain_digital"`, `"interrupt"` or `"event"`
- `edge` (required for `inMode: "interrupt"` or `"event"`): either
`"rising"`, `"falling"` or `"both"`
- `pull` (optional): either `"up"`, `"down"` or unset
### `Pin.write()`
Writes a digital value to a pin configured with `direction: "out"`
#### Parameters
- `value`: boolean logic level to write
### `Pin.read()`
Reads a digital value from a pin configured with `direction: "in"` and any
`inMode` except `"analog"`
#### Returns
Boolean logic level
### `Pin.read_analog()`
Reads an analog voltage level in millivolts from a pin configured with
`direction: "in"` and `inMode: "analog"`
#### Returns
Voltage on pin in millivolts
### `Pin.interrupt()`
Attaches an interrupt to a pin configured with `direction: "in"` and
`inMode: "interrupt"` or `"event"`
#### Returns
An event loop `Contract` object that identifies the interrupt event source. The
event does not produce any extra data.

161
documentation/js/js_gui.md Normal file
View File

@@ -0,0 +1,161 @@
# js_gui {#js_gui}
# GUI module
```js
let eventLoop = require("event_loop");
let gui = require("gui");
```
This module depends on the `event_loop` module, so it _must_ only be imported
after `event_loop` is imported.
## Conceptualizing GUI
### Event loop
It is highly recommended to familiarize yourself with the event loop first
before doing GUI-related things.
### Canvas
The canvas is just a drawing area with no abstractions over it. Drawing on the
canvas directly (i.e. not through a viewport) is useful in case you want to
implement a custom design element, but this is rather uncommon.
### Viewport
A viewport is a window into a rectangular portion of the canvas. Applications
always access the canvas through a viewport.
### View
In Flipper's terminology, a "View" is a fullscreen design element that assumes
control over the entire viewport and all input events. Different types of views
are available (not all of which are unfortunately currently implemented in JS):
| View | Has JS adapter? |
|----------------------|------------------|
| `button_menu` | ❌ |
| `button_panel` | ❌ |
| `byte_input` | ❌ |
| `dialog_ex` | ✅ (as `dialog`) |
| `empty_screen` | ✅ |
| `file_browser` | ❌ |
| `loading` | ✅ |
| `menu` | ❌ |
| `number_input` | ❌ |
| `popup` | ❌ |
| `submenu` | ✅ |
| `text_box` | ✅ |
| `text_input` | ✅ |
| `variable_item_list` | ❌ |
| `widget` | ❌ |
In JS, each view has its own set of properties (or just "props"). The programmer
can manipulate these properties in two ways:
- Instantiate a `View` using the `makeWith(props)` method, passing an object
with the initial properties
- Call `set(name, value)` to modify a property of an existing `View`
### View Dispatcher
The view dispatcher holds references to all the views that an application needs
and switches between them as the application makes requests to do so.
### Scene Manager
The scene manager is an optional add-on to the view dispatcher that makes
managing applications with complex navigation flows easier. It is currently
inaccessible from JS.
### Approaches
In total, there are three different approaches that you may take when writing
a GUI application:
| Approach | Use cases | Available from JS |
|----------------|------------------------------------------------------------------------------|-------------------|
| ViewPort only | Accessing the graphics API directly, without any of the nice UI abstractions | ❌ |
| ViewDispatcher | Common UI elements that fit with the overall look of the system | ✅ |
| SceneManager | Additional navigation flow management for complex applications | ❌ |
# Example
An example with three different views using the ViewDispatcher approach:
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let loadingView = require("gui/loading");
let submenuView = require("gui/submenu");
let emptyView = require("gui/empty_screen");
// Common pattern: declare all the views in an object. This is absolutely not
// required, but adds clarity to the script.
let views = {
// the view dispatcher auto-✨magically✨ remembers views as they are created
loading: loadingView.make(),
empty: emptyView.make(),
demos: submenuView.makeWith({
items: [
"Hourglass screen",
"Empty screen",
"Exit app",
],
}),
};
// go to different screens depending on what was selected
eventLoop.subscribe(views.demos.chosen, function (_sub, index, gui, eventLoop, views) {
if (index === 0) {
gui.viewDispatcher.switchTo(views.loading);
} else if (index === 1) {
gui.viewDispatcher.switchTo(views.empty);
} else if (index === 2) {
eventLoop.stop();
}
}, gui, eventLoop, views);
// go to the demo chooser screen when the back key is pressed
eventLoop.subscribe(gui.viewDispatcher.navigation, function (_sub, _, gui, views) {
gui.viewDispatcher.switchTo(views.demos);
}, gui, views);
// run UI
gui.viewDispatcher.switchTo(views.demos);
eventLoop.run();
```
# API reference
## `viewDispatcher`
The `viewDispatcher` constant holds the `ViewDispatcher` singleton.
### `viewDispatcher.switchTo(view)`
Switches to a view, giving it control over the display and input
#### Parameters
- `view`: the `View` to switch to
### `viewDispatcher.sendTo(direction)`
Sends the viewport that the dispatcher manages to the front of the stackup
(effectively making it visible), or to the back (effectively making it
invisible)
#### Parameters
- `direction`: either `"front"` or `"back"`
### `viewDispatcher.sendCustom(event)`
Sends a custom number to the `custom` event handler
#### Parameters
- `event`: number to send
### `viewDispatcher.custom`
An event loop `Contract` object that identifies the custom event source,
triggered by `ViewDispatcher.sendCustom(event)`
### `viewDispatcher.navigation`
An event loop `Contract` object that identifies the navigation event source,
triggered when the back key is pressed
## `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.
### `ViewFactory.make()`
Creates an instance of a `View`
### `ViewFactory.make(props)`
Creates an instance of a `View` and assigns initial properties from `props`
#### Parameters
- `props`: simple key-value object, e.g. `{ header: "Header" }`

53
documentation/js/js_gui__dialog.md Normal file
View File

@@ -0,0 +1,53 @@
# js_gui__dialog {#js_gui__dialog}
# Dialog GUI view
Displays a dialog with up to three options.
<img src="dialog.png" width="200" alt="Sample screenshot of the view" />
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let dialogView = require("gui/dialog");
```
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
recommended to conceptualize these modules first before using this one.
# Example
For an example refer to the `gui.js` example script.
# View props
## `header`
Text that appears in bold at the top of the screen
Type: `string`
## `text`
Text that appears in the middle of the screen
Type: `string`
## `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
## `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`

22
documentation/js/js_gui__empty_screen.md Normal file
View File

@@ -0,0 +1,22 @@
# js_gui__empty_screen {#js_gui__empty_screen}
# Empty Screen GUI View
Displays nothing.
<img src="empty.png" width="200" alt="Sample screenshot of the view" />
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let emptyView = require("gui/empty_screen");
```
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
recommended to conceptualize these modules first before using this one.
# Example
For an example refer to the GUI example.
# View props
This view does not have any props.

23
documentation/js/js_gui__loading.md Normal file
View File

@@ -0,0 +1,23 @@
# js_gui__loading {#js_gui__loading}
# Loading GUI View
Displays an animated hourglass icon. Suppresses all `navigation` events, making
it impossible for the user to exit the view by pressing the back key.
<img src="loading.png" width="200" alt="Sample screenshot of the view" />
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let loadingView = require("gui/loading");
```
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
recommended to conceptualize these modules first before using this one.
# Example
For an example refer to the GUI example.
# View props
This view does not have any props.

37
documentation/js/js_gui__submenu.md Normal file
View File

@@ -0,0 +1,37 @@
# js_gui__submenu {#js_gui__submenu}
# Submenu GUI view
Displays a scrollable list of clickable textual entries.
<img src="submenu.png" width="200" alt="Sample screenshot of the view" />
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let submenuView = require("gui/submenu");
```
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
recommended to conceptualize these modules first before using this one.
# Example
For an example refer to the GUI example.
# View props
## `header`
Single line of text that appears above the list
Type: `string`
## `items`
The list of options
Type: `string[]`
# View events
## `chosen`
Fires when an entry has been chosen by the user. The item contains the index of
the entry.
Item type: `number`

25
documentation/js/js_gui__text_box.md Normal file
View File

@@ -0,0 +1,25 @@
# js_gui__text_box {#js_gui__text_box}
# Text box GUI view
Displays a scrollable read-only text field.
<img src="text_box.png" width="200" alt="Sample screenshot of the view" />
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let textBoxView = require("gui/text_box");
```
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
recommended to conceptualize these modules first before using this one.
# Example
For an example refer to the `gui.js` example script.
# View props
## `text`
Text to show in the text box.
Type: `string`

44
documentation/js/js_gui__text_input.md Normal file
View File

@@ -0,0 +1,44 @@
# js_gui__text_input {#js_gui__text_input}
# Text input GUI view
Displays a keyboard.
<img src="text_input.png" width="200" alt="Sample screenshot of the view" />
```js
let eventLoop = require("event_loop");
let gui = require("gui");
let textInputView = require("gui/text_input");
```
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
recommended to conceptualize these modules first before using this one.
# Example
For an example refer to the `gui.js` example script.
# View props
## `minLength`
Smallest allowed text length
Type: `number`
## `maxLength`
Biggest allowed text length
Type: `number`
Default: `32`
## `header`
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`

48
documentation/js/js_submenu.md
View File

@@ -1,48 +0,0 @@
# js_submenu {#js_submenu}
# Submenu module
```js
let submenu = require("submenu");
```
# Methods
## setHeader
Set the submenu header text.
### Parameters
- header (string): The submenu header text
### Example
```js
submenu.setHeader("Select an option:");
```
## addItem
Add a new submenu item.
### Parameters
- label (string): The submenu item label text
- id (number): The submenu item ID, must be a Uint32 number
### Example
```js
submenu.addItem("Option 1", 1);
submenu.addItem("Option 2", 2);
submenu.addItem("Option 3", 3);
```
## show
Show a submenu that was previously configured using `setHeader()` and `addItem()` methods.
### Returns
The ID of the submenu item that was selected, or `undefined` if the BACK button was pressed.
### Example
```js
let selected = submenu.show();
if (selected === undefined) {
// if BACK button was pressed
} else if (selected === 1) {
// if item with ID 1 was selected
}
```

69
documentation/js/js_textbox.md
View File

@@ -1,69 +0,0 @@
# js_textbox {#js_textbox}
# Textbox module
```js
let textbox = require("textbox");
```
# Methods
## setConfig
Set focus and font for the textbox.
### Parameters
- focus: "start" to focus on the beginning of the text, or "end" to focus on the end of the text
- font: "text" to use the default proportional font, or "hex" to use a monospaced font, which is convenient for aligned array output in HEX
### Example
```js
textbox.setConfig("start", "text");
textbox.addText("Hello world");
textbox.show();
```
## addText
Add text to the end of the textbox.
### Parameters
- text (string): The text to add to the end of the textbox
### Example
```js
textbox.addText("New text 1\nNew text 2");
```
## clearText
Clear the textbox.
### Example
```js
textbox.clearText();
```
## isOpen
Return true if the textbox is open.
### Returns
True if the textbox is open, false otherwise.
### Example
```js
let isOpen = textbox.isOpen();
```
## show
Show the textbox. You can add text to it using the `addText()` method before or after calling the `show()` method.
### Example
```js
textbox.show();
```
## close
Close the textbox.
### Example
```js
if (textbox.isOpen()) {
textbox.close();
}
```