Skip to content

Commit 79bd399

Browse files
HipsterBrownHipsterBrown
authored
docs: add persistent storage pages (#4)
* docs(storage): add persistent storage overview page * docs(sidebar): add persistent storage section to navigation
1 parent 4e35b9b commit 79bd399

3 files changed

Lines changed: 136 additions & 7 deletions

File tree

‎astro.config.mjs‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -87,11 +87,17 @@ export default defineConfig({
8787
label: "WebSocket Client Class",
8888
link: "/api/websocket-client-class"
8989
}, {
90-
label: "MQTT Client Class",
91-
link: "/api/mqtt-client-class"
92-
}, {
93-
label: "Host Provider",
94-
link: "/api/host-provider"
90+
label: "MQTT Client Class",
91+
link: "/api/mqtt-client-class"
92+
}, {
93+
label: "Persistent Storage",
94+
autogenerate: {
95+
directory: "/api/storage"
96+
},
97+
collapsed: true
98+
}, {
99+
label: "Host Provider",
100+
link: "/api/host-provider"
95101
}, {
96102
label: "Provenance Sensor Class",
97103
link: "/api/provenance-sensor-class"

‎src/content/docs/api/index.md‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,37 @@ title: API Overview
33
description: Overview of the ECMA-419 embedded systems API.
44
---
55

6-
The ECMA-419 specification defines a suite of APIs for JavaScript on embedded systems. These APIs are organized into several patterns and classes.
6+
# API Reference
7+
8+
## Overview
9+
10+
The first edition of the ECMA Standard was adopted by the ECMA General Assembly of June 2021. It was built around the IO Class Pattern which provides consistent, efficient, extensible access to the IO capabilities of embedded systems. Driver-style classes for IO extenders, sensors, and displays build on the IO foundation.
11+
12+
The second edition extends IO with asynchronous capabilities used by I²C and the system management bus. It introduces new sensor classes, including many gas sensors; classes to manage and monitor network interfaces; client support for common network protocols including HTTP, MQTT, NTP, DNS, WebSocket, and TLS; server support for the HTTP and WebSocket protocols; and a real-time clock peripheral class.
13+
14+
## Scope
15+
16+
The Standard defines application programming interfaces (APIs) for ECMAScript modules that support programs executing on embedded systems.
17+
18+
The Standard defines APIs for capabilities found in common across embedded systems. Implementations for embedded systems that include additional capabilities are encouraged to provide ECMAScript APIs for those using the many extensibility options provided by the Standard.
19+
20+
The Standard does not make any changes to the ECMAScript language as defined by ECMAScript Language Specification (ECMA-262).
21+
22+
## Class Pattern
23+
24+
A Class Pattern, as used in the Standard, is a combination of requirements and guidelines for a class. For example, the IO Class Pattern defines behaviours for all IO classes.
25+
26+
## Module Specifiers
27+
28+
The Standard defines classes which are accessed through modules. Because many embedded systems lack a file system, using file paths to access modules is impractical. Instead, modules are accessed using bare module specifiers. While such specifiers are currently forbidden in a web browser, they are permitted in other environments.
29+
30+
A namespace prefix is used to minimise the chance of name collisions with other bare module specifiers. This Standard uses the namespace prefix **`embedded:`**.
31+
32+
```
33+
import Digital from "embedded:io/digital";
34+
```
35+
36+
The use of module namespaces in this Standard is intended to be compatible with the [Built In Modules Proposal](https://github.com/tc39/proposal-built-in-modules#namespace).
737

838
## Patterns
939

@@ -23,7 +53,7 @@ The ECMA-419 specification defines a suite of APIs for JavaScript on embedded sy
2353
- [**HTTP Server**](/api/http-server-class): Web responses.
2454
- [**WebSocket Client**](/api/websocket-client-class): Real-time web communication.
2555
- [**MQTT Client**](/api/mqtt-client-class): Message queuing telemetry transport.
26-
- [**Persistent Storage**](/api/storage/files): Files, key-value pairs, and flash memory.
56+
- [**Persistent Storage**](/api/storage/): Files, key-value pairs, and flash memory.
2757

2858
## Host Provider
2959

‎src/content/docs/api/storage/index.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Persistent Storage
3+
description: Overview of persistent storage modules for files, flash memory, and key-value pairs.
4+
---
5+
6+
The Persistent Storage APIs provide mechanisms for reliable data storage on embedded systems. ECMA-419 defines four complementary storage modules, each optimized for different use cases and access patterns.
7+
8+
## Storage Types
9+
10+
### Files
11+
The **Files** module provides a hierarchical file system interface for storing, organizing, and retrieving data in a directory structure. It supports:
12+
- Creating and navigating directories
13+
- Reading and writing files with various access modes
14+
- Moving, copying, and deleting files and directories
15+
- Symbolic links for file system abstraction
16+
- Synchronous or asynchronous operations
17+
18+
Use the Files module when you need a traditional file system interface with structured organization, similar to operating system file systems.
19+
20+
**Module**: `embedded:storage/files`
21+
**Documentation**: [Files](/api/storage/files)
22+
23+
### Flash
24+
The **Flash** module provides low-level access to flash memory partitions for advanced use cases requiring direct hardware control. It supports:
25+
- Opening flash partitions by name
26+
- Reading and writing raw data at byte offsets
27+
- Erasing memory blocks (sectors)
28+
- Querying partition size and block information
29+
- Multiple data format support
30+
31+
Use the Flash module when you need direct control over flash memory partitions, such as for boot loaders, raw data storage, or performance-critical applications.
32+
33+
**Module**: `embedded:storage/flash`
34+
**Documentation**: [Flash](/api/storage/flash)
35+
36+
### Key-Value
37+
The **Key-Value** module provides simple key-value pair storage organized within named domains. It supports:
38+
- Reading and writing values by key
39+
- Deleting key-value pairs
40+
- Domain organization for logical separation
41+
- Multiple data format support
42+
- Transactional operations
43+
44+
Use the Key-Value module when you need simple, fast access to configuration data, application settings, or small cached values without file system overhead.
45+
46+
**Module**: `embedded:storage/key-value`
47+
**Documentation**: [Key-Value](/api/storage/key-value)
48+
49+
### Update
50+
The **Update** module provides firmware update functionality, enabling in-place firmware upgrades for flash partitions. It supports:
51+
- Writing update data in append or random-access modes
52+
- Progress tracking and cancellation
53+
- Atomic activation of updates
54+
- Automatic rollback on failure
55+
56+
Use the Update module to implement over-the-air (OTA) firmware updates, allowing devices to update themselves without external tools.
57+
58+
**Module**: `embedded:update`
59+
**Documentation**: [Update](/api/storage/update)
60+
61+
## Choosing a Storage Type
62+
63+
| Use Case | Recommended Module | Reason |
64+
|----------|-------------------|--------|
65+
| Application files, documents | **Files** | Natural hierarchical organization |
66+
| Configuration settings | **Key-Value** | Fast, simple access to small data |
67+
| Raw data, boot code | **Flash** | Direct hardware control |
68+
| Firmware updates | **Update** | Safe, atomic firmware replacement |
69+
| Multi-file projects | **Files** | Directory structure and navigation |
70+
| Cached values | **Key-Value** | Low overhead, quick lookup |
71+
| Legacy binary formats | **Flash** | Arbitrary byte-level access |
72+
73+
## Getting Started
74+
75+
Each storage module is accessed through the `device.storage` global object:
76+
77+
```js
78+
import files from "embedded:storage/files";
79+
import flash from "embedded:storage/flash";
80+
import keyValue from "embedded:storage/key-value";
81+
import update from "embedded:update";
82+
83+
// Access persistent storage modules
84+
const rootDir = files;
85+
const partition = await flash.open({ path: "app" });
86+
const config = await keyValue.open({ path: "settings" });
87+
```
88+
89+
Refer to each module's documentation page for detailed API reference, parameters, and code examples.
90+
91+
## Specifications
92+
93+
[Persistent Storage (Section 26)](https://419.ecma-international.org/#-26-persistent-storage)

0 commit comments

Comments
 (0)