-A classic LED style clock built using the Moddable SDK. For more information, see the [Clock Project](https://blog.moddable.com/blog/clock-project/) blog post.
\ No newline at end of file
+A classic LED style clock built using the Moddable SDK. For more information, see the [Clock Project](https://blog.moddable.com/blog/clock-project/) blog post.
diff --git a/contributed/serial/SerialModule.md b/contributed/serial/SerialModule.md
index a4235e9d18..8ebeddfc76 100644
--- a/contributed/serial/SerialModule.md
+++ b/contributed/serial/SerialModule.md
@@ -26,7 +26,7 @@ The `Serial` constructor takes its configuration information from the **manifest
let serial = new Serial();
-Revised: March 22, 2022 @@ -13,7 +13,7 @@ This document provides information about using the M5Paper with the Moddable SDK - [Troubleshooting](#troubleshooting) - [Development Resources](#development-resources) - [Port Status](#port-status) - - [Display Driver](#display-driver) + - [Display Driver](#display-driver) - [Update Modes](#update-modes) - [Image Filters](#image-filters) - [Examples](#examples) @@ -50,19 +50,19 @@ After you've set up your host environment and ESP32 tools, take the following st 2. Build and deploy the app with `mcconfig`. - `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md). - + `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md). + Use the platform `-p esp32/m5paper` with `mcconfig` to build for M5Paper. For example, to build the [`epaper-photos` example](../../examples/piu/epaper-photos): - + ```text cd $MODDABLE/examples/piu/epaper-photos mcconfig -d -m -p esp32/m5paper ``` - + The [examples readme](../../examples) contains additional information about other commonly used `mcconfig` arguments for screen rotation, Wi-Fi configuration, and more. Use the platform `-p simulator/m5paper` with `mcconfig` to build for the M5Paper simulator. - + ## Troubleshooting @@ -79,7 +79,7 @@ The following are implemented and working: - EPD display driver - GT911 touch driver - SHT30 temperature/humidity sensor -- A / B / C buttons +- A / B / C buttons - RTC > **Note**: The I2C address of the GT911 touch controller floats. The implementation tries both addresses 0x14 and 0x5D. This is handled in host provider's Touch constructor -- not in driver and not in user script. If 0x14 fails, an exception is thrown before it retries at 0x5D. If you encounter this, just hit Go in xsbug. @@ -154,7 +154,7 @@ screen.config({filter}); ### Examples -The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. Many of these examples run on M5Paper. +The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. Many of these examples run on M5Paper. That said, not every example is compatible with M5Paper hardware. For example, some examples are designed to test specific display and touch drivers that are not compatible with the M5Paper display and give a build error. @@ -163,7 +163,7 @@ There are several example applications in the Moddable SDK that show how to take ### Documentation -All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include: +All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include: - The `commodetto` subdirectory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine. - The `piu` subdirectory, which contains resources related to Piu, a user interface framework that makes it easier to create complex, responsive layouts. diff --git a/documentation/devices/moddable-four.md b/documentation/devices/moddable-four.md index 88127a02d1..2847f1fe02 100644 --- a/documentation/devices/moddable-four.md +++ b/documentation/devices/moddable-four.md @@ -41,9 +41,9 @@ It also includes an integrated LIS3DH accelerometer, jog dial, and CR2032 batter
-**Note:** LCD-PWR / GPIO23 is not for use as a general GPIO. It is used to provide power to a sensor and to the screen.
+**Note:** LCD-PWR / GPIO23 is not for use as a general GPIO. It is used to provide power to a sensor and to the screen.
-- Writing `0` to GPIO23 emits 3.3V on LCD-PWR, which also gives power to the screen.
+- Writing `0` to GPIO23 emits 3.3V on LCD-PWR, which also gives power to the screen.
- Writing `1` to GPIO23 turns off the the pin and the screen.
@@ -112,17 +112,17 @@ After you've setup your environment and nRF5 tools, take the following steps to
3. Build and deploy the app with `mcconfig`.
- `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
-
+ `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
+
Use the platform `-p nrf52/moddable_four` with `mcconfig` to build for Moddable Four. Build the [`piu/balls`](../../examples/piu/balls) example:
-
+
```text
cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p nrf52/moddable_four
```
-
+
The [examples readme](../../examples) contains additional information about other commonly used `mcconfig` arguments for screen rotation and more.
-
+
Use the platform -p `sim/moddable_four` with `mcconfig` to build for the Moddable Four simulator.
@@ -167,7 +167,7 @@ new Host.JogDial({
}
});
```
-
+
#### Display Power
To use the Moddable Four display, the LCD power pin must be enabled. In the `moddable_four/setup-target.js` file, the screen is enabled if the `autobacklight` config variable is set:
@@ -230,7 +230,7 @@ There are many energy management APIs available on Moddable Four. These include:
should have a readme.md in that directory which describes the examples
-->
-See the [nRF52 Low Power Notes](./nRF52-low-power.md) for details. Examples of different sleep and wakeup modes can be found in `$MODDABLE/build/devices/nrf52/examples/sleep`.
+See the [nRF52 Low Power Notes](./nRF52-low-power.md) for details. Examples of different sleep and wakeup modes can be found in `$MODDABLE/build/devices/nrf52/examples/sleep`.
## Troubleshooting
@@ -264,7 +264,7 @@ The Moddable Four simulator renders images in 8-bit grayscale, which matches how
### Examples
-The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. Many of these examples run on Moddable Four.
+The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. Many of these examples run on Moddable Four.
Many of the examples that use Commodetto and Piu are designed for colored QVGA screens. While they will run on Moddable Four, the colors will be dithered when rendered and some screens may be cropped. Not every example is compatible with Moddable Four hardware. Some examples are designed to test specific display and touch drivers that are not compatible with the Moddable Four display and give a build error.
@@ -273,7 +273,7 @@ Many of the examples that use Commodetto and Piu are designed for colored QVGA s
Documentation for the nRF5 device and SDK can be found on the [Nordic Semiconductor Infocenter](https://infocenter.nordicsemi.com/topic/struct_nrf52/struct/nrf52840.html). Of particular interest is the documentation for the Nordic nRF5 SDK v17.0.2, which is available [here](https://infocenter.nordicsemi.com/topic/struct_sdk/struct/sdk_nrf5_latest.html).
-Documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
+Documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
- [Using the Moddable SDK with nRF52](./nrf52.md) explains how to get set-up for development, supported devices, and more.
- [nRF52 Low Power Notes](./nRF52-low-power.md) describes the techniques and APIs to maximize battery life by minimizing power consumption.
diff --git a/documentation/devices/moddable-one.md b/documentation/devices/moddable-one.md
index 739053b38a..5ff70106ca 100644
--- a/documentation/devices/moddable-one.md
+++ b/documentation/devices/moddable-one.md
@@ -65,7 +65,7 @@ After you've set up your host environment and ESP8266 tools, take the following
1. Attach the programmer to your Moddable One.
Make sure you have the programmer oriented correctly. The orientation should match the image below.
-
+
**Note**: The USB port on Moddable One may be used to provide power when operating without the programmer. The USB port is only for powering Moddable One. It cannot be used to program Moddable One.
@@ -76,15 +76,15 @@ After you've set up your host environment and ESP8266 tools, take the following
3. Build and deploy the app with `mcconfig`.
- `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
-
+ `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
+
Use the platform `-p esp/moddable_one` with `mcconfig` to build for Moddable One. For example, to build the [`piu/balls` example](../../examples/piu/balls):
-
+
```text
cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p esp/moddable_one
```
-
+
The [examples readme](../../examples) contains additional information about other commonly used `mcconfig` arguments for screen rotation, Wi-Fi configuration, and more.
Use the platform `-p simulator/moddable_one` with `mcconfig` to build for the Moddable One simulator.
@@ -101,14 +101,14 @@ See the Troubleshooting section of the [ESP8266 documentation](./esp8266.md) for
### Examples
-The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. The vast majority of these examples run on Moddable One.
+The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. The vast majority of these examples run on Moddable One.
That said, not every example is compatible with Moddable One hardware. For example, the ESP8266 does not have BLE capabilities so BLE examples do not build or run. Some examples are designed to test specific display and touch drivers that are not compatible with the Moddable One display and give a build error.
### Documentation
-All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
+All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
- The `commodetto` subdirectory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine.
- The `piu` subdirectory, which contains resources related to Piu, a user interface framework that makes it easier to create complex, responsive layouts.
diff --git a/documentation/devices/moddable-three.md b/documentation/devices/moddable-three.md
index df29453926..6c6baff525 100644
--- a/documentation/devices/moddable-three.md
+++ b/documentation/devices/moddable-three.md
@@ -55,15 +55,15 @@ After you've set up your host environment and ESP8266 tools, take the following
3. Build and deploy the app with `mcconfig`.
- `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
-
+ `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
+
Use the platform `-p esp/moddable_three` with `mcconfig` to build for Moddable Three. For example, to build the [`piu/love-e-ink` example](../../examples/piu/love-e-ink):
-
+
```text
cd $MODDABLE/examples/piu/love-e-ink
mcconfig -d -m -p esp/moddable_three
```
-
+
The [examples readme](../../examples) contains additional information about other commonly used `mcconfig` arguments for screen rotation, Wi-Fi configuration, and more.
Use the platform `-p simulator/moddable_three` with `mcconfig` to build for the Moddable Three simulator.
@@ -79,14 +79,14 @@ See the Troubleshooting section of the [ESP8266 documentation](./esp8266.md) for
### Examples
-The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. Most of these examples run on Moddable Three.
+The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. Most of these examples run on Moddable Three.
That said, many of the examples that use Commodetto and Piu are designed for colored screens with a faster refresh rate. In addition, not every example is compatible with Moddable Three hardware. For example, the ESP8266 does not have BLE capabilities so BLE examples do not build or run. Some examples are designed to test specific display and touch drivers that are not compatible with the Moddable Three display and give a build error.
### Documentation
-All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
+All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
- The `commodetto` subdirectory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine.
- The `piu` subdirectory, which contains resources related to Piu, a user interface framework that makes it easier to create complex, responsive layouts.
diff --git a/documentation/devices/moddable-two.md b/documentation/devices/moddable-two.md
index 4c127120fd..5220271b5d 100644
--- a/documentation/devices/moddable-two.md
+++ b/documentation/devices/moddable-two.md
@@ -99,7 +99,7 @@ Power can be supplied to the Moddable Two via the following:
### Dimensions
-The complete dimensions of Moddable Two are provided in this [PDF document](../assets/devices/moddable-two-dimensions.pdf). These are helpful when designing a case for Moddable Two.
+The complete dimensions of Moddable Two are provided in this [PDF document](../assets/devices/moddable-two-dimensions.pdf). These are helpful when designing a case for Moddable Two.
## SDK and Host Environment Setup
@@ -118,7 +118,7 @@ After you've set up your host environment and ESP32 tools, take the following st
1. Attach the programmer to your Moddable Two.
Make sure you have the programmer oriented correctly. The orientation should match the image below.
-
+
**Note**: The USB port on Moddable Two may be used to provide power when operating without the programmer. The USB port is only for powering Moddable Two. It cannot be used to program Moddable Two.
@@ -129,19 +129,19 @@ After you've set up your host environment and ESP32 tools, take the following st
3. Build and deploy the app with `mcconfig`.
- `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
-
+ `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
+
Use the platform `-p esp32/moddable_two` with `mcconfig` to build for Moddable Two. For example, to build the [`piu/balls` example](../../examples/piu/balls):
-
+
```text
cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p esp32/moddable_two
```
-
+
The [examples readme](../../examples) contains additional information about other commonly used `mcconfig` arguments for screen rotation, Wi-Fi configuration, and more.
-
+
Use the platform `-p simulator/moddable_two` with `mcconfig` to build for the Moddable Two simulator.
-
+
## Troubleshooting
@@ -154,14 +154,14 @@ See the Troubleshooting section of the [ESP32 documentation](./esp32.md) for a l
### Examples
-The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. The vast majority of these examples run on Moddable Two.
+The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. The vast majority of these examples run on Moddable Two.
That said, not every example is compatible with Moddable Two hardware. For example, some examples are designed to test specific display and touch drivers that are not compatible with the Moddable Two display and give a build error.
### Documentation
-All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
+All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
- The `commodetto` subdirectory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine.
- The `piu` subdirectory, which contains resources related to Piu, a user interface framework that makes it easier to create complex, responsive layouts.
@@ -170,7 +170,7 @@ All the documentation for the Moddable SDK is in the [documentation](../) direct
### Backlight
-The original Moddable Two has an always-on backlight. The second revision has the ability to adjust the backlight brightness in software. Moddable Two units with backlight brightness control are identified by the small `ESP32 r9` printed on the back of the board to the right of the Moddable logo.
+The original Moddable Two has an always-on backlight. The second revision has the ability to adjust the backlight brightness in software. Moddable Two units with backlight brightness control are identified by the small `ESP32 r9` printed on the back of the board to the right of the Moddable logo.
The backlight control is connected to GPIO 18. There is a constant defined for the backlight GPIO in the host config.
diff --git a/documentation/devices/moddable-zero.md b/documentation/devices/moddable-zero.md
index 521a013dcd..ba4b5266c1 100644
--- a/documentation/devices/moddable-zero.md
+++ b/documentation/devices/moddable-zero.md
@@ -55,15 +55,15 @@ After you've set up your host environment, take the following steps to install a
2. Build and deploy the app with `mcconfig`.
- `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
-
+ `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
+
Use the platform `-p esp/moddable_zero` with `mcconfig` to build for Moddable Zero. For example, to build the [`piu/balls` example](../../examples/piu/balls):
-
+
```
cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p esp/moddable_zero
```
-
+
The [examples readme](../../examples) contains additional information about other commonly used `mcconfig` arguments for screen rotation, Wi-Fi configuration, and more.
@@ -77,14 +77,14 @@ See the Troubleshooting section of the [ESP8266 documentation](./esp8266.md) for
### Examples
-The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. The vast majority of these examples run on Moddable Zero.
+The Moddable SDK has over 150 [example apps](../../examples) that demonstrate how to use its many features. The vast majority of these examples run on Moddable Zero.
That said, not every example is compatible with Moddable Zero hardware. For example, the ESP8266 does not have BLE capabilities so BLE examples do not build or run. Some examples are designed to test specific display and touch drivers that are not compatible with the Moddable Zero display and give a build error.
### Documentation
-All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
+All the documentation for the Moddable SDK is in the [documentation](../) directory. The **documentation**, **examples**, and **modules** directories share a common structure to make it straightforward to locate information. Some of the highlights include:
- The `commodetto` subdirectory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine.
- The `piu` subdirectory, which contains resources related to Piu, a user interface framework that makes it easier to create complex, responsive layouts.
diff --git a/documentation/devices/nRF52-low-power.md b/documentation/devices/nRF52-low-power.md
index 436b147137..39f335a234 100644
--- a/documentation/devices/nRF52-low-power.md
+++ b/documentation/devices/nRF52-low-power.md
@@ -42,7 +42,7 @@ System OFF power mode is deep sleep. The CPU and most peripherals are asleep and
## FreeRTOS and Low Power
Moddable apps run on FreeRTOS on nRF52 devices. To conserve energy, FreeRTOS supports a [Tickless Idle](https://www.freertos.org/low-power-tickless-rtos.html) mode. Tickless idle disables the periodic tick interrupt, allowing the CPU to enter low power mode until a task needs to run or interrupt occurs, at which point the RTOS tick value is adjusted.
-The core of the tickless idle implementation/hook is provided by our `vApplicationSleep()` function. This function enters System ON sleep mode when the application is idle and exits System ON sleep mode when an interrupt occurs or a task needs to run.
+The core of the tickless idle implementation/hook is provided by our `vApplicationSleep()` function. This function enters System ON sleep mode when the application is idle and exits System ON sleep mode when an interrupt occurs or a task needs to run.
The main loop in a Moddable app on nRF52 executes all "ready" timers and then waits on messages until the next timer needs to fire. If no timers are active, the app waits for a maximum delay time. This wait triggers the FreeRTOS scheduler, which in turn calls the tickless idle function and puts the app into System ON sleep mode.
@@ -154,7 +154,7 @@ The `powerMode` setter function sets the System ON low power sub-mode. The `Powe
### Properties
-| Name | Description |
+| Name | Description |
| --- | --- |
| `ConstantLatency` | Constant Latency sub-mode |
| `LowPower` | Low Power sub-mode |
@@ -172,7 +172,7 @@ Sleep.powerMode = PowerMode.LowPower;
#### `setRetainedValue(index, value)`
| Argument | Type | Description |
-| --- | --- | :--- |
+| --- | --- | :--- |
| `index` | `number` | Index of 32-bit memory slot to retain
| `value` | `number` | 32-bit value to retain
@@ -186,7 +186,7 @@ import {Sleep} from "sleep";
// retain values
for (let index = 0; index < 32; ++index)
Sleep.setRetainedValue(index, index + 1);
-
+
// sleep
Sleep.deep();
```
@@ -194,7 +194,7 @@ Sleep.deep();
#### `getRetainedValue(index)`
| Argument | Type | Description |
-| --- | --- | :--- |
+| --- | --- | :--- |
| `index` | `number` | Zero-based index of 32-bit memory slot to retrieve.
The `getRetainedValue` method allows an application to retrieve a 32-bit memory value previously retained across System OFF sleep. The function returns a `number` containing the retained memory value when available. If no memory was retained the function returns the value `0`.
@@ -210,7 +210,7 @@ trace(`Retrieved value ${value} at index ${index}\n`);
#### `setup()`
-The `setup` method is called internally by the nRF52 [power.js](./../../build/devices/nrf52/setup/power.js) [setup module](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/base/setup.md) to initialize low power features at launch. This method restores the system time after waking up from deep sleep, i.e. after a call to `Sleep.deep` when a milliseconds timeout value is provided. The function also powers down unused RAM for applications that specify a RAM configuration.
+The `setup` method is called internally by the nRF52 [power.js](./../../build/devices/nrf52/setup/power.js) [setup module](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/base/setup.md) to initialize low power features at launch. This method restores the system time after waking up from deep sleep, i.e. after a call to `Sleep.deep` when a milliseconds timeout value is provided. The function also powers down unused RAM for applications that specify a RAM configuration.
## Example apps
@@ -223,9 +223,9 @@ Example apps are provided to demonstrate the various `Sleep` class features:
| [retained-values](./../../build/devices/nrf52/examples/sleep/retained-values) | Retain 32 values across System OFF sleep mode and verify the values on reset.
| [wake-on-analog](./../../build/devices/nrf52/examples/sleep/wake-on-analog) | Configure wake-up on analog crossing configurations.
| [wake-on-digital](./../../build/devices/nrf52/examples/sleep/wake-on-digital) | Configure wake-up on a button press.
-| [wake-on-motion](./../../build/devices/nrf52/examples/sleep/wake-on-motion) | Configure wake-up from a connected LIS3DH accelerometer configured to generate interrupts on motion.
-| [wake-on-multiple](./../../build/devices/nrf52/examples/sleep/wake-on-multiple) | Configure wake-up from a combination of analog and digital triggers.
-| [wake-on-timer](./../../build/devices/nrf52/examples/sleep/wake-on-timer) | Configure wake-up after the specified number of milliseconds have passed.
+| [wake-on-motion](./../../build/devices/nrf52/examples/sleep/wake-on-motion) | Configure wake-up from a connected LIS3DH accelerometer configured to generate interrupts on motion.
+| [wake-on-multiple](./../../build/devices/nrf52/examples/sleep/wake-on-multiple) | Configure wake-up from a combination of analog and digital triggers.
+| [wake-on-timer](./../../build/devices/nrf52/examples/sleep/wake-on-timer) | Configure wake-up after the specified number of milliseconds have passed.
## Power Consumption on Moddable Four
diff --git a/documentation/devices/nrf52.md b/documentation/devices/nrf52.md
index a95af47ee3..74110882bf 100644
--- a/documentation/devices/nrf52.md
+++ b/documentation/devices/nrf52.md
@@ -19,7 +19,7 @@ This document is a guide to building apps for the nRF52840 SoC from Nordic using
| [](#mac) | [](#win) | [](#lin) |
| :--- | :--- | :--- |
| • [Installing](#mac-instructions)• [Troubleshooting](#mac-troubleshooting) | • [Installing](#win-instructions)
• [Troubleshooting](#win-troubleshooting) | • [Installing](#lin-instructions)
• [Troubleshooting](#lin-troubleshooting) - + * [Troubleshooting](#troubleshooting) * [Debugging Native Code](#debugging-native-code) * [Bootloader](#bootloader) @@ -73,7 +73,7 @@ nRF52840 has the following features: ## Build Types The nRF52 supports three kinds of builds: debug, instrumented, and release. Each is appropriate for different stages in the product development process. You select which kind of build you want from the command line when running `mcconfig`. - + ### Debug A debug build is used for debugging JavaScript. In a debug build, the device will attempt to connect to xsbug at startup over USB or serial depending on the device configuration. Symbols will be included for native gdb debugging. @@ -124,7 +124,7 @@ The Moddable SDK build for nRF52 currently uses Nordic nRF5 SDK v17.0.2. 6. Moddable Four uses a modified [Adafruit nRF52 Bootloader](https://github.com/Moddable-OpenSource/Adafruit_nRF52_Bootloader) that supports the UF2 file format for flashing firmware to a device. Moddable uses the `uf2conv.py` Python tool from Microsoft that packages the UF2 binary for transfer to the device. Download the [uf2conv](https://github.com/Moddable-OpenSource/tools/releases/download/v1.0.0/uf2conv.py) tool. Move or copy the `uf2conv.py` file into the `nrf5` directory. Use `chmod` to change the access permissions of `uf2conv` to make it executable. - + ```text cd ~/nrf5 chmod 755 uf2conv.py @@ -392,15 +392,15 @@ GDB communicates with the nRF58240 device via a J-Link connection in the nRF5284 ```text arm-none-eabi-gdb $MODDABLE/build/tmp/nrf52/moddable_four/debug/heart-rate-server/xs_nrf52.out -x ~/nrf5/gdb_cmds.txt ``` - + The GDB server connects with the client, downloads the application and stops at the breakpoint `main` specified in the GDB setup command file: ```text Breakpoint 1 at 0x46550: file /Users/
> Note: For best results with a virtual machine, capture the Pico device in both the Boot mode state and running state. The image below shows the configuration in VirtualBox:
-
+
3. Build and deploy the app with `mcconfig`.
- `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
-
+ `mcconfig` is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of `mcconfig` is available [here](../tools/tools.md).
+
Specify the platform `-p pico` with `mcconfig` to build for the Pico. Build the [`helloworld`](../../examples/helloworld) example:
-
+
```text
cd $MODDABLE/examples/helloworld
mcconfig -d -m -p pico
@@ -316,7 +316,7 @@ The app will be built and installed. `xsbug` will be launched and connected to t
## Debugging Native Code
-Refer to the [Getting Started With Pico][picogettingstarteddoc] for
+Refer to the [Getting Started With Pico][picogettingstarteddoc] for
instructions on setting up your hardware.
These instructions have been tested on a macOS host using the two Pico SWD setup described in Appendix A: Using Picoprobe.
@@ -345,7 +345,7 @@ These instructions have been tested on a macOS host using the two Pico SWD setup
(gdb) monitor reset init
(gdb) continue
```
-
+
## Reference Documents
@@ -354,7 +354,7 @@ These instructions have been tested on a macOS host using the two Pico SWD setup
[Hardware Design with RP2040][picohwdoc]
[Raspberry Pi Pico C SDK][picosdkdoc]
-
+
[picogettingstarteddoc]:https://datasheets.raspberrypi.org/pico/getting-started-with-pico.pdf
[picohwdoc]:https://datasheets.raspberrypi.org/rp2040/hardware-design-with-rp2040.pdf
diff --git a/documentation/devices/qca4020/README.md b/documentation/devices/qca4020/README.md
index ecc2133aee..12974f5322 100644
--- a/documentation/devices/qca4020/README.md
+++ b/documentation/devices/qca4020/README.md
@@ -57,7 +57,7 @@ After the initial host setup, there are four major steps to build and deploy a M
3. Flash the application to the board.
-4. Use `gdb` to launch and debug the native portion of your application. Use `xsbug` to debug your ECMAScript application.
+4. Use `gdb` to launch and debug the native portion of your application. Use `xsbug` to debug your ECMAScript application.
## Getting Started
@@ -76,7 +76,7 @@ Decompress the SDK file into a `~/qualcomm` directory making:
```text
/home/J1, J6, J7, J8 Open
R1-R10=0R
R19=0R
R21-R28=0R
R17, R18, R20 not soldered -**Display input voltage** +**Display input voltage** The TFTM028-4 can be configured to be powered by either 5v or 3.3v via a solder jumper. See Table 4.3 in the [datasheet](http://www.buydisplay.com/download/manual/ER-TFTM028-4_Datasheet.pdf). For this guide the display was set to run with 3.3v input. If the display was configured for 5v Pin 2 on the display header would require 5v input. @@ -35,23 +35,23 @@ The [drag](../../examples/piu/drag/) example is good for testing this display. T ``` cd $MODDABLE/examples/piu/drag -mcconfig -d -m -p esp/buydisplay_ctp +mcconfig -d -m -p esp/buydisplay_ctp ``` ## ESP8266 Pinout | BuyDisplay CTP Display | ESP8266 | ESP8266 Devboard label | --- | --- | --- | -| 1 - VSS | GND | -| 2 - VDD | 3.3V | -| 21 - Reset | 3.3V | -| 23 - CS | GPIO 15 | (D8) +| 1 - VSS | GND | +| 2 - VDD | 3.3V | +| 21 - Reset | 3.3V | +| 23 - CS | GPIO 15 | (D8) | 24 - SCK | GPIO 14 | (D5) -| 25 - DC | GPIO 2 | (D4) +| 25 - DC | GPIO 2 | (D4) | 27 - SDI | GPIO 13 | (D7) | 28 - SDO | GPIO 12 | (D6) | 30 - CPT SCL | GPIO 4 | (D2) -| 31 - CPT SDA | GPIO 5 | (D1) +| 31 - CPT SDA | GPIO 5 | (D1)  diff --git a/documentation/displays/wiring-guide-sharp-memory-1.3-spi.md b/documentation/displays/wiring-guide-sharp-memory-1.3-spi.md index 07ccf5841c..e1e76df188 100644 --- a/documentation/displays/wiring-guide-sharp-memory-1.3-spi.md +++ b/documentation/displays/wiring-guide-sharp-memory-1.3-spi.md @@ -22,15 +22,15 @@ The [transitions](../../examples/piu/transitions/) example is good for testing t ``` cd $MODDABLE/examples/piu/transitions -mcconfig -d -m -p esp/sharp_memory_square +mcconfig -d -m -p esp/sharp_memory_square ``` ## ESP8266 Pinout | 1.3" Memory Display | ESP8266 | ESP8266 Devboard label -| --- | --- | --- | -| 3v3 | 3.3V | -| GND | GND | +| --- | --- | --- | +| 3v3 | 3.3V | +| GND | GND | | CLK | GPIO 14 | (D5) | DI | GPIO 13 | (D7) | CS | GPIO 15 | (D8) diff --git a/documentation/displays/wiring-guide-sharp-memory-2.7-spi.md b/documentation/displays/wiring-guide-sharp-memory-2.7-spi.md index c87e70f1cd..b13c922fd8 100644 --- a/documentation/displays/wiring-guide-sharp-memory-2.7-spi.md +++ b/documentation/displays/wiring-guide-sharp-memory-2.7-spi.md @@ -22,21 +22,21 @@ The [balls](../../examples/piu/balls/) example is good for testing this display. ``` cd $MODDABLE/examples/piu/balls -mcconfig -d -m -p esp/sharp_memory +mcconfig -d -m -p esp/sharp_memory ``` ## ESP8266 pinout | Sharp Memory Display | ESP8266 | ESP8266 Devboard label | --- | --- | --- | -| VIN | 3.3V | -| GND | GND | -| EXTMODE | | -| DISP | 3.3V | -| EXTCOMM | | -| SCS | GPIO 4 | (D2) -| SI | GPIO 13 | (D7) -| SCK | GPIO 14 | (D5) +| VIN | 3.3V | +| GND | GND | +| EXTMODE | | +| DISP | 3.3V | +| EXTCOMM | | +| SCS | GPIO 4 | (D2) +| SI | GPIO 13 | (D7) +| SCK | GPIO 14 | (D5)  diff --git a/documentation/displays/wiring-guide-sparkFun-teensyview-spi.md b/documentation/displays/wiring-guide-sparkFun-teensyview-spi.md index 03a398b532..550eeb12b2 100644 --- a/documentation/displays/wiring-guide-sparkFun-teensyview-spi.md +++ b/documentation/displays/wiring-guide-sparkFun-teensyview-spi.md @@ -8,7 +8,7 @@ Revised: October 23, 2018 | | | | :---: | :--- | -| **Part** | Sparkfun - LCD-14048 +| **Part** | Sparkfun - LCD-14048 | **Size** | 128 x 32 | **Type** | OLED, Monochrome |**Interface** | SPI @@ -16,25 +16,25 @@ Revised: October 23, 2018 |**Availability** | [TeensyView on Sparkfun](https://www.sparkfun.com/products/14048) |**Description** | Very small monochrome, OLED display. Moddable uses the TeensyView configured in [standard](https://learn.sparkfun.com/tutorials/teensyview-hookup-guide) mode. -## Moddable example code +## Moddable example code The [balls](../../examples/piu/balls/) example is good for testing this display. To run a debug build, use the following build command: ``` cd $MODDABLE/examples/piu/balls -mcconfig -d -m -p esp/teensyview +mcconfig -d -m -p esp/teensyview ``` ## ESP8266 pinout | TeensyView Display | ESP8266 | ESP8266 Devboard label | --- | --- | --- | -| GND | GND | +| GND | GND | | 5 | GPIO 2 | (D4) | 10 | GPIO 4 | (D2) -| 11 | GPIO 13 | (D7) -| 13 | GPIO 14 | (D5) -| 15 | GPIO 0 | (D3) +| 11 | GPIO 13 | (D7) +| 13 | GPIO 14 | (D5) +| 15 | GPIO 0 | (D3) | 3v | 3.3V |  diff --git a/documentation/displays/wiring-guide-switch-science-LCD.md b/documentation/displays/wiring-guide-switch-science-LCD.md index 8af0fd771e..929b9008c3 100644 --- a/documentation/displays/wiring-guide-switch-science-LCD.md +++ b/documentation/displays/wiring-guide-switch-science-LCD.md @@ -8,7 +8,7 @@ Revised: October 23, 2018 | | | | :---: | :--- | -| **Part** | 2858: JDI - REFLCD - 128 +| **Part** | 2858: JDI - REFLCD - 128 | **Size** | 1.28", 176 × 176 | **Type** | Color reflective LCD (no backlight) | **Interface** | SPI @@ -30,11 +30,11 @@ mcconfig -d -m -p esp/switch_science_reflective_lcd | Switch Science LCD | ESP8266 | ESP8266 Devboard label | --- | --- | --- | | 14 - SCLK | GPIO 14 | (D5) -| 13 - SI | GPIO 13 | (D7) +| 13 - SI | GPIO 13 | (D7) | 15 - SCS | GPIO 15 | (D8) -| DISP | 3.3v | -| GND | GND | -| VIN | 3.3v | +| DISP | 3.3v | +| GND | GND | +| VIN | 3.3v |  diff --git a/documentation/drivers/MCP230XX/MCP230XX.md b/documentation/drivers/MCP230XX/MCP230XX.md index e618e17ee7..ca72e1a489 100644 --- a/documentation/drivers/MCP230XX/MCP230XX.md +++ b/documentation/drivers/MCP230XX/MCP230XX.md @@ -11,15 +11,15 @@ The [MCP23017](http://www.microchip.com/wwwproducts/en/MCP23017) device provides The driver module "MCP230XX" exports the following: ```js -export { - MCP23008, +export { + MCP23008, MCP23017 }; ``` ### MCP23008 Class -The `MCP23008` class produces instances that represent a single MCP23008 IC on the I2C bus. The `MCP23008` class extends an internal `Expander` class, which extends the `SMBus` class. `Expander` is not exported. +The `MCP23008` class produces instances that represent a single MCP23008 IC on the I2C bus. The `MCP23008` class extends an internal `Expander` class, which extends the `SMBus` class. `Expander` is not exported. Instance objects of `MCP23008` contain 8 `Pin` instance object entries. @@ -63,8 +63,8 @@ let leds = new MCP23008({ sda: 4, scl: 5 }); | Parameter | Type | Default Value | Description | --- | --- | --- | :--- | | `address` | `number` | `0x20` | The address of the I2C device | -| `hz` | `number` | 100kHz | The clock speed of the I2C device. | -| `sda` | `number` | 4 | The I2C sda (data) pin. | +| `hz` | `number` | 100kHz | The clock speed of the I2C device. | +| `sda` | `number` | 4 | The I2C sda (data) pin. | | `scl` | `number` | 5 | The I2C scl (clock) pin. | | `inputs` | `number` (byte) | `0b11111111` | A byte representing the input/output initialization state of the 8 GPIO pins. `1` for input, `0` for output | | `pullups` | `number` (byte) | `0b00000000` | A byte representing the pullup initialization state of the 8 GPIO pins. `1` for pullup, `0` for default | @@ -86,7 +86,7 @@ All properties are read-only. ##### `write(byte)` -Temporarily sets the mode of all pins to output and writes all pins at once. +Temporarily sets the mode of all pins to output and writes all pins at once. ```js let expander = new MCP23008(); // defaults to 0x20! @@ -99,7 +99,7 @@ Temporarily sets the mode of all pins to input, reads all pins at once, and retu ```js let expander = new MCP23008(); // defaults to 0x20! -trace(`${expander.read()}\n`); +trace(`${expander.read()}\n`); ``` @@ -157,7 +157,7 @@ let leds = new MCP23017({ sda: 4, scl: 5 }); #### Properties -All properties are read-only. +All properties are read-only. | Name | Type | Value | Description| | --- | --- | --- | :--- | @@ -173,7 +173,7 @@ All properties are read-only. ##### `write(word)` -Temporarily sets the mode of all pins to output and writes all pins at once. +Temporarily sets the mode of all pins to output and writes all pins at once. ```js let expander = new MCP23017(); // defaults to 0x20! @@ -186,7 +186,7 @@ Temporarily sets the mode of all pins to input, reads all pins at once, and retu ```js let expander = new MCP23017(); // defaults to 0x20! -trace(`${expander.read()}\n`); +trace(`${expander.read()}\n`); ``` ### Pin Class @@ -201,7 +201,7 @@ export default function() { const leds = new MCP23008({ inputs: 0b00000000 }); - + // leds[0], leds[1], etc. are Pin instances leds[0].write(1); leds[1].write(0); @@ -237,7 +237,7 @@ export default function() { All properties are read-only. -| Name | Type | Description +| Name | Type | Description | --- | --- | :--- | | `pin` | `number` | The GPIO pin number | | `expander` | `expander` | The instance of `Expander` that this `Pin` belongs to | @@ -250,7 +250,7 @@ All properties are read-only. | --- | --- | :--- | | `mode` | `number` | A number representing the desired mode. May be input, input pullup, or output. -Sets the pin's mode to the specified mode. +Sets the pin's mode to the specified mode. ##### `read()` diff --git a/documentation/drivers/destm32s/destm32s.md b/documentation/drivers/destm32s/destm32s.md index 5263123eeb..1e886bea02 100644 --- a/documentation/drivers/destm32s/destm32s.md +++ b/documentation/drivers/destm32s/destm32s.md @@ -66,11 +66,11 @@ For 104 x 212 black, white, gray, and red: } ### Configuring SPI -The `defines` object must contain the `spi_port`, along with the `DC`, `CS`, and `BUSY`. pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, `rst_port`, or `busy_port` properties are not provided, they default to NULL. +The `defines` object must contain the `spi_port`, along with the `DC`, `CS`, and `BUSY`. pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, `rst_port`, or `busy_port` properties are not provided, they default to NULL. "defines": { "ssd1351": { - /* other properties here */ + /* other properties here */ "cs_pin": 4, "dc_pin": 2, "rst_pin": 0, diff --git a/documentation/drivers/dotstar/dotstar.md b/documentation/drivers/dotstar/dotstar.md index ef34c28d55..609643319d 100644 --- a/documentation/drivers/dotstar/dotstar.md +++ b/documentation/drivers/dotstar/dotstar.md @@ -31,11 +31,11 @@ In the `defines` object, the optional `brightness` property may be set, where 25 } ### Configuring SPI -The `defines` object must contain the `spi_port`. +The `defines` object must contain the `spi_port`. "defines": { "dotstar": { - /* other properties here */ + /* other properties here */ "spi_port": "#HSPI" } } diff --git a/documentation/drivers/ili9341/ili9341.md b/documentation/drivers/ili9341/ili9341.md index 00e5bb9829..26cdfce84f 100644 --- a/documentation/drivers/ili9341/ili9341.md +++ b/documentation/drivers/ili9341/ili9341.md @@ -48,7 +48,7 @@ In the `defines` object, declare the pixel `width` and `height`. } } -The optional `registers` property is used to override the default initialization of registers on the ILI9341. The register property is compiled in C as part of the driver source code, so it has access to the same #define constants as the driver, hence the use of `kDelayMS`, `MODDEF_ILI9341_FLIPY`, and `MODDEF_ILI9341_FLIPX` below. The list of register commands is terminated with pseudo-registers `kDelayMS` with a value of 0. +The optional `registers` property is used to override the default initialization of registers on the ILI9341. The register property is compiled in C as part of the driver source code, so it has access to the same #define constants as the driver, hence the use of `kDelayMS`, `MODDEF_ILI9341_FLIPY`, and `MODDEF_ILI9341_FLIPX` below. The list of register commands is terminated with pseudo-registers `kDelayMS` with a value of 0. "defines": { "ili9341": { @@ -80,11 +80,11 @@ The optional `registers` property is used to override the default initialization } ### Configuring SPI -The `defines` object must contain the `spi_port`, along with the `DC` and `CS` pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, or `rst_port` properties are not provided, they default to NULL. +The `defines` object must contain the `spi_port`, along with the `DC` and `CS` pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, or `rst_port` properties are not provided, they default to NULL. "defines": { "ili9341": { - /* other properties here */ + /* other properties here */ "cs_pin": 4, "dc_pin": 2, "rst_pin": 0, diff --git a/documentation/drivers/lpm013m126a/lpm013m126a.md b/documentation/drivers/lpm013m126a/lpm013m126a.md index 26b8490c34..ff72e6340a 100644 --- a/documentation/drivers/lpm013m126a/lpm013m126a.md +++ b/documentation/drivers/lpm013m126a/lpm013m126a.md @@ -43,11 +43,11 @@ The driver's dithering implementation operates on eight rows of pixels at a time touchCount: 0, pixels: 176 * 8 }); ### Configuring SPI -The `defines` object must contain the `spi_port`, along with the `CS` pin number. If the `cs_port` property is not provided, it defaults to NULL. +The `defines` object must contain the `spi_port`, along with the `CS` pin number. If the `cs_port` property is not provided, it defaults to NULL. "defines": { "lpm013m126a": { - /* other properties here */ + /* other properties here */ "cs_pin": 4, "spi_port": "#HSPI", } diff --git a/documentation/drivers/ls013b4dn04/ls013b4dn04.md b/documentation/drivers/ls013b4dn04/ls013b4dn04.md index fe0af8a854..b41b3ccc68 100644 --- a/documentation/drivers/ls013b4dn04/ls013b4dn04.md +++ b/documentation/drivers/ls013b4dn04/ls013b4dn04.md @@ -35,11 +35,11 @@ In the `defines` object, declare the pixel `width` and `height`. } ### Configuring SPI -The `defines` object must contain the `spi_port`, along with the `CS` pin number. If the `cs_port` property is not provided, it defaults to NULL. +The `defines` object must contain the `spi_port`, along with the `CS` pin number. If the `cs_port` property is not provided, it defaults to NULL. "defines": { "ls013b4dn04": { - /* other properties here */ + /* other properties here */ "cs_pin": 4, "spi_port": "#HSPI", } diff --git a/documentation/drivers/neostrand/neostrand.md b/documentation/drivers/neostrand/neostrand.md index f3bc8ed4dc..b0cc956559 100644 --- a/documentation/drivers/neostrand/neostrand.md +++ b/documentation/drivers/neostrand/neostrand.md @@ -49,7 +49,7 @@ const strand = new NeoStrand({length: 50, pin: 22, order: "RGB", > Note: You may want to tone down your lights during development so you don't blind yourself. -> +> > ```js > strand.brightness(10); > ``` @@ -125,7 +125,7 @@ start | `0` | [0..strand.length] | The index of the first pixel of effect end | `strand.length` | [0..strand.length] | The index of the last pixel of effect size | `strand.length` | [0..strand.length] | The length of one hue cycle, in pixels duration | `1000` | | The duration of one complete cycle of the effect, in ms -reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards +reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards loop | `1` | [0, 1] | Set to 1 to loop the effect `start` and `end` define the span of pixels that this effect will operate on. `duration` is the length of one cycle of the effect. @@ -197,7 +197,7 @@ start | `0` | [0..strand.length] | The index of the first pixel of effect end | `strand.length` | [0..strand.length] | The index of the last pixel of effect size | `strand.length` | [0..strand.length] | The length of one hue cycle, in pixels duration | 1000 | | time of one complete cycle of the pattern, in ms -reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards +reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards loop | `1` | [0, 1] | Set to 1 to loop the effect sizeA | 1 | [1..strand.length] | number of pixels in the A part of pattern sizeB | 3 | [1..strand.length] | number of pixels in the B part of pattern @@ -218,7 +218,7 @@ start | `0` | [0..strand.length] | The index of the first pixel of effect end | `strand.length` | [0..strand.length] | The index of the last pixel of effect size | `strand.length` | [0..strand.length] | The length of one hue cycle, in pixels duration | 1000 | | time of one complete cycle of the color wheel, in ms -reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards +reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards loop | `1` | [0, 1] | Set to 1 to loop the effect speed | 1.0 | | speed multiplier position | 0 | [0..1] | starting HSV hue position @@ -240,7 +240,7 @@ start | `0` | [0..strand.length] | The index of the first pixel of effect end | `strand.length` | [0..strand.length] | The index of the last pixel of effect size | `strand.length` | [0..strand.length] | The length of one hue cycle, in pixels duration | 1000 | | time of one complete sine cycle, in ms -reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards +reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards loop | `1` | [0, 1] | Set to 1 to loop the effect speed | 1.0 | | speed multiplier loop | 1 | [0, 1] | loop the effect @@ -262,7 +262,7 @@ start | `0` | [0..strand.length] | The index of the first pixel of effect end | `strand.length` | [0..strand.length] | The index of the last pixel of effect size | `strand.length` | [0..strand.length] | The length of one hue cycle, in pixels duration | 3000 | | time of one pulse cycle, in ms -reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards +reverse | `0` | [0, 1] | Set to 1 to run the effect in reverse, i.e. run the timeline of the effect backwards loop | `1` | [0, 1] | Set to 1 to loop the effect position | "random" | [-strand.length..strand.length] | index of the pulse starting pixel
negative numbers are off-strand and okay
"random" picks a random starting location mode | 1 | [-1, 0, 1] | **1** to add, **-1** to subtract, or **0** set the pixel color @@ -314,7 +314,7 @@ size | 5 | [0..strand.length] | size of each color max | 127 | [0..255] | maximium value of random RGB component Using *Pattern* as a starting point, we'll change the class name and constructor, set up the timeline in `activate` and provide a setter for the changing `effectValue`. The `loopPrepare` function will be called before a looping effect starts or restarts. - + ```js class RandomColor extends NeoStrandEffect { @@ -356,7 +356,7 @@ manySchemes.push( randomColorScheme ); ## Timing -Timing specifications for the various driver chips of the LEDs are included for reference below. +Timing specifications for the various driver chips of the LEDs are included for reference below. ```js const Timing_WS2812B = { diff --git a/documentation/drivers/ssd1306/ssd1306.md b/documentation/drivers/ssd1306/ssd1306.md index a30e9463cc..6d9b0b7961 100644 --- a/documentation/drivers/ssd1306/ssd1306.md +++ b/documentation/drivers/ssd1306/ssd1306.md @@ -47,11 +47,11 @@ The SSD1306 driver implements optional dithering. Dithering allows an approximat } ### Using SPI -When using a SPI interface, the `defines` object must contain the `spi_port`, along with the `DC` and `CS` pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, or `rst_port` properties are not provided, they default to NULL. +When using a SPI interface, the `defines` object must contain the `spi_port`, along with the `DC` and `CS` pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, or `rst_port` properties are not provided, they default to NULL. "defines": { "ssd1306": { - /* other properties here */ + /* other properties here */ "cs_pin": 4, "dc_pin": 2, "rst_pin": 0, @@ -68,7 +68,7 @@ When using an I2C interface, the `defines` object may contain the I2C address of "defines": { "ssd1306": { - /* other properties here */ + /* other properties here */ "scl_pin": 4, "sda_pin": 5, "address": 0x3c, diff --git a/documentation/drivers/ssd1351/ssd1351.md b/documentation/drivers/ssd1351/ssd1351.md index 837588a870..b9075b1562 100644 --- a/documentation/drivers/ssd1351/ssd1351.md +++ b/documentation/drivers/ssd1351/ssd1351.md @@ -33,7 +33,7 @@ In the `defines` object, declare the pixel `width` and `height`. "height": 128, } } - + The optional `offset_column` and `offset_row` properties offset the `x` and `y` position of the image within the display, which is useful for some configurations. "defines": { @@ -76,11 +76,11 @@ The optional `initialization` property is used to override the default initializ } ### Configuring SPI -The `defines` object must contain the `spi_port`, along with the `DC` and `CS` pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, or `rst_port` properties are not provided, they default to NULL. +The `defines` object must contain the `spi_port`, along with the `DC` and `CS` pin numbers. If a `RST` pin is provided, the device will be reset when the constructor is invoked. If the `cs_port`, `dc_port`, or `rst_port` properties are not provided, they default to NULL. "defines": { "ssd1351": { - /* other properties here */ + /* other properties here */ "cs_pin": 4, "dc_pin": 2, "rst_pin": 0, diff --git a/documentation/files/files.md b/documentation/files/files.md index 21c86e7d31..78d1c38b09 100644 --- a/documentation/files/files.md +++ b/documentation/files/files.md @@ -37,7 +37,7 @@ As a rule, scripts should always prefix full paths with this root. The forward slash character (`/`) is always used as a path separator, even on hosts that natively use a different path separator. -The `System.config()` function, described below, provides the length of the longest supported path through the `maxPathLength` property. +The `System.config()` function, described below, provides the length of the longest supported path through the `maxPathLength` property. ### class File @@ -232,7 +232,7 @@ Directory.delete(config.file.root + "tmp"); - **Source code:** [file](../../modules/files/file) - **Relevant Examples:** [files](../../examples/files/files/) -The File `Iterator` class enumerates the files and subdirectories in a directory. +The File `Iterator` class enumerates the files and subdirectories in a directory. ```js import {Iterator} from "file"; @@ -420,7 +420,7 @@ By default, the FAT32 file system is mounted at `/mod`. To change the default ro #### littlefs The [littlefs](https://github.com/littlefs-project/littlefs) file system is "a little fail-safe filesystem designed for microcontrollers." It provides a high reliability, hierarchical file system in a small code footprint (about 60 KB) using minimal memory (well under 1 KB) with a high degree of configurability. littlefs also supports long file names (up to 255 characters) and formats a new partition very quickly. -The Moddable SDK supports littlefs using the APIs described above. To use littlefs, include its manifest. +The Moddable SDK supports littlefs using the APIs described above. To use littlefs, include its manifest. ```json "includes": { @@ -433,7 +433,7 @@ The Moddable SDK supports littlefs using the APIs described above. To use little The backing store for littlefs varies depending the host platform: - **ESP32** - littlefs uses the "storage" partition to hold the file system. -- **ESP8266** - the file system is stored in the upper 3 MB of flash (the same area used by SPIFFS). +- **ESP8266** - the file system is stored in the upper 3 MB of flash (the same area used by SPIFFS). - **nRF52** - littlefs uses the free space following the firmware image and installed mod. The default size is 64 KB, which may be overridden by `MODDEF_FILE_LFS_PARITION_SIZE` in the manifest `defines`. If there is not enough space, an exception is thrown when accessing the file system. - **Others**, littlefs uses a static memory buffer to hold the file system. The default size is 64 KB, which may be overridden by `MODDEF_FILE_LFS_PARITION_SIZE` in the manifest. This RAM disk mode allows littlefs to be used with the simulator. @@ -637,7 +637,7 @@ The `Preference` class provides storage of persistent preference storage. Prefer ```js import Preference from "preference"; ``` - + Preferences are grouped by domain. A domain contains one or more keys. Each domain/key pair holds a single value, which is either a `Boolean`, integer (e.g. `Number` with no fractional part), `String` or `ArrayBuffer`. ```js @@ -692,13 +692,13 @@ Preference.delete("wifi", "password"); ### `static keys(domain)` Returns an array of all keys under the given domain. - + ```js let wifiKeys = Preference.keys("wifi"); for (let key of wifiKeys) trace(`${key}: ${Preference.get("wifi", key)}\n`); ``` - + *** diff --git a/documentation/io/firmata.md b/documentation/io/firmata.md index 23272e0ca7..14d0cc6eb8 100644 --- a/documentation/io/firmata.md +++ b/documentation/io/firmata.md @@ -7,13 +7,13 @@ The Moddable SDK contains an implementation of the Firmata protocol for communic The primary goal of the implementation is to explore using the new IO class. The Firmata protocol is an interesting test case as it exercises many different kinds of IO. The Firmata protocol has been invaluable in this regard. The resulting Firmata implementation may also be useful more broadly. As the TC53 IO class becomes available on other hardware platforms, this Firmata implementation should run more-or-less as-is there, perhaps providing Firmata support on additional hardware hosts. -> **Note**: The IO Class implementation is available only for the ESP8266 microcontroller which was selected as the initial target because it is representative of resource constrained devices, widely available, well-understood at Moddable, and inexpensive. +> **Note**: The IO Class implementation is available only for the ESP8266 microcontroller which was selected as the initial target because it is representative of resource constrained devices, widely available, well-understood at Moddable, and inexpensive. The Firmata protocol is effectively a client/server protocol with the microcontroller taking the role of the server, and the device controller, often a computer, taking the role of the client. In the Firmata ecosystem, [Firmata.js](https://github.com/firmata/firmata.js#firmatajs) is a popular client, providing a [JavaScript API](https://github.com/firmata/firmata.js/tree/master/packages/firmata.js#firmata-prototype-api) in the Node.js environment to communicate with Firmata servers. There are [many other](https://github.com/firmata/arduino#firmata-client-libraries) Firmata clients available for various languages and environments. There are many fewer implementations of the Firmata server, with the [Standard Firmata Adruino implementation](https://github.com/firmata/arduino#firmata) being the most commonly used. -The implementation of Firmata in the Moddable SDK includes both a client and server. Each is implemented in JavaScript using the proposed TC53 IO class APIs. In the case of the client, it presents Firmata as a TC53 IO class provider. +The implementation of Firmata in the Moddable SDK includes both a client and server. Each is implemented in JavaScript using the proposed TC53 IO class APIs. In the case of the client, it presents Firmata as a TC53 IO class provider. -Implementing both the client and server allowed more uses of the IO class to be explored. The server implementation was developed against the Firmata.js client; the client implementation, against the server. The Firmata.js and Arduino Firmata server code were consulted to supplement the information in the protocol documentation. +Implementing both the client and server allowed more uses of the IO class to be explored. The server implementation was developed against the Firmata.js client; the client implementation, against the server. The Firmata.js and Arduino Firmata server code were consulted to supplement the information in the protocol documentation. > **Note:** To build and run the examples in this document, you must have already installed the Moddable SDK and followed the instructions to set up the build tools for the ESP8266 target from the [Getting Started document](../Moddable%20SDK%20-%20Getting%20Started.md). @@ -55,11 +55,11 @@ To build and run the Firmata server, execute the following commands: cd $MODDABLE/examples/io/firmata/server mcconfig -m -p esp -This builds and deploys the Firmata server to an ESP8266. Note that this a release build, not a debug build. This is because Firmata uses the serial port for communication, which precludes it from being by the xsbug debugger to communicate with the ESP8266. +This builds and deploys the Firmata server to an ESP8266. Note that this a release build, not a debug build. This is because Firmata uses the serial port for communication, which precludes it from being by the xsbug debugger to communicate with the ESP8266. From here, the Firmata.js server may be used as usual with Firmata clients. Note that the Firmata server does not announce itself over serial so it is necessary to wait about five seconds for Firmata.js to issue a probe request before the connection is fully established. -The Firmata server implementation supports the following standard pin types: +The Firmata server implementation supports the following standard pin types: - digital input - digital input pull-up @@ -67,9 +67,9 @@ The Firmata server implementation supports the following standard pin types: - analog input - serial -The pins that are available depend on the configuration. For example, only a single serial port is available in the implementation. If that port is being used for Firmata transport, it is unavailable for use by a Firmata client. +The pins that are available depend on the configuration. For example, only a single serial port is available in the implementation. If that port is being used for Firmata transport, it is unavailable for use by a Firmata client. -The Firmata Server was tested primarily on a [Moddable One](https://www.moddable.com/moddable-one.php), which combines an ESP8266 with a high quality IPS display and capacitive touch screen. +The Firmata Server was tested primarily on a [Moddable One](https://www.moddable.com/moddable-one.php), which combines an ESP8266 with a high quality IPS display and capacitive touch screen. ### Example code @@ -144,7 +144,7 @@ void board.i2cStop(0x38) ### Communicating with the Firmata Server Over TCP -The Firmata server implements communication over a TCP network connection, in addition to serial. The Firmata server can operate in TCP in two different ways. One way is by initiating a TCP connection to a Firmata client, in which case (confusingly) the Firmata server is acting as a TCP client while the Firmata client is acting as a TCP server. This is the more common way. Alternatively, it can listen for an incoming TCP request from a Firmata client, in which case the Firmata server is a TCP server and the Firmata client is a TCP client. +The Firmata server implements communication over a TCP network connection, in addition to serial. The Firmata server can operate in TCP in two different ways. One way is by initiating a TCP connection to a Firmata client, in which case (confusingly) the Firmata server is acting as a TCP client while the Firmata client is acting as a TCP server. This is the more common way. Alternatively, it can listen for an incoming TCP request from a Firmata client, in which case the Firmata server is a TCP server and the Firmata client is a TCP client. #### Using `FirmataTCPClient` To configure the Firmata server to initiate a TCP connection to a Firmata client, do the following: @@ -215,7 +215,7 @@ The I2C bus on Moddable One uses pin 5 for data and pin 4 for a clock. The primary serial connection on ESP8266 uses pin 1 for TX and pin 3 for RX. -The Moddable Firmata Server implementation combines a general purpose Firmata server with specific knowledge of the ESP2866 pin configuration. The ESP8266 knowledge is largely isolated and should eventually migrate to a separate file to ease supporting additional microcontrollers. +The Moddable Firmata Server implementation combines a general purpose Firmata server with specific knowledge of the ESP2866 pin configuration. The ESP8266 knowledge is largely isolated and should eventually migrate to a separate file to ease supporting additional microcontrollers. The Firmata Server implements the optional `STRING_DATA` message with the `doSendString` function which allows the server implementation to send short text strings to the client. These messages have no meaning defined in the protocol. They proved useful for debugging to generate a simple console trace from the server to the client, which is not possible when communicating with Firmata over serial which makes the xsbug debugging connection unavailable. To output these messages to the console using Firmata.js, add this line: @@ -236,7 +236,7 @@ To build and run the Firmata client, execute the following commands: cd $MODDABLE/examples/io/firmata/client mcconfig -d -m -p esp ssid="Moddable" password="secret" -This builds and deploys the Firmata client to an ESP8266. Note that unlike the server, this a debug build, as the examples will only use Firmata over TCP, not serial. +This builds and deploys the Firmata client to an ESP8266. Note that unlike the server, this a debug build, as the examples will only use Firmata over TCP, not serial. The Client API is the proposed TC53 IO provider class. An IO provider is an object that gives access to one or more kinds of IO. The IO it provides access to may be remote, as is the case with the Firmata use described here, or local, for example an GPIO expander connected over I2C. @@ -286,7 +286,7 @@ let led = new firmata.Digital({ pin: 2, mode: firmata.Digital.Output, }); - + let value = 0; System.setInterval(() => { led.write(value); @@ -295,7 +295,7 @@ System.setInterval(() => { ``` #### Monitor Remote Flash Button - + ```js let remoteButton = new firmata.Digital({ pin: 0, @@ -339,7 +339,7 @@ let remoteBank = new firmata.DigitalBank({ ``` #### I2C -I2C is a bit more complicated than Analog and Digital pins as it is a transaction-based hardware protocol: requests are made to the hardware to read and write bytes. The provider is fully asynchronous. This is not a problem for write operations as the Firmata protocol assumes reliable delivery, so the write request will eventually be delivered to the write pins. +I2C is a bit more complicated than Analog and Digital pins as it is a transaction-based hardware protocol: requests are made to the hardware to read and write bytes. The provider is fully asynchronous. This is not a problem for write operations as the Firmata protocol assumes reliable delivery, so the write request will eventually be delivered to the write pins. ```js let i2c = new firmata.I2C({ @@ -452,7 +452,7 @@ Colors are transmitted from client to server using seven bits per channel (R, G, The Firmata Server informs the client that the Poco protocol extension is supported by sending a `STRING_DATA` message with the value `hasPoco` following the response to the `CAPABILITY_QUERY` message. A client which is unaware of the feature will ignore the message. This is a temporary ad-hoc approach. -All Poco messages contained within the Sysex message `User Command 1` to avoid conflicting with any existing or proposed extension to Firmata. +All Poco messages contained within the Sysex message `User Command 1` to avoid conflicting with any existing or proposed extension to Firmata. ## Conclusion diff --git a/documentation/io/io.md b/documentation/io/io.md index a371ddbcb5..d1a9421fad 100644 --- a/documentation/io/io.md +++ b/documentation/io/io.md @@ -1,4 +1,4 @@ -# TC53 IO: A New Take on JavaScript Input/Output on Microcontrollers +# TC53 IO: A New Take on JavaScript Input/Output on Microcontrollers Author: Peter Hoddie
Updated: April 7, 2021
Copyright 2019-2021 Moddable Tech, Inc. @@ -20,7 +20,7 @@ The remainder of this document describes the IO Class Pattern and how it is appl ## The Basic IO Pattern The IO Class Pattern design starts with the idea that the majority of IO operations on a microcontroller are described by four basic operations: -1. **Create** -- Establish and configure a connection to an IO resource. +1. **Create** -- Establish and configure a connection to an IO resource. 1. **Read** -- Get data from the IO resource. 1. **Write** -- Send data to the IO resource. 1. **Close** -- Release the IO resource. @@ -58,7 +58,7 @@ let serial = new Serial({ }) ``` -This way of providing the callback as a property of the configuration is often convenient. The same approach is used by streams in Node.js as described in [Simplified Construction](https://nodejs.org/api/stream.html#stream_simplified_construction). +This way of providing the callback as a property of the configuration is often convenient. The same approach is used by streams in Node.js as described in [Simplified Construction](https://nodejs.org/api/stream.html#stream_simplified_construction). Each IO implementation defines the notifications it supports. The IO Class Pattern proposal defines four notifications: @@ -96,10 +96,10 @@ Scripts that perform read operations may call read at any time. To avoid polling Most kinds of IO have one of the following behaviors for their read operation: -- Return the current value of the IO resource. +- Return the current value of the IO resource. Examples of this include digital inputs and analog inputs. Performing a read operation does not change what will be returned by the next read operation. Only changes to the IO resource itself change the value. The `onReadable` callback is invoked when the value of the IO resource changes. -- Return data from the input buffer. +- Return data from the input buffer. Examples of this include serial and TCP network connections. Once data is read from a serial connection, that data is removed from the input buffer. A subsequent read will receive the next data in the buffer. The `onReadable` callback is invoked when new data is received. @@ -132,10 +132,10 @@ new Serial({ Most kinds of IO have one of the following behaviors for their write operation: -- Change the current value output by the IO resource. +- Change the current value output by the IO resource. A digital output is an example of this behavior. Performing a write operation immediately changes what is output by the IO resource. The `onWritable` callback is not useful for this case, as the value may be changed at any time. -- Add data to the output buffer. +- Add data to the output buffer. Examples of this include serial and TCP network connections. Once data is written from a serial connection, that data is transmitted over a period of time. The `onWritable` callback is invoked when space has been freed in the output buffer. @@ -375,7 +375,7 @@ let pwm = new PWM({ pin: 5, hz: 10000 }); pwm.write(0.5 * ((1 << pwm.resolution) - 1)); ``` -### I2C +### I2C The built-in `I2C` class implements an I2C Master to communicate with one address on an I2C bus. ```js @@ -399,7 +399,7 @@ The data format is always a buffer. The `write` call accepts an `ArrayBuffer` or #### Use Notes Many I2C buses use the higher-level SMB protocol, an extension to the I2C protocol that simplifies its use. The `SMBus` class is a subclass of the `I2C` class that provides support for working with SMBus devices. -The I2C protocol is transaction-based. At the end of each read and write operation, a stop bit is sent. If the stop bit is 1, it indicates the end of the transaction; if 0, it indicates that there are additional operations on the transaction. The `read` and `write` calls set the stop bit to 1 by default. An optional second parameter to the `read` and `write` allows the stop bit to be specified. Pass `false` to set the stop bit to 0, and `true` to set the stop bit to 1. +The I2C protocol is transaction-based. At the end of each read and write operation, a stop bit is sent. If the stop bit is 1, it indicates the end of the transaction; if 0, it indicates that there are additional operations on the transaction. The `read` and `write` calls set the stop bit to 1 by default. An optional second parameter to the `read` and `write` allows the stop bit to be specified. Pass `false` to set the stop bit to 0, and `true` to set the stop bit to 1. #### Example The following example reads the number of touch points from an FT6206 touch sensor, and then retrieves the X and Y coordinates for the active touch points. @@ -437,7 +437,7 @@ import Serial from "embedded:io/serial"; | :---: | :--- | | `baud` | A number specifying the baud rate of the connection. This property is required. -> **Note**: No pins are specified because there is only a single full-duplex hardware serial port on the ESP8266, which is always connected to GPIO pins 1 and 3. +> **Note**: No pins are specified because there is only a single full-duplex hardware serial port on the ESP8266, which is always connected to GPIO pins 1 and 3. #### Callbacks @@ -487,7 +487,7 @@ The following example continuously outputs text to the serial output. It uses th const message = ArrayBuffer.fromString("Since publication of the first edition in 1997, ECMAScript has grown to be one of the world's most widely used general-purpose programming languages. It is best known as the language embedded in web browsers but has also been widely adopted for server and embedded applications.\r\n"); let offset = 0; - + const serial = new Serial({ baud: 921600, onWritable: function(count) { @@ -505,7 +505,7 @@ serial.format = "buffer"; ``` ### TCP Socket -The built-in `TCP` network socket class implements a general purpose, bi-directional TCP connection. +The built-in `TCP` network socket class implements a general purpose, bi-directional TCP connection. ```js import TCP from "embedded:io/socket/tcp"; @@ -623,14 +623,14 @@ class TCPEcho { } onReadable() { const response = this.read(); - + this.write(ArrayBuffer.fromString("HTTP/1.1 200 OK\r\n")); this.write(ArrayBuffer.fromString("connection: close\r\n")); this.write(ArrayBuffer.fromString("content-type: text/plain\r\n")); this.write(ArrayBuffer.fromString(`content-length: ${response.byteLength}\r\n`)); this.write(ArrayBuffer.fromString("\r\n")); this.write(response); - + this.close(); } } @@ -648,7 +648,7 @@ new Listener({ ``` ### UDP Socket -The built-in `UDP` network socket class implements the sending and receiving of UDP packets. +The built-in `UDP` network socket class implements the sending and receiving of UDP packets. ```js import UDP from "embedded:io/socket/udp"; @@ -669,7 +669,7 @@ Invoked when one or more packets are received. The callback receives a single ar The data format is always `buffer`. The `write` call accepts an `ArrayBuffer` or a `TypedArray`. The `read` call always returns an `ArrayBuffer`. #### Use Notes -The `read` call returns a complete UDP packet as an `ArrayBuffer`. Partial reads are not supported. The returned packet data has two properties attached to it: +The `read` call returns a complete UDP packet as an `ArrayBuffer`. Partial reads are not supported. The returned packet data has two properties attached to it: - `address`, a string containing the packet sender's address - `port`, the port number used to send the packet. @@ -726,7 +726,7 @@ Putting the ESP8266 into deep sleep is out of scope for IO. The `System.deepSlee **`onReadable()`** -Invoked following instantiation if the device was woken from deep sleep. +Invoked following instantiation if the device was woken from deep sleep. #### Data Format The Wakeable Digital IO always uses a data format of `number`. A value of 0 indicates the device did not wake from a deep sleep and a value of 1 indicates that it did wake from a deep sleep. @@ -748,16 +748,16 @@ trace(wakeable.read() ? "Woke from deep sleep\n" : "Hard reset\n"); ## IO Providers IO providers access IO resources that are external to the built-in IO resources. IO providers often use the built-in IO resources to access their external IO resources. The definition of "external" encompasses a wide range of possibilities. -- A separate component on the same board as the microcontroller. +- A separate component on the same board as the microcontroller. Examples of this include GPIO and Analog expanders. These operate over shared-bus protocols like I2C and SPI to provide additional IO pins. -- A separate board physically connected to the board holding the microcontroller. +- A separate board physically connected to the board holding the microcontroller. An example of this is an Arduino connected to a microcontroller over a serial connection as used by the Firmata protocol. -- A separate physical device in close proximity. +- A separate physical device in close proximity. Examples of this include peripherals connected by Bluetooth LE and Decentralized Ambient Synchronization ([DAS](https://blog.moddable.com/blog/das/)) using mDNS over a UDP network connection. -- A separate physical device at a physically remote location. +- A separate physical device at a physically remote location. Examples of this include the Firmata protocol running over a TCP connection and many IoT cloud services operating over protocols including HTTP/REST, MQTT, and WebSocket. @@ -823,7 +823,7 @@ const expander = new Expander({ }); ``` -With the interrupt configured, the `onReadable` callback may be used. +With the interrupt configured, the `onReadable` callback may be used. ```js let buttons = new expander.DigitalBank({ @@ -833,7 +833,7 @@ let buttons = new expander.DigitalBank({ mode: expander.Digital.Input, onReadable(pins) { const result = this.read(); - trace(`Pins ${pins.toString(2)} changed. Buttons now ${result.toString(2)}.`); + trace(`Pins ${pins.toString(2)} changed. Buttons now ${result.toString(2)}.`); } }); ``` @@ -863,7 +863,7 @@ let provider = new CloudProvider({ Note that the MCP23017 expander does not implement the `onReady` callback as it supports a separate component on the same board as the microcontroller accessing it, so there are no significant latencies. -#### Asynchronous I2C +#### Asynchronous I2C All of the IO kinds defined earlier in this document implement asynchronous IO by following the IO Class Pattern directly. It is less obvious how to implement an I2C Master. An implementation of the Firmata Client through the IO Provider API provided a motivation to explore the problem and to find a solution. I2C performs read and write operations with buffers of bytes, much like serial and TCP IO. Serial and TCP (once the connection is established) are essentially peer protocols -- either side of the connection may initiate a write operation at any time. I2C , by contrast, is a master/slave protocol. The slave may only send bytes for the master to read when requested to do so. That requires the master to issue a read request to the slave device to receive data. @@ -898,6 +898,6 @@ From the API perspective, the IO Class Pattern provides clear guidance to the de Perhaps the most interesting perspective is as a script writer using IO classes that follow the pattern. The small API size is easy to remember. This makes it quick and comfortable to work with a range of IO. There are, of course, details that differ from one IO type to another. A digital input is quite different from a UDP socket. Still, these differences are consistent with needs of the IO, not arbitrary differences because their APIs happened to be designed by different individuals at different times with different priorities or different programming style preferences. Overall, this makes it relatively easy to both read and write code that applies the IO Class Pattern. -Based on this exercise of building an implementation of the IO Class Pattern for a microcontroller, the design achieves its goals well. The API meets the needs of low-level script developers to access IO, it is possible to implement efficiently on resource-constrained embedded hardware, and the implementation/porting effort is focused and manageable. +Based on this exercise of building an implementation of the IO Class Pattern for a microcontroller, the design achieves its goals well. The API meets the needs of low-level script developers to access IO, it is possible to implement efficiently on resource-constrained embedded hardware, and the implementation/porting effort is focused and manageable. There is a great deal of work remaining to fully explore the IO Class Pattern. More will be learned from future work, and those lessons will lead to refinements in the design. Areas for future work include ports to other microcontrollers, support for other runtime environments beyond the Moddable SDK, and implementations of other kinds of IO and providers. diff --git a/documentation/network/ble/ble.md b/documentation/network/ble/ble.md index c5676a4d9c..115a210a78 100644 --- a/documentation/network/ble/ble.md +++ b/documentation/network/ble/ble.md @@ -41,7 +41,7 @@ To add the BLE client to a project: /* other includes here */ "$(MODDABLE)/modules/network/ble/manifest_client.json", ], - + To add the BLE server to a project: "include": [ @@ -68,7 +68,7 @@ class Scanner extends BLEClient { trace(completeName + "\n"); } } - + let scanner = new Scanner; ``` @@ -77,7 +77,7 @@ The following BLE server example subclasses `BLEServer` to advertise the device ```javascript import BLEServer from "bleserver"; import {uuid} from "btutils"; - + class HealthThermometerService extends BLEServer { onReady() { this.startAdvertising({ @@ -85,7 +85,7 @@ class HealthThermometerService extends BLEServer { }); } } - + let htm = new HealthThermometerService; ``` @@ -176,7 +176,7 @@ let client = new BLEClient; #### `startScanning([params])` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Object containing scan properties. The `params` object contains the following properties: @@ -186,8 +186,8 @@ The `params` object contains the following properties: | `active` | `boolean` | Set `true` for active scanning, `false` for passive scanning. Default is `true`. | `duplicates` | `boolean` | Set `true` to receive all advertising packets, `false` to filter out multiple advertising packets received from the same peripheral device. Default is `true`. | `filterPolicy` | `number` | Filter policy applied to scan. Default is `GAP.ScanFilterPolicy.NONE` (no filtering). Refer to the [BLE whitelisting](#blewhitelisting) section for details. -| `interval` | `number` | Scan interval value in units of 0.625 ms. Default is `0x50`. -| `window` | `number` | Scan window value in units of 0.625 ms. Default is `0x30`. +| `interval` | `number` | Scan interval value in units of 0.625 ms. Default is `0x50`. +| `window` | `number` | Scan window value in units of 0.625 ms. Default is `0x30`. The `filterPolicy` parameter can be one of the following: @@ -230,10 +230,10 @@ class Scanner extends BLEClient { #### `onDiscovered(device)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | -The `onDiscovered` callback function is called one or more times for each peripheral device discovered. +The `onDiscovered` callback function is called one or more times for each peripheral device discovered. To connect to a device named "Brian" from the `onDiscovered` callback: @@ -246,7 +246,7 @@ onDiscovered(device) { ``` *** - + #### `stopScanning()` The `stopScanning` function disables scanning for nearby peripherals. @@ -255,7 +255,7 @@ The `stopScanning` function disables scanning for nearby peripherals. #### `connect(device)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | The `connect` function initiates a connection request between the `BLEClient` and a target peripheral `device`. @@ -274,7 +274,7 @@ onConnected(device) { #### `onConnected(device)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | The `onConnected` callback function is called when the client connects to a target peripheral `device`. @@ -284,7 +284,7 @@ The `onConnected` callback function is called when the client connects to a targ #### `onDisconnected(device)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | The `onDisconnected` callback is called when the connection is closed. @@ -340,12 +340,12 @@ An instance of the `Client` class is instantiated by `BLEClient` and provided to | `scanResponse` | `object` | Instance of [Advertisement](#classadvertisement) class containing advertisement and scan response packet values. | `rssi` | `number` | Discovered device signal strength. -### Functions +### Functions #### `exchangeMTU(mtu)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `mtu` | `number` | Requested MTU value | Use the `exchangeMTU ` function to request a higher MTU once the peripheral connection has been established. @@ -354,7 +354,7 @@ Use the `exchangeMTU ` function to request a higher MTU once the peripheral conn #### `onMTUExchanged(device, mtu)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | | `mtu` | `number` | Exchanged MTU value | @@ -382,7 +382,7 @@ Use the `readRSSI` function to read the connected peripheral's signal strength. #### `onRSSI(device, rssi)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | | `rssi` | `number` | Received signal strength | @@ -409,7 +409,7 @@ Use the `discoverAllPrimaryServices` function to discover all the peripheral's G #### `discoverPrimaryService(uuid)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `uuid` | `object` | A [Bytes](#classbytes) object containing the UUID to discover | Use the `discoverPrimaryService` function to discover a single GATT primary service by UUID. @@ -418,7 +418,7 @@ Use the `discoverPrimaryService` function to discover a single GATT primary serv #### `findServiceByUUID(uuid)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `uuid` | `object` | A [Bytes](#classbytes) object containing the Service UUID to find | The `findServiceByUUID` function finds and returns the service identified by `uuid`. This function searches the `services` property array. @@ -428,7 +428,7 @@ The `findServiceByUUID` function finds and returns the service identified by `uu #### `onServices(services)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `services` | `array` | An array of `service` objects, or an empty array if no services are discovered. See the section [Class Service](#classservice) for more information. | The `onServices` callback function is called when service discovery completes. If `findServiceByUUID` was called to find a single service, the `services` array contains the single service found. @@ -444,7 +444,7 @@ onServices(services) { } ``` -To discover a single primary service: +To discover a single primary service: ```javascript const SERVICE_UUID = uuid`0xFF00`; @@ -476,7 +476,7 @@ onDisconnected() { ## Class Service -The `Service` class provides access to a single peripheral GATT service. +The `Service` class provides access to a single peripheral GATT service. ### Properties @@ -498,7 +498,7 @@ Use the `discoverAllCharacteristics()` function to discover all the service char #### `discoverCharacteristic(uuid)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `uuid` | `object` | A [Bytes](#classbytes) object containing the Characteristic UUID to discover | Use the `discoverCharacteristic` function to discover a single service characteristic by UUID. @@ -508,7 +508,7 @@ Use the `discoverCharacteristic` function to discover a single service character #### `findCharacteristicByUUID(uuid)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `uuid` | `object` | A [Bytes](#classbytes) object containing the Characteristic UUID to find | The `findCharacteristicByUUID` function finds and returns the characteristic identified by `uuid`. This function searches the `characteristics` property array. @@ -518,7 +518,7 @@ The `findCharacteristicByUUID` function finds and returns the characteristic ide #### `onCharacteristics(characteristics)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristics` | `array` | An array of `characteristic` objects, or an empty array if no characteristics are discovered. See the section [Class Characteristic](#classcharacteristic) for more information. | The `onCharacteristics` callback function is called when characteristic discovery completes. If `findCharacteristicByUUID` was called to find a single characteristic, the `characteristics` array contains the single characteristic found. @@ -587,7 +587,7 @@ Use the `discoverAllDescriptors` function to discover all the characteristic's d #### `onDescriptors(descriptors)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `descriptors` | `array` | An array of `descriptor` objects, or an empty array if no descriptors are discovered. See the section [Class Descriptor](#classdescriptor) for more information. | The `onDescriptors` callback function is called when descriptor discovery completes. @@ -620,7 +620,7 @@ Use the `enableNotifications` function to enable characteristic value change not #### `onCharacteristicNotificationEnabled(characteristic)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | A `characteristic` object. | The `onCharacteristicNotificationEnabled` callback function is called when notifications have been enabled for the `characteristic`. @@ -635,7 +635,7 @@ Use the `disableNotifications` function to disable characteristic value change n #### `onCharacteristicNotificationDisabled(characteristic)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | A `characteristic` object. | The `onCharacteristicNotificationDisabled` callback function is called when notifications have been disabled for the `characteristic`. @@ -645,7 +645,7 @@ The `onCharacteristicNotificationDisabled` callback function is called when noti #### `onCharacteristicNotification(characteristic, value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | A `characteristic` object. | | `value` | `varies` | The `characteristic` value. The value is automatically converted to the `type` defined in the service JSON, when available. Otherwise `value` is an `ArrayBuffer`. | @@ -680,7 +680,7 @@ onCharacteristicNotification(characteristic, value) { Use the `readValue` function to read a characteristic value on demand. | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `auth` | `number` | Optional `SM.Authorization` applied to the read request. | The `Authorization` object contains the following properties: @@ -698,7 +698,7 @@ The `Authorization` object contains the following properties: #### `onCharacteristicValue(characteristic, value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | A `characteristic` object. | | `value` | `varies` | The `characteristic` value read. The value `type` is defined by the service JSON, when available. Otherwise `value` is an `ArrayBuffer`. | @@ -732,7 +732,7 @@ onCharacteristicValue(characteristic, value) { #### `writeWithoutResponse(value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `value` | `varies` | The `characteristic` value to write. The value `type` is defined by the service JSON, when available. Otherwise `value` is an `ArrayBuffer` or `String`. | Use the `writeWithoutResponse` function to write a characteristic value on demand. @@ -779,7 +779,7 @@ The `Descriptor` class provides access to a single characteristic descriptor. Use the `readValue` function to read a descriptor value on demand. | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `auth` | `number` | Optional `SM.Authorization` applied to the read request. | The `Authorization` object contains the following properties: @@ -797,7 +797,7 @@ The `Authorization` object contains the following properties: #### `onDescriptorValue(descriptor, value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `descriptor ` | `object` | A `descriptor` object. | | `value` | `varies` | The `descriptor` value read. The value `type` is defined by the service JSON, when available. Otherwise `value` is an `ArrayBuffer`. | @@ -822,7 +822,7 @@ onDescriptorValue(descriptor, value) { #### `writeValue(value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `value` | `varies` | The `descriptor` value to write. The value `type` is defined by the service JSON, when available. Otherwise `value` is an `ArrayBuffer` or `String`. | Use the `writeValue` function to write a descriptor value. @@ -840,7 +840,7 @@ onDescriptors(descriptors) { } } ``` - + > **Note:** The `Characteristic` `enableNotifications` convenience function is typically used for this purpose, though writing the CCCD descriptor directly provides the same net result. @@ -866,11 +866,11 @@ The `Advertisement` class provides accessor functions to read common advertiseme Use the `findIndex` function to find the index of a specific advertisement data type in the raw advertisement data bytes. | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `type` | `number` | The `GAP.ADType` to search for. | | `index` | `number` | The optional starting index to search from. Defaults to 0. | -### Examples +### Examples To identify an advertised device with the complete name "Zip": @@ -888,8 +888,8 @@ To identify a [Blue Maestro Environment Monitor](https://www.bluemaestro.com/pro ```javascript onDiscovered(device) { let manufacturerSpecific = device.scanResponse.manufacturerSpecific; - const TempoManufacturerID = 307; - + const TempoManufacturerID = 307; + // If this is a Tempo device... if (manufacturerSpecific && (TempoManufacturerID == manufacturerSpecific.identifier)) { let data = manufacturerSpecific.data; @@ -919,13 +919,13 @@ onDiscovered(device) { ## Class Bytes The private `Bytes` class extends `ArrayBuffer`. Applications typically use the provided `uuid` and `address` tagged templates to create a `Bytes` instance from hex strings. - + #### Constructor Description #### `Bytes(bytes [,littleEndian])` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `bytes` | `object` or `string` | The ArrayBuffer `bytes` to set. The bytes can be a String or ArrayBuffer. | | `littleEndian` | `boolean` | When set `true` the contents of the ArrayBuffer are stored in reverse order. Default is `false`.| ### Functions @@ -954,11 +954,11 @@ const CHARACTERISTIC_RX_UUID = uuid`6E400002-B5A3-F393-E0A9-E50E24DCCA9E`; #### `equals(buffer)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `buffer` | `object` | The `Bytes` instance to compare. | The `equals` function returns `true` if the instance ArrayBuffer data equals the data contained in `buffer`. - + ```javascript import {uuid} from "btutils"; @@ -1207,7 +1207,7 @@ import {address} from "btutils"; this.startAdvertising({ connectable: false, advertisingData: {flags: 5, completeName: "Moddable HRS"}, - scanResponseData: {shortName: "Moddable", randomAddress: address`00:11:22:33:44:55`} + scanResponseData: {shortName: "Moddable", randomAddress: address`00:11:22:33:44:55`} }); ``` @@ -1245,7 +1245,7 @@ onConnected(device) { #### `notifyValue(characteristic, value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | The `characteristic` object to notify. | | `value` | `varies` | The `characteristic` notification value. The value is automatically converted from the `type` defined in the service JSON. | @@ -1271,21 +1271,21 @@ startNotifications(characteristic) { The `onAdvertisementSent` callback function is called after each advertising data packet sent, when a server enables advertisement notifications from the `startAdvertising()` function. > Note: The `onAdvertisementSent` callback is only implemented for nRF52 devices. - + *** #### `onCharacteristicNotifyEnabled(characteristic)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | The `characteristic` object with notifications enabled. The `onCharacteristicNotifyEnabled` callback function is called when a client enables notifications on the `characteristic`. - + *** #### `onCharacteristicWritten(characteristic, value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic` | `object` | The `characteristic` object written. | `value` | `varies` | The value written. The value is automatically converted to the `type` defined in the service JSON. @@ -1321,7 +1321,7 @@ onCharacteristicWritten(characteristic, value) { #### `onCharacteristicRead(characteristic)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `characteristic ` | `object` | The characteristic object being read. The `characteristic` object contains the following properties: @@ -1349,7 +1349,7 @@ onCharacteristicRead(characteristic) { *** #### `disconnect()` -Use the `disconnect` function to terminate the BLE client connection. +Use the `disconnect` function to terminate the BLE client connection. ```javascript import {address} from "btutils"; @@ -1371,7 +1371,7 @@ onDisconnected(device) { #### `onConnected(device)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | The `onConnected` callback function is called when a client connects to the `BLEServer`. @@ -1380,7 +1380,7 @@ The `onConnected` callback function is called when a client connects to the `BLE #### `onDisconnected(device)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `device` | `object` | A `device` object. See the section [Class Client](#classclient) for more information. | The `onDisconnected` callback function is called when the client connection is closed. @@ -1438,7 +1438,7 @@ The following is an example of JSON corresponding to a Bluetooth [Battery Servic } } } - + The service is defined as follows: * The service UUID is 0x180F @@ -1483,7 +1483,7 @@ onReady() { #### `deleteBonding(address, addressType)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `address` | `object` | `ArrayBuffer` containing peer device Bluetooth address | `addressType` | `number` | Peer device Bluetooth address type. Refer to `GAP.AddressType` for supported address types. @@ -1517,7 +1517,7 @@ onReady() { #### `passkeyInput(address, value)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `address` | `object` | `ArrayBuffer` containing peer device Bluetooth address | `value` | `number` | passkey value input @@ -1535,7 +1535,7 @@ onPasskeyInput(params) { #### `passkeyReply(address, result)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `address` | `object` | `ArrayBuffer` containing peer device Bluetooth address | `result` | `boolean` | Set `true` to confirm passkey value, `false` otherwise @@ -1553,7 +1553,7 @@ onPasskeyConfirm(params) { #### `onSecurityParameters(params)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Device security properties applied. The `onSecurityParameters` callback is called after the device security requirements and I/O capabilities have been set. @@ -1574,7 +1574,7 @@ onSecurityParameters() { #### `onAuthenticated(params)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Properties associated with the authentication procedure. The `params` object contains the following properties: @@ -1597,7 +1597,7 @@ onAuthenticated(params) { #### `onPasskeyConfirm(params)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Properties associated with the passkey confirmation. The `params` object contains the following properties: @@ -1612,7 +1612,7 @@ The `onPasskeyConfirm` callback is called when the user needs to confirm a passk ```javascript onPasskeyConfirm(params) { trace(`confirm passkey: ${params.passkey}\n`); - + // passkey is valid this.passkeyReply(params.address, true); } @@ -1622,7 +1622,7 @@ onPasskeyConfirm(params) { #### `onPasskeyDisplay(params)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Properties associated with the passkey display. The `params` object contains the following properties: @@ -1646,7 +1646,7 @@ onPasskeyDisplay(params) { #### `onPasskeyInput(params)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Properties associated with the passkey input. The `params` object contains the following properties: @@ -1670,7 +1670,7 @@ onPasskeyInput(params) { #### `onPasskeyRequested(params)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `params` | `object` | Properties associated with the passkey to request. The `params` object contains the following properties: @@ -1713,7 +1713,7 @@ import GAPWhitelist from "gapwhitelist"; #### `add(address [,addressType])` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `address` | `string` or `object` | The peer address to whitelist. | `addressType` | `number` | Optional peer address type. Defaults to `GAP.AddressType.PUBLIC`. @@ -1750,7 +1750,7 @@ onDisconnected() { #### `remove(address [,addressType])` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `address` | `string` or `object` | The peer address to whitelist. | `addressType` | `number` | Optional peer address type. Defaults to `GAP.AddressType.PUBLIC`. @@ -1790,9 +1790,9 @@ After building the BLE archive, the archive is linked to the native app hosted i initMcu(); initBoard(); initApp(); - + xs_setup(); - + while (1) { xs_loop(); } @@ -1802,7 +1802,7 @@ BLE apps require additional stack and heap. We've been able to run the Moddable __STACK_SIZE=0x2000 __HEAP_SIZE=0xA000 - + Simplicity Studio includes a **BLE GATT Configurator** to define BLE services. Moddable apps define BLE services in JSON files and hence don't use the `gatt_db.c` and `gatt_db.h` files generated by the configurator tool. These two files must be removed from the Simplicity Studio project. @@ -1840,5 +1840,5 @@ The Moddable SDK includes many BLE client and server example apps to build from. | [heart-rate-server](../../../examples/network/ble/heart-rate-server) | Implements the Bluetooth [Heart Rate Service](https://www.bluetooth.com/wp-content/uploads/Sitecore-Media-Library/Gatt/Xml/Services/org.bluetooth.service.heart_rate.xml). | [security-server](../../../examples/network/ble/security-server) | Demonstrates how to implement a secure health thermometer BLE server using SMP. The `security-server` can connect to the [security-client](../../../examples/network/ble/security-client) app. | [uri-beacon](../../../examples/network/ble/uri-beacon) | Implements a [UriBeacon](https://github.com/google/uribeacon/tree/uribeacon-final/specification) compatible with Google's [Physical Web](https://github.com/google/physical-web) discovery service. -| [wifi-connection-server](../../../examples/network/ble/wifi-connection-server) | Deploys a BLE WiFi connection service on ESP32. The connection service allows BLE clients to connect the BLE device to a WiFi access point, by writing the SSID and password characteristics. +| [wifi-connection-server](../../../examples/network/ble/wifi-connection-server) | Deploys a BLE WiFi connection service on ESP32. The connection service allows BLE clients to connect the BLE device to a WiFi access point, by writing the SSID and password characteristics. | [uart-server](../../../examples/network/ble/uart-server) | Shows how implement a Nordic UART Service server. The `uart-server` can connect to the [uart-client](../../../examples/network/ble/uart-client) app. diff --git a/documentation/network/ethernet.md b/documentation/network/ethernet.md index e2f0f39096..2f5a5dfa74 100644 --- a/documentation/network/ethernet.md +++ b/documentation/network/ethernet.md @@ -6,7 +6,7 @@ Revised: November 16, 2021 The Moddable SDK supports Ethernet for the ESP32. Ethernet support is an extension to our [network support](./network.md), which includes support for Wi-Fi and protocols like HTTP/HTTPS, MQTT, WebSockets, DNS, and mDNS. Most of the [networking examples](../../examples/network) in the Moddable SDK enable Wi-Fi by default, but examples that work with Wi-Fi can easily be made to use Ethernet instead. -This document provides information about how to enable Ethernet in applications, details of the JavaScript API used to establish and monitor an Ethernet connection, and wiring instructions for a compatible Ethernet breakout board. +This document provides information about how to enable Ethernet in applications, details of the JavaScript API used to establish and monitor an Ethernet connection, and wiring instructions for a compatible Ethernet breakout board. ## Table of Contents @@ -124,7 +124,7 @@ let monitor = new Ethernet((msg) => { // Got IP address break; } -}); +}); ``` ### `close()` @@ -134,7 +134,7 @@ The `close` method closes the connection between the `Ethernet` instance and the ```js let monitor = new Ethernet((msg) => { trace(`Ethernet msg: ${msg}\n`); -}); +}); monitor.close(); ``` @@ -152,7 +152,7 @@ let monitor = new Ethernet((msg) => { case Ethernet.connected: trace(`Physical link established. Waiting for IP address.\n`); break; - + case Ethernet.gotIP: let ip = Net.get("IP", "ethernet"); trace(`Ethernet connected. IP address ${ip}\n`); @@ -162,7 +162,7 @@ let monitor = new Ethernet((msg) => { trace(`Ethernet connection lost.\n`); break; } -}); +}); ``` ### Example: Get MAC address of Ethernet device diff --git a/documentation/network/network.md b/documentation/network/network.md index f87280a217..e0e14660a9 100644 --- a/documentation/network/network.md +++ b/documentation/network/network.md @@ -9,7 +9,7 @@ Revised: March 8, 2022 * HTTP * [Request](#http-request) * [Server](#http-server) -* WebSocket +* WebSocket * [Client](#websocket-client) * [Server](#websocket-server) * [Net](#net) @@ -186,7 +186,7 @@ For a RAW socket, the first parameter is IP address to transmit the packet to. T socket.write("1.2.3.4", packet); ``` -It is more efficient to make a single `write` call with several parameters instead of multiple calls to `write`. +It is more efficient to make a single `write` call with several parameters instead of multiple calls to `write`. *** @@ -390,7 +390,7 @@ The user of the `Request` object receives status information through the callbac | `message` | `Request.` | Description | | :---: | :---: | :--- | -|-2 | `error` | +|-2 | `error` | | 0 | `requestFragment` | Get request body fragment. This callback is only received if the `body` property in the dictionary is set to `true`. When called, `val1` is the maximum number of bytes that can be transmitted. Return either a `String` or `ArrayBuffer` containing the next fragment of the request body. Return `undefined` when there are no more fragments. | 1 | `status` | Response status received with status code. This callback is invoked when the HTTP response status line is successfully received. When called, `val1` is the HTTP status code (e.g. 200 for OK). | 2 | `header` | One header received. The callback is called for each header in the response. When called, `val1` is the header name in lowercase letters (e.g. `connection`) and `val2` is the header value (e.g. `close`). @@ -414,7 +414,7 @@ import {Server} from "http" ### `constructor(dictionary)` -A new HTTP server is configured using a dictionary of properties. The dictionary is a super-set of the `Socket` dictionary. +A new HTTP server is configured using a dictionary of properties. The dictionary is a super-set of the `Socket` dictionary. To open an HTTP server, on the default port (80): @@ -503,7 +503,7 @@ The following example implements an HTTP server that responds to requests with a switch (message) { case 8: // prepare response body return {headers: ["Content-type", "text/plain"], body: true}; - + case 9: // provide response body fragment let i = Math.round(Math.random() * 20); if (0 == i) @@ -560,7 +560,7 @@ import {File} from "file"; case 4: // prepare for request body return true; // provide request body in fragments - + case 5: // request body fragment this.file.write(this.read(ArrayBuffer)); break; @@ -696,7 +696,7 @@ ws.close(); ### `attach(socket)` -The `attach` function creates a new incoming WebSockets connection from the provided socket. The server issues the `Server.connect` callback and then performs the WebSockets handshake. The status line has been read from the socket, but none of the HTTP headers have been read as these are required to complete the handshake. +The `attach` function creates a new incoming WebSockets connection from the provided socket. The server issues the `Server.connect` callback and then performs the WebSockets handshake. The status line has been read from the socket, but none of the HTTP headers have been read as these are required to complete the handshake. See the [httpserverwithwebsockets](../../examples/network/http/httpserverwithwebsockets/main.js) for an example of sharing a single listener socket between the HTTP and WebSockets servers. @@ -732,7 +732,7 @@ The `get` function returns properties of the active network connection. The following properties are available: -| Property | Description | +| Property | Description | | :---: | :--- | | `IP` | The IP address of the network connection as a `String`, e.g. "10.0.1.4". These may be IPv4 or IPv6 addresses. | `MAC` | The MAC address of the device as a `String`, e.g. "A4:D1:8C:DB:C0:20" @@ -747,7 +747,7 @@ The following properties are available: trace(`Connected to Wi-Fi access point: ${Net.get("SSID")}\n`); ``` -For a device operating as both a Wi-Fi station (client) and a Wi-Fi access point, the static `get` method accepts an optional second argument to indicate if the request is for the station or access point interface. The interface accepts values of `"station"` and `"ap"`. It is used for the `IP` and `MAC` properties. +For a device operating as both a Wi-Fi station (client) and a Wi-Fi access point, the static `get` method accepts an optional second argument to indicate if the request is for the station or access point interface. The interface accepts values of `"station"` and `"ap"`. It is used for the `IP` and `MAC` properties. On ESP32, the optional second argument can also be used to explicitly request information about the Ethernet interface by providing the value `"ethernet"`. @@ -788,7 +788,7 @@ import WiFi from "wifi"; ### `constructor(dictionary, callback)` -The `WiFi` constructor takes a single argument, a dictionary of initialization parameters. The constructor begins the process of establishing a connection. +The `WiFi` constructor takes a single argument, a dictionary of initialization parameters. The constructor begins the process of establishing a connection. The dictionary always contains the required `ssid` property with the name of the base station to connect to. The optional `password` property is included when the base station requires a password. When the optional `bssid` property is included, it may accelerate connecting to Wi-Fi on device targets that support it. @@ -826,7 +826,7 @@ monitor.close(); ### `static scan(dictionary, callback)` -The `scan` static function initiates a scan for available Wi-Fi access points. +The `scan` static function initiates a scan for available Wi-Fi access points. The dictionary parameter supports two optional properties: @@ -959,10 +959,10 @@ The DNS module contains constants that are useful when implementing code that in ```js import DNS from "dns"; ``` - + - `DNS.RR` contains constants for resource record types, such as `DNS.RR.PTR`. - `DNS.OPCODE` contains values for `DNS.OPCODE.QUERY` and `DNS.OPCODE.UPDATE`. -- `DNS.CLASS` contains values for `DNS.CLASS.IN`, `DNS.CLASS.NONE`, and `DNS.CLASS.ANY`. +- `DNS.CLASS` contains values for `DNS.CLASS.IN`, `DNS.CLASS.NONE`, and `DNS.CLASS.ANY`. - `DNS.SECTION` contains values that include `DNS.QUESTION` and `DNS.ANSWER`. @@ -988,12 +988,12 @@ No validation is performed by the constructor. Errors, if any, are reported when *** ### `questions(index)` -Returns the question resource record corresponding to the index argument. Indices are numbered from 0. Returns `null` if index is greater than number of question records in the packet. +Returns the question resource record corresponding to the index argument. Indices are numbered from 0. Returns `null` if index is greater than number of question records in the packet. *** ### `answers(index)` -Returns the answer resource record corresponding to the index argument. Indices are numbered from 0. Returns `null` if index is greater than number of answer records in the packet. +Returns the answer resource record corresponding to the index argument. Indices are numbered from 0. Returns `null` if index is greater than number of answer records in the packet. *** @@ -1003,7 +1003,7 @@ Returns the authority resource record corresponding to the index argument. Indic *** ### `additionals(index)` -Returns the additional resource record corresponding to the index argument. Indices are numbered from 0. Returns `null` if index is greater than number of additional records in the packet. +Returns the additional resource record corresponding to the index argument. Indices are numbered from 0. Returns `null` if index is greater than number of additional records in the packet. *** @@ -1026,7 +1026,7 @@ The parser instance has properties for the `id` and `flags` fields in the DNS pa let id = packet.id; let flags = packet.flags; ``` - + *** ### Example: Determining the number of records @@ -1069,7 +1069,7 @@ The DNS `Serializer` constructor accepts a dictionary with properties to configu | Property | Default Value | Description | | :---: | :---: | :--- | -| `opcode` | `DNS.OPCODE.QUERY` | The numeric value of the `opcode` header field +| `opcode` | `DNS.OPCODE.QUERY` | The numeric value of the `opcode` header field | `query` | `true` | A boolean that indicates whether this packet contains a query or response | `authoritative` | `false` | A boolean indicating the value of the `authoritative` bit in the header | `id` | 0 | A numeric value for the ID field @@ -1095,7 +1095,7 @@ The optional `data` argument is used to build the resource data portion of the r | `A` | A string containing the IP address. | `NSEC` | A dictionary with two keys. The first is `next` containing a string with the next hostname value. The second is a Uint8Array containing the bit-mask. | `PTR` | A string with the PTR value. -| `SRV` | A dictionary with four keys. The `priority`, `weight`, and `port` fields are numbers with the value of the corresponding field. The `target` property is a string containing the name of the target. +| `SRV` | A dictionary with four keys. The `priority`, `weight`, and `port` fields are numbers with the value of the corresponding field. The `target` property is a string containing the name of the target. | `TXT` | A dictionary of key / value pairs for the TXT record. The property name is the key. Only string values are supported at this time. *** @@ -1168,7 +1168,7 @@ new DNSServer((message, value) => { }) ``` -> **Note:**: This example expects to be run on a Wi-Fi connection in access point mode. It passes "ap" for the interface argument to `Net.get` to retrieve the IP address for access point. +> **Note:**: This example expects to be run on a Wi-Fi connection in access point mode. It passes "ap" for the interface argument to `Net.get` to retrieve the IP address for access point. ### Example: DNS server for a single host name @@ -1187,7 +1187,7 @@ new DNSServer((message, value) => { ## class MDNS - **Source code:** [mdns](../../modules/network/mdns) -- **Relevant Examples:** [discoverhttp](../../examples/network/mdns/discoverhttp), [httpserver](../../examples/network/mdns/httpserver), [ntpclient](../../examples/network/mdns/ntpclient), [ntpservice](../../examples/network/mdns/ntpservice), +- **Relevant Examples:** [discoverhttp](../../examples/network/mdns/discoverhttp), [httpserver](../../examples/network/mdns/httpserver), [ntpclient](../../examples/network/mdns/ntpclient), [ntpservice](../../examples/network/mdns/ntpservice), The `MDNS` class implements services for working with [Multicast DNS](https://tools.ietf.org/html/rfc6762) discovery and services. It includes claiming `.local` names, advertising mDNS service availability, and scanning for available mDNS services. @@ -1216,7 +1216,7 @@ const mdns = new MDNS({hostName: "mydevice"}); ``` The claiming process takes some time, usually under one second. Claiming the name may not succeed because the name may already be in use. An optional callback function provides status on the claim: - + ```js const mdns = new MDNS({hostName: "mydevice"}, function(message, value) { switch (message) { @@ -1289,7 +1289,7 @@ let service = mdns.services[0]; service.txt["value"] = 123; mdns.update(service); ``` - + *** ### `remove(service)` or `remove(serviceType)` @@ -1466,7 +1466,7 @@ Use the `unsubscribe` method to unsubscribe to a topic. mqtt.unsubscribe("test/string"); ``` -### `onMessage(topic, data)` +### `onMessage(topic, data)` The `onMessage` callback is invoked when a message is received for any topic that your client has subscribed to. The `topic` argument is the name of the topic and the `data` argument is the complete message. diff --git a/documentation/network/securesocket.md b/documentation/network/securesocket.md index 48fce34511..9505a791f0 100644 --- a/documentation/network/securesocket.md +++ b/documentation/network/securesocket.md @@ -51,7 +51,7 @@ In the following example, the TLS socket is created with support for version `0x ```js let socket = new SecureSocket({ - host: "www.example.com", + host: "www.example.com", port: 443, secure: { protocolVersion: 0x303 @@ -68,8 +68,8 @@ The HTTP `Client` class accepts an optional `Socket` property in the dictionary let request = new Request({ host: "www.howsmyssl.com", path: "/", - response: String, - Socket: SecureSocket, + response: String, + Socket: SecureSocket, port: 443, secure: { trace: true, @@ -85,9 +85,9 @@ The WebSocket `Client` class accepts an optional `Socket` property in the dictio ```js let ws = new Client({ - host: "echo.websocket.org", + host: "echo.websocket.org", port: 443, - Socket: SecureSocket, + Socket: SecureSocket, secure: { protocolVersion: 0x302 } @@ -150,10 +150,10 @@ As an alternative to the certificate store, you can put the certificates needed ```js let request = new Request({ - host: "www.howsmyssl.com", + host: "www.howsmyssl.com", path: "/", - response: String, - Socket: SecureSocket, + response: String, + Socket: SecureSocket, port: 443, secure: { certificate: new Resource("ca109.der") @@ -170,19 +170,19 @@ let request = new Request({ ... secure: { certificate: new Resource("mycert.der") - } + } }); ``` #### Converting PEM to DER -The `SecureSocket` implementation requires certificates to be provided in DER (binary) format. If you have a certificate in PEM (a Base64 encoded) format, you need to convert it to DER. +The `SecureSocket` implementation requires certificates to be provided in DER (binary) format. If you have a certificate in PEM (a Base64 encoded) format, you need to convert it to DER. Whenever possible, convert the PEM file to DER format before adding it to your project. There are many tools that can perform the conversion. A reliable choice is `openssl`. The following command line works for many certificates (substitute your PEM file path for `data.pem` and the desired output file path for `data.der`): ``` openssl x509 -inform pem -in data.pem -out data.der -outform der -``` +``` Sometimes there is no choices but to convert the PEM to DER at runtime. For example, during provisioning you might receive a certificate in PEM format from a service, and later you need to use that certificate to establish a TLS connection. The Moddable SDK provides the [`pemtoDER`](../crypt/crypt.md#transform-pemToDER) and [`privateKeyToPrivateKeyInfo`](../crypt/crypt.md#transform-privateKeyToPrivateKeyInfo) functions for these situations. These functions are part of the Crypt `Transform` class. diff --git a/documentation/network/webthings.md b/documentation/network/webthings.md index ce4938e24e..390e1e0387 100644 --- a/documentation/network/webthings.md +++ b/documentation/network/webthings.md @@ -14,7 +14,7 @@ Revised: August 28, 2019 ## Introduction -The Web Thing API is part of the [Project Things](https://iot.mozilla.org) initiative by Mozilla to define open communication protocols between IoT products. The Web Thing API is a protocol built using JSON, HTTP, and mDNS. It is related to the larger [Web of Things](https://www.w3.org/WoT/) effort of W3C. The IoT team at Mozilla created a home gateway that works with IoT products that implement the Web Thing API protocol. Mozilla also provides embedded device APIs to make it easier to create products that support the Web Thing API. All this work is in development, so it is not ready incorporate into products. +The Web Thing API is part of the [Project Things](https://iot.mozilla.org) initiative by Mozilla to define open communication protocols between IoT products. The Web Thing API is a protocol built using JSON, HTTP, and mDNS. It is related to the larger [Web of Things](https://www.w3.org/WoT/) effort of W3C. The IoT team at Mozilla created a home gateway that works with IoT products that implement the Web Thing API protocol. Mozilla also provides embedded device APIs to make it easier to create products that support the Web Thing API. All this work is in development, so it is not ready incorporate into products. In the goals of Mozilla's Web Thing API effort we hear echoes of Moddable's own goals of creating an open environment of IoT products that put the user in control. Consequently, at Moddable we have begun experimenting with the Web Thing API. One result of that work is a set of simple JavaScript classes for building devices compatible with the Web Thing API. The classes have been successfully used on ESP8266 and ESP32 hardware with the Mozilla gateway. @@ -31,7 +31,7 @@ The Web of Things [gateway software](https://iot.mozilla.org/gateway/) is availa The Moddable SDK repository on GitHub contains the [WebThings implementation](https://github.com/Moddable-OpenSource/moddable/tree/public/modules/network/webthings) and several [example device implementations](https://github.com/Moddable-OpenSource/moddable/tree/public/examples/network/webthings). -This documentation describes how to implement a `WebThing` subclass to be used with the `WebThings` host. The `WebThing` class is a base class to be subclassed by specific implementations. It contains no device specific capabilities. +This documentation describes how to implement a `WebThing` subclass to be used with the `WebThings` host. The `WebThing` class is a base class to be subclassed by specific implementations. It contains no device specific capabilities. ### Implementing a Light using the WebThing class @@ -168,14 +168,14 @@ The `add` function registers a subclass of `WebThing`. The constructor argument In this example, `OnOffLight` is the class defined in the "Implementing a Light using the WebThing class" section above. ```js -things.add(OnOffLight); +things.add(OnOffLight); ``` *** ## class WebThing -The `WebThing` class is subclassed to create implementations of specific Web Things. +The `WebThing` class is subclassed to create implementations of specific Web Things. ```js import {WebThing} from "webthings"; diff --git a/documentation/pins/audioout.md b/documentation/pins/audioout.md index 353b397352..ad96a05071 100644 --- a/documentation/pins/audioout.md +++ b/documentation/pins/audioout.md @@ -93,7 +93,7 @@ This is done by using the ability to repeat a sample an infinite number of times audio.enqueue(0, AudioOut.Samples, aSample, 1, aSample.attackStart, aSample.attackCount); audio.enqueue(0, AudioOut.Samples, aSample, Infinity, aSample.sustainStart, aSample.sustainCount); ``` - + When it is time to end playback of the sample, enqueue the decay section. This will terminate the enqueue sustain section when it completes the current repetition: ```js @@ -101,7 +101,7 @@ audio.enqueue(0, AudioOut.Samples, aSample, 1, aSample.decayStart, aSample.decay ``` ### constructor(dictionary) -The constructor accepts a dictionary to configure the audio output. +The constructor accepts a dictionary to configure the audio output. ```js let audio = new AudioOut({sampleRate: 11025, bitsPerSample: 16, numChannels: 2, streams: 3}); @@ -132,7 +132,7 @@ audio.start(); ``` ### stop() -Call the `stop` function to immediately suspend audio playback. +Call the `stop` function to immediately suspend audio playback. ```js audio.stop(); @@ -174,12 +174,12 @@ audio.enqueue(0, AudioOut.Samples, bufferTwo, Infinity); ``` If the repeat count is `Infinity`, the buffer is repeated until the audio out instance is closed, the streaming is flushed, or another buffer of audio is enqueued. In the final case, the currently playing buffer plays to completion, and then the following buffer is played. - + A subset of the samples in the buffer may be selected for playback by using the optional `offset` and `count` parameters. Both parameters are in units of samples, not bytes. The `offset` parameter indicates the number of samples into the buffer to begin playback. If the `count` parameter is not provided, playback proceeds to the end of the buffer. It the `count` parameter is provided, only the number of samples it specifies are played. #### Enqueuing tones and silence -To `enqueue` a tone, provide the frequency and number of samples. The square wave will be generated. The following queues 8000 samples of a 440 Hz A natural. Pass `Infinty` for the sample count to play the tone until `flush`, `stop`, or `close`. +To `enqueue` a tone, provide the frequency and number of samples. The square wave will be generated. The following queues 8000 samples of a 440 Hz A natural. Pass `Infinty` for the sample count to play the tone until `flush`, `stop`, or `close`. ```js audio.enqueue(0, AudioOut.Tone, 440, 8000); diff --git a/documentation/pins/pins.md b/documentation/pins/pins.md index 56f0f0b254..56f70269b5 100644 --- a/documentation/pins/pins.md +++ b/documentation/pins/pins.md @@ -50,7 +50,7 @@ To open a GPIO pin on a specific port, use the Digital constructor with the opti ```js let blink = 1; let led = new Digital("gpioPortName", 5, Digital.Output); - + Timer.repeat(id => { blink = blink ^ 1; led.write(blink); @@ -91,7 +91,7 @@ The following example configures pin 5 as an output and then blinks it one per s ```js let blink = 1; - + Timer.repeat(id => { blink = blink ^ 1; Digital.write(5, blink); @@ -192,7 +192,7 @@ let monitor = new Monitor({pin: 0, port: "B", mode: Digital.Input, edge: Monitor ### `onChanged()` callback -A script must install an `onChanged` callback on the instance to be invoked with the specified edge events occur. +A script must install an `onChanged` callback on the instance to be invoked with the specified edge events occur. ```js monitor.onChanged = function() { @@ -285,7 +285,7 @@ The `Analog` class provides access to the analog input pins. ```js import Analog from "pins/analog"; ``` - + ### `constructor(dictionary)` The `Analog` dictionary requires a `pin` property. On platforms supporting wake-up from deep sleep on analog input triggers, the `onWake`, `wakeCrossing`, and `wakeValue` properties are additionally required to configure the analog input as a wake-up trigger. Refer to the `onWake() callback` section below for further details. @@ -297,17 +297,17 @@ let analog = new Analog({ pin: 5 }); trace(`Analog value is ${analog.read()}\n`); ``` -**Note**: The nRF52 platform currently only supports the constructor and instance read function. On all other platforms, the Analog class provides only static functions. +**Note**: The nRF52 platform currently only supports the constructor and instance read function. On all other platforms, the Analog class provides only static functions. ### `static read(pin)` -The `read` function samples the value of the specified pin, returning a value from 0 to 1023. +The `read` function samples the value of the specified pin, returning a value from 0 to 1023. Pin numbers are device dependent: - The ESP8266 NodeMCU board has a single analog input pin, analog pin number 0. - On the ESP32, use the analog channel number, not the associated GPIO number. You can find GPIO number to analog channel mappings for ESP32 and ESP32-S2 in the [ESP-IDF ADC documentation](https://docs.espressif.com/projects/esp-idf/en/v4.2-beta1/esp32/api-reference/peripherals/adc.html#_CPPv414adc1_channel_t). Only ADC1 is supported on the ESP32. -The following example samples an analog temperature sensor, converting the result to celsius degrees. +The following example samples an analog temperature sensor, converting the result to celsius degrees. let temperature = (Analog.read(0) / 1023) * 330 - 50; trace(`Temperature is ${temperature} degrees celsius\n`); @@ -361,7 +361,7 @@ import PWM from "pins/pwm"; ### `constructor(dictionary)` -The PWM constructor takes a dictionary which contains the pin number to use. Pin numbers are device dependent. +The PWM constructor takes a dictionary which contains the pin number to use. Pin numbers are device dependent. The dictionary may optionally contain a `port` property. If the port is not provided, the default port (`NULL`) is used. @@ -452,19 +452,19 @@ sensor.read(3, bytes.buffer); ### `write(...value [, stop])` -The `write` function writes up to 40 bytes to the target device. The write function accepts multiple arguments, concatenating them together to send to the device. The values may be numbers, which are transmitted as bytes, Arrays, TypedArrays, and strings (which are transmitted as UTF-8 encoded text bytes). +The `write` function writes up to 40 bytes to the target device. The write function accepts multiple arguments, concatenating them together to send to the device. The values may be numbers, which are transmitted as bytes, Arrays, TypedArrays, and strings (which are transmitted as UTF-8 encoded text bytes). The `write` function accepts an optional final boolean argument, `stop`, which indicates if a stop condition should be sent when the write is complete. If the final argument is not a boolean value, a stop condition is sent. ```js let sensor = new I2C({address: 0x48}); -sensor.write(0); +sensor.write(0); ``` *** ### Example: Reading an I2C temperature sensor -The following example instantiates an I2C connection to a [temperature sensor](https://www.sparkfun.com/products/11931) with address 0x48 connected to pins 4 and 5. +The following example instantiates an I2C connection to a [temperature sensor](https://www.sparkfun.com/products/11931) with address 0x48 connected to pins 4 and 5. ```js let sensor = new I2C({sda: 5, scl: 4, address: 0x48}); @@ -482,7 +482,7 @@ value *= 0.0625; trace(`Celsius temperature: ${value}\n`); ``` - + *** @@ -546,7 +546,7 @@ The following example establishes an SMBus connection to a [triple axis magnetom ```js let sensor = new SMBus({address: 0x1E}); - + let id = sensor.readBlock(10, 3); id = String.fromCharCode(id[0]) + String.fromCharCode(id[1]) + String.fromCharCode(id[2]); if ("H43" != id) @@ -557,7 +557,7 @@ sensor.writeByte(2, 0); // continuous measurement mode *** - + ## class Servo @@ -569,7 +569,7 @@ The `Servo` class uses digital pins to control servo motors. The API is designed ```js import Servo from "pins/servo"; ``` - + ### `constructor(dictionary)` The Servo constructor takes a dictionary. The `pin` property is required, and specifies the digital pin to use. The `min` and `max` properties are optional, and specify the range of the pulse duration in microseconds. @@ -595,7 +595,7 @@ servo.write(45); ### `writeMicroseconds(us)` -The `writeMicroseconds` call sets the duration of the pulse width in microseconds. The value provided is pinned by the `min` and `max` values. +The `writeMicroseconds` call sets the duration of the pulse width in microseconds. The value provided is pinned by the `min` and `max` values. The Servo implementation pulses a digital signal for a number of microseconds that is proportional to the angle of rotation. Scripts may provide the number of microseconds for the signal pulse instead of degrees, for greater precision. @@ -619,9 +619,9 @@ import RMT from "pins/rmt"; ### `constructor(dictionary)` -The RMT constructor initializes the RMT module and associates it with the specified pin. +The RMT constructor initializes the RMT module and associates it with the specified pin. -The RMT constructor takes a dictionary. The `pin` property is required, and specifies the pin to associate with the RMT module. +The RMT constructor takes a dictionary. The `pin` property is required, and specifies the pin to associate with the RMT module. ```js let rmt = new RMT({pin: 17}); @@ -629,7 +629,7 @@ let rmt = new RMT({pin: 17}); The constructor dictionary also has several optional properties: -- The `channel` property specifies the RMT channel to use with this instance, with a default value of `0`. +- The `channel` property specifies the RMT channel to use with this instance, with a default value of `0`. - The `divider` property specifies the clock divider used to generate RMT ticks, with a range of `1` to `255` and a default value of `255`. - The `direction` property specifies whether to use this RMT as an input or an output. Use `"rx"` for input and `"tx"` for output. The default is output. @@ -665,7 +665,7 @@ The write is performed asynchronously, so `write` returns immediately. When the ### `onWriteable()` callback -A script may install an `onWriteable` callback on the instance to be invoked when the RMT module is ready to write data. +A script may install an `onWriteable` callback on the instance to be invoked when the RMT module is ready to write data. ```js rmt.onWritable = function() { @@ -679,12 +679,12 @@ The `onWriteable` function is called once when the RMT module is initialized and ### `read(buffer)` -The `read` function returns RMT data in an ArrayBuffer provided by the `buffer` argument. Up to `buffer.byteLength` bytes from the RMT module's ring buffer are returned in the ArrayBuffer. +The `read` function returns RMT data in an ArrayBuffer provided by the `buffer` argument. Up to `buffer.byteLength` bytes from the RMT module's ring buffer are returned in the ArrayBuffer. -`read` returns an object with three properties: +`read` returns an object with three properties: -- The `buffer` property is the ArrayBuffer provided to `read` as an argument, filled with the received pulse duration sequence read by the RMT module. -- The `count` property is the total number of pulses received in the sequence. +- The `buffer` property is the ArrayBuffer provided to `read` as an argument, filled with the received pulse duration sequence read by the RMT module. +- The `count` property is the total number of pulses received in the sequence. - The `phase` property is the logic level of the first item in the sequence (`0` or `1`) — subsequent pulses in the `buffer` alternate logic levels. ```js diff --git a/documentation/piu/ae motion export.md b/documentation/piu/ae motion export.md index 87bbfcd879..ba5a236a25 100644 --- a/documentation/piu/ae motion export.md +++ b/documentation/piu/ae motion export.md @@ -6,7 +6,7 @@ Revised: September 26, 2017 Adobe After Effects can be used to export motion data into a Moddable sample app for use in development. -Moddable motion control only supports position. +Moddable motion control only supports position. In AE only layers with assets are exported and only positions are exported. Scaling, rotation, transparncy, etc. are not exported. @@ -16,16 +16,16 @@ Piu interpolates linearly between values in the array. You can reduce the frame Install the ae2piu.jsx script in the "scripts" folder within your After Effects application folder. -
+
+
-
### Exporting motion data
To run the script select "ae2piu.jsx" from the File -> Scripts menu.
-
+
When you run the export script in After Effects, it displays a dialog box to select a folder. Create a new folder the first time. The export script copies the assets and creates the manifest.json and main.js files for a complete Moddable application. To build the project and run in the Moddable Simulator use the following command.
@@ -41,10 +41,10 @@ Time values are exported as milliseconds.
AE easing is not exported but Moddable easing can be added to the exported code.
-Example: (null replaced by Math.quadEaseOut)
+Example: (null replaced by Math.quadEaseOut)
this.steps(ball, { x:ballX, y:ballY }, 2333, null, 0, 0);
-
+
this.steps(ball, { x:ballX, y:ballY }, 2333, Math.quadEaseOut, 0, 0);
diff --git a/documentation/piu/die-cut.md b/documentation/piu/die-cut.md
index 4f6303c3f1..f0b6f4a409 100644
--- a/documentation/piu/die-cut.md
+++ b/documentation/piu/die-cut.md
@@ -7,7 +7,7 @@ Revised: November 22, 2016
To get animations on a screen connected to a microcontroller by a serial interface (SPI), the game is to minimize the number of pixels that change from frame to frame.
> FYI, here is what is happening at every frame when changes in the appearance or the layout invalidate and update the screen:
->
+>
> - The dirty region accumulates the invalidations.
> - The containment hierarchy is traversed once to build the command list that will update the screen.
> - The dirty region and the command list are decomposed into rectangles and display lists.
@@ -43,14 +43,14 @@ Let us begin with a static example:
}),
]
}));
-
+
The `empty`, `or`, `xor` and `sub` methods are chainable operations to build the region. The `cut` method changes the region.
If you add the `TestContainer` to an application, here is what it will look like:
-But of course the `die` object is mostly interesting to build animations and transitions. You will find examples in the Piu libraries: WipeTransition and CombTransition.
+But of course the `die` object is mostly interesting to build animations and transitions. You will find examples in the Piu libraries: WipeTransition and CombTransition.
Let us build a "venitian blind" transition:
@@ -88,9 +88,9 @@ The `attach` and `detach` methods allow to temporarily insert a `die` object in
## Reference
-The `die` object is a `layout` object that allows to “die cut” its contents with a region. The `die` object maintains two regions:
+The `die` object is a `layout` object that allows to “die cut” its contents with a region. The `die` object maintains two regions:
-- the work region that the available operations build,
+- the work region that the available operations build,
- the clip region that clips the contents of the `die` object
Both regions are initially empty.
@@ -102,13 +102,13 @@ Prototype inherits from `Layout.prototype`.
##### `Die.prototype.and(x, y, width, height)`
> `x, y, width, height` a local rectangle, in pixels
->
+>
> Intersect the rectangle with the work region. Return this.
##### `Die.prototype.attach(content)`
> `content ` the `content` object to attach
->
+>
> Bind the `die` object to the content hierarchy by replacing the specified `content` object in the content's container with this `die` object and adding the `content` object to this `die` object.
##### `Die.prototype.cut()`
@@ -130,25 +130,25 @@ Prototype inherits from `Layout.prototype`.
##### `Die.prototype.or(x, y, width, height)`
> `x, y, width, height` a local rectangle, in pixels
->
+>
> Inclusively union the rectangle with the work region. Return `this`.
##### `Die.prototype.set(x, y, width, height)`
> `x, y, width, height` a local rectangle, in pixels
->
+>
> Set the work region to the rectangle. Return `this`.
##### `Die.prototype.sub(x, y, width, height)`
> `x, y, width, height` a local rectangle, in pixels
->
+>
> Subtract the rectangle from the work region. Return `this`.
##### `Die.prototype.xor(x, y, width, height)`
> `x, y, width, height` a local rectangle, in pixels
->
+>
> Exclusively union the work region with the rectangle. Return `this`.
diff --git a/documentation/piu/expanding-keyboard.md b/documentation/piu/expanding-keyboard.md
index d3a435b408..d4be71f9f3 100644
--- a/documentation/piu/expanding-keyboard.md
+++ b/documentation/piu/expanding-keyboard.md
@@ -2,7 +2,7 @@
Copyright 2019 Moddable Tech, Inc.Revised: July 2, 2019 -The vertical and horizontal expanding keyboard modules implement touch screen keyboards for use with [Piu](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/piu/piu.md) on Moddable One and Moddable Two [products](https://www.moddable.com/product.php). The keys automatically expand when tapped, eliminating the need for a stylus. Both keyboards implement the same API. +The vertical and horizontal expanding keyboard modules implement touch screen keyboards for use with [Piu](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/piu/piu.md) on Moddable One and Moddable Two [products](https://www.moddable.com/product.php). The keys automatically expand when tapped, eliminating the need for a stylus. Both keyboards implement the same API. - **Source code:** [`vertical/keyboard.js`](../../modules/input/expanding-keyboard/vertical/keyboard.js) [`horizontal/keyboard.js`](../../modules/input/expanding-keyboard/horizontal/keyboard.js) - **Relevant Examples:** [vertical-expanding-keyboard](../../examples/piu/vertical-expanding-keyboard/main.js) [horizontal-expanding-keyboard](../../examples/piu/horizontal-expanding-keyboard/main.js) @@ -43,7 +43,7 @@ import {KeyboardField} from "common/keyboard"; #### `HorizontalExpandingKeyboard(behaviorData, dictionary)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `behaviorData` | `*` | A parameter that is passed into the `onCreate `function of the keyboard's `behavior`. This may be any type of object, including `null` or a dictionary with arbitrary parameters. | `dictionary` | `object` | An object with properties to configure the resulting keyboard. Only parameters specified in the [Dictionary](#keyboard-dictionary) section below will have an effect; other parameters will be ignored. @@ -60,7 +60,7 @@ let keyboard = new VerticalExpandingKeyboard(null, { Style:KeyboardStyle, target ### Dictionary | Parameter | Type | Default Value | Description | -| :---: | :---: | :---: | :--- | +| :---: | :---: | :---: | :--- | | `Style` | `style` | n/a | **Required.** A Piu Style object that will be used for the text on keys. | | `target` | `object` | n/a | **Required.** A Piu Container object that will receive the `onKeyUp` event. | | `doTransition` | `boolean` | `false`| Whether or not to transition in the keyboard when it is first displayed and transition out when dismissed. | @@ -71,7 +71,7 @@ let keyboard = new VerticalExpandingKeyboard(null, { Style:KeyboardStyle, target #### `onKeyboardOK(container, text)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `container` | `object` | The behavior's Container object | | `text` | `string` | The complete string entered into the field | @@ -80,7 +80,7 @@ The keyboard bubbles this event when the OK button is pressed. #### `onKeyboardRowsContracted(container)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `container` | `object` | The behavior's Container object | The keyboard bubbles this event when it is done horizontally contracting the keyboard rows back to the unzoomed view. @@ -88,7 +88,7 @@ The keyboard bubbles this event when it is done horizontally contracting the key #### `onKeyboardRowsExpanded(container)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `container` | `object` | The behavior's Container object | The keyboard bubbles this event when it is done horizontally expanding the keyboard rows to the zoomed view. @@ -96,7 +96,7 @@ The keyboard bubbles this event when it is done horizontally expanding the keybo #### `onKeyboardTransitionFinished(container, out)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `container` | `object` | The behavior's Container object | | `out` | `boolean` | Set `true` when the keyboard transitions out of view, `false` when the keyboard transitions into view | @@ -105,7 +105,7 @@ The keyboard bubbles this event when it is done transitioning on and off the scr #### `onKeyUp(container, key)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `container` | `object` | The behavior's Container object | | `key` | `string` | The string value of the key that was pressed (e.g., `'a'`, `'3'`, `'$'`). It can also be `\b` for backspace or `\r` for the submit button.| @@ -120,7 +120,7 @@ The keyboard bubbles the `onKeyUp` event when a key is released. The `onKeyUp` f #### `KeyboardField(behaviorData, dictionary)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `behaviorData` | `*` | A parameter that is passed into the `onCreate `function of the keyboard field's `behavior`. This may be any type of object, including `null` or a dictionary with arbitrary parameters. | `dictionary` | `object` | An object with properties to configure the resulting keyboard field. Only parameters specified in the [Dictionary](#keyboard-field-dictionary) section below will have an effect; other parameters will be ignored. @@ -135,7 +135,7 @@ let keyboardField = new KeyboardField(null, { Style:FieldStyle }); ### Dictionary | Parameter | Type | Default Value | Description | -| :---: | :---: | :---: | :--- | +| :---: | :---: | :---: | :--- | | `Style` | `style` | n/a | **Required.** A Piu Style object that will be used for the keyboard entry text. | | `password` | `boolean` | `false` | Set `true` to enable password mode. The password mode hides each character displayed after a short delay. | @@ -144,7 +144,7 @@ let keyboardField = new KeyboardField(null, { Style:FieldStyle }); #### `onKeyboardOK(container, text)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `container` | `object` | The behavior's Container object | | `text` | `string` | The complete string entered into the field | diff --git a/documentation/piu/keyboard.md b/documentation/piu/keyboard.md index 87839ab2ba..bb27d2b3cf 100644 --- a/documentation/piu/keyboard.md +++ b/documentation/piu/keyboard.md @@ -30,7 +30,7 @@ import {Keyboard, BACKSPACE, SUBMIT} from "keyboard"; #### `Keyboard(behaviorData, dictionary)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `behaviorData` | `*` | A parameter that is passed into the `onCreate `function of the keyboard's `behavior`. This may be any type of object, including `null` or a dictionary with arbitrary parameters. | `dictionary` | `object` | An object with properties to configure the resulting keyboard. Only parameters specified in the [Dictionary](#keyboard-dictionary) section below will have an effect; other parameters will be ignored. @@ -47,7 +47,7 @@ let keyboard = new Keyboard(null, {style: OpenSans18, doTransition: false}) ### Dictionary | Parameter | Type | Default Value | Description | -| :---: | :---: | :---: | :--- | +| :---: | :---: | :---: | :--- | | `style` | `style` | n/a | **Required.** A Piu Style object that will be used for the text on keys. | | `bgColor` | `string` | `"#5b5b5b"`| The background fill color. | | `doTransition` | `boolean` | `false`| Whether or not to transition in the keyboard when it is first displayed. | @@ -71,7 +71,7 @@ The keyboard will bubble this event when it is done transitioning off-screen. Th #### `onKeyDown(key)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `key` | `string` | In most cases, the string will be the value of the key that is down (e.g. `"a"`, `"3"`, `"$"`). It can also be one of the two constants exported by the module: `BACKSPACE` or `SUBMIT` which indicate that those keys are down on the keyboard.| The keyboard will bubble this event when a key is pressed down. The `onKeyDown` function will usually be implemented and triggered in the calling application's behavior. @@ -82,7 +82,7 @@ The keyboard will bubble this event when a key is pressed down. The `onKeyDown` #### `onKeyUp(key)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `key` | `string` | In most cases, the string will be the value of the key that was released (e.g. `"a"`, `"3"`, `"$"`). It can also be one of the two constants exported by the module: `BACKSPACE` or `SUBMIT` which indicate that those keys were released on the keyboard.| The keyboard will bubble an event `onKeyUp` when a key is released. The `onKeyUp` function will usually be implemented and triggered in the calling application's behavior. @@ -94,7 +94,7 @@ The keyboard will bubble an event `onKeyUp` when a key is released. The `onKeyUp #### `doKeyboardTransitionOut(keyboard)` | Argument | Type | Description | -| :---: | :---: | :--- | +| :---: | :---: | :--- | | `keyboard` | `keyboard` | The `keyboard` object that received the event. | This function can be triggered to cause the keyboard to transition off screen. When the transition is complete, the `onKeyboardTransitionFinished` event will be bubbled by the keyboard. diff --git a/documentation/piu/localization.md b/documentation/piu/localization.md index 51ab3d44e4..15ad7bf241 100644 --- a/documentation/piu/localization.md +++ b/documentation/piu/localization.md @@ -10,7 +10,7 @@ When using JavaScript, the most obvious format to localize strings is a dictiona "I love you": "I love you", "Me neither": "Me neither", }; - + var fr = { "I love you": "Je t'aime", "Me neither": "Moi non plus", @@ -20,8 +20,8 @@ When using JavaScript, the most obvious format to localize strings is a dictiona function localize(it) { return language[it]; } - -It is not always possible to use the English string as the key, because of homonyms, contexts, etc. However, when it is possible, it is recommended: the code is easier to read and obvious redundancies are avoided. + +It is not always possible to use the English string as the key, because of homonyms, contexts, etc. However, when it is possible, it is recommended: the code is easier to read and obvious redundancies are avoided. The trivial examples here above are used to compare solutions here under. Of course real applications use dictionaries with thousands of entries, small and large keys and values, so multiply accordingly. @@ -32,11 +32,11 @@ Since usually applications need only one language at a time, dictionaries can be #### en.json {"I love you":"I love you","Me neither":"Me neither"} - + #### fr.json {"I love you":"Je t'aime","Me neither":"Moi non plus"} - + Storing JSON files in ROM is a waste since all dictionaries have to define all keys. For instance here above the keys `I love you` and `Me neither` are repeated in the English and French dictionaries. ROM|Size @@ -60,7 +60,7 @@ Instead of JSON files, dictionaries could be JavaScript modules that XS can comp #### en.js export default {"I love you":"I love you","Me neither":"Me neither"} - + #### fr.js export default {"I love you":"Je t'aime","Me neither":"Moi non plus"} @@ -77,12 +77,12 @@ Moreover, since XS has no special case for such objects, the time to lookup a st ## Strings Tables -The first optimization is to use strings tables instead of JSON files or JavaScript modules. Each table begins with the length of the table followed by the offsets of the strings in the table. All numbers are little-endian 32-bit integers. +The first optimization is to use strings tables instead of JSON files or JavaScript modules. Each table begins with the length of the table followed by the offsets of the strings in the table. All numbers are little-endian 32-bit integers. #### locals.en.mhr 2 12 23 I love you Me neither - + #### locals.fr.mhr 2 12 22 Je t'aime Moi non plus @@ -98,7 +98,7 @@ A tool can generate the strings table from the JSON files. Applications can get ## Strings Indexes -Now something is of course necessary to map keys to indexes into the tables, so `I love you` maps to `0`, `Me neither ` maps to `1`, etc. +Now something is of course necessary to map keys to indexes into the tables, so `I love you` maps to `0`, `Me neither ` maps to `1`, etc. Again a dictionary could be used, at least there would be only one dictionary for all languages. @@ -112,20 +112,20 @@ Again a dictionary could be used, at least there would be only one dictionary fo function localize(it) { return language.get(locals[it]); } - + But such a dictionary would have the already mentioned drawbacks: populating the XS symbols table and taking time to lookup an index. ## Minimal Perfect Hashing When all keys and results are known, a perfect hash function can map keys into results without collisions. A practical solution is to use two hash functions and an intermediary table. The first hash function maps keys into seeds. The second hash function uses the seeds to maps keys into results. The seeds table can be sparse, but both the seeds and results tables contain only one entry by result. Finding the seeds take some time but is done by a tool at build time. -Here are some references: +Here are some references: - [CMPH](http://cmph.sourceforge.net/index.html): a C library with a lot of algorithms and explanations. - [Steve Hanov's blog](http://stevehanov.ca/blog/index.php?id=119): a detailed presentation of the practical solution in PHP. - [mixu/perfect](https://github.com/mixu/perfect): a node.js port. -Here the results are indexes into the strings tables. So the results table does not need to be stored, the results table is only used to reorder the strings tables. +Here the results are indexes into the strings tables. So the results table does not need to be stored, the results table is only used to reorder the strings tables. Only the seeds table needs to be stored. Negative seeds signal that the second hash function can be skipped, the index is the absolute of the seed minus one. @@ -152,12 +152,12 @@ locals.mhi (debug)|46 bytes ## mclocal -**mclocal** is a command line tool that generates strings tables and seeds table from JSON files. +**mclocal** is a command line tool that generates strings tables and seeds table from JSON files. For instance mclocal en.json fr.json - + will generate the `locals.en.mhr`, `locals.fr.mhr` and `locals.mhi` here above. **mclocal** unions the keys from all the JSON files and reports missing keys in the JSON files. @@ -179,22 +179,22 @@ By convention, **mcconfig** will generate a make file with a rule to call **mclo Piu defines a class, `Locals`, to get localized strings and to switch languages. var locals = new Locals; - + The constructor takes two arguments, `name` and `language`. The defaults are `locals` and `en`. Resources are accessed by combining `name`, `language` and the `.mhi` or `.mhr` extensions. - + Applications switch the language with an accessor. - + var what = locals.get("I love you"); // what == "I love you" locals.language = "fr"; var quoi = locals.get("I love you"); // quoi == "Je t'aime" - + For convenience, applications can define a global function to localize strings. global.localize = function(it) { return locals.get(it); - } - - + } + + diff --git a/documentation/piu/piu.md b/documentation/piu/piu.md index 8a7f54491f..0fe1f37254 100644 --- a/documentation/piu/piu.md +++ b/documentation/piu/piu.md @@ -47,7 +47,7 @@ Piu is a user interface framework designed to run on microcontrollers. The progr ## Inheritance Hierarchy -Figure 1 summarizes the inheritance hierarchy for the objects described in this document. +Figure 1 summarizes the inheritance hierarchy for the objects described in this document. **Figure 1.** Piu Inheritance Hierarchy @@ -58,7 +58,7 @@ The basic relationship between these objects in the context of a Piu application - Graphical parts of the user interface are all `content` objects - `skin`, `style`, and `texture` objects customize the look (colors, fonts, etc.) of `content` objects - `behavior` objects are bound to `content` objects to handle events -- `timeline` and `transition` objects animate `content` objects +- `timeline` and `transition` objects animate `content` objects ## Introduction to Important Concepts @@ -77,7 +77,7 @@ Applications use constructors to define `content` and `container` objects. These #### Bound and Unbound Contents -Contents that are not attached to the containment hierarchy are called *unbound* contents; contents attached to the containment hierarchy, *bound* contents. Only objects that are part of the containment hierarchy appear on screen. +Contents that are not attached to the containment hierarchy are called *unbound* contents; contents attached to the containment hierarchy, *bound* contents. Only objects that are part of the containment hierarchy appear on screen. Unbound contents do not participate in layout. They are neither measured nor fitted; consequently, their position and size are `undefined` and cannot be changed. @@ -90,7 +90,7 @@ let after = content.position; // {x: 160, y:120} (assuming the application is 32 #### Constraints -The coordinates of an object define implicit constraints on its position and size. +The coordinates of an object define implicit constraints on its position and size. For example, centered content and contents whose sizes/position are dependent on their container's size/position cannot move. @@ -99,12 +99,12 @@ For example, centered content and contents whose sizes/position are dependent on let centeredContent = new Content(null, { width: 10, height: 10 }); -let dependentOnContainerContent = new Content(null, { +let dependentOnContainerContent = new Content(null, { top: 0, left: 0, bottom: 100, right: 100, }); // Can move -let unconstrainedContent = new Content(null, { +let unconstrainedContent = new Content(null, { top: 0, left: 0, height: 100, width: 100 }); ``` @@ -117,27 +117,27 @@ let unconstrainedContent = new Content(null, { All contents have a *measured width* and *measured height*, which are the default width and height computed by the content itself. For example, the measured width of the following content object will be 100. ```javascript -let sampleContent = new Content(null, { - width: 100 +let sampleContent = new Content(null, { + width: 100 }); ``` The measured width of the following content will be 0, because the content has no default width. ```javascript -let sampleContent = new Content(null, { - left: 0, right: 0 +let sampleContent = new Content(null, { + left: 0, right: 0 }); ``` The `coordinates` property of a `content` object reflect the content's measured size. This property can be changed at any time. ```javascript -sampleContent.coordinates = { +sampleContent.coordinates = { left: 0, width: 100, top: 0, - height: 100 + height: 100 }; ``` @@ -149,8 +149,8 @@ All contents also have a *fitted width* and *fitted height*, which are the effec If both `left` and `right` coordinates are defined, the content stretches horizontally with its container, and the fitted width of the content depends on the fitted width of its container. Similarly, if both `top` and `bottom` coordinates are defined, the content stretches vertically with its container, and the fitted height of the content depends on the fitted height of its container. For example, the fitted width and fitted height of the `sampleContent` object here will both be 100. ```javascript -let sampleContent = new Content(null, { - left: 0, right: 0 +let sampleContent = new Content(null, { + left: 0, right: 0 }); let sampleContainer = new Container(null, { height: 100, width: 100, @@ -163,8 +163,8 @@ let sampleContainer = new Container(null, { If a `left` or `right` coordinate (but not both) is defined, or if neither `left` nor `right` is defined, the fitted width equals the measured width. Similarly, if a `top` or `bottom` coordinate (but not both) is defined, or if neither `top` nor `bottom` is defined, the fitted width equals the measured height. For example, the fitted width and fitted height of the `sampleContent` object here will both be 50. ```javascript -let sampleContent = new Content(null, { - left: 0, top: 0, width: 50, height: 50 +let sampleContent = new Content(null, { + left: 0, top: 0, width: 50, height: 50 }); let sampleContainer = new Container(null, { height: 100, width: 100, @@ -331,7 +331,7 @@ Traces the specified string in the virtual machine of the hosted application. > Note: Strings will not be traced until a line break ("\n") has also been traced. ```javascript -trace("Hello world\n"); +trace("Hello world\n"); let sampleVariable = 2; trace(`sampleVariable value is: ${sampleVariable}\n`); // "sampleVariable value is 2" @@ -391,7 +391,7 @@ application.add(new SampleContainer({ title: "Tap to update", color: "blue" })); A `color` parameter can be passed into the dictionaries of `skin` and `style` constructors. To specify a color, you can use CSS names (Level 2) or hexadecimal notations (`"#RGB"`, `"#RGBA"`, `"#RRGGBB"`, `"#RRGGBBAA"`): - + ```javascript const whiteSkin = new Skin({ fill:"white" }); const redSkin = new Skin({ fill:"#F00" }); @@ -421,7 +421,7 @@ In dictionaries, colors can be a single color or an array of 2, 3, or 4 colors. ### Coordinates -All `content` objects have a `coordinates` property. The coordinates property is an object with `left`, `width`, `right`, `top`, `height`, and `bottom` properties, all of which can be `undefined`. The coordinates of contents determine their position and size relative to their container and their `previous` and `next` properties (other `content` objects in the same container). +All `content` objects have a `coordinates` property. The coordinates property is an object with `left`, `width`, `right`, `top`, `height`, and `bottom` properties, all of which can be `undefined`. The coordinates of contents determine their position and size relative to their container and their `previous` and `next` properties (other `content` objects in the same container). When a content's container is an `application`, `container`, `scroller`, or `layout` object: @@ -447,8 +447,8 @@ When a content's container is a `row` object: Every content in the containment hierarchy can be used as a clock to control time-based animation behaviors using its `duration`, `fraction`, `interval`, and `time` properties. -- The `duration` property is the duration of the animation, expressed in milliseconds. -- The `time` property provides the current time of the content’s clock. +- The `duration` property is the duration of the animation, expressed in milliseconds. +- The `time` property provides the current time of the content’s clock. - The `fraction` property is the ratio of the clock’s current time to the content’s duration. - The `interval` property is the time between frames (frame rate) of the animation, expressed in milliseconds. @@ -549,7 +549,7 @@ let expandingButton = new Content(null, { A `font` parameter must be passed into the dictionary of `style` constructors. -Piu uses bitmap fonts. The metrics are provided by binary FNT files, the glyphs are provided by PNG files. +Piu uses bitmap fonts. The metrics are provided by binary FNT files, the glyphs are provided by PNG files. Fonts are assets and must be defined in the resources of your manifest. Use the default target or the `-alpha` or `-color` pseudo targets for fonts. @@ -576,7 +576,7 @@ In order to cascade styles, you may want to use something similar to the [CSS fo const style = new Style({ font:"italic bold 16px Open Sans" }); ``` -In Piu, the font property has five optional parts, in that order: +In Piu, the font property has five optional parts, in that order: 1. style: `italic` | `normal` | `inherit` 2. weight: `100` | `ultralight` | `200` | `thin` | `300` | `light` | `400` | `normal` | `500` | `medium` | `600` | `semibold` | `700` | `bold` | `800` | `heavy` | `900` | `black` | `lighter` | `bolder` | `inherit ` @@ -600,7 +600,7 @@ For Piu to find the corresponding bitmap font files in your assets, you have to * the family, without spaces, * `-`, * the capitalized name of the stretch, if not `normal`, -* the capitalized name of the computed weight, if not `normal`, +* the capitalized name of the computed weight, if not `normal`, * the capitalized name of the style, if not `normal`, * `Regular`, if the stretch, the computed weight and the style are all `normal`, * `-`, @@ -624,20 +624,20 @@ Tiling skins allows content objects of different sizes to share a single asset. ```javascript let roundedRectangleTexture = new Texture("roundedRectangle.png"); -let roundedRectangleSkin = new Skin({ - texture: roundedRectangleTexture, - x: 0, y: 0, width: 30, height: 30, +let roundedRectangleSkin = new Skin({ + texture: roundedRectangleTexture, + x: 0, y: 0, width: 30, height: 30, tiles: { left: 5, right: 5, top: 5, bottom: 5 } }); let sampleStyle = new Style({ font:"600 28px Open Sans", color: "white" }); let smallText = new Label(null, { - skin: roundedRectangleSkin, top: 20, left: 20, height: 30, width: 30, + skin: roundedRectangleSkin, top: 20, left: 20, height: 30, width: 30, style: sampleStyle, string: "Hi" }); let bigText = new Text(null, { - skin: roundedRectangleSkin, top: 70, left: 20, height: 120, width: 100, + skin: roundedRectangleSkin, top: 70, left: 20, height: 120, width: 100, style: sampleStyle, string: "This is a long string" }); @@ -657,17 +657,17 @@ A common way that the `state` property is used is to update the color of content ```javascript let multiColoredSkin = new Skin({ fill: ["black", "white", "red"] }); -let blackContent = new Content(null, { - top: 20, left: 20, width: 80, height: 80, - skin: multiColoredSkin, state: 0, +let blackContent = new Content(null, { + top: 20, left: 20, width: 80, height: 80, + skin: multiColoredSkin, state: 0, }); -let redContent = new Content(null, { - top: 20, left: 120, width: 80, height: 80, +let redContent = new Content(null, { + top: 20, left: 120, width: 80, height: 80, skin: multiColoredSkin, state: 2 }); -let grayContent = new Content(null, { - top: 20, left: 220, width: 80, height: 80, - skin: multiColoredSkin, state: 0.5 +let grayContent = new Content(null, { + top: 20, left: 220, width: 80, height: 80, + skin: multiColoredSkin, state: 0.5 }); application.add(blackContent); application.add(redContent); @@ -678,7 +678,7 @@ application.add(grayContent); #### Reusing textures -It is often convenient to store several icons or other user interface elements in a single image. Specifying `states` and `variants` properties in the dictionary of `skin` constructors enables you to reference different sections of the same texture. This prevents an application from having to reference similar images and create multiple skins. +It is often convenient to store several icons or other user interface elements in a single image. Specifying `states` and `variants` properties in the dictionary of `skin` constructors enables you to reference different sections of the same texture. This prevents an application from having to reference similar images and create multiple skins. The `states` and `variants` properties of a skin are numerical values used to define the size of a single element in the texture. The `states` property represents the vertical offset between states, and the `variants` property represents the horizontal offset between variants. Here is an example of an asset that includes ten 28x28 pixel icons in one image, and a `skin` that will allow applications to reference each icon separately. @@ -686,9 +686,9 @@ The `states` and `variants` properties of a skin are numerical values used to de ```javascript const wiFiStripTexture = new Texture({ path:"wifi-strip.png" }); -const wiFiSkin = new Skin({ - texture: wiFiStripTexture, - width: 28, height: 28, +const wiFiSkin = new Skin({ + texture: wiFiStripTexture, + width: 28, height: 28, states: 28, variants: 28 }); ``` @@ -745,7 +745,7 @@ For the complete JavaScript programming interface, see [`piuAll.js`][0]. - **Source code:** [`piuApplication.c`][2] - **Relevant Examples:** all -All Piu applications must have an `application` object at the root of their containment hierarchy. All other `content` objects must be added to the `application` to appear on screen. +All Piu applications must have an `application` object at the root of their containment hierarchy. All other `content` objects must be added to the `application` to appear on screen. There is no default object, so you have to create one yourself and export it in the main module. @@ -753,7 +753,7 @@ There is no default object, so you have to create one yourself and export it in export default new Application(); ``` -Alternatively, you can export a function that returns an `application` object. +Alternatively, you can export a function that returns an `application` object. ```javascript export default function() { @@ -842,7 +842,7 @@ class SampleBehavior extends Behavior { } } -let sampleContent = new Content({ name: "Moddable" }, { +let sampleContent = new Content({ name: "Moddable" }, { active: true, height: 100, width: 100, skin: new Skin({fill: "blue"}), Behavior: SampleBehavior @@ -952,7 +952,7 @@ let ColoredSquare = Content.template($ => ({ skin: new Skin({ fill: $ }) })); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({fill: "white"}), contents: [ @@ -980,7 +980,7 @@ let ColoredSquare = Content.template($ => ({ skin: new Skin({ fill: $ }) })); -let SampleContainer = Container.template($ => ({ +let SampleContainer = Container.template($ => ({ top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: $.backgroundColor }), contents: [ @@ -1003,7 +1003,7 @@ Same as for `content` object (see [Dictionary](#content-dictionary) in the secti #### Prototype Description -Prototype inherits from `Content.prototype`. +Prototype inherits from `Content.prototype`. ##### Properties @@ -1034,7 +1034,7 @@ let ColoredSquare = Content.template($ => ({ height: 100, width: 100, skin: new Skin({ fill: $ }) })); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), }); @@ -1086,7 +1086,7 @@ let ColoredSquare = Content.template($ => ({ skin: new Skin({ fill: $ }) })); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1120,7 +1120,7 @@ class SampleBehavior extends Behavior { } } -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1154,7 +1154,7 @@ let ColoredSquare = Content.template($ => ({ skin: new Skin({ fill: $ }) })); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1188,7 +1188,7 @@ class SampleBehavior extends Behavior { } } -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1210,7 +1210,7 @@ application.add(sampleContainer); **`remove(content)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `content` | `content` | The `content` object to remove. Its container must be this container. Removes the specified `content` object from this container @@ -1224,7 +1224,7 @@ let ColoredSquare = Content.template($ => ({ let redSquare = new ColoredSquare("red"); let blueSquare = new ColoredSquare("blue"); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1258,7 +1258,7 @@ let ColoredSquare = Content.template($ => ({ let redSquare = new ColoredSquare("red"); let blueSquare = new ColoredSquare("blue"); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1296,11 +1296,11 @@ class SwitchScreenBehavior extends Behavior { } } let ColoredScreen = Container.template($ => ({ - top: 0, bottom: 0, left: 0, right: 0, + top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: $.color }), contents: [ Content($, { - active: true, height: 100, width: 100, + active: true, height: 100, width: 100, skin: new Skin({ fill: $.nextColor }), Behavior: SwitchScreenBehavior }) @@ -1327,7 +1327,7 @@ let ColoredSquare = Content.template($ => ({ skin: new Skin({ fill: $ }) })); -let sampleContainer = new Container(null, { +let sampleContainer = new Container(null, { active: true, top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), contents: [ @@ -1365,7 +1365,7 @@ This event is triggered when a `transition` object starts in the specified `cont **`onTransitionEnded(container)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `container` | `container` | The `container` object that triggered the event This event is triggered when a `transition` object ends in the specified `container` object. @@ -1384,14 +1384,14 @@ Applications use `content` objects for graphical parts of their user interface, ##### `Content([behaviorData, dictionary])` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `behaviorData` | `*` | A parameter that is passed into the `onCreate` function of this content's `behavior`. This may be any type of object, including `null` or a dictionary with arbitrary parameters. | `dictionary` | `object` | An object with properties to initialize the result. Only parameters specified in the [Dictionary](#content-dictionary) section below will have an effect; other parameters will be ignored. Returns a `content` instance, an object that inherits from `Content.prototype` ```javascript -let sampleContent = new Content("Hello", { +let sampleContent = new Content("Hello", { top: 0, right: 50, height: 100, width: 100, skin: new Skin({fill: "blue"}), Behavior: class extends Behavior { @@ -1404,7 +1404,7 @@ application.add(sampleContent); ```  - + ##### `Content.template(anonymous)` | Arguments | Type | Description @@ -1414,7 +1414,7 @@ application.add(sampleContent); Returns a constructor, a function that creates instances of `Content.prototype`. The `prototype` property of the result is `Content.prototype`. The result also provides a `template` function. ```javascript -let SampleContent = Content.template($ => ({ +let SampleContent = Content.template($ => ({ height: 100, width: 100, skin: new Skin({fill: $.color}), Behavior: class extends Behavior { @@ -1437,7 +1437,7 @@ application.add(new SampleContent({color: "blue"})); | `active` | `boolean` | If `true`, this content can be touched; that is, it triggers touch events. | | `anchor` | `string` | Creates an anchor, a reference to the created `content` object in the instantiating data | `backgroundTouch ` | `boolean` | If `true`, this container receives any touch events that are received by its contents; that is, it will trigger touch events when one of its contents has been touched. -| `Behavior` | `function` | A function that creates instances of `Behavior.prototype`; generally a class that extends the `Behavior` class. This content will create an instance of this `behavior`, set its `behavior` parameter to the created instance, and trigger the `onCreate` method. +| `Behavior` | `function` | A function that creates instances of `Behavior.prototype`; generally a class that extends the `Behavior` class. This content will create an instance of this `behavior`, set its `behavior` parameter to the created instance, and trigger the `onCreate` method. | `bottom` | `number` | This content's `bottom` coordinate, in pixels (setting `bottom` in the created instance's `coordinates` property) | `duration` | `number` |This content's duration, in milliseconds. This content triggers the `onFinished` event when its clock is running and its time equals its duration. | `exclusiveTouch` | `boolean` | If `true`, this content always captures touches; that is, `captureTouch` is implicitly invoked on `onTouchDown` for this content. Setting `exclusiveTouch` to `true` is equivalent to calling `captureTouch` in response to the `onTouchDown` event for every touch id. @@ -1462,7 +1462,7 @@ application.add(new SampleContent({color: "blue"})); #### Prototype Description -Prototype inherits from `Object.prototype`. +Prototype inherits from `Object.prototype`. ##### Properties @@ -1491,14 +1491,14 @@ Prototype inherits from `Object.prototype`. | `previous` | `object` | | ✓ | The previous `content` object in this content's container; `null` if this content is the first `content` object of this content's container or if this content has no container | `running` | `boolean` | | ✓ | If `true`, this content's clock is running. | `size` | `object` | | | This content's size, as an object with `width` and `height` number properties, specified in pixels -| `skin` | `skin` | `null` | | This content's skin or `null` +| `skin` | `skin` | `null` | | This content's skin or `null` `state` | `number` | 0 | | This content's state. If this content's skin defines states, setting the state changes the appearance of this content. | `style` | `style` | `null` | |This content's style or `null` | `time` | `number` | 0 | |This content's time, in milliseconds. When its time is set, this content triggers the `onTimeChanged` event. | `variant` | `number` | 0 | |This content's variant. If this content's skin defines variants, setting the variant changes the appearance of this content. | `visible` | `boolean` | `true` | |If `true`, this content is visible. | `width` | `number` | | |This content's width, in pixels -| `x` | `number` | | | This content's global x position. If this content is unbound, the getters return `undefined` and the setters are ignored. +| `x` | `number` | | | This content's global x position. If this content is unbound, the getters return `undefined` and the setters are ignored. | `y` | `number` | | |This content's global y position. If this content is unbound, the getters return `undefined` and the setters are ignored. @@ -1507,7 +1507,7 @@ Prototype inherits from `Object.prototype`. **`bubble(id [, ...])`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `id` | `string` | The name of the event to trigger | `...` | `*` | Zero or more extra parameters @@ -1542,7 +1542,7 @@ application.add(outerContainer); **`captureTouch(id, x, y, ticks)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `id` | `number` | The identifier of the touch | `x, y` | `number` | The global position of the touch, in pixels | `ticks` | `number` | The global time of the touch @@ -1559,7 +1559,7 @@ class BlueBehavior extends Behavior { trace("Blue touch ended\n"); } } -let blueCapturingContent = new Content(null, { +let blueCapturingContent = new Content(null, { active: true, top: 25, left: 25, height: 50, width: 50, skin: new Skin({fill: "blue"}), Behavior: BlueBehavior @@ -1576,7 +1576,7 @@ class RedBehavior extends Behavior { trace("Red touch ended\n"); } } -let redContainer = new Container(null, { +let redContainer = new Container(null, { active: true, backgroundTouch: true, top: 0, left: 0, height: 100, width: 100, skin: new Skin({fill: "red"}), @@ -1693,8 +1693,8 @@ Returns this content if this content is active, bound, and contains the position > Note that this function should only be used after a content has been measured and fitted; otherwise it will always return `undefined`. ```javascript -let sampleContent = new Content(null, { - active: true, top: 0, left: 0, height: 100, width: 100, +let sampleContent = new Content(null, { + active: true, top: 0, left: 0, height: 100, width: 100, skin: new Skin({fill: "blue"}), Behavior: class extends Behavior { onDisplaying(content) { @@ -1706,7 +1706,7 @@ let sampleContent = new Content(null, { ``` *** - + **`measure()`** Returns the [measured size](#measured-size) of this content, as an object with `width` and `height` parameters. @@ -1714,8 +1714,8 @@ Returns the [measured size](#measured-size) of this content, as an object with ` Example 1: ```javascript -let sampleContent = new Content(null, { - top: 0, left: 0, height: 100, width: 100, +let sampleContent = new Content(null, { + top: 0, left: 0, height: 100, width: 100, skin: new Skin({fill: "blue"}) }); application.add(sampleContent); @@ -1728,7 +1728,7 @@ let fittedWidth = sampleContent.width; // 100 Example 2: ```javascript -let sampleContent = new Content(null, { +let sampleContent = new Content(null, { top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({fill: "blue"}) }); @@ -1740,24 +1740,24 @@ let fittedWidth = sampleContent.width; // 240 (assuming running on 240x320 scr ``` *** - + **`moveBy(x, y)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `x, y` | `number` | The deltas by which to move this content, in pixels Moves this content as specified by the parameters. If the content's coordinates constrain its position, the `moveBy` function ignores the corresponding horizontal or vertical deltas. ```javascript -let unconstrainedContent = new Content(null, { +let unconstrainedContent = new Content(null, { top: 0, left: 0, height: 100, width: 100, skin: new Skin({fill: "blue"}), }); application.add(unconstrainedContent); unconstrainedContent.moveBy(100,100); // Moves unconstrainedContent 100 pixels in the x and y directions -let constrainedContent = new Content(null, { +let constrainedContent = new Content(null, { top: 0, left: 0, bottom: 140, right: 220, skin: new Skin({fill: "red"}), }); @@ -1778,14 +1778,14 @@ constrainedContent.moveBy(100,100); // Does nothing Sizes this content as specified by the parameters. If this content's coordinates constrain its size, the `sizeBy` function ignores the corresponding horizontal or vertical deltas. ```javascript -let unconstrainedContent = new Content(null, { +let unconstrainedContent = new Content(null, { top: 0, left: 0, height: 100, width: 100, skin: new Skin({fill: "blue"}), }) application.add(unconstrainedContent); -unconstrainedContent.sizeBy(100,100); // Makes unconstrainedContent 100 pixels wider and taller +unconstrainedContent.sizeBy(100,100); // Makes unconstrainedContent 100 pixels wider and taller -let constrainedContent = new Content(null, { +let constrainedContent = new Content(null, { top: 0, left: 0, bottom: 140, right: 220, skin: new Skin({fill: "red"}), }) @@ -1815,7 +1815,7 @@ class SampleBehavior extends Behavior { content.state = state; } } -let sampleContent = new Content(null, { +let sampleContent = new Content(null, { height: 100, width: 100, skin: new Skin({fill: ["red", "orange", "yellow", "green"]}), Behavior: SampleBehavior @@ -1849,7 +1849,7 @@ class SampleBehavior extends Behavior { content.start(); } } -let sampleContent = new Content(null, { +let sampleContent = new Content(null, { active: true, height: 100, width: 100, skin: new Skin({ fill: ["blue", "white"]}), Behavior: SampleBehavior @@ -1862,7 +1862,7 @@ application.add(sampleContent); #### Events -The following standard events are triggered by `content` objects. +The following standard events are triggered by `content` objects. **`onCreate(content, data, context)`** @@ -1908,10 +1908,10 @@ This event is triggered when the time of the specified `content` object changes. **`onTouchBegan(content, id, x, y, ticks)`** **`onTouchCancelled(content, id)`** - + **`onTouchEnded(content, id, x, y, ticks)`** - -**`onTouchMoved(content, id, x, y, ticks)`** + +**`onTouchMoved(content, id, x, y, ticks)`** | Argument | Type | Description | | --- | --- | :--- | @@ -1929,9 +1929,9 @@ These events are triggered when the specified `content` object is active and tou The `die` object is a `layout` object that allows you to “die cut” its contents with a region, minimizing the areas to invalidate and to update. These are useful for building animations and transitions on constrained devices that cannot update every screen pixel at every frame. -The `die` object maintains two regions: +The `die` object maintains two regions: -- the work region that the available operations build, +- the work region that the available operations build, - the clip region that clips the contents of the `die` object Both regions are initially empty. @@ -1957,15 +1957,15 @@ let sampleDie = new Die(null, { } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] }); let sampleScreenWithDie = new Container(null, { - left:0, right:0, top:0, bottom:0, + left:0, right:0, top:0, bottom:0, contents: [ Content(null, { top: 0, bottom: 120, left: 0, right: 0, @@ -2001,15 +2001,15 @@ let SampleDie = Die.template($ => ({ } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] })); let sampleScreenWithDie = new Container(null, { - left:0, right:0, top:0, bottom:0, + left:0, right:0, top:0, bottom:0, contents: [ Content(null, { top: 0, bottom: 0, left: 0, right: 0, @@ -2060,8 +2060,8 @@ let sampleContainer = new Container(null, { } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] @@ -2084,8 +2084,8 @@ application.add(sampleContainer); Binds the `die` object to the containment hierarchy by replacing the specified `content` object in the content's container with this `die` object and adding the `content` object to this `die` object. ```javascript -let whiteScreen = new Content(null, { - left:0, right:0, top:0, bottom:0, +let whiteScreen = new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), Behavior: class extends Behavior { onDisplaying(content) { @@ -2098,8 +2098,8 @@ let whiteScreen = new Content(null, { } } }); -let blueScreen = new Content(null, { - left:0, right:0, top:0, bottom:0, +let blueScreen = new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "blue" }), }); application.add(whiteScreen); @@ -2120,8 +2120,8 @@ Copies the work region into the current region, and invalidates only the differe Unbind this `die` object from the content hierarchy by removing the first `content` object from this `die` object and replacing this `die` object in its container with the removed `content` object. ``` -let whiteScreen = new Content(null, { - active: true, left:0, right:0, top:0, bottom:0, +let whiteScreen = new Content(null, { + active: true, left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), Behavior: class extends Behavior { onTouchBegan(content) { @@ -2139,8 +2139,8 @@ let whiteScreen = new Content(null, { } } }); -let blueScreen = new Content(null, { - active: true, left:0, right:0, top:0, bottom:0, +let blueScreen = new Content(null, { + active: true, left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "blue" }), }); application.add(whiteScreen); @@ -2184,8 +2184,8 @@ let sampleContainer = new Container(null, { } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] @@ -2202,7 +2202,7 @@ application.add(sampleContainer); **`set(x, y, width, height)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `x, y, width, height` | `number` | A local rectangle, in pixels Sets the work region to the rectangle and returns `this`. @@ -2220,8 +2220,8 @@ let sampleContainer = new Container(null, { } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] @@ -2238,7 +2238,7 @@ application.add(sampleContainer); **`sub(x, y, width, height)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `x, y, width, height` | `number` | A local rectangle, in pixels @@ -2260,8 +2260,8 @@ let sampleContainer = new Container(null, { } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] @@ -2278,7 +2278,7 @@ application.add(sampleContainer); **`xor(x, y, width, height)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `x, y, width, height` | `number` | A local rectangle, in pixels Exclusively unions the work region with the rectangle and returns `this`. @@ -2297,8 +2297,8 @@ let sampleContainer = new Container(null, { } }, contents: [ - new Content(null, { - left:0, right:0, top:0, bottom:0, + new Content(null, { + left:0, right:0, top:0, bottom:0, skin: new Skin({ fill: "white" }), }), ] @@ -2313,7 +2313,7 @@ application.add(sampleContainer); ### Image Object - **Source code:** [`piuImage.c`][30] -- **Relevant Examples:** [images][31] +- **Relevant Examples:** [images][31] The `image` object is a `content` object that displays images. @@ -2417,7 +2417,7 @@ Prototype inherits from `Content.prototype`. - **Source code:** [`piuLabel.c`][8] - **Relevant Examples:** [cards][24], [keyboard][20] -The `label` object is a `content` object that renders a string on a single line with a single style. The string is truncated if it does not fit the bounds of the `label` object. +The `label` object is a `content` object that renders a string on a single line with a single style. The string is truncated if it does not fit the bounds of the `label` object. #### Constructor Description @@ -2433,7 +2433,7 @@ Returns a `label` instance, an object that inherits from `Label.prototype` ```javascript let sampleStyle = new Style({ font:"600 28px Open Sans", color: "blue" }); let sampleLabel = new Label(null, { - top: 0, bottom: 0, left: 0, right: 0, + top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), style: sampleStyle, string: "Hello, World!" }); @@ -2607,7 +2607,7 @@ Same as for `container` object (see [Events](#container-events) in the section [ | `layout` | `object` | The `layout` object that triggered the event | `width` | `number` | The fitted width of the `layout` object, in pixels -This event is triggered when the [fitted width](#fitted-size) of the `layout` object is calculated. Once this is triggered, the behavior can modify the coordinates of its contents. Returns the fitted width of the `layout` object, in pixels. +This event is triggered when the [fitted width](#fitted-size) of the `layout` object is calculated. Once this is triggered, the behavior can modify the coordinates of its contents. Returns the fitted width of the `layout` object, in pixels. *** @@ -2721,22 +2721,22 @@ Prototype inherits from `Content.prototype`. **`drawContent(x, y, width, height) `** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `x, y, width, height` | `number` | The local position and size of the area in which to draw, in pixels Draws this port's skin in the position specified ```javascript -let heartSkin = new Skin({ - texture: new Texture("heart.png"), +let heartSkin = new Skin({ + texture: new Texture("heart.png"), color: "red", - x: 0, y: 0, width: 60, height: 60, + x: 0, y: 0, width: 60, height: 60, }); let sampleStyle = new Style({ font:"600 28px Open Sans", color: ["red", "yellow", "green", "blue"] }); let samplePort = new Port(null, { top: 0, bottom: 0, left: 0, right: 0, - skin: heartSkin, + skin: heartSkin, Behavior: class extends Behavior { onDraw(port) { let size = 60; @@ -2757,7 +2757,7 @@ application.add(samplePort); **`drawLabel(string, x, y, width, height)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `string ` | `string ` | The string to draw | `x, y, width, height` | `number` | The local position and size of the area in which to draw, in pixels @@ -2786,7 +2786,7 @@ application.add(samplePort); **`drawSkin(skin, x, y, width, height [, variant, state])`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `skin ` | `skin ` | The skin to draw | `x, y, width, height` | `number` | The local position and size of the area in which to draw, in pixels | `variant` | `number` | The variant of the skin to draw. If the specified skin defines variants, setting the variant changes the appearance. @@ -2795,10 +2795,10 @@ application.add(samplePort); Draws the skin the way a `content` instance would, with the state, variant, and position specified. ```javascript -let heartSkin = new Skin({ - texture: new Texture("heart.png"), +let heartSkin = new Skin({ + texture: new Texture("heart.png"), color: ["red", "blue"], - x: 0, y: 0, width: 60, height: 60, + x: 0, y: 0, width: 60, height: 60, }); let samplePort = new Port(null, { @@ -2806,7 +2806,7 @@ let samplePort = new Port(null, { skin: new Skin({ fill: "white" }), Behavior: class extends Behavior { onDraw(port) { - port.drawSkin(heartSkin, 20, 20, 60, 60, 0, 1); + port.drawSkin(heartSkin, 20, 20, 60, 60, 0, 1); } } }) @@ -2820,7 +2820,7 @@ application.add(samplePort); **`drawString(string, style, color, x, y, width, height)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `string` | `string` | The string to draw | `style` | `style` | The style to use to draw the string | `color` | `string` | The color to draw the string, as a string of the form specified in the [Color](#color) section of this document @@ -2850,7 +2850,7 @@ application.add(samplePort); **`drawStyle(string, style, x, y, w, h [, ellipsis, state])`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `string` | `string` | The string to draw | `style` | `style` | The style to use to draw the string | `x, y, width, height` | `number` | The local position and size of the area in which to draw, in pixels @@ -2863,7 +2863,7 @@ Draws a string with the style, position, and state specified. let sampleStyle = new Style({ font:"600 28px Open Sans", color: ["red", "yellow", "green", "blue"] }); let samplePort = new Port(null, { top: 0, bottom: 0, left: 0, right: 0, - skin: new Skin({ fill: "white" }), + skin: new Skin({ fill: "white" }), Behavior: class extends Behavior { onDraw(port) { let string = "Hello, World!"; @@ -2947,7 +2947,7 @@ application.add(samplePort); **`fillTexture(texture, color, x, y, width, height, sx, sy, sw, sh)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `texture ` | `texture` | The filling image | `x, y, width, height` | `number` | The destination area--the local position and size of the area to copy pixels to, in pixels | `sx, sy, sw, sh` | `number` | The source area--the position and size of the area to copy pixels from, in pixels. @@ -2979,7 +2979,7 @@ application.add(samplePort); **`invalidate([x, y, width, height])`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `x, y, width, height` | `number` | The local position and size of the area to invalidate, in pixels Invalidates the specified area of this port (or the entire port if no area is specified), which triggers the `onDraw` event. @@ -3011,7 +3011,7 @@ application.add(samplePort); **`measureString(string, style)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `string` | `string` | The string to measure | `style` | `style` | The style to use when measuring the string @@ -3055,7 +3055,7 @@ Restores the current clip rectangle from this port's clip rectangles stack **`pushClip([x, y, width, height])`** | Argument | Type | Description | -| --- | --- | --- +| --- | --- | --- | `x, y, width, height` | `number` | The local position and size of the clip rectangle Saves the specified clip rectangle to this port's clip rectangles stack @@ -3186,7 +3186,7 @@ import { VerticalScrollerBehavior } from "scroller"; // See "scroller.js" from t let sampleStyle = new Style({ font:"600 28px Open Sans", color: "white" }); let scrollerSample = new Scroller(null, { - left: 0, right: 0, top: 0, bottom: 0, + left: 0, right: 0, top: 0, bottom: 0, style: sampleStyle, skin: new Skin({ fill: "blue" }), active: true, backgroundTouch: true, clip: true, Behavior: VerticalScrollerBehavior, @@ -3233,7 +3233,7 @@ let ScrollerSample = Scroller.template($ => ({ })); let screenWithScrollerSample = new Column(null, { top: 0, bottom: 0, left: 0, right: 0, - style: sampleStyle, + style: sampleStyle, contents: [ Text(null, { top: 0, height: 40, left: 0, right: 0, @@ -3294,7 +3294,7 @@ let ScrollerItem = Label.template($ => ({ style: sampleStyle, string: "Item" + $ })); let scrollerSample = new Scroller(null, { - left: 0, right: 0, top: 0, bottom: 0, + left: 0, right: 0, top: 0, bottom: 0, skin: new Skin({ fill: "black" }), Behavior: SampleScrollerBehavior, contents:[ @@ -3340,7 +3340,7 @@ let ColoredSquare = Content.template($ => ({ skin: new Skin({ fill: $ }) })); let scrollerSample = new Scroller(null, { - left: 0, right: 0, top: 0, bottom: 0, + left: 0, right: 0, top: 0, bottom: 0, skin: new Skin({ fill: "black" }), active: true, backgroundTouch: true, clip: true, Behavior: SampleScrollerBehavior, @@ -3389,7 +3389,7 @@ let ColoredSquare = Content.template($ => ({ } })); let scrollerSample = new Scroller(null, { - left: 0, right: 0, top: 0, bottom: 0, + left: 0, right: 0, top: 0, bottom: 0, skin: new Skin({ fill: "black" }), contents:[ Column(null, { @@ -3420,10 +3420,10 @@ Same as for `container` object (see [Events](#container-events) in the section [ ##### `onScrolled(scroller)` | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `scroller` | `scroller` | The `scroller` object that triggered the event -This event is triggered when the specified `scroller` object scrolls. +This event is triggered when the specified `scroller` object scrolls. When triggered by a scroller, this event is also triggered by all the contents of the scroller. This makes it easier to implement scrollbars, for example. @@ -3468,7 +3468,7 @@ application.add(borderedContent); ##### `Skin.template([dictionary])` | Arguments | Type | Description -| --- | --- | --- +| --- | --- | --- | `dictionary` | `object` | An object with properties to initialize the result. Only parameters specified in the [Dictionary](#skin-dictionary) section below will have an effect; other parameters will be ignored. Returns a constructor, a function that creates instances of `Skin.prototype`. The `prototype` property of the result is `Skin.prototype`. @@ -3619,7 +3619,7 @@ Sound.close(); **`play([stream, repeat, callback]) `** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `stream` | `number` | The stream to play the sound on. Defaults to `0`. | `repeat` | `number` | The number of times to repeat the sound. Defaults to `1`. Set the `repeat` property to `Infinity` to repeat the sound indefinitely. | `callback` | `function` | An optional callback function to invoke after the audio resource completes playback. @@ -3631,7 +3631,7 @@ Plays the audio sample on the specified stream `repeat` times. If the `callback` sampleSound.play(); // Play sampleSound 5 times -sampleSound.play(0, 5); +sampleSound.play(0, 5); // Play sampleSound once and print to the console when finished sampleSound.play(0, 1, () => { @@ -3661,7 +3661,7 @@ Returns `style` instance, an object that inherits from `Style.prototype` ```javascript let sampleStyle = new Style({ font:"600 28px Open Sans", color: "blue" }); let sampleLabel = new Label(null, { - top: 0, bottom: 0, left: 0, right: 0, + top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), style: sampleStyle, string: "Hello, World!" }); @@ -3682,12 +3682,12 @@ Returns a constructor, a function that creates instances of `Style.prototype`. T let RedStyle = Style.template({ font:"600 28px Open Sans", color: "red" }); let BlueStyle = Style.template({ font:"600 28px Open Sans", color: "blue" }); let sampleLabel = new Label(null, { - top: 0, height:30, left: 0, right: 0, + top: 0, height:30, left: 0, right: 0, skin: new Skin({ fill: "white" }), Style: RedStyle, string: "Hello, World!" // Note the capital "S" in "Style" }); let sampleLabel2 = new Label(null, { - top: 30, height: 30, left: 0, right: 0, + top: 30, height: 30, left: 0, right: 0, skin: new Skin({ fill: "white" }), style: new BlueStyle, string: "Hello, World!" // Note the lowercase "s" in "style" }); @@ -3731,7 +3731,7 @@ application.add(sampleLabel2); #### Prototype Description Prototype inherits from `Object.prototype`. - + ##### Properties All properties of a `style` object are read-only, but you can change the style of content objects at any time. @@ -3773,7 +3773,7 @@ let size = normalStyle.measure("Moddable"); // {"width":134,"height":38} ``` *** - + ### Text Object - **Source code:** [`piuText.c`][15] @@ -3964,7 +3964,7 @@ Returns a `texture` instance, an object that inherits from `Object.prototype` const logoTexture = new Texture({ path: "logo.png" }); const logoSkin = new Skin({ texture: logoTexture, x: 0, y: 0, width: 100, height: 20 }); ``` - + ##### `Texture.template(dictionary)` | Argument | Type | Description | @@ -3990,7 +3990,7 @@ const AnotherLogoSkin = Skin.template({ texture: new AnotherLogoTexture(), x: 0, | Parameter | Type | Description | | --- | --- | :--- | | `path` | `string` | The URL of the image file. It must be a file URL. - + #### Prototype Description Prototype inherits from `Object.prototype`. @@ -3999,7 +3999,7 @@ Prototype inherits from `Object.prototype`. | Name | Type | Read Only | Description | | --- | --- | --- | :--- | -| `height` | `number` | ✓ | This texture's height, in physical pixels +| `height` | `number` | ✓ | This texture's height, in physical pixels | `width` | `number` | ✓ | This texture's width, in physical pixels ### Timeline Object @@ -4043,14 +4043,14 @@ let timeline = new Timeline(); ##### Functions - **`from(target, fromProperties, duration, [easing, delay])`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `target` | `object` | The object that will have its properties tweened by the timeline. | `fromProperties` | `object` | The keys of this object are the properties of the `target` object that will be tweened by the timeline. Their values are the starting values the properties of the `target` object will have at the begining of the tween. | `duration` | `number` | The duration of the tween in ms. @@ -4064,7 +4064,7 @@ Returns this timeline, useful for chaining together multiple `to`, `from`, and ` ```javascript let sampleStyle = new Style({ font: "600 28px Open Sans", color: ["blue", "white"] }); let sampleColumn = new Column(null, { - top: 0, bottom: 0, left: 0, right: 0, + top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), style: sampleStyle, contents: [ Label(null, { top: 90, height: 28, left: 80, string: "Hello", state: 0 }), @@ -4093,7 +4093,7 @@ application.add(sampleColumn); **`on(target, onProperties, duration, easing, delay, when)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `target` | `object` | The object that will have its properties tweened by the timeline. | `onProperties` | `object` | The keys of this object are the properties of the `target` object that will be tweened by the timeline. Their values are arrays of values that the tween will ease between over the duration of the timeline. | `duration` | `number` | The duration of the tween in ms. @@ -4142,7 +4142,7 @@ application.add(sampleContainer); **`seekTo(time)`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `time` | `number` | The position in the Timeline to seek to. Causes this timeline to jump its tweens to the specified time. This sets the properties of the tweens' target objects. @@ -4150,7 +4150,7 @@ Causes this timeline to jump its tweens to the specified time. This sets the pro **`to(target, toProperties, duration, [easing, delay])`** | Argument | Type | Description | -| --- | --- | :--- | +| --- | --- | :--- | | `target` | `object` | The object that will have its properties tweened by the timeline. | `toProperties` | `object` | The keys of this object are the properties of the `target` object that will be tweened by the timeline. Their values are the destination values the properties of the `target` object will have when the tween is complete. | `duration` | `number` | The duration of the tween in ms. @@ -4164,7 +4164,7 @@ Returns this timeline, useful for chaining together multiple `to`, `from`, and ` ```javascript let sampleStyle = new Style({ font: "600 28px Open Sans", color: ["blue", "white"] }); let sampleColumn = new Column(null, { - top: 0, bottom: 0, left: 0, right: 0, + top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: "white" }), style: sampleStyle, contents: [ Label(null, { top: 90, height: 28, left: 80, string: "Hello", state: 0 }), @@ -4195,7 +4195,7 @@ application.add(sampleColumn); - **Source code:** [`piuTransition.c`][17] - **Relevant Examples:** N/A -The `transition` object is used to animate modifications of the containment hierarchy. +The `transition` object is used to animate modifications of the containment hierarchy. #### Constructor Description @@ -4241,11 +4241,11 @@ class SwitchScreenBehavior extends Behavior { } } let ColoredScreen = Container.template($ => ({ - top: 0, bottom: 0, left: 0, right: 0, + top: 0, bottom: 0, left: 0, right: 0, skin: new Skin({ fill: $.color }), contents: [ Content($, { - active: true, height: 100, width: 100, + active: true, height: 100, width: 100, skin: new Skin({ fill: $.nextColor }), Behavior: SwitchScreenBehavior }) diff --git a/documentation/readme.md b/documentation/readme.md index 05107e0c14..1e7ca919d6 100644 --- a/documentation/readme.md +++ b/documentation/readme.md @@ -22,10 +22,10 @@ Guides for working with specific microcontrollers supported by the Moddable SDK The JavaScript APIs for the modules in the Moddable SDK are documented in the following files: - [**Base**](./base/base.md): Fundamental runtime capabilities including time, timer, debug, instrumentation, and UUID - - [**Setup**](./base/setup.md): Using `setup` modules to configure a host before other modules execute - - [**Worker**](./base/worker.md): Using Web Workers and Shared Workers + - [**Setup**](./base/setup.md): Using `setup` modules to configure a host before other modules execute + - [**Worker**](./base/worker.md): Using Web Workers and Shared Workers - [**Commodetto**](./commodetto/commodetto.md): Bitmap graphics library including parsing and rendering of BMP, JPEG, and PNG images, and BMFont files; classes for operating on bitmaps, and pixel format conversion - - [**Poco**](./commodetto/poco.md): Examples and reference for using the JavaScript and C APIs of the Poco renderer + - [**Poco**](./commodetto/poco.md): Examples and reference for using the JavaScript and C APIs of the Poco renderer - [**Crypt**](./crypt/crypt.md): Cryptographic primitives - [**Data**](./data/data.md): Base64 and hex encoding and decoding - [**Files**](./files/files.md): Storage capabilities including files, flash, preferences, resources, and ZIP diff --git a/documentation/tools/defines.md b/documentation/tools/defines.md index 9c67fc304f..84f4381193 100644 --- a/documentation/tools/defines.md +++ b/documentation/tools/defines.md @@ -82,8 +82,8 @@ To support option #defines, the driver implementation provides default values an #define MODDEF_ILI9341_FLIPY (false) #endif -Many deployments do not need to reset the ILI9341 display explicitly, as the automatic reset at power-up is sufficient. The reset pin has a behavior which is only implemented when the reset pin is defined in the manifest. - +Many deployments do not need to reset the ILI9341 display explicitly, as the automatic reset at power-up is sufficient. The reset pin has a behavior which is only implemented when the reset pin is defined in the manifest. + #ifdef MODDEF_ILI9341_RST_PIN SCREEN_RST_INIT; SCREEN_RST_ACTIVE; diff --git a/documentation/tools/manifest.md b/documentation/tools/manifest.md index 3b290af634..6831adb342 100644 --- a/documentation/tools/manifest.md +++ b/documentation/tools/manifest.md @@ -75,22 +75,22 @@ When you build an application, the default output directory name is taken from t "NAME": "balls" } ``` - + #### ESP32-specific environment variables The `esp32` platform object supports a number of optional environment variables applications can use to customize the Moddable SDK build for ESP32 devices: | Variable | Description | -| --- | :--- | +| --- | :--- | | `ESP32_SUBCLASS` | If a device other than the `esp32`, set `esp32s2`, `esp32s3` or `esp32c3` -| `SDKCONFIGPATH` | Pathname to a directory containing custom [sdkconfig defaults](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#custom-sdkconfig-defaults) entries. +| `SDKCONFIGPATH` | Pathname to a directory containing custom [sdkconfig defaults](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#custom-sdkconfig-defaults) entries. | `PARTITIONS_FILE` | Pathname to a [partition table](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html) in CSV format. | `BOOTLOADERPATH` | Pathname to a directory containing a custom [ESP-IDF bootloader component](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/bootloader.html#custom-bootloader). | `C_FLAGS_SUBPLATFORM` | C compiler flags to use when compiling Moddable SDK sources. -| `USE_USB` | Configure the device to use the USB port for programming and debugging. +| `USE_USB` | Configure the device to use the USB port for programming and debugging. > Note: This document does not cover native code ESP32 and ESP-IDF build details. Refer to the [ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/v4.2/esp32/get-started/index.html) for additional information. - + #### `ESP32_SUBCLASS` The target ESP32 subclass for a build is specified using the `ESP32_SUBCLASS` property. @@ -239,12 +239,12 @@ The default value of the `"include"` property is `"manifest.json"`. The `"includ { "git":"$(URL)/test0.git" }, - { - "git":"$(URL)/test1.git", + { + "git":"$(URL)/test1.git", "include":"modules/test1/manifest.json" }, - { - "git":"$(URL)/test23.git", + { + "git":"$(URL)/test23.git", "include": [ "test2/module.json", "test3/module.json" @@ -391,8 +391,8 @@ The `strip` object in a manifest is a string or array that specifies which built ```json "strip": "*", ``` - -- If you only want certain objects or functions to be stripped, pass in an array of JavaScript class and function names. Items in the array will be stripped. Anything not included in the array will not be stripped. + +- If you only want certain objects or functions to be stripped, pass in an array of JavaScript class and function names. Items in the array will be stripped. Anything not included in the array will not be stripped. The following strips the `RegExp` class, `eval` function, and the two `Array` reduce functions. @@ -408,7 +408,7 @@ The `strip` object in a manifest is a string or array that specifies which built - You can also specify that specific items be stripped in addition to anything unused. The `"*"` means to strip everything unused. Because the two `Array` reduce functions are explicitly listed, they will also be stripped, whether or not they are used. - + ```json "strip": [ "*", @@ -743,8 +743,8 @@ The second pass matches files with the properties of the combined `modules` and There are no extensions: -- In the `modules` object, `mcconfig` matches `.c`, `.cc`, `.cpp`, `.h`, `.js` and `.m` files. -- In the `resources` object, `mcconfig` matches `.act`, `.bmp`, `.cct`, `.dat`, `.der`, `.fnt`, `.jpg`, `.json`, `.nfnt`, `.pk8`, `.png`, `.rle`, `.ski` and `.ttf` files. +- In the `modules` object, `mcconfig` matches `.c`, `.cc`, `.cpp`, `.h`, `.js` and `.m` files. +- In the `resources` object, `mcconfig` matches `.act`, `.bmp`, `.cct`, `.dat`, `.der`, `.fnt`, `.jpg`, `.json`, `.nfnt`, `.pk8`, `.png`, `.rle`, `.ski` and `.ttf` files. ### Generate diff --git a/documentation/tools/testing.md b/documentation/tools/testing.md index 00b5fb4688..593a9455a0 100644 --- a/documentation/tools/testing.md +++ b/documentation/tools/testing.md @@ -52,11 +52,11 @@ The TEST262 tests are located in a repository on GitHub. git clone https://github.com/tc39/test262 ``` -> Note: The `xst` tool may be used to [run test262 tests](../xs/xst.md#test262) on the local computer from the command line. +> Note: The `xst` tool may be used to [run test262 tests](../xs/xst.md#test262) on the local computer from the command line. ### Moddable SDK Tests -The Moddable SDK tests are a suite of tests created by Moddable to validate the correctness and consistency the implementations across different device targets. The tests cover a wide range of functionality including hardware I/O, networking, graphics, data, and more. Because of differences in hardware capabilities and features supported in each port, not all tests will pass in all environments. +The Moddable SDK tests are a suite of tests created by Moddable to validate the correctness and consistency the implementations across different device targets. The tests cover a wide range of functionality including hardware I/O, networking, graphics, data, and more. Because of differences in hardware capabilities and features supported in each port, not all tests will pass in all environments. The Moddable SDK tests are located in the Moddable SDK repository at `$MODDABLE/tests`. @@ -117,7 +117,7 @@ Clicking to the left of a category or individual test selects that test or categ
-You may also use the `SELECT` text field to type in the name of the test(s) that you would like to run.
+You may also use the `SELECT` text field to type in the name of the test(s) that you would like to run.
### Run Tests
@@ -210,7 +210,7 @@ flags: [module]
assert.sameValue("Java" + "Script", "JavaScript");
```
-The `module` flag tells the test runner that the test should loaded as an ECMAScript module, not a program. If the `module` flag is not present, the test is run as a program. All tests written for the Moddable SDK should include the `module` flag because nearly all scripts in the Moddable SDK are executed as modules.
+The `module` flag tells the test runner that the test should loaded as an ECMAScript module, not a program. If the `module` flag is not present, the test is run as a program. All tests written for the Moddable SDK should include the `module` flag because nearly all scripts in the Moddable SDK are executed as modules.
In addition to flags, the frontmatter may contain a short description of the test or a longer informational section:
@@ -226,7 +226,7 @@ flags: [module]
---*/
```
-The frontmatter is required. If it is not present, the test script will not be executed. If the frontmatter is incorrect, the test script may not run correctly.
+The frontmatter is required. If it is not present, the test script will not be executed. If the frontmatter is incorrect, the test script may not run correctly.
By convention, the copyright notice appears immediately before or after the frontmatter, but always before the test script.
@@ -330,7 +330,7 @@ flags: [module,async]
$TESTMC.timeout(500, "timeout on promise resolve");
```
-Asynchronous tests are more difficult to write than synchronous tests, just as asynchronous code is more challenging to write than synchronous code When getting started, take care and try to follow the patterns of existing tests that already work.
+Asynchronous tests are more difficult to write than synchronous tests, just as asynchronous code is more challenging to write than synchronous code When getting started, take care and try to follow the patterns of existing tests that already work.
### Assertions
@@ -413,7 +413,7 @@ The tests in TEST262 itself are are often just a few lines of code. Keeping test
### Minimize Assumptions about the Environment
-Each test is run in a fresh virtual machine. This helps to ensure consistent test results because each test executes independently of the tests that ran before it. But there are limits to how much a test can be isolated from those that ran earlier.
+Each test is run in a fresh virtual machine. This helps to ensure consistent test results because each test executes independently of the tests that ran before it. But there are limits to how much a test can be isolated from those that ran earlier.
A test for the file system will create, delete, and modify files. Such tests should clean-up after themselves, by removing any temporary files. However, this is imperfect. If the test fails, it will not have a chance to clean-up. Therefore, in general tests should be written so they work even if previous tests did not properly clean-up.
@@ -469,7 +469,7 @@ Image checksums also work with screens generated by the Piu user interface frame
```js
/*---
-description:
+description:
flags: [module]
---*/
import Bitmap from "commodetto/Bitmap";
@@ -498,7 +498,7 @@ The following test sends a touch begin event. The behavior confirms that the exp
```js
/*---
-description:
+description:
flags: [async, module]
---*/
class TouchTestBehavior extends $TESTMC.Behavior {
@@ -507,7 +507,7 @@ class TouchTestBehavior extends $TESTMC.Behavior {
assert.sameValue(x, 10);
assert.sameValue(y, 20);
$DONE();
- }
+ }
}
new Application(null, {
@@ -536,7 +536,7 @@ $TESTMC.timeout(5000, "dns lookup timeout");
```
#### `HostObject`, `HostObjectChunk`, `HostBuffer`
-These constructors are used to create host objects to pass as arguments to functions being tested.
+These constructors are used to create host objects to pass as arguments to functions being tested.
```js
new $TESTMC.HostObject // host object with pointer (-1) for storage
@@ -634,11 +634,11 @@ await screen.doTouchBegan(0, 100, 100, Time.ticks);
```
#### Test Configuration in `mc/config`
-The testmc manifest contains configuration values for on-device testing, such as hardware pin numbers and I/O ports. These values are used by tests, so that they may written to be independent of the device being tested. When running testmc on a new device, the configuration values for the device must be added to the manifest.
+The testmc manifest contains configuration values for on-device testing, such as hardware pin numbers and I/O ports. These values are used by tests, so that they may written to be independent of the device being tested. When running testmc on a new device, the configuration values for the device must be added to the manifest.
- `config.digital[]`
-An array of ECMA-419 digital pin specifiers.
+An array of ECMA-419 digital pin specifiers.
- `config.i2c`
@@ -654,7 +654,7 @@ An object with properties for SPI testing. `select` is the ECMA-419 pin specifie
- `config.invalidPins`
-An array of ECMA-419 pin specifiers that are invalid for the target device.
+An array of ECMA-419 pin specifiers that are invalid for the target device.
- `config.flashPartition`
diff --git a/documentation/tools/tools.md b/documentation/tools/tools.md
index e6f356f498..f9ba3cf925 100644
--- a/documentation/tools/tools.md
+++ b/documentation/tools/tools.md
@@ -6,7 +6,7 @@ Revised: March 23, 2023
This document describes the tools provided by Moddable to build, debug, and run JavaScript apps on microcontrollers or in the Moddable simulator.
-The tools compile and link JavaScript modules, and prepare assets for specific platforms and specific screens. The only tools you use directly are **mcconfig**, **mcrun**, and **xsbug**. The other tools are used indirectly, through the make file generated by **mcconfig** and **mcrun**, but are nevertheless presented here to help you understand what is happening under the hood.
+The tools compile and link JavaScript modules, and prepare assets for specific platforms and specific screens. The only tools you use directly are **mcconfig**, **mcrun**, and **xsbug**. The other tools are used indirectly, through the make file generated by **mcconfig** and **mcrun**, but are nevertheless presented here to help you understand what is happening under the hood.
To build the tools themselves, and to build and run apps in the Moddable simulator, you only need standard development tools. To build and run apps on microcontrollers, you also need the microcontrollers toolchains to compile and link C code, and to transfer apps to flash storage. See the [Getting Started document](../Moddable%20SDK%20-%20Getting%20Started.md) for full instructions on how to build the Moddable SDK tools.
@@ -24,7 +24,7 @@ To build the tools themselves, and to build and run apps in the Moddable simulat
## mcconfig
-**mcconfig** is a command line tool that generates a make file based on a manifest, then runs **make** to build and launch Moddable apps on microcontrollers or in the simulator.
+**mcconfig** is a command line tool that generates a make file based on a manifest, then runs **make** to build and launch Moddable apps on microcontrollers or in the simulator.
For example:
@@ -39,14 +39,14 @@ builds and launches the [balls example](../../examples/piu/balls) in the simulat
cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p esp/moddable_two
```
-
+
builds and launches the balls example on Moddable Two, and
```shell
cd $MODDABLE/examples/network/http/httpgetjson
mcconfig -d -m -p esp ssid="Public Wi-Fi"
```
-
+
configures an ESP8266 target device to connect to an open Wi-Fi access point called "Public Wi-Fi," then build and launch the httpgetjson example on the device.
A few notes:
@@ -70,7 +70,7 @@ mcconfig [manifest] [-d] [-f format] [-i] [-m] [-o directory] [-p platform] [-r
- `-x`: overrides the default host and port (localhost:5002) debug builds use to connect to xsbug.
- `-m`: to run `make` automatically, otherwise **mcconfig** just generates the make file.
- `-o directory`: the output directory. Defaults to the `$MODDABLE/build` directory.
-- `-p platform`: to select the platform. Consult the documentation for your device target for its platform identifier. The supported values include: `esp`, `esp/moddable_one`, `esp/moddable_three`, `esp32`, `esp32/moddable_two`, `win`, `lin`, `mac`, `sim/moddable_one`, `sim/moddable_two`, `sim/moddable_three`, and `wasm`. Defaults to the host build platform:`mac`, `win` or `lin`.
+- `-p platform`: to select the platform. Consult the documentation for your device target for its platform identifier. The supported values include: `esp`, `esp/moddable_one`, `esp/moddable_three`, `esp32`, `esp32/moddable_two`, `win`, `lin`, `mac`, `sim/moddable_one`, `sim/moddable_two`, `sim/moddable_three`, and `wasm`. Defaults to the host build platform:`mac`, `win` or `lin`.
- `-r rotation`: to select the screen rotation: `0`, `90`, `180` or `270`. Defaults to `0`. See [png2bmp](#png2bmp) for more detail.
- `-t target`: to select the build target: `build`, `deploy`, `xsbug`, `clean`, or `all`. Defaults to `all`. See [Build Targets](#buildtargets) for more detail.
- `-v`: to trace all commands executed by `make`
@@ -169,7 +169,7 @@ png2bmp balls.png -o ~/Desktop -f gray256 -r 90
### Arguments
-```text
+```text
png2bmp file.png [-a] [-c] [f format] [-o directory] [-r rotation]
```
@@ -182,7 +182,7 @@ png2bmp file.png [-a] [-c] [f format] [-o directory] [-r rotation]
## xsc
-**xsc** is the XS compiler, a command line tool that compiles files containing JavaScript source code (usually stored in a file with a `.js` extension) into XS binary files containing symbols and byte codes.
+**xsc** is the XS compiler, a command line tool that compiles files containing JavaScript source code (usually stored in a file with a `.js` extension) into XS binary files containing symbols and byte codes.
By default **xsc** parses the JavaScript file as an ECMAScript module. Optionally, for compatibility and conformance, **xsc** can parse the JavaScript file as an ECMAScript program. Moddable apps only use ECMAScript modules.
@@ -201,7 +201,7 @@ The `Point` class creates host objects. The `Point_destructor` C function is cal
Without the `-e` option, **xsc** generates C code that declares XS symbols and the interface of the host functions. Such C code can then be compiled and linked with the implementation of the host functions to build a dynamic library.
-With the `-e` option, **xsc** embeds the references to host functions and host objects into the XS binary file. It is the linker, **xsl**, that generates C code for all the modules. That is how Moddable apps work.
+With the `-e` option, **xsc** embeds the references to host functions and host objects into the XS binary file. It is the linker, **xsl**, that generates C code for all the modules. That is how Moddable apps work.
### Arguments
@@ -223,7 +223,7 @@ xsc file [-c] [-d] [-e] [-o directory] [-p] [-r name] [-t directory]
**xsl** is the XS linker, a command line tool that links several XS binary files into one XS archive file, and generates C code that declares XS symbols and the interface of the host functions.
-With the `-p` option, **xsl** can also preload modules and generate C code that defines a read-only XS virtual machine suitable to be cloned to run apps. That is how Moddable apps work.
+With the `-p` option, **xsl** can also preload modules and generate C code that defines a read-only XS virtual machine suitable to be cloned to run apps. That is how Moddable apps work.
The C code can then be compiled and linked with the implementation of the host functions to build a dynamic library or an executable.
@@ -234,9 +234,9 @@ xsl files... [-a name] [-b directory] [c creation] [-o directory] [-p modules]..
```
- `files`: the paths of the XS binary files to link.
-- `-a name`: the name of the XS archive file. Defaults to `a`.
+- `-a name`: the name of the XS archive file. Defaults to `a`.
- `-b directory`: the path of the base directory. Defaults to the output directory. The names of the modules in the archive are the paths of the XS binary files, relative to the base directory. It is an error to link XS binary files which are not directly or indirectly inside the base directory.
-- `-c creation`: the parameters used to create the cloned machines.
+- `-c creation`: the parameters used to create the cloned machines.
- `-o directory`: the path of the output directory. Defaults to the current directory.
- `-p module`: the name of a module to preload. Use one `-p module` option by module to preload.
- `-r name`: the name of the output file. Defaults to `mc`.
@@ -297,7 +297,7 @@ The shell script, the app archive folder, and the app archive file are located i
### Arguments
```text
-mcbundle [manifest] [-d] [-m] [-o directory]
+mcbundle [manifest] [-d] [-m] [-o directory]
```
- `manifest`: the manifest file. Defaults to the `manifest.json` file in the current directory.
diff --git a/documentation/xs/ROM Colors.md b/documentation/xs/ROM Colors.md
index 7c269fc0e5..9b6d25caf0 100644
--- a/documentation/xs/ROM Colors.md
+++ b/documentation/xs/ROM Colors.md
@@ -6,7 +6,7 @@ Revised: August 12, 2020
In XS, instances are mostly linked list of properties with a key and a value. To get a value by key, the runtime iterates the linked list to find a property with a matching key.
-Of course XS already implements several optimizations to access properties by index: in array instances, in closures, in global and local scopes.
+Of course XS already implements several optimizations to access properties by index: in array instances, in closures, in global and local scopes.
The XS linker prepares most classes, objects, prototypes, functions to be accessed straightly from ROM. Such instances and their properties never change. That is an opportunity to access properties by index, especially since iterating a linked list in ROM is not optimal.
@@ -22,7 +22,7 @@ The technique is based on graph coloring. Similar techniques are applied to obje
When intrinsics and all modules are preloaded, the XS linker traverses all instances and their properties to build a conflict graph. The nodes are the keys, the edges are the conflicts. Two keys conflict if there is an instance that has properties for both keys. Choosing indexes for keys is equivalent to coloring nodes in the graph.
-Once the graph is colored, each key has a color that can be used to access a property by index.
+Once the graph is colored, each key has a color that can be used to access a property by index.
property = instance[key.color]
@@ -30,9 +30,9 @@ Since non conflicting keys can reuse the same color, the runtime has to check if
if (property.key == key)
return property
-
-Optimal graph coloring could be complex, but coloring from the most to the least conflicted key usually gives good enough results: the number of colors is significantly smaller than the number of keys.
-
+
+Optimal graph coloring could be complex, but coloring from the most to the least conflicted key usually gives good enough results: the number of colors is significantly smaller than the number of keys.
+
## Memory Layout
What remains to be done is to reorganize the ROM so properties are where the color of their key wants them to be.
@@ -97,11 +97,11 @@ Eventually instances are moved to fill the holes.
Now the two objects are intertwined to reduce the memory footprint. There are usually enough instances without properties or with a few properties to fill all holes.
-> Despite all movements, the order of the linked lists is maintained. That is required by several object traversal functions.
+> Despite all movements, the order of the linked lists is maintained. That is required by several object traversal functions.
## Results
-Here is a simple test.
+Here is a simple test.
const math = Math;
const now = Date.now();
@@ -115,7 +115,7 @@ Here is a simple test.
-The `Math` object is in ROM and its `imul`, `max`, `min` and `sign` properties are accessed 100000 times. The `Math` object is cached into a `const` to avoid the interference of global scope optimizations, the properties are selected to avoid floating point operations.
+The `Math` object is in ROM and its `imul`, `max`, `min` and `sign` properties are accessed 100000 times. The `Math` object is cached into a `const` to avoid the interference of global scope optimizations, the properties are selected to avoid floating point operations.
Here are results without and with the optimization:
diff --git a/documentation/xs/XS Compartment.md b/documentation/xs/XS Compartment.md
index 86aa576fd2..ae887dd678 100644
--- a/documentation/xs/XS Compartment.md
+++ b/documentation/xs/XS Compartment.md
@@ -8,9 +8,9 @@ XS implements most of the [TC39 Compartment Proposal](https://github.com/tc39/pr
In XS, the real host is the application that creates an XS machine to evaluate scripts and import modules.
-Compartments are lightweight virtual hosts that evaluate scripts and import modules separately from the real host and from other compartments.
+Compartments are lightweight virtual hosts that evaluate scripts and import modules separately from the real host and from other compartments.
-Compartments have their own `globalThis` object, their own global lexical scope and their own module map.
+Compartments have their own `globalThis` object, their own global lexical scope and their own module map.
> The module map binds module specifiers to modules. Inside compartments like inside the real host, the same module specifier always imports the same module.
@@ -22,8 +22,8 @@ By default:
Compartments run in the same XS machine:
-- Except for `Compartment`, `Function` and `eval`, built-ins are shared.
-- Other objects can be shared thru the `globals` and `globalLexicals` options.
+- Except for `Compartment`, `Function` and `eval`, built-ins are shared.
+- Other objects can be shared thru the `globals` and `globalLexicals` options.
- Modules can be shared thru the `modules`, `loadHook` and `loadNowHook` options.
For the sake of security, it is the responsibility of a real host that creates compartments to ensure that shared features are immutable.
@@ -49,13 +49,13 @@ XS implements compartments natively, without `Module` and `Evaluators` classes,
#### Compartment(options)
-Returns a compartment, an instance of `Compartment.prototype`.
+Returns a compartment, an instance of `Compartment.prototype`.
If present, the `options` argument must be an object with optional properties: `globals`, `globalLexicals`, `modules`, `loadHook`, `loadNowHook`, `resolveHook`.
#### options.globals
-The `globals` option adds properties to the compartment `globalThis` object.
+The `globals` option adds properties to the compartment `globalThis` object.
If defined, the value of the `globals` option must be an object.
@@ -67,12 +67,12 @@ A compartment does not keep a reference to the `globals` object.
The `globalLexicals` option initializes the compartment global lexical scope.
-If defined, the value of the `globalLexicals` option must be an object.
+If defined, the value of the `globalLexicals` option must be an object.
Each own enumerable named property of the `globalLexicals ` object become a variable or a constant:
- property names are variable or constant names,
-- property values are variable or constant values.
+- property values are variable or constant values.
If the property is writable, a variable (`let`) is created, else a constant (`const`) is created.
@@ -82,7 +82,7 @@ A compartment does not keep a reference to the `globalLexicals` object.
The `modules` option initializes the compartment module map.
-If defined, the value of the `modules` option must be an object.
+If defined, the value of the `modules` option must be an object.
Each own enumerable named property of the `modules` object creates an entry in the compartment module map:
@@ -99,7 +99,7 @@ The `loadHook` option is an asynchronous function that takes a module specifier
The `loadHook` function is only called directly or indirectly by `Compartment.prototype.import` if the module map of the compartment has no entry for a module specifier.
-The `loadHook` function is useful if the module descriptor is unavailable when constructing the compartment, or to create a module descriptor dynamically.
+The `loadHook` function is useful if the module descriptor is unavailable when constructing the compartment, or to create a module descriptor dynamically.
A compartment keeps a reference to the `loadHook` function.
@@ -109,7 +109,7 @@ The `loadNowHook` option is a function that takes a module specifier and returns
The `loadNowHook` function is only called directly or indirectly by `Compartment.prototype.importNow` if the module map of the compartment has no entry for a module specifier.
-The `loadNowHook ` function is useful if the module descriptor is unavailable when constructing the compartment, or to create a module descriptor dynamically.
+The `loadNowHook ` function is useful if the module descriptor is unavailable when constructing the compartment, or to create a module descriptor dynamically.
A compartment keeps a reference to the `loadNowHook ` function.
@@ -173,7 +173,7 @@ The initial value of this property is the `"Compartment"` string.
Returns a module source, an instance of `ModuleSource.prototype`.
-The source argument is coerced into a string, then parsed as a module and compiled into byte codes.
+The source argument is coerced into a string, then parsed as a module and compiled into byte codes.
XS does not keep a reference to the `source` string.
@@ -201,7 +201,7 @@ The initial value of this property is the `"ModuleSource"` string.
### Module Descriptor
-Comparments can load and initialize module namespaces from module descriptors. Like property descriptors, module descriptors are ordinary objects with various forms.
+Comparments can load and initialize module namespaces from module descriptors. Like property descriptors, module descriptors are ordinary objects with various forms.
#### descriptors with `source`, `importMeta` and `specifier` properties
@@ -213,26 +213,26 @@ Comparments can load and initialize module namespaces from module descriptors. L
If the `importMeta` property is present, its value must be an object. The default `importMeta` object is an empty object.
-Compartments copy the `importMeta` object properties into the module `import.meta` object like `Object.assign`.
+Compartments copy the `importMeta` object properties into the module `import.meta` object like `Object.assign`.
If the `specifier` property is present, its value is coerced into a string and becomes the referrer specifier of the module.
#### descriptors with `namespace` and `compartment` properties
-- If fhe value of the `namespace` property is a string, the descriptor shares a module to be loaded and initialized by the compartment referred by the `compartment` property.
+- If fhe value of the `namespace` property is a string, the descriptor shares a module to be loaded and initialized by the compartment referred by the `compartment` property.
- If the `compartment` property is present, its value must be a compartment.
- If absent, the `compartment` property defaults to the compartment being constructed in the `modules` option, or being hooked in the `loadHook` and `loadNowHook` options.
-
+
- Else if the value of the `namespace ` property is a module namepace, the descriptor shares a module that is already available.
- Else the value of `record` property must be an object. The module is loaded and initialized from the object according to the [virtual module namespace](#VirtualModuleNamespace) pattern.
-
+
#### descriptor with `archive` and `path` properties
-To construct a static module record from a [mod](./mods.md). In Moddable runtime, mods are separate archives of modules and resources.
+To construct a static module record from a [mod](./mods.md). In Moddable runtime, mods are separate archives of modules and resources.
-- The `archive` property must be an archive.
+- The `archive` property must be an archive.
- The `path` property is coerced into a string then used to find the module in the archive.
### Module Binding
@@ -240,7 +240,7 @@ To construct a static module record from a [mod](./mods.md). In Moddable runtime
A module binding is an ordinary object with properties that mimick the `import` and `export` constructs. There are many forms of module bindings. See the
[imports](https://tc39.es/ecma262/#table-import-forms-mapping-to-importentry-records) and [exports](https://tc39.es/ecma262/#table-export-forms-mapping-to-exportentry-records) tables.
-Most bindings can be represented as JSON-like objects with `export`, `import`, `as`, `from` properties. Except `*` bindings, which requires special forms because module namespace identifiers can be arbitrary.
+Most bindings can be represented as JSON-like objects with `export`, `import`, `as`, `from` properties. Except `*` bindings, which requires special forms because module namespace identifiers can be arbitrary.
| Construct | Module Binding |
| :--- | :--- |
@@ -253,13 +253,13 @@ Most bindings can be represented as JSON-like objects with `export`, `import`, `
| import x from "mod" | { import: "default", as: "x", from: "mod" }
| import { x } from "mod" | { import: "x", from: "mod" }
| import { x as y } from "mod" | { import: "x", as: "y", from: "mod" }
-| import * as star from "mod" | { importAllFrom: "mod", as: "star" }
+| import * as star from "mod" | { importAllFrom: "mod", as: "star" }
### Virtual Module Source
A virtual module source is an ordinary object with `execute`, `bindings`, `needsImport` and `needsImportMeta` properties
-- The `execute` property must be a function.
+- The `execute` property must be a function.
- If defined, the `bindings` property must be an array of [module bindings](#ModuleBinding). The default is an empty array.
- If defined, the `needsImport` property is coerced into a boolean. The default is `false`.
- If defined, the `needsImportMeta` property is coerced into a boolean. The default is `false`.
@@ -272,7 +272,7 @@ Once the module is loaded and linked, the compartment calls the `execute` functi
- `Import`: a function equivalent to the `import` call in a module body. The argument is `undefined` if `needsImport` was false.
- `ImportMeta`: an object equivalent to the `import.meta` object in a module body. The argument is `undefined` if `needsImportMeta` was false.
-The module environment record is sealed:
+The module environment record is sealed:
- no properties can be created or deleted,
- export properties are writable,
@@ -285,4 +285,4 @@ Like a module body, the `execute` function can be asynchronous.
A virtual module namespace is an ordinary object posing as a module namespace.
-When a compartment loads a virtual module namespace, each own enumerable named property of the object becomes an exported property of the module.
+When a compartment loads a virtual module namespace, each own enumerable named property of the object becomes an exported property of the module.
diff --git a/documentation/xs/XS Conformance.md b/documentation/xs/XS Conformance.md
index f0faea92d5..3f6500b281 100644
--- a/documentation/xs/XS Conformance.md
+++ b/documentation/xs/XS Conformance.md
@@ -14,7 +14,7 @@ XS does not implement ECMA-402, the Internationalization API Specification, so t
#### Annex B
-No XS hosts are web browsers, so the `annexB` tests are skipped. However XS implements `Date.prototype.getYear`, `Date.prototype.setYear`, `Object.prototype.__defineGetter__`, `Object.prototype.__defineSetter__`, `Object.prototype.__lookupGetter__`, `Object.prototype.__lookupSetter__`, `Object.prototype.__proto__`, `String.prototype.substr`, `escape` and `unescape`,
+No XS hosts are web browsers, so the `annexB` tests are skipped. However XS implements `Date.prototype.getYear`, `Date.prototype.setYear`, `Object.prototype.__defineGetter__`, `Object.prototype.__defineSetter__`, `Object.prototype.__lookupGetter__`, `Object.prototype.__lookupSetter__`, `Object.prototype.__proto__`, `String.prototype.substr`, `escape` and `unescape`,
## Runtime models
@@ -23,7 +23,7 @@ On microcontrollers, XS uses a runtime model based on a virtual machine prepared
Such a runtime model introduces no conformance issues in itself since XS can alias shared classes, functions and objects if apps modify them. However, in order to save ROM and RAM, other restrictions have been introduced:
- Host functions, i.e. functions implemented in C, are primitive values like booleans, numbers, strings, etc. They are promoted to `Function` objects when necessary.
-- Scripts evaluation is optional. So some platforms do not support `eval`, `new Function`, etc. But all platforms support `JSON.parse`.
+- Scripts evaluation is optional. So some platforms do not support `eval`, `new Function`, etc. But all platforms support `JSON.parse`.
- Optionnally the XS linker can dead strip ECMAScript built-ins that Moddable apps do not use, and remove `length` and `name` properties from functions.
Here the conformance is tested on macOS with a traditional runtime model and without any restrictions. For each case, XS creates a virtual machine, then parses and runs the script. The XS harness, `xst`, uses [LibYAML](http://pyyaml.org/wiki/LibYAML) to load the frontmatter, which contains, among other information, the harness scripts to parse and run before the case script itself.
@@ -34,17 +34,17 @@ To build `xst`:
cd $MODDABLE/xs/makefiles/lin
make
-
+
#### macOS
cd $MODDABLE/xs/makefiles/mac
make
-
+
#### Windows
cd %MODDABLE%\xs\makefiles\win
build
-
+
To pass some tests, clone [test262](https://github.com/tc39/test262.git) and change the directory to the `test` directory inside the `test262` directory. Then you can run `xst` with files or directories. For instance:
cd ~/test262/test
@@ -1481,7 +1481,7 @@ Details are here under. The numbers of skipped cases are between parentheses. Th
## Failures
-Here under are the failed tests. The comments are primarily here for the sake of future versions of XS.
+Here under are the failed tests. The comments are primarily here for the sake of future versions of XS.
### Language
@@ -1512,19 +1512,19 @@ Assignments should rename functions only if the left hand side is an identifier.
The name of a function expression always defines a constant variable that reference the current function. In sloppy mode it should define a variable that can be assigned but does not change!
language/expressions/object/literal-property-name-bigint.js
-
+
XS does not support bigint as property name.
- language/expressions/super/call-proto-not-ctor.js
-
+ language/expressions/super/call-proto-not-ctor.js
+
XS checks if super is a constructor before evaluating arguments.
language/statements/class/subclass/default-constructor-spread-override.js
-
+
The default derived constructor should not use `%Array.prototype% @@iterator`
-
+
language/statements/for-await-of/head-lhs-async.js
-
+
`for (async of x)` is a syntax error but `for await (async of x)` should not be!
language/statements/try/tco-catch.js (strict)
@@ -1535,7 +1535,7 @@ XS does not tail call optimize `return` inside `catch`
language/expressions/assignment/target-member-computed-reference-undefined.js
language/identifier-resolution/assign-to-global-undefined.js
-To be investigated.
+To be investigated.
### Built-ins
@@ -1548,26 +1548,26 @@ To be investigated.
built-ins/RegExp/prototype/global/cross-realm.js
built-ins/RegExp/prototype/ignoreCase/cross-realm.js
built-ins/RegExp/prototype/multiline/cross-realm.js
- built-ins/RegExp/prototype/source/cross-realm.js
+ built-ins/RegExp/prototype/source/cross-realm.js
built-ins/RegExp/prototype/sticky/cross-realm.js
built-ins/RegExp/prototype/unicode/cross-realm.js
built-ins/Symbol/for/cross-realm.js
built-ins/Symbol/for/cross-realm.js
built-ins/Symbol/keyFor/cross-realm.js
built-ins/Symbol/keyFor/cross-realm.js
-
+
One realm.
-
+
built-ins/Array/prototype/reduceRight/length-near-integer-limit.js
built-ins/String/prototype/localeCompare/15.5.4.9_CE.js
built-ins/JSON/stringify/replacer-function-object-deleted-property.js
-
+
To be investigated.
built-ins/Function/prototype/toString/method-computed-property-name.js
Invalid test.
-
+
### Skipped cases
`xst` skips cases with the following features:
diff --git a/documentation/xs/XS Differences.md b/documentation/xs/XS Differences.md
index 6e9a39a878..85daa7024e 100644
--- a/documentation/xs/XS Differences.md
+++ b/documentation/xs/XS Differences.md
@@ -5,18 +5,18 @@ Revised: October 10, 2018
## Ultra-light JavaScript
XS is the JavaScript engine at the core of Moddable applications and tools. XS has existed since the beginning of this century. You can get the latest version on [GitHub](https://github.com/Moddable-OpenSource/moddable).
-Other JavaScript engines are primarily used for client or server side web development. Their main focus is speed, their main cost is the significant resources they consume to get that speed.
+Other JavaScript engines are primarily used for client or server side web development. Their main focus is speed, their main cost is the significant resources they consume to get that speed.
The XS engine targets embedded platforms built around microcontrollers like the [ESP8266](https://www.espressif.com/en/products/hardware/esp8266ex/overview) or [ESP32](https://www.espressif.com/en/products/hardware/esp32/overview). XS also runs on the usual desktop and mobile platforms.
The challenges of embedded development are well known: limited memory and limited performance. Compared to hardware that usually runs JavaScript for the web on the client or the server sides, the differences are measured in orders of magnitude, not percentages. Moreover battery life is often critical.
-Despite such constraints, and unlike other scripting libraries available on microcontrollers, XS always strives to fully implement the quite extensive [ECMAScript Language Specification](https://tc39.github.io/ecma262/).
+Despite such constraints, and unlike other scripting libraries available on microcontrollers, XS always strives to fully implement the quite extensive [ECMAScript Language Specification](https://tc39.github.io/ecma262/).
These constraints have consequences. This document highlights key differences between XS, with its focus on embedded devices, and JavaScript engines focused on web development.
## Spare runtime resources
-Embedded platforms do not exist alone. You need a computer to develop applications for them. Therefore, you should prepare in advance of execution, at *compile* time, everything you can in order to spare *run*-time resources.
+Embedded platforms do not exist alone. You need a computer to develop applications for them. Therefore, you should prepare in advance of execution, at *compile* time, everything you can in order to spare *run*-time resources.
On the web, JavaScript engines currently execute scripts and modules from their source code. For microcontrollers, the XS compiler transforms modules source code into byte code on your computer, so the XS engine on the microcontroller only has to execute byte code.
@@ -27,12 +27,12 @@ At Moddable, we generalized this approach beyond scripts to all kinds of assets.
Despite being based on JavaScript, embedded development with XS is more similar to mobile development than web development. Applications built with XS are described by a manifest and built with a tool chain that includes the XS compiler and linker, asset encoders, C compiler and linker, a debugger, and ROM flasher.
## Prepare the environment
-On embedded platforms, the amount of RAM is extremely small, often under 64 KB. The amount of ROM is larger, 512 KB to 4 MB, roughly the same amount of data downloaded for a typical modern web page. An application's native code and data are flashed into ROM.
+On embedded platforms, the amount of RAM is extremely small, often under 64 KB. The amount of ROM is larger, 512 KB to 4 MB, roughly the same amount of data downloaded for a typical modern web page. An application's native code and data are flashed into ROM.
JavaScript modules compiled to byte code and encoded assets are stored in flash ROM as part of the native data. This allows the byte code and assets to be used in place, rather than being copied to RAM first. For example, the XS engine executes byte code directly from ROM. Still, a significant amount of RAM is needed for the JavaScript environment your application runs in. For example:
-- JavaScript Built-ins including `Object`, `Function`, `Boolean`, `Symbol`, `Error`, `Number`, `Math`, `Date`, `String`, `RegExp`, `Array`, `TypedArray`, `Map`, `Set`, `WeakMap`, `WeakSet`, `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, `Atomics`, `JSON`, `Generator`, `AsyncGenerator`, `AsyncFunction`, `Promise`, `Reflect`, `Proxy`, etc.
-- Modules your application uses to do something useful, like a user interface framework, a secure network framework, etc.
+- JavaScript Built-ins including `Object`, `Function`, `Boolean`, `Symbol`, `Error`, `Number`, `Math`, `Date`, `String`, `RegExp`, `Array`, `TypedArray`, `Map`, `Set`, `WeakMap`, `WeakSet`, `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, `Atomics`, `JSON`, `Generator`, `AsyncGenerator`, `AsyncFunction`, `Promise`, `Reflect`, `Proxy`, etc.
+- Modules your application uses to do something useful, like a user interface framework, a secure network framework, etc.
Constructing built-ins and loading modules creates many classes, functions, and prototype objects. These objects often require more RAM than is present on a modest microcontroller.
@@ -41,7 +41,7 @@ To solve this problem, the XS linker allows you to prepare a JavaScript environm
The benefits are significant:
- Since almost nothing is ever copied from ROM to RAM, your application runs with a small amount of RAM.
-- Since everything is ready in ROM, your application boots instantaneously.
+- Since everything is ready in ROM, your application boots instantaneously.
> The XS linker cannot preload a module with a body that calls a native function that is only available on the microcontroller. Typically there will be only one module like that to start your application.
@@ -50,9 +50,9 @@ But what happens when applications want to modify objects that the XS linker pre
The XS engine maintains a a table of aliases which is initially empty. All aliasable objects in ROM have an index in that table. When an application modifies an aliasable object, the aliasable object is cloned into RAM and inserted into the table to override the aliasable object.
-Such a mechanism has a cost in memory footprint and performance, but is essential for conformance with the JavaScript language specification. However JavaScript has a feature to specify that an object cannot be modified: `Object.freeze`. When objects are frozen, the XS linker does not index them as aliasable.
+Such a mechanism has a cost in memory footprint and performance, but is essential for conformance with the JavaScript language specification. However JavaScript has a feature to specify that an object cannot be modified: `Object.freeze`. When objects are frozen, the XS linker does not index them as aliasable.
-Modules can use `Object.freeze` in their body to tell the XS linker which objects do not need to be indexed as aliasable. Calling that for each object is tedious enough, so the XS linker can automatically freeze all class, function and prototype objects, as well as other built-in objects like `Atomics`, `JSON`, `Math` and `Reflect`.
+Modules can use `Object.freeze` in their body to tell the XS linker which objects do not need to be indexed as aliasable. Calling that for each object is tedious enough, so the XS linker can automatically freeze all class, function and prototype objects, as well as other built-in objects like `Atomics`, `JSON`, `Math` and `Reflect`.
In ECMAScript parlance, that is related to a [frozen realm](https://github.com/tc39/proposal-frozen-realms).
@@ -63,7 +63,7 @@ As mentioned above, JavaScript defines many of built-ins, which are all implemen
Based on the byte code of your modules, the XS linker can strip unused native code from the XS engine itself. So your application will run its own version of the XS engine, tailored to reduce its ROM footprint.
-That is automatic for applications that are self-contained and updated as a whole, which is still common on embedded platforms for the sake of consistency, safety, and security.
+That is automatic for applications that are self-contained and updated as a whole, which is still common on embedded platforms for the sake of consistency, safety, and security.
For applications that expect to be customized or updated with separate modules, you can manually specify the built-in features to strip from the XS engine and to document the profiled JavaScript environment. For instance you can strip `eval`, `Function`, etc to get rid of the XS parser and byte coder.
@@ -77,7 +77,7 @@ Web development often claims to be "pure" Javascript while it is in fact relying
At Moddable, we use native code only when necessary, for instance to build drivers, or when the memory footprint or performance gains are obvious, for instance in our graphics library and user interface framework.
-Indeed a reasonable solution to sparing resources is to sometimes use native code instead of JavaScript. Remember that your application is in charge of everything.
+Indeed a reasonable solution to sparing resources is to sometimes use native code instead of JavaScript. Remember that your application is in charge of everything.
> Since the tool chain always requires compiling and linking native code, there is no overhead in your development cycle.
diff --git a/documentation/xs/XS Marshalling.md b/documentation/xs/XS Marshalling.md
index 7b89ef955d..cfbeff12d2 100644
--- a/documentation/xs/XS Marshalling.md
+++ b/documentation/xs/XS Marshalling.md
@@ -4,13 +4,13 @@ Revised: March 15, 2021
## Introduction
-To exchange data between machines that can run in separate threads, XS always supported marshalling thru the **XS in C** programming interface.
+To exchange data between machines that can run in separate threads, XS always supported marshalling thru the **XS in C** programming interface.
Even if you do not write C code, this document is useful if you write JavaScript code using the standard `Worker` programming interface provided by the [worker](../base/worker.md) module of the Moddable SDK.
## What Is Marshalling?
-Similar to what `JSON.stringify` and `JSON.parse` do with a string, *marshalling* creates a memory block from a JavaScript value and *demarshalling* creates a JavaScript value from a memory block. The format of the memory block is binary.
+Similar to what `JSON.stringify` and `JSON.parse` do with a string, *marshalling* creates a memory block from a JavaScript value and *demarshalling* creates a JavaScript value from a memory block. The format of the memory block is binary.
XS machines can be created from scratch or cloned from a read-only machine. Typically on micro-controllers, multiple small machines can be created in RAM based based on one large read-only machine in ROM.
@@ -34,10 +34,10 @@ When two machines are cloned from the same read-ony machinee, marshalling can ta
What can be exchanged between alien machines?
-Firstly, everything that can be exchanged thru JSON:
+Firstly, everything that can be exchanged thru JSON:
- `false`
-- `null`
+- `null`
- `true`
- numbers
- strings
@@ -49,9 +49,9 @@ Firstly, everything that can be exchanged thru JSON:
XS can also marshall other values not possible using JSON:
-- `undefined`
+- `undefined`
- bigints
-- instances of
+- instances of
- `Boolean`, `Error`, `EvalError`, `RangeError`, `ReferenceError`, `SyntaxError`, `TypeError`, `URIError`, `AggregateError`
- `Number`, `Date`
- `String`, `RegExp`
@@ -87,7 +87,7 @@ In these cases, XS tries to report a meaningful error:
catch {
}
-breaks into **xsbug** with
+breaks into **xsbug** with
main.js (2) # Break: (host): marshall [0].p.x: accessor!
@@ -110,7 +110,7 @@ Like what happens with `JSON.stringify` and `JSON.parse`, custom prototypes are
const o = new C();
trace(`${o.constructor.name}\n`); // C
worker.postMessage(o);
-
+
##### worker.js
self.onmessage = function(m) {
trace(`${m.constructor.name}\n`); // Object
@@ -126,7 +126,7 @@ But if custom prototypes are in the read-only machine, they are kept:
const o = new C();
trace(`${o.constructor.name}\n`); // C
worker.postMessage(o);
-
+
##### worker.js
self.onmessage = function(m) {
trace(`${m.constructor.name}\n`); // C
@@ -135,7 +135,7 @@ But if custom prototypes are in the read-only machine, they are kept:
### Private Fields
Similarly, private fields are ignored when marshalled.
-
+
##### main.js
class C {
#x;
@@ -148,7 +148,7 @@ Similarly, private fields are ignored when marshalled.
}
const o = new C("oops");
worker.postMessage(o);
-
+
##### worker.js
self.onmessage = function(m) {
trace(`${m.toString()}\n`); // [object Object]
@@ -166,12 +166,12 @@ Except when the class is in the read-only machine:
return this.#x;
}
}
-
+
##### main.js
import { C } from "preload";
const o = new C("wow");
worker.postMessage(o);
-
+
##### worker.js
self.onmessage = function(m) {
trace(`${m.toString()}\n`); // wow
@@ -187,7 +187,7 @@ References to instances in the read-only machine are preserved:
##### main.js
import { o } from "preload";
worker.postMessage({ o });
-
+
##### worker.js
import { o } from "preload";
self.onmessage = function(m) {
@@ -205,7 +205,7 @@ That is especially useful for exchanging references to objects with methods, lik
return Reflect.get(...arguments);
}
});
-
+
##### main.js
const target = {
message1: "hello",
@@ -213,7 +213,7 @@ That is especially useful for exchanging references to objects with methods, lik
};
import { handler } from "preload";
worker.postMessage(new Proxy(target, handler));
-
+
##### worker.js
self.onmessage = function(m) {
trace(`${m.message1}\n`); // hello
@@ -231,7 +231,7 @@ Like private fields, properties keyed by symbols are ignored when marshalled, ex
import { s } from "preload";
const o = { [s]: "wow" };
worker.postMessage(o);
-
+
##### worker.js
import { s } from "preload";
self.onmessage = function(m) {
diff --git a/documentation/xs/XS Platforms.md b/documentation/xs/XS Platforms.md
index 8ff9de9ea6..f4c64e1ce4 100644
--- a/documentation/xs/XS Platforms.md
+++ b/documentation/xs/XS Platforms.md
@@ -8,11 +8,11 @@ A platform is a combination of hardware and system software. For each platform,
Historically, XS used one interface file, `xsPlatform.h` splitting the implementation into two files: `xsPlatform.c` and `xsHost.c`. Many platforms shared the same interface and implementation files, based either on the KinomaJS platform abstraction, or on an adhoc platform abstraction for command line tools.
-Further, an XS machine had many ways to find and load modules and programs: from JS files, from stand alone compiled XSB files with or without companion DLL or SO files, and from a linked XSA file with a companion DLL or SO file... The XS platform was in charge of providing such options.
+Further, an XS machine had many ways to find and load modules and programs: from JS files, from stand alone compiled XSB files with or without companion DLL or SO files, and from a linked XSA file with a companion DLL or SO file... The XS platform was in charge of providing such options.
When we started working on microcontrollers, the main inspiration for XS platforms was the adhoc platform abstraction for command line tools, which was the most complex version.
-Today the XS runtime has been significantly streamlined, especially on microcontrollers. XS machines are always cloned from a read-only machine prepared by the XS linker. There are only modules, byte coded by the XS compiler. Modules are either preloaded or prepared to be loaded and unloaded at runtime.
+Today the XS runtime has been significantly streamlined, especially on microcontrollers. XS machines are always cloned from a read-only machine prepared by the XS linker. There are only modules, byte coded by the XS compiler. Modules are either preloaded or prepared to be loaded and unloaded at runtime.
Consequently, it is now much simpler to build an XS platform. This document describes the necessary interface and implementation files.
@@ -42,7 +42,7 @@ XS mostly relies on constants and functions from the C stantard library, accesse
#define c_free free
#define c_malloc malloc
//...
-
+
Such definitions, and the corresponding includes, are the most significant part of the interface file. The macros allows a platform to provide its own constants and functions. See any of the provided `xsPlatform.h` for the list of macros to define.
### ESP macros
@@ -52,7 +52,7 @@ The Xtensa instruction set and architecture, used most notably in microcontrolle
#define c_read8(POINTER) *((txU1 *)(POINTER))
#define c_read16(POINTER) *((txU2 *)(POINTER))
#define c_read32(POINTER) *((txU4 *)(POINTER))
-
+
#define ICACHE_FLASH_ATTR
#define ICACHE_RODATA_ATTR
#define ICACHE_XS6RO_ATTR
@@ -87,7 +87,7 @@ On Windows, the `mxMachinePlatform` macro adds the socket and message window han
The implementation file first includes `xsAll.h`, which contains the definitions of all XS macros and types, and the declarations of all XS extern functions. Then the platform has to implement the functions described here under.
-XS machines do not support multiple threads, though platforms can support multiple threads, each with their own XS machines. All calls and callbacks described here must happen in the thread that created or cloned the machine.
+XS machines do not support multiple threads, though platforms can support multiple threads, each with their own XS machines. All calls and callbacks described here must happen in the thread that created or cloned the machine.
The functions are grouped into meaningful sections. The xsPlatform.c file can also provide POSIX functions that the platform is missing.
@@ -112,7 +112,7 @@ The functions in this section are only necessary for the debug version of XS. Th
#ifdef mxDebug
// debug functions
#endif
-
+
If the platform does not support the communication with **xsbug**, functions in this section can be empty, except `fxIsConnected` and `fxIsReadable`, which must return `0`.
Communication between **xsbug** and the XS machine can be done over either a TCP/IP or serial connection. In the case of a TCP/IP connection, **xsbug** is the server and XS machines are clients. When using a serial connection, **xsbug** continues to communication over TCP/IP and a bridge running on the computer relays data between the serial and TCP connections. In the case of the ESP8266, this relay is performed by **serial2xsbug**.
@@ -150,7 +150,7 @@ On Windows the platform uses `WSAAsyncSelect` with the `WM_XSBUG` message:
- `void fxConnect(txMachine* the)`
-XS calls `fxConnect` to connect `the` machine to **xsbug**.
+XS calls `fxConnect` to connect `the` machine to **xsbug**.
For TCP/IP connections, platforms create a socket and connect it to **xsbug**. On Mac and Windows the address of **xsbug** is usually `localhost`, on other platforms it is usually defined by an environment variable. The port of **xsbug** defaults to `5002` by convention.
@@ -160,7 +160,7 @@ Machines are connect to **xsbug** after being created, i.e. `fxConnect` happens
- `void fxDisconnect(txMachine* the)`
-XS calls `fxDisconnect` to disconnect `the` machine from **xsbug**.
+XS calls `fxDisconnect` to disconnect `the` machine from **xsbug**.
For TCP/IP connections, platforms close the socket.
@@ -176,7 +176,7 @@ XS calls `fxIsConnected` to know if `the` machine is connected to **xsbug**.
- `txBoolean fxIsReadable(txMachine* the)`
-XS calls `fxIsReadable` to know if `the` machine received a message from **xsbug**. Platforms must return 1 or 0 depending on the availability of bytes to read.
+XS calls `fxIsReadable` to know if `the` machine received a message from **xsbug**. Platforms must return 1 or 0 depending on the availability of bytes to read.
The performance of the implementation of `fxIsReadable` is important since XS calls `fxIsReadable` at every `LINE` byte code (e.g. for each line of JavaScript source code executed).
@@ -184,7 +184,7 @@ The performance of the implementation of `fxIsReadable` is important since XS ca
- `void fxReceive(txMachine* the)`
-XS calls `fxReceive` to receive a message from **xsbug**. The implementation reads bytes into `the->debugBuffer` and sets `the->debugOffset` to the number of bytes received.
+XS calls `fxReceive` to receive a message from **xsbug**. The implementation reads bytes into `the->debugBuffer` and sets `the->debugOffset` to the number of bytes received.
XS calls `fxReceive` repeatedly until the entire message is received. The maximum number of bytes that can be read by `fxReceive` is `sizeof(the->debugBuffer) - 1`.
@@ -192,15 +192,15 @@ XS calls `fxReceive` repeatedly until the entire message is received. The maximu
- `void fxSend(txMachine* the, txBoolean more)`
-XS calls `fxSend` to send a message to **xsbug**. The implementation gets the number of bytes to send from `the->echoOffset` and write bytes from `the->echoBuffer`.
+XS calls `fxSend` to send a message to **xsbug**. The implementation gets the number of bytes to send from `the->echoOffset` and write bytes from `the->echoBuffer`.
-XS calls `fxSend ` repeatedly until the entire message is sent, `more` equals `1` while the message is incomplete, `0` when the message is complete.
+XS calls `fxSend ` repeatedly until the entire message is sent, `more` equals `1` while the message is incomplete, `0` when the message is complete.
--
### Eval
-The standard `eval` function, `Function` constructor and `Generator` constructor must transform source code into byte codes and keys.
+The standard `eval` function, `Function` constructor and `Generator` constructor must transform source code into byte codes and keys.
XS lets the platform decides is such feature is worth the memory it takes.
@@ -248,7 +248,7 @@ Keys are the names and symbols that XS uses to identify properties.
`fxBuildKeys` is called only when creating an XS machine, in order to initialize the default keys used by the standard ECMAScript host functions.
-On most platforms today, XS machines are cloned. The default keys are available and ready to be used in the read-only machine. So `fxBuildKeys` is never called and can be empty.
+On most platforms today, XS machines are cloned. The default keys are available and ready to be used in the read-only machine. So `fxBuildKeys` is never called and can be empty.
If the platform supports the creation of XS machines from scratch, `fxBuildKeys` must be implemented as:
@@ -271,7 +271,7 @@ If the platform supports the creation of XS machines from scratch, `fxBuildKeys`
### Memory
-XS machines use two heaps: the chunks heap and the slots heap.
+XS machines use two heaps: the chunks heap and the slots heap.
Chunks are blocks of variable size that the garbage collector can move to compact memory. XS stores strings, buffers, arrays, etc into chunks. On microcontrollers without a dedicated memory management unit, chunks are also useful to store any kind of data. For instance Piu uses chunks to store its containment hierarchy.
@@ -325,15 +325,15 @@ On platforms that support several ways to get modules, the implementation of `fx
- `txID fxFindModule(txMachine* the, txID moduleID, txSlot* slot)`
-XS calls `fxFindModule` to find an imported or required module.
+XS calls `fxFindModule` to find an imported or required module.
The `moduleID` argument is the importing or requiring module identifier. It is `XS_NO_ID` when the machine itself requires a module.
-The `slot` argument is the imported or required module name. It is the module specifier of the `import` syntactical construct or the module parameter of the `require` host function.
+The `slot` argument is the imported or required module name. It is the module specifier of the `import` syntactical construct or the module parameter of the `require` host function.
If the module is found, `fxFindModule` returns the module identifier, otherwise `fxFindModule` returns `XS_NO_ID`.
-A module identifier is a unique `txID`, but the platform defines the format of its corresponding key: it can be a path, a URL, a URI...
+A module identifier is a unique `txID`, but the platform defines the format of its corresponding key: it can be a path, a URL, a URI...
The platform defines also how the importing or requiring module identifier and the imported or required module name are merged. The usual convention is based on absolute (`/*`), relative (`./*`, `../*`) or search (*) paths.
@@ -349,15 +349,15 @@ Finding modules can involve looking for various kinds of files, using a set of p
txSlot *key;
txString slash;
txID id;
-
+
fxToStringBuffer(the, slot, name, sizeof(name));
if (!c_strncmp(name, "/", 1)) {
absolute = 1;
- }
+ }
else if (!c_strncmp(name, "./", 2)) {
dot = 1;
relative = 1;
- }
+ }
else if (!c_strncmp(name, "../", 3)) {
dot = 2;
relative = 1;
@@ -401,7 +401,7 @@ Finding modules can involve looking for various kinds of files, using a set of p
}
return XS_NO_ID;
}
-
+
txBoolean fxFindScript(txMachine* the, txString path, txID* id)
{
txPreparation* preparation = the->archive;
@@ -436,7 +436,7 @@ Preparing modules can involve reading and mapping files, parsing, scoping and by
txScript* script = fxLoadScript(the, path);
fxResolveModule(the, moduleID, script, C_NULL, C_NULL);
}
-
+
txScript* fxLoadScript(txMachine* the, txString path)
{
txPreparation* preparation = the->archive;
@@ -460,7 +460,7 @@ Promises are essentially asynchronous. The `then` method of a `Promise` object t
> *A Job is an abstract operation that initiates an ECMAScript computation when no other ECMAScript computation is currently in progress.* (ECMAScript® 2015 Language Specification, Section 8.4).
-XS takes care queuing and running Jobs but relies on platforms for their scheduling.
+XS takes care queuing and running Jobs but relies on platforms for their scheduling.
--
@@ -475,7 +475,7 @@ For instance on Mac the platform uses a run loop source and `CFRunLoopSourceSign
txMachine* the = info;
fxRunPromiseJobs(the);
}
-
+
void fxQueuePromiseJobs(txMachine* the)
{
CFRunLoopSourceSignal(the->promiseSource);
@@ -495,7 +495,7 @@ On Windows the platform uses a message window and `PostMessage`:
}
return 0;
}
-
+
void fxQueuePromiseJobs(txMachine* the)
{
PostMessage(the->window, WM_PROMISE, 0, 0);
@@ -529,7 +529,7 @@ Applications that use `Atomics.wait` and `Atomics.wake` must call `xsTerminateSh
void* fxCreateSharedChunk(txInteger byteLength);
-`fxCreateSharedChunk` allocates a shared chunk, `byteLength` is the size of its data, which must be initialised to zero.
+`fxCreateSharedChunk` allocates a shared chunk, `byteLength` is the size of its data, which must be initialised to zero.
Typically platforms use a reference count to track how many machines are referencing the shared chunk. `fxCreateSharedChunk` must initialise the reference count to one.
@@ -537,7 +537,7 @@ Typically platforms use a reference count to track how many machines are referen
void fxLockSharedChunk(void* data);
-`fxLockSharedChunk` locks the shared chunk, `data` is a pointer to the data of the shared chunk.
+`fxLockSharedChunk` locks the shared chunk, `data` is a pointer to the data of the shared chunk.
`fxLockSharedChunk` is never called if the platform supports GCC atomics.
@@ -551,7 +551,7 @@ Machines call `fxReleaseSharedChunk` when they do not reference the shared chunk
Typically platforms use an atomic operation to decrement the reference count of the shared chunk and free the shared chunk when the reference count is zero.
-`fxReleaseSharedChunk` is the destructor of the host slot.
+`fxReleaseSharedChunk` is the destructor of the host slot.
void* fxRetainSharedChunk(void* data);
@@ -561,7 +561,7 @@ Typically platforms use an atomic operation to increment the reference count of
void fxUnlockSharedChunk(void* data);
-`fxUnlockSharedChunk` unlocks the shared chunk. `data` is a pointer to the data of the shared chunk.
+`fxUnlockSharedChunk` unlocks the shared chunk. `data` is a pointer to the data of the shared chunk.
`fxUnlockSharedChunk` is never called if the platform supports GCC atomics.
@@ -569,11 +569,11 @@ Typically platforms use an atomic operation to increment the reference count of
If the application did not call `fxInitializeSharedCluster` or if the current thread is the thread that called `fxInitializeSharedCluster`, `fxWaitSharedChunk` throws a `TypeError` object.
-If the 32-bit signed integer at `byteOffset` in `data` is not equal to `value`, `fxWaitSharedChunk` returns `-1` immediately. Else `fxWaitSharedChunk` suspends the current thread.
+If the 32-bit signed integer at `byteOffset` in `data` is not equal to `value`, `fxWaitSharedChunk` returns `-1` immediately. Else `fxWaitSharedChunk` suspends the current thread.
If a matching call to `fxWakeSharedChunk` resumed the thread, `fxWaitSharedChunk` returns `1`. A matching call is a call with the same `data` and `byteOffset`.
-If `timeout` expired, `fxWaitSharedChunk` returns `0`. `timeout` is a number between `Date.now()` and `C_INFINITY`.
+If `timeout` expired, `fxWaitSharedChunk` returns `0`. `timeout` is a number between `Date.now()` and `C_INFINITY`.
txInteger fxWakeSharedChunk(txMachine* the, void* data, txInteger byteOffset, txInteger count);
diff --git a/documentation/xs/XS Profiler.md b/documentation/xs/XS Profiler.md
index 4786ae16f4..7a0f3bff08 100644
--- a/documentation/xs/XS Profiler.md
+++ b/documentation/xs/XS Profiler.md
@@ -5,13 +5,13 @@ The XS profiler is a sample based JavaScript profiler. The XS profiler also repo
There are two implementations of the profiler:
-- **Instrument**: XS sends profile records and samples to **xsbug**. The instrument profiler is used by Moddable SDK applications in the simulator and on devices.
+- **Instrument**: XS sends profile records and samples to **xsbug**. The instrument profiler is used by Moddable SDK applications in the simulator and on devices.
> Build XS with `mxInstrument` defined.
-- **File**: XS accumulates profile records and samples in RAM then saves them into a [`.cpuprofile`](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#type-Profile) file. The file profiler is used by command line tools including **xst** and **xsnap**.
+- **File**: XS accumulates profile records and samples in RAM then saves them into a [`.cpuprofile`](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#type-Profile) file. The file profiler is used by command line tools including **xst** and **xsnap**.
-> Build XS with `mxProfile` defined and xsProfile.c included.
+> Build XS with `mxProfile` defined and xsProfile.c included.
Both profilers require debugging information, so scripts must be built with debugging enabled. The instrument profiler requires a connection to **xsbug**. Therefore, profiling is only supported in builds of XS with debugging support enabled.
@@ -33,7 +33,7 @@ for (let i = 0; i < 10; i++) {
```
For function instances, the profile ID is stored in the ID of the internal home slot. For function primitives, the profile ID is stored in the slot itself. This approach means that profile IDs require no additional RAM or storage space. All debug builds are ready to be profiled.
-
+
The profile ID of the host is 0. The profile ID of the garbage collector is 1. For newly created machines, function profile IDs start incrementing from 2; for cloned machines, from the profile ID stored in the preparation.
### Record
@@ -47,7 +47,7 @@ A profile record is created for each function observed to run during a profile s
Profile records are only stored once by the file profiler and only sent once to **xsbug** by the instrument profiler.
-The home slot allows function identifiers to be more detailed for function instances (`Array.prototype.push`) than for function primitives (`push`).
+The home slot allows function identifiers to be more detailed for function instances (`Array.prototype.push`) than for function primitives (`push`).
### Sample
@@ -56,7 +56,7 @@ A profile sample is created for each sample taken during a profile session. The
- Time delta: microseconds since the last sample.
- Profile ID stack: sequence of profile ID in stack order. The first profile ID is the function hit by the profiler. The last profile ID is always the host (0).
-For each sample, The instrument profiler simply sends the sample to **xsbug**, which updates the call graph and the durations of the profile records. The file profiler updates the call graph and stores the time delta and the first profile ID.
+For each sample, The instrument profiler simply sends the sample to **xsbug**, which updates the call graph and the durations of the profile records. The file profiler updates the call graph and stores the time delta and the first profile ID.
### Time
@@ -78,12 +78,12 @@ Both the instrument and file profilers allocate their buffers outside the XS hea
The instrument profiler uses:
-- A bitmap to remember which profile records have already been sent to **xsbug**, i.e. one bit for each profile ID.
+- A bitmap to remember which profile records have already been sent to **xsbug**, i.e. one bit for each profile ID.
- Buffers for profile samples. The size of the buffers is the size of the XS stack divided by the size of a frame and multiplied by the size of a profile ID.
### File Profiler
-The file profiler uses growing buffers to store profile records and samples.
+The file profiler uses growing buffers to store profile records and samples.
## How To Use
@@ -109,7 +109,7 @@ Use the `xsStartProfiling` and `xsStopProfiling` macros to start and stop the pr
Because you can open the `.cpuprofile` file created by the File Profiler with at least three different applications, you get somewhat different views of the same data.
-In the three viewers, the first column is the "Self Time", the second column is the "Total Time".
+In the three viewers, the first column is the "Self Time", the second column is the "Total Time".
Google Chrome DevTools and xsbug can toggle between a "Bottom Up" viewer (from callees to callers) and a "Top Down" viewer (from callers to callees).
diff --git a/documentation/xs/XS in C.md b/documentation/xs/XS in C.md
index c2e2f8bb75..36b61a8f6c 100644
--- a/documentation/xs/XS in C.md
+++ b/documentation/xs/XS in C.md
@@ -2,22 +2,22 @@
| Copyright (c) 2016-2023 Moddable Tech, Inc.
|
| This file is part of the Moddable SDK Runtime.
- |
+ |
| The Moddable SDK Runtime is free software: you can redistribute it and/or modify
| it under the terms of the GNU Lesser General Public License as published by
| the Free Software Foundation, either version 3 of the License, or
| (at your option) any later version.
- |
+ |
| The Moddable SDK Runtime is distributed in the hope that it will be useful,
| but WITHOUT ANY WARRANTY; without even the implied warranty of
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
| GNU Lesser General Public License for more details.
- |
+ |
| You should have received a copy of the GNU Lesser General Public License
| along with the Moddable SDK Runtime. If not, see **`void xsmcGetArrayBufferData(xsSlot theSlot, xsIntegerValue theOffset, void *theData, xsIntegerValue theSize)`** - + | Arguments | Description | | --- | :-- | | `theSlot` | The `ArrayBuffer` slot @@ -475,7 +475,7 @@ Copies bytes from the `ArrayBuffer` **`void xsSetArrayBufferData(xsSlot theSlot, xsIntegerValue theOffset, void *theData, xsIntegerValue theSize)`**
**`void xsmcSetArrayBufferData(xsSlot theSlot, xsIntegerValue theOffset, void *theData, xsIntegerValue theSize)`** - + | Arguments | Description | | --- | :-- | | `theSlot` | The `ArrayBuffer` slot @@ -511,7 +511,7 @@ Returns the size of the `ArrayBuffer` in bytes *** **`void xsSetArrayBufferLength(xsSlot theSlot, xsIntegerValue theSize)`** - + | Arguments | Description | | --- | :-- | | `theSlot` | The `ArrayBuffer` slot @@ -523,14 +523,14 @@ Sets the length of the `ArrayBuffer` **`void *xsToArrayBuffer(xsSlot theSlot)`**
**`void *xsmcToArrayBuffer(xsSlot theSlot)`** - + | Arguments | Description | | --- | :-- | | `theSlot` | The `ArrayBuffer` slot Returns a pointer to the `ArrayBuffer` data -For speed, the `xsToArrayBuffer ` macro returns the value contained in the slot itself, a pointer to the buffer in the memory managed by XS. Since the XS runtime can compact memory containing string values, the result of the `xsToArrayBuffer ` macro cannot be used across or in other macros of XS in C. +For speed, the `xsToArrayBuffer ` macro returns the value contained in the slot itself, a pointer to the buffer in the memory managed by XS. Since the XS runtime can compact memory containing string values, the result of the `xsToArrayBuffer ` macro cannot be used across or in other macros of XS in C. *** @@ -581,7 +581,7 @@ Returns a reference to the prototype instance created by the XS runtime. | --- | :-- | | `theLength` | The array length property to set -Creates an array instance, and returns a reference to the new array instance +Creates an array instance, and returns a reference to the new array instance ##### In ECMAScript: @@ -600,7 +600,7 @@ xsNewArray(5); **`xsSlot xsNewObject()`**
**`xsSlot xsmcNewObject()`** -Creates an object instance, and returns a reference to the new object instance +Creates an object instance, and returns a reference to the new object instance ##### In ECMAScript: @@ -620,7 +620,7 @@ xsNewObject(); | Arguments | Description | | --- | :-- | -| `theSlot` | The result slot +| `theSlot` | The result slot The `xsmcSetNewObject` macro is functionally equivalent to the `xsNewObject` macro. The property is returned in the slot provided. @@ -670,7 +670,7 @@ if (xsIsInstanceOf(xsThis, xsObjectPrototype)) ### Keys, Identifiers and Indexes -In ECMAScript, the properties of an object are identified by number, string or symbol values – a.k.a. the property **key**. In XS in C you can access properties with property keys through the `xsGetAt`, `xsSetAt`, etc macros described below. +In ECMAScript, the properties of an object are identified by number, string or symbol values – a.k.a. the property **key**. In XS in C you can access properties with property keys through the `xsGetAt`, `xsSetAt`, etc macros described below. If the number or string value of a property key can be converted into a 32-bit unsigned integer, XS uses the result of the conversion – a.k.a. the property **index** — to identify the property. In XS in C, you can access properties directy with property indexes through the `xsGetIndex`, `xsSetIndex`, etc macros described below. A property index can be used with all instances but is typically used to access items of `Array` instances. @@ -726,7 +726,7 @@ Tests whether a given string corresponds to an existing property identifier. Ret *** -### Properties +### Properties This section describes the macros related to accessing properties of objects (or items of arrays), as summarized in Table 1. @@ -741,74 +741,74 @@ This section describes the macros related to accessing properties of objects (or
xsGlobalxsDefine, xsmcDefinexsDefineAtxsHas, xsmcHasxsHasAtxsHasIndex, xsmcHasIndexxsGet, xsmcGetxsGetAt, xsmcGetAtxsGetIndex, xsmcGetIndexxsSet, xsmcSetxsSetAt, xsmcSetAtxsSetIndex, xsmcSetIndexxsDelete, xsmcDeletexsDeleteAt, xsmcDeleteAtxsCall0 ... xsCall7, xsmcCallxsNew0 ... xsNew7, xsmcNewxsTest, xsmcTestxsEnumeratexsNewHostConstructor
xsNewHostObjectxsNewHostInstance, xsmcNewHostInstancexsGetHostData, xsmcGetHostData
xsSetHostData, xsmcSetHostData
xsGetHostChunk, xsmcGetHostChunk
xsSetHostChunk, xsmcSetHostChunk
xsSetHostDestructorxsBeginHost
xsEndHost
`void* xsmcGetHostChunk(xsSlot theThis)`** @@ -2228,10 +2228,10 @@ Returns the data | Arguments | Description | | --- | :-- | | `theThis` | A reference to a host object -| `theData` | The data to set or `NULL` to leave the chunk data uninitialized +| `theData` | The data to set or `NULL` to leave the chunk data uninitialized | `theSize` | The size of the data in bytes -> Note that an object has either host data or a host chunk but never both. +> Note that an object has either host data or a host chunk but never both. *** @@ -2244,14 +2244,14 @@ To set the destructor of a host object (or to clear the destructor, by passing ` | Arguments | Description | | --- | :-- | -| `theThis` | A reference to a host object +| `theThis` | A reference to a host object | `theDestructor` | The destructor to be executed by the garbage collector, or `NULL` to clear the destructor *** #### xsBeginHost and xsEndHost -Use the `xsBeginHost` macro to establish a new stack frame and the `xsEndHost` macro to remove it. +Use the `xsBeginHost` macro to establish a new stack frame and the `xsEndHost` macro to remove it. **`void xsBeginHost(xsMachine* the)`**
**`void xsEndHost(xsMachine* the)`** @@ -2281,7 +2281,7 @@ The `prototype` is a host object which includes the native destructor `xs_file_d This example adds the `close` function to the prototype after creating the constructor. It may be added before instead. -This example also adds a getter accessor function for the property `isOpen`. +This example also adds a getter accessor function for the property `isOpen`. ```c #define kPrototype (0) @@ -2476,7 +2476,7 @@ void xs_rectangle_union(xsMachine *the) } ``` -Standalone functions -- functions that are not part of a class -- can also be implemented in C. The `@` syntax extension is used where the function body normally appears. +Standalone functions -- functions that are not part of a class -- can also be implemented in C. The `@` syntax extension is used where the function body normally appears. ```c function restart() @ "xs_restart"; @@ -2522,34 +2522,34 @@ The value of `xsThis` in the implementation of `xs_restart` matches the receiver ## License Copyright (c) 2016-2023 Moddable Tech, Inc. - + This file is part of the Moddable SDK Runtime. - + The Moddable SDK Runtime is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. - + The Moddable SDK Runtime is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. - + You should have received a copy of the GNU Lesser General Public License along with the Moddable SDK Runtime. If not, see
Revised: November 4, 2021 -These examples demonstrate how to use features of [Commodetto](../../documentation/commodetto/commodetto.md), a bitmap graphics library that provides a 2D graphics API. Commodetto includes the lightweight [Poco rendering engine](../../documentation/commodetto/poco.md), a display list renderer able to efficiently render a single scanline at a time, saving considerable memory by eliminating the need for a frame buffer. +These examples demonstrate how to use features of [Commodetto](../../documentation/commodetto/commodetto.md), a bitmap graphics library that provides a 2D graphics API. Commodetto includes the lightweight [Poco rendering engine](../../documentation/commodetto/poco.md), a display list renderer able to efficiently render a single scanline at a time, saving considerable memory by eliminating the need for a frame buffer. Most of the examples are designed for a QVGA (320x240) screen, but many work on a variety of screen sizes. All of the examples in this folder run on the desktop simulator with the exception of the `mini-drag` example. @@ -13,7 +13,7 @@ This document provides a brief description of each example and a preview of each - **Text:** `text`, `text-ticker`, `cfe8x8`, `cfeNFNT` - **Animation:** `docs`, `progress`, `text-ticker` - **Touch input:** `mini-drag` -- **Networking:** `jpeghttp`, `jpegstream`, `epaper-mini-travel-time`, +- **Networking:** `jpeghttp`, `jpegstream`, `epaper-mini-travel-time`, *** @@ -141,7 +141,7 @@ The `outline/random-triangles` example demonstrates using both stroked and fille ### `pngdisplay` -The `pngdisplay` allows you to use the curl command line tool to push PNG images to the display. Created for use by user interface designers, not developers. +The `pngdisplay` allows you to use the curl command line tool to push PNG images to the display. Created for use by user interface designers, not developers. > See the [blog post](https://blog.moddable.com/blog/pngdisplay/) Pushing PNG Images to a Display for more information about this example. @@ -159,7 +159,7 @@ The `progress` example displays high frame rate animations of progress bars and  -The `rotated` example demonstrates how to define the rotation of the screen. This example rotates 90 degrees; 0, 180, and 270 degree rotation is also supported. +The `rotated` example demonstrates how to define the rotation of the screen. This example rotates 90 degrees; 0, 180, and 270 degree rotation is also supported. *** diff --git a/examples/drivers/peripherals/rtc/readme.md b/examples/drivers/peripherals/rtc/readme.md index 5f35e94361..ddd6a6228b 100644 --- a/examples/drivers/peripherals/rtc/readme.md +++ b/examples/drivers/peripherals/rtc/readme.md @@ -30,6 +30,6 @@ in the `manifest.json` file, change the `include` for your device. For example: ``` "include": [ - "$(MODDABLE)/modules/drivers/peripherals/ds1307/manifest.json" + "$(MODDABLE)/modules/drivers/peripherals/ds1307/manifest.json" ] ``` diff --git a/examples/drivers/readme.md b/examples/drivers/readme.md index 31d4a45d0b..f797789aa9 100644 --- a/examples/drivers/readme.md +++ b/examples/drivers/readme.md @@ -73,7 +73,7 @@ Demonstrates use of the the Hitachi HD44780 character LCD module. ### [`HMC5883L`](./HMC5883L) -Reads digital compass measurements at 250ms intervals from the I2C [SparkFun Triple Axis Magnetometer Breakout - HMC5883L](https://www.sparkfun.com/products/retired/10530). +Reads digital compass measurements at 250ms intervals from the I2C [SparkFun Triple Axis Magnetometer Breakout - HMC5883L](https://www.sparkfun.com/products/retired/10530). *** ### [`hx711`](./hx711) diff --git a/examples/drivers/sensors/hc-sr04/multiple-sensors/readme.md b/examples/drivers/sensors/hc-sr04/multiple-sensors/readme.md index d0496d677d..6a24043921 100644 --- a/examples/drivers/sensors/hc-sr04/multiple-sensors/readme.md +++ b/examples/drivers/sensors/hc-sr04/multiple-sensors/readme.md @@ -1,5 +1,5 @@ -This example demonstrates how to trigger and read from multiple HC-SR04 sensors in a round-robin fashion. +This example demonstrates how to trigger and read from multiple HC-SR04 sensors in a round-robin fashion. The Echo pins are all connected to a shared bus (ESP32 GPIO 12 by default) while each HC-SR04 needs a separate trigger pin (ESP32 GPIOs 13, 14, and 27 by default). To avoid damage to the HC-SR04 sensors, the Echo pins must be electrically isolated from each other. That can be accomplished with diodes, as shown in the diagram below: - \ No newline at end of file + diff --git a/examples/io/tcp/readme.md b/examples/io/tcp/readme.md index acaf79a476..e8719602f9 100644 --- a/examples/io/tcp/readme.md +++ b/examples/io/tcp/readme.md @@ -22,6 +22,6 @@ The examples in this directory use the [TCP socket](https://419.ecma-internation The `HTTPRequest`, `WebSocketClient`, and `MQTTClient` classes are designed to use runtime resources efficiently while supporting all the fundamental capabilities of the underlying protocol. They give the most control and the lightest footprint, but as lower-level APIs they are less convenient to use. -The `fetch`, `WebSocket`, and `mqtt` classes provide embedded developers access to familiar, standard APIs from the web platform. They are generally more convenient to use and use more resources (RAM, code size, CPU). +The `fetch`, `WebSocket`, and `mqtt` classes provide embedded developers access to familiar, standard APIs from the web platform. They are generally more convenient to use and use more resources (RAM, code size, CPU). -The choice of which API to use for a project depends on the requirements of that project. For many situations, the standard `fetch`, `WebSocket`, and `mqtt` APIs work well. +The choice of which API to use for a project depends on the requirements of that project. For many situations, the standard `fetch`, `WebSocket`, and `mqtt` APIs work well. diff --git a/examples/js/compartments/readme.md b/examples/js/compartments/readme.md index 95f87c5085..a128d85249 100644 --- a/examples/js/compartments/readme.md +++ b/examples/js/compartments/readme.md @@ -1,3 +1,3 @@ # Compartment Examples -We're working on this to sync with [the TC39 Compartment proposal](https://github.com/tc39/proposal-compartments) and with [Agoric SES compartments](https://github.com/endojs/endo/blob/kris-sketch-api-docs/packages/ses/index.d.ts). We'll update this when it settles down. \ No newline at end of file +We're working on this to sync with [the TC39 Compartment proposal](https://github.com/tc39/proposal-compartments) and with [Agoric SES compartments](https://github.com/endojs/endo/blob/kris-sketch-api-docs/packages/ses/index.d.ts). We'll update this when it settles down. diff --git a/examples/network/aws/moddable-aws-guide.md b/examples/network/aws/moddable-aws-guide.md index 813fe4d1a4..e73a253cb7 100644 --- a/examples/network/aws/moddable-aws-guide.md +++ b/examples/network/aws/moddable-aws-guide.md @@ -105,4 +105,4 @@ Notes: * Change the `
Revised: March 13, 2023 -The `WavStream` and `SBCStream` classes plays audio streams delivered over HTTP. The `WavStream` class plays uncompressed WAV audio files and `Audio/L16`; the `SBCStream` class plays [SBC compressed](https://en.wikipedia.org/wiki/SBC_%28codec%29) audio. SBC is a low-complexity format used primarily by Bluetooth. Its relatively high quality and simple decoder make it well suited for microcontrollers. +The `WavStream` and `SBCStream` classes plays audio streams delivered over HTTP. The `WavStream` class plays uncompressed WAV audio files and `Audio/L16`; the `SBCStream` class plays [SBC compressed](https://en.wikipedia.org/wiki/SBC_%28codec%29) audio. SBC is a low-complexity format used primarily by Bluetooth. Its relatively high quality and simple decoder make it well suited for microcontrollers. The `WavStream` and `SBCStream` classes share a common API but have separate implementations. They uses the following modules: diff --git a/examples/piu/readme.md b/examples/piu/readme.md index 13506ce1be..9407006e6e 100755 --- a/examples/piu/readme.md +++ b/examples/piu/readme.md @@ -20,7 +20,7 @@ This document provides a brief description of each example and a preview of each ### `backlight` -The `backlight` example allows you to adjust the backlight brightness on Moddable Two. +The `backlight` example allows you to adjust the backlight brightness on Moddable Two. > For more information about the backlight, see the **Backlight** section of the [Moddable Two documentation](https://github.com/Moddable-OpenSource/moddable/blob/public/documentation/devices/moddable-two.md#backlight). @@ -170,7 +170,7 @@ The `keyboard` example demonstrates the use of the keyboard module to create an  -The `list` example uses a Piu `Port` object to create a scrolling list of items that may be tapped. +The `list` example uses a Piu `Port` object to create a scrolling list of items that may be tapped. *** @@ -259,7 +259,7 @@ The `preferences` example demonstrates how to set preferences that are saved acr  -The `scroller` example shows how to create vertical and horizontal scrolling content. Tap the title bar to toggle between the two directions. +The `scroller` example shows how to create vertical and horizontal scrolling content. Tap the title bar to toggle between the two directions. *** @@ -338,4 +338,4 @@ The `weather` and `mini-weather` examples display the weather forecast for five The `wifi-config` example allows the user to configure the Wi-Fi network by selecting from a list of available networks. The on-screen keyboard is used to enter the password for secure networks. -*** \ No newline at end of file +*** diff --git a/examples/readme.md b/examples/readme.md index 68e15ed265..9a7dba976d 100644 --- a/examples/readme.md +++ b/examples/readme.md @@ -26,12 +26,12 @@ The `mcconfig` command line tool builds Moddable apps. To use it, open a termina cd $MODDABLE/examples/piu/balls mcconfig -m - + On Windows, use the **Developer Command Prompt for VS 2017** to build apps: cd %MODDABLE%\examples\piu\balls mcconfig -m - + By default, `mcconfig` generates a release build that targets the host platform. These are common command line options: - `-d`: build a debug instrumented version @@ -54,7 +54,7 @@ Also note that `mcconfig` automatically deploys apps to target devices. For many The `-p` command line option specifies the target platform/subplatform you are building for. For example, to build a release app that targets Moddable One: mcconfig -m -p esp/moddable_one - + To build a debug app that targets ESP32 devices: mcconfig -d -m -p esp32 @@ -80,7 +80,7 @@ For example, to build a debug version of the `balls` example app with the 8-bit ### Screen rotation -Some example apps are designed to render on a rotated screen. Use the `-r` command line option to specify the target rotation angle: +Some example apps are designed to render on a rotated screen. Use the `-r` command line option to specify the target rotation angle: - `-r 0`: no rotation (default) - `-r 90`: 90 degree rotation @@ -97,7 +97,7 @@ To build the `progress` app to run at 180 degrees rotation on the host platform: cd $MODDABLE/examples/commodetto/progress mcconfig -d -m -r 180 - + ### Wi-Fi configuration @@ -114,7 +114,7 @@ To build and run the `sntp` app for the open network `Free Wifi`: cd $MODDABLE/examples/network/sntp mcconfig -d -m -p esp ssid="Free WiFi" - + ### Screen driver configuration @@ -132,7 +132,7 @@ The remainder of this section explains how to do these steps. To run the `text` app on an ESP8266 device with a [LPM013M126A](../modules/drivers/lpm013m126a) 8-color display: cd $MODDABLE/examples/commodetto/text - mcconfig -d -m -p esp screen=lpm013m126a + mcconfig -d -m -p esp screen=lpm013m126a To run the `map-puzzle` app on an ESP8266 device with a [FT6206](../modules/drivers/ft6206) multi-touch controller: cd $MODDABLE/examples/piu/map-puzzle @@ -160,7 +160,7 @@ To build an app for the `ft6206` touch controller driver, modify both the `confi "screen": "ili9341", "touch": "ft6206" } - + "include": [ "$(MODDABLE)/modules/drivers/ili9341/manifest.json", "$(MODDABLE)/modules/drivers/ft6206/manifest.json" diff --git a/modules/commodetto/gif/readme.md b/modules/commodetto/gif/readme.md index 4b3507f273..52acc7e8b3 100644 --- a/modules/commodetto/gif/readme.md +++ b/modules/commodetto/gif/readme.md @@ -10,7 +10,7 @@ Most GIF implementations for microcontrollers decode directly to the frame buffe The Commodetto animated GIF decoder has several special decoding modes to significantly reduce the amount of memory required to decode many animated GIF sequences. -Because of the increased memory requirements, the Commodetto animated GIF decoder is not practical on all microcontrollers. It works very well on an ESP32 (with no external RAM) and Pico (RP2040) for images that are about 200 pixels on a side. +Because of the increased memory requirements, the Commodetto animated GIF decoder is not practical on all microcontrollers. It works very well on an ESP32 (with no external RAM) and Pico (RP2040) for images that are about 200 pixels on a side. ## Examples @@ -47,7 +47,7 @@ The `width` and `height` properties of the reader instance provide the dimension The `duration` property is the total length of the animation in milliseconds. The `frameCount` is the total number of frames in the animation. ### Decoding a frame -To decode an image, call `next`. When the end of the animated frame sequence is reached, the decoder automatically loops back to the start. +To decode an image, call `next`. When the end of the animated frame sequence is reached, the decoder automatically loops back to the start. ```js reader.next(); @@ -122,7 +122,7 @@ poco.drawBitmapWithKeyColor(reader, 0, 0, reader.transparentColor); Note that the `fillRectangle` call draws behind the animated GIF. Your code can draw anything behind the GIF, such as a pattern or a logo or even another animation. It is safe to use `drawBitmapWithKeyColor`. ### Reducing memory use -A GIF image contains between 2 and about 16 million colors. Images with many colors must be stored at 16-bits per pixel, which uses quite a bit of memory. The Commodetto GIF decoder is also able to decode GIF images to 8-bit, 4-bit, and 1-bit pixels. The decoder automatically determines the format that uses the least memory while maintaining full color fidelity. Thee bitmap format used may always be drawn using `poco.drawBitmapWithKeyColor`. The format of the bitmap used is available from the `pixelFormat` property of the GIF Reader instance. +A GIF image contains between 2 and about 16 million colors. Images with many colors must be stored at 16-bits per pixel, which uses quite a bit of memory. The Commodetto GIF decoder is also able to decode GIF images to 8-bit, 4-bit, and 1-bit pixels. The decoder automatically determines the format that uses the least memory while maintaining full color fidelity. Thee bitmap format used may always be drawn using `poco.drawBitmapWithKeyColor`. The format of the bitmap used is available from the `pixelFormat` property of the GIF Reader instance. Some applications may wish to force decoding to a specific format, overriding the automatic format detection. This may generate an image which does not render correctly, but should never crash. To force decoding to a particular format, pass the pixel format to the `ReadGIF` constructor as part of the optional options argument. The following example shows requesting pixels in RGB565 little-endian format: @@ -161,4 +161,4 @@ The following table describes the properties available on the GIF reader instanc ## Thank you -The core GIF decoder is [GIF Animator](https://github.com/bitbank2/AnimatedGIF) by [Larry Bank](https://github.com/bitbank2) of [BitBank Software](https://www.bitbanksoftware.com). +The core GIF decoder is [GIF Animator](https://github.com/bitbank2/AnimatedGIF) by [Larry Bank](https://github.com/bitbank2) of [BitBank Software](https://www.bitbanksoftware.com). diff --git a/readme.md b/readme.md index 59340bd5b1..ba0104a44b 100755 --- a/readme.md +++ b/readme.md @@ -48,7 +48,7 @@ The Moddable SDK implements a variety of hardware protocols including digital (G ### Source level debugger -The `xsbug` JavaScript source level debugger is a full-featured debugger that supports debugging modules and applications for XS platforms. +The `xsbug` JavaScript source level debugger is a full-featured debugger that supports debugging modules and applications for XS platforms. Similar to other debuggers, `xsbug` supports setting breakpoints, browsing source code, and inspection of the call stack and variables. The `xsbug` debugger additionally provides real-time instrumentation to track memory usage and profile application and resource consumption. @@ -59,7 +59,7 @@ Similar to other debuggers, `xsbug` supports setting breakpoints, browsing sourc 1. To do anything with the Moddable SDK, you have to install it on your computer. This involves downloading this repository, installing some development tools, configuring settings over the command line, and building the Moddable SDK tools. The [Getting Started Guide](./documentation/Moddable%20SDK%20-%20Getting%20Started.md) in the `documentation` directory walks you through the whole process of installing the Moddable SDK. - + 2. With the Moddable SDK installed, you can build and run apps on hardware simulators. 3. To develop for a particular device, you need to install additional tools and SDKs for that device. The setup process for each device is different, but usually involves installing some additional SDKs, drivers, and development tools. @@ -162,7 +162,7 @@ The Moddable SDK supports four Gecko boards, shown below. | | | | | | :---: | :---: | :---: | :---: | -|
Giant Gecko |
Mighty Gecko |
Thunderboard Sense 2 |
Blue Gecko +|
Giant Gecko |
Mighty Gecko |
Thunderboard Sense 2 |
Blue Gecko ### QCA4020 by Qualcomm @@ -213,7 +213,7 @@ The Moddable SDK repository contains the following top level directories: The JavaScript APIs supported by the Moddable SDK are documented in a suite of documents in the [documentation](./documentation) directory. The documentation is an extensive reference, with numerous examples. The primary [Piu document](./documentation/piu/piu.md) alone is over 100 pages. All documentation is provided in markdown format. -See the [readme](./documentation#api-documentation-for-modules) document in that directory for an overview of the API documents. +See the [readme](./documentation#api-documentation-for-modules) document in that directory for an overview of the API documents. ## Resources @@ -244,7 +244,7 @@ If you're an independent developer, we recommend you [start a discussion](./disc To learn more about Moddable, see [our website](http://www.moddable.com). -For companies interested in the benefits of using JavaScript and the Moddable SDK to power your products, Moddable provides consulting services to help you get started. We're available to help with design, implementation, training, and support. +For companies interested in the benefits of using JavaScript and the Moddable SDK to power your products, Moddable provides consulting services to help you get started. We're available to help with design, implementation, training, and support. You can also reach out to us on Twitter ([@moddabletech](https://twitter.com/moddabletech)). Following us on Twitter is the best way to keep up with what we’re doing—we post announcements about new blog posts there, along with other Moddable news.