@geastack/cli 0.1.115 → 0.1.117
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -82
- package/docs/ESP32-WAVESHARE-AMOLED-QUICKSTART.md +1 -1
- package/docs/PEBBLE-QUICKSTART.md +1 -1
- package/docs/SETUP.md +30 -28
- package/examples/catalog.json +0 -15
- package/package.json +2 -2
- package/src/build-config.mjs +1 -1
- package/src/commands/apps.mjs +1 -0
- package/src/commands/board.mjs +1 -0
- package/src/commands/doctor.mjs +6 -3
- package/src/create-geastack.mjs +11 -2
- package/src/esp32/build.mjs +21 -21
- package/src/esp32/idf-version.mjs +19 -42
- package/src/gea.mjs +6 -6
- package/src/macos/adapter.mjs +18 -1
- package/src/manifest.mjs +23 -3
- package/src/setup-wizard.mjs +20 -14
- package/src/web/adapter.mjs +2 -1
package/README.md
CHANGED
|
@@ -18,41 +18,43 @@ gea dev
|
|
|
18
18
|
gea build --target web
|
|
19
19
|
gea build --target ios
|
|
20
20
|
gea build --target tvos
|
|
21
|
-
gea flash --board
|
|
22
|
-
gea screenshot board.png --board
|
|
23
|
-
gea monitor --board
|
|
24
|
-
gea inspect --json
|
|
21
|
+
gea flash --board <alias> --monitor
|
|
22
|
+
gea screenshot board.png --board <alias>
|
|
23
|
+
gea monitor --board <alias>
|
|
24
|
+
gea apps inspect --json
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
+
The CLI needs Node.js 22 or later. `gea --help` prints the full command
|
|
28
|
+
surface; `gea apps inspect --json` runs inside an app directory.
|
|
29
|
+
|
|
27
30
|
## Interactive Menu Map
|
|
28
31
|
|
|
29
32
|
```mermaid
|
|
30
33
|
flowchart TD
|
|
31
34
|
create["gea create my-app"] --> identity["Resolve app identity<br/>argument, optional --id, optional --name"]
|
|
32
|
-
identity --> starter{"
|
|
33
|
-
|
|
34
|
-
starter -->|"Embedded component counter"| counter["Copy the touchscreen counter used in the embedded tutorial"]
|
|
35
|
+
identity --> starter{"What do you want to build?"}
|
|
35
36
|
|
|
36
|
-
starter -->|"Blank application"| emptyTarget{"Where should
|
|
37
|
+
starter -->|"Blank application"| emptyTarget{"Where should this application run?"}
|
|
37
38
|
emptyTarget -->|"Web browser"| emptyWeb["Generate browser entry, HTML, and Vite config"]
|
|
38
|
-
emptyTarget -->|"ESP32 board"| emptyEsp["Generate native entry<br/>Ask whether to enable
|
|
39
|
-
emptyTarget -->|"
|
|
39
|
+
emptyTarget -->|"ESP32 board"| emptyEsp["Generate native entry<br/>Ask whether to enable wireless firmware updates over Bluetooth"]
|
|
40
|
+
emptyTarget -->|"RP2350, GeaOS, macOS, iOS, tvOS, Android, or Windows"| emptyNative["Generate native entry for the selected platform"]
|
|
40
41
|
|
|
41
|
-
starter -->|"Example application"| pickExample["Pick from the example gallery<br/>web, ESP32, GeaOS, iOS,
|
|
42
|
-
pickExample
|
|
43
|
-
|
|
44
|
-
|
|
42
|
+
starter -->|"Example application"| pickExample["Pick from the example gallery<br/>bundled Component Counter first, then GitHub examples<br/>for web, ESP32, RP2350, GeaOS, iOS, macOS, Android, and Windows"]
|
|
43
|
+
pickExample -->|"Component Counter"| counter["Copy the bundled touchscreen counter used in the embedded tutorial"]
|
|
44
|
+
pickExample -->|"GitHub example"| fetchExample["Fetch selected app from GitHub"]
|
|
45
|
+
fetchExample --> rewriteExample["Rewrite package name and gea manifest"]
|
|
45
46
|
|
|
46
|
-
counter --> projectWiring["Add @geastack/core
|
|
47
|
-
rewriteExample --> projectWiring
|
|
47
|
+
counter --> projectWiring["Add @geastack/core, @geastack/cli, @geajs/core, TypeScript<br/>+ @geastack/targets for ESP32/RP2350, @geastack/apple for macOS/iOS/tvOS,<br/>@geastack/windows for Windows, Vite for web"]
|
|
48
|
+
rewriteExample --> projectWiring
|
|
48
49
|
emptyWeb --> projectWiring
|
|
49
50
|
emptyEsp --> projectWiring
|
|
50
51
|
emptyNative --> projectWiring
|
|
51
52
|
projectWiring --> boardConfig["Create .gea/boards.json"]
|
|
52
|
-
boardConfig --> install["Install npm dependencies<br/>(interactive default)"]
|
|
53
|
+
boardConfig --> install["Install npm dependencies<br/>(interactive default; --no-install skips)"]
|
|
53
54
|
install --> setup["Next: npx gea setup"]
|
|
54
55
|
|
|
55
56
|
auto["Automation flags"] -.-> starter
|
|
57
|
+
auto --> autoCounter["--yes or no terminal: Component Counter"]
|
|
56
58
|
auto --> autoEmpty["--starter blank --yes"]
|
|
57
59
|
auto --> autoExample["--starter example --example watch"]
|
|
58
60
|
```
|
|
@@ -61,33 +63,33 @@ flowchart TD
|
|
|
61
63
|
flowchart TD
|
|
62
64
|
setup["npx gea setup"] --> mode{"Mode?"}
|
|
63
65
|
|
|
64
|
-
mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.2"]
|
|
65
|
-
mode -->|"--board alias"| directBoard["
|
|
66
|
-
mode -->|"--target target-id"| directTarget["
|
|
66
|
+
mode -->|"--esp-idf"| directIdf["Install or check ESP-IDF v6.0.2<br/>(--idf-version installs another release)<br/>plus the 6.2-dev line the ESP32-S31 builds with"]
|
|
67
|
+
mode -->|"--board alias"| directBoard["Configure the build for that board alias"]
|
|
68
|
+
mode -->|"--target target-id"| directTarget["Configure the build for that target directly"]
|
|
67
69
|
|
|
68
70
|
mode -->|"Interactive"| interactive{"What do you want to set up?"}
|
|
69
71
|
|
|
70
|
-
interactive -->|"Known supported board"| knownBoard["
|
|
71
|
-
knownBoard --> alias["
|
|
72
|
-
alias --> serial["
|
|
73
|
-
serial -->
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
interactive -->|"
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
72
|
+
interactive -->|"Known supported board"| knownBoard["Which board do you have?"]
|
|
73
|
+
knownBoard --> alias["Board alias"]
|
|
74
|
+
alias --> serial["Is the board connected over USB right now?<br/>detect its USB serial (registry + GEADEV ping)"]
|
|
75
|
+
serial --> ota["OTA host/IP (optional)"]
|
|
76
|
+
ota --> reviewKnown["Review, then: Save this board setup?"]
|
|
77
|
+
reviewKnown --> writeKnown["Write the alias to boards.json"]
|
|
78
|
+
|
|
79
|
+
interactive -->|"Custom board profile"| custom["Custom board alias, then MCU / SoC (ESP32-S3)"]
|
|
80
|
+
custom --> chipConfig["Display, touch, power, IMU, audio and I/O expander<br/>with bus and pin questions from @geastack/chips/catalog.json"]
|
|
81
|
+
chipConfig --> features["Optional microSD slot and launcher button"]
|
|
82
|
+
features --> connection["Detect the USB serial"]
|
|
83
|
+
connection --> reviewCustom["Review, then: Save this custom board target?"]
|
|
84
|
+
reviewCustom --> writeProfile["Write targets/alias.json next to boards.json"]
|
|
85
|
+
writeProfile --> writeCustomAlias["Write the alias to boards.json"]
|
|
86
|
+
|
|
87
|
+
interactive -->|"Only install/check project npm dependencies"| npmInstall["Run npm install when package.json exists"]
|
|
88
|
+
interactive -->|"Only install/check ESP-IDF toolchain"| idfOnly["Same as --esp-idf"]
|
|
89
|
+
|
|
90
|
+
writeKnown --> idfCheck["Check ESP-IDF for the board, offer to install it"]
|
|
91
|
+
writeCustomAlias --> idfCheck
|
|
92
|
+
idfCheck --> initialize["Initialize board target for an app"]
|
|
91
93
|
initialize --> ready["Ready: npx gea flash --board alias --monitor"]
|
|
92
94
|
npmInstall --> done
|
|
93
95
|
idfOnly --> done
|
|
@@ -96,6 +98,12 @@ flowchart TD
|
|
|
96
98
|
directTarget --> done
|
|
97
99
|
```
|
|
98
100
|
|
|
101
|
+
The wizard writes `boards.json` (and a custom board's `targets/<alias>.json`)
|
|
102
|
+
to `<project>/.gea/` when the project already has a `.gea/boards.json`, which
|
|
103
|
+
every `gea create` project does, and to `~/.geastack/` otherwise. `--local`
|
|
104
|
+
forces the project directory, `--global` forces `~/.geastack/`, and
|
|
105
|
+
`--boards-config <file>` names the file outright.
|
|
106
|
+
|
|
99
107
|
The CLI resolves `@geastack/core`, `@geastack/targets`, the compiler, chips,
|
|
100
108
|
host bindings, and the other native packages from npm. A project can use a
|
|
101
109
|
local CLI with `npx gea` or a global installation with `gea`; neither command
|
|
@@ -108,9 +116,9 @@ Boards are managed without editing JSON by hand; aliases live in
|
|
|
108
116
|
```sh
|
|
109
117
|
gea boards discover # which registered board is on which USB port, its app and IP
|
|
110
118
|
gea boards list
|
|
111
|
-
gea boards set
|
|
112
|
-
gea boards rename
|
|
113
|
-
gea boards remove
|
|
119
|
+
gea boards set <alias> host 192.168.1.100
|
|
120
|
+
gea boards rename <alias> <new-alias>
|
|
121
|
+
gea boards remove <new-alias>
|
|
114
122
|
```
|
|
115
123
|
|
|
116
124
|
Custom boards remain editable after setup:
|
|
@@ -122,7 +130,8 @@ gea chips add co5300 ft3168 --board my-board
|
|
|
122
130
|
gea chips remove ft3168 --board my-board
|
|
123
131
|
```
|
|
124
132
|
|
|
125
|
-
These commands update the
|
|
133
|
+
These commands update the custom board's target definition
|
|
134
|
+
(`targets/<alias>.json`). They do not copy native
|
|
126
135
|
sources into the application; the target adapter compiles the selected drivers
|
|
127
136
|
directly from the installed `@geastack/chips` package.
|
|
128
137
|
|
|
@@ -146,9 +155,13 @@ Run from this repo during local development:
|
|
|
146
155
|
```sh
|
|
147
156
|
node bin/gea.mjs doctor
|
|
148
157
|
node bin/gea.mjs --help
|
|
149
|
-
node bin/create-geastack.mjs demo-panel --dir ./demo-panel --dry-run
|
|
150
158
|
```
|
|
151
159
|
|
|
160
|
+
`GEA_DEBUGGER_DIR` points `gea run --debug` at a debugger checkout instead of
|
|
161
|
+
the installed `@geastack/debugger`. Contributor native debug launches use the
|
|
162
|
+
sibling `apple` and `core` checkouts and the shared compiler; explicit
|
|
163
|
+
overrides win.
|
|
164
|
+
|
|
152
165
|
## Machine Setup
|
|
153
166
|
|
|
154
167
|
Use [docs/SETUP.md](docs/SETUP.md) for Node/npm, ESP-IDF, Emscripten, Xcode,
|
|
@@ -176,34 +189,37 @@ expose stable command contracts.
|
|
|
176
189
|
|
|
177
190
|
- [docs/PEBBLE-QUICKSTART.md](docs/PEBBLE-QUICKSTART.md): install the Pebble SDK,
|
|
178
191
|
enable a TSX app, build a `.pbw`, and run on Pebble Time 2 or its emulator.
|
|
179
|
-
|
|
180
192
|
- [docs/SPEC.md](docs/SPEC.md): command surface, manifest expectations, and
|
|
181
193
|
backend contract for the first implementation.
|
|
182
194
|
- [docs/SETUP.md](docs/SETUP.md): toolchains per target, the ESP-IDF version
|
|
183
195
|
GeaStack resolves, and the board configuration files.
|
|
184
196
|
- [docs/DEVICE-CONTROL.md](docs/DEVICE-CONTROL.md): `gea devctl` in full, both
|
|
185
197
|
wire protocols, and the display knobs.
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
- `create
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
198
|
+
- [docs/NATIVE-BUILD-CONFIG.md](docs/NATIVE-BUILD-CONFIG.md): native build
|
|
199
|
+
settings, their precedence, and board overrides.
|
|
200
|
+
- [docs/LINUX-NATIVE-DEPLOYMENT.md](docs/LINUX-NATIVE-DEPLOYMENT.md): register
|
|
201
|
+
and deploy to a Raspberry Pi OS board over SSH.
|
|
202
|
+
- [docs/qspi-panels.md](docs/qspi-panels.md): panel startup settings for custom
|
|
203
|
+
boards with a `co5300` or `sh8601` QSPI display.
|
|
204
|
+
|
|
205
|
+
## Command Surface
|
|
206
|
+
|
|
207
|
+
- `gea create`, `gea setup`, `gea doctor`: scaffolding, guided board and
|
|
208
|
+
toolchain setup, and dependency checks.
|
|
209
|
+
- `gea dev`, `gea simulate`, `gea build --target web`: browser development,
|
|
210
|
+
device-viewport emulation, and static web builds.
|
|
211
|
+
- `gea build|run --target macos|ios|tvos|windows|raspberry-pi-os|pebble`:
|
|
212
|
+
native desktop, mobile, TV, and watch apps through `@geastack/apple`,
|
|
213
|
+
`@geastack/windows`, `@geastack/linux`, and `@geastack/pebble`.
|
|
214
|
+
- `gea build|flash|run|ota|clean --board <alias>`: ESP32 and RP2350 firmware
|
|
215
|
+
through `@geastack/targets`, with USB flashing, WiFi and BLE OTA, and OTA
|
|
216
|
+
slot management.
|
|
217
|
+
- `gea logs`, `gea monitor`, `gea screenshot`, `gea devctl`: device access over
|
|
218
|
+
USB or WiFi.
|
|
219
|
+
- `gea run --debug`: Chrome DevTools for native macOS apps and ESP32 boards.
|
|
220
|
+
- `gea apps`, `gea boards`, `gea targets`, `gea chips`, `gea config`,
|
|
221
|
+
`gea heap-report`: app, board, target, and chip catalogs, effective build
|
|
222
|
+
settings, and heap analysis.
|
|
207
223
|
|
|
208
224
|
## Browser development and emulation
|
|
209
225
|
|
|
@@ -213,9 +229,9 @@ opens the browser. Use `--no-open` to suppress opening, and `--width`, `--height
|
|
|
213
229
|
`--zoom`, and `--dpr` to configure the preview. DPR is a simulated Display API
|
|
214
230
|
value; it does not override the browser's pixel ratio.
|
|
215
231
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
232
|
+
`gea simulate` uses the DOM renderer by default. For the embedded renderer and
|
|
233
|
+
framebuffer workflow, use `gea simulate --renderer wasm`; that mode requires
|
|
234
|
+
Emscripten. Unknown renderer values are rejected.
|
|
219
235
|
|
|
220
236
|
`gea build --target web` emits HTML/JS/CSS into `.gea/build/web/site` (override
|
|
221
237
|
with `--out-dir`). The app's `index.html` is honored. Web-only Vite customization
|
|
@@ -239,7 +255,7 @@ target is not required for debugging; the source manifest is unchanged. On Mac,
|
|
|
239
255
|
`gea run --debug --target web` uses the existing DOM/CSS runtime with Vite HMR.
|
|
240
256
|
|
|
241
257
|
`gea build --debug --target macos` produces the same instrumented native app
|
|
242
|
-
without launching it or opening Chrome. `gea build --debug --board
|
|
258
|
+
without launching it or opening Chrome. `gea build --debug --board <alias>`
|
|
243
259
|
builds ESP32 debug firmware without flashing or opening USB. Both commands use
|
|
244
260
|
the same debug configuration as `run`, including editable CSS. macOS retains
|
|
245
261
|
full symbols and unoptimized code by default; `--no-debug-sources` disables
|
|
@@ -258,19 +274,15 @@ Use `--debug-port 9223` for CDP and `--port 5182` for the DOM server. Native
|
|
|
258
274
|
or browser stops the session. Other native targets, WASM and
|
|
259
275
|
direct AppKit widget graphs outside the Gea retained tree remain unsupported.
|
|
260
276
|
|
|
261
|
-
The CLI installs `@geastack/debugger` automatically. Debugging requires
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
CLI integration. `GEA_DEBUGGER_DIR` selects a development checkout;
|
|
265
|
-
contributor native launches use sibling Apple,
|
|
266
|
-
core/plugin packages and the shared compiler; explicit overrides win. Set
|
|
267
|
-
`GEA_CHROME_PATH` for a custom browser. Chrome uses its own app profile inside
|
|
277
|
+
The CLI installs `@geastack/debugger` automatically. Debugging requires
|
|
278
|
+
Chrome/Chromium, and native builds need compiler and target runtimes with
|
|
279
|
+
debugger instrumentation. Set `GEA_CHROME_PATH` for a custom browser. Chrome uses its own app profile inside
|
|
268
280
|
`.gea/build/web`.
|
|
269
281
|
|
|
270
282
|
|
|
271
|
-
From your app directory, `gea run --debug --board
|
|
272
|
-
firmware on
|
|
273
|
-
|
|
283
|
+
From your app directory, `gea run --debug --board <alias> --debug-fps 10` builds
|
|
284
|
+
and flashes debug firmware on a registered ESP32 board, then opens Chrome
|
|
285
|
+
DevTools through USB. `--attach` connects to already-running
|
|
274
286
|
debug firmware without flashing; regular firmware is rejected before JTAG or
|
|
275
287
|
Chrome starts. `--no-open` exposes only the CDP endpoint.
|
|
276
288
|
`--port` selects the USB device when using `--board`, while `--debug-port` selects
|
|
@@ -312,3 +324,11 @@ debugger exits. `--overrides edits.json` replays them as soon as it attaches:
|
|
|
312
324
|
```sh
|
|
313
325
|
gea run --debug --target macos --overrides edits.json --save-overrides edits.json
|
|
314
326
|
```
|
|
327
|
+
|
|
328
|
+
## License
|
|
329
|
+
|
|
330
|
+
Apache-2.0 (see `LICENSE`). You can ship closed-source products
|
|
331
|
+
built on it. The only GeaStack code under a different license is
|
|
332
|
+
the embedded board support (`targets` and `@geastack/chips`, GPL-3.0-only):
|
|
333
|
+
shipping closed-source firmware through those needs a commercial license.
|
|
334
|
+
Contact [contact@geastack.com](mailto:contact@geastack.com) for commercial terms, support and hosted builds.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Pebble Time 2 quickstart
|
|
2
2
|
|
|
3
|
-
Requires Gea CLI 0.1.85 or newer, Node.js
|
|
3
|
+
Requires Gea CLI 0.1.85 or newer, Node.js 22 or newer, Bash, and the Pebble
|
|
4
4
|
SDK. This target builds ordinary `.pbw` apps for Pebble Time 2 (`emery`);
|
|
5
5
|
it does not flash watch firmware. The build script supports macOS and Linux.
|
|
6
6
|
|
package/docs/SETUP.md
CHANGED
|
@@ -21,14 +21,14 @@ npx gea setup
|
|
|
21
21
|
|
|
22
22
|
For simulator-only development:
|
|
23
23
|
|
|
24
|
-
- Node.js
|
|
24
|
+
- Node.js 22 or newer.
|
|
25
25
|
- npm.
|
|
26
26
|
- Emscripten SDK if you want `npx gea build --target web` and the WASM simulator
|
|
27
27
|
bundle path.
|
|
28
28
|
|
|
29
29
|
For ESP32 hardware:
|
|
30
30
|
|
|
31
|
-
- Node.js
|
|
31
|
+
- Node.js 22 or newer.
|
|
32
32
|
- npm.
|
|
33
33
|
- Python 3.
|
|
34
34
|
- ESP-IDF v6.0.2 (GeaStack's pinned default; see ESP-IDF For ESP32 Targets below).
|
|
@@ -54,7 +54,7 @@ For Android targets:
|
|
|
54
54
|
## Node And npm
|
|
55
55
|
|
|
56
56
|
Install Node.js from the official download page or your normal version manager.
|
|
57
|
-
GeaStack currently requires Node.js
|
|
57
|
+
GeaStack currently requires Node.js 22 or newer. Node 24 LTS is a good
|
|
58
58
|
default on new machines.
|
|
59
59
|
|
|
60
60
|
Verify:
|
|
@@ -66,21 +66,15 @@ npm --version
|
|
|
66
66
|
|
|
67
67
|
## ESP-IDF For ESP32 Targets
|
|
68
68
|
|
|
69
|
-
|
|
70
|
-
|
|
69
|
+
ESP32 builds use ESP-IDF v6.0.2, and `gea setup` installs or verifies that
|
|
70
|
+
release. To install another one instead:
|
|
71
71
|
|
|
72
72
|
1. `--idf-version <tag>` (e.g. `npx gea setup --esp-idf --idf-version v6.1.0-rc1`)
|
|
73
|
-
|
|
74
|
-
2. `GEA_ESP_IDF_VERSION` (same shape) when no `--idf-version` is given.
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
unreachable, etc).
|
|
79
|
-
|
|
80
|
-
Verifying an existing install accepts any installed version whose
|
|
81
|
-
major.minor is the same as or newer than the resolved target -- an installed
|
|
82
|
-
6.0.2 is never rejected just because the resolved target moved on to, say,
|
|
83
|
-
6.1.0, unless it genuinely trails it.
|
|
73
|
+
names an exact release, a release candidate or a branch.
|
|
74
|
+
2. `GEA_ESP_IDF_VERSION` (same shape) applies when no `--idf-version` is given.
|
|
75
|
+
|
|
76
|
+
Builds pick the v6.0.2 install on their own. To build with any other ESP-IDF,
|
|
77
|
+
point `IDF_PATH` at it.
|
|
84
78
|
|
|
85
79
|
Command-line install:
|
|
86
80
|
|
|
@@ -336,7 +330,8 @@ at call time, so never record a port path.
|
|
|
336
330
|
### Composed targets
|
|
337
331
|
|
|
338
332
|
A composed target is a JSON definition that extends a base (`esp32-s3` or
|
|
339
|
-
`esp32-p4`, with `mcu` set to `esp32s3` or `esp32p4` to match) and picks its
|
|
333
|
+
`esp32-p4`, with `mcu` set to `esp32s3` or `esp32p4` to match) and picks its
|
|
334
|
+
chips from the `@geastack/chips` catalog (`gea chips list`). Every
|
|
340
335
|
role is optional, so the definition describes the hardware that is there:
|
|
341
336
|
`display`, `touch`, `power`, `imu`, `audio`, `rtc` and `expander`. Some boards are
|
|
342
337
|
shipped composed in `@geastack/targets` and need no definition of your own,
|
|
@@ -413,23 +408,30 @@ to one role. The CrowPanel Advance 7.0 definition uses all of these.
|
|
|
413
408
|
|
|
414
409
|
#### The `esp32-p4` base
|
|
415
410
|
|
|
416
|
-
A P4 definition takes the same roles, with GPIOs up to 54.
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
`flashMode`.
|
|
411
|
+
A P4 definition takes the same roles, with GPIOs up to 54. The base is the
|
|
412
|
+
Waveshare ESP32-P4 7-inch project (`esp32-p4-waveshare-touch-lcd-7`), as
|
|
413
|
+
`esp32-s3-touch-amoled-2.06` is for `esp32-s3`; everything the definition
|
|
414
|
+
names replaces that board's own chips, console, camera sensor and wireless
|
|
415
|
+
wiring. Its sdkconfig and partition table are laid out for the Waveshare's
|
|
416
|
+
32MB flash at DIO 40MHz, so a board with other flash sets `flashSize`,
|
|
417
|
+
`flashMode`, `flashFreq` and its own `partitions`.
|
|
418
|
+
|
|
419
|
+
Its display is a parallel RGB panel scanned straight out of the P4's
|
|
420
|
+
in-package PSRAM by the LCD driver, through only a small FIFO: a PSRAM stall
|
|
421
|
+
of a few microseconds underruns it and the picture creeps right. Run flash the
|
|
422
|
+
way the vendor's own firmware does; the CrowPanel Advanced 5.0 underran every
|
|
423
|
+
few seconds at DIO 40MHz and never at its vendor's QIO 80MHz. Use
|
|
423
424
|
`scanFramebuffers: 3` so the renderer draws straight into a buffer not being
|
|
424
425
|
scanned (one buffer adds a PSRAM-to-PSRAM copy of every changed region; with
|
|
425
426
|
two, each swap can wait up to a frame for the panel to let go of the old
|
|
426
427
|
front). Scroll copies and full-width patches between the buffers go through
|
|
427
428
|
the AXI-GDMA, about three times faster than the CPU. Keep the L2 cache's
|
|
428
429
|
64-byte lines: 128-byte lines speed CPU copies up but stall PSRAM long enough
|
|
429
|
-
for the panel to underrun at 60Hz. Leave `restartInVsync` off; the driver
|
|
430
|
-
if it ever falls behind. `psram` is
|
|
431
|
-
it up). `pclkIdleHigh: true` idles the pixel
|
|
432
|
-
some panels need. Two sections exist only on
|
|
430
|
+
for the panel to underrun at 60Hz. Leave `restartInVsync` off; the driver
|
|
431
|
+
restarts the DMA itself at the next VSYNC if it ever falls behind. `psram` is
|
|
432
|
+
not configurable (the base sets it up). `pclkIdleHigh: true` idles the pixel
|
|
433
|
+
clock high between lines, which some panels need. Two sections exist only on
|
|
434
|
+
this base:
|
|
433
435
|
|
|
434
436
|
- `wireless`: the WiFi/BLE coprocessor (an ESP32-C6, say) on SDIO through
|
|
435
437
|
esp_hosted: `slot`, `busWidth` (1 or 4), `clockKhz`, `resetActiveHigh`, and
|
package/examples/catalog.json
CHANGED
|
@@ -152,21 +152,6 @@
|
|
|
152
152
|
"ios": false
|
|
153
153
|
}
|
|
154
154
|
},
|
|
155
|
-
{
|
|
156
|
-
"id": "car-dashboard",
|
|
157
|
-
"name": "Car Dashboard",
|
|
158
|
-
"description": "1280x720 cluster",
|
|
159
|
-
"path": "apps/car-dashboard",
|
|
160
|
-
"entry": "index.tsx",
|
|
161
|
-
"runtime": "gea",
|
|
162
|
-
"targets": {
|
|
163
|
-
"web": true,
|
|
164
|
-
"esp32": true,
|
|
165
|
-
"geaos": true,
|
|
166
|
-
"macos": false,
|
|
167
|
-
"ios": false
|
|
168
|
-
}
|
|
169
|
-
},
|
|
170
155
|
{
|
|
171
156
|
"id": "counter-jsx",
|
|
172
157
|
"name": "Counter",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@geastack/cli",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.117",
|
|
4
4
|
"description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"dependencies": {
|
|
39
39
|
"@clack/prompts": "^1.8.0",
|
|
40
40
|
"@geastack/simulator": "^0.1.15",
|
|
41
|
-
"@geastack/targets": "^0.1.
|
|
41
|
+
"@geastack/targets": "^0.1.114",
|
|
42
42
|
"picocolors": "^1.1.1",
|
|
43
43
|
"serialport": "^13.0.0"
|
|
44
44
|
},
|
package/src/build-config.mjs
CHANGED
|
@@ -128,7 +128,7 @@ export function validateBuildManifest(manifest) {
|
|
|
128
128
|
if (!isObject(target.boards)) fail(where + '.boards must be an object')
|
|
129
129
|
for (const [id, board] of Object.entries(target.boards)) {
|
|
130
130
|
if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(id) || !isObject(board)) fail(where + '.boards must contain board IDs mapped to objects')
|
|
131
|
-
for (const key of Object.keys(board)) if (!['build', 'cssDevicePixelRatio', 'defines', 'buttons'].includes(key)) fail(`Unknown setting ${where}.boards.${id}.${key}`)
|
|
131
|
+
for (const key of Object.keys(board)) if (!['build', 'cssDevicePixelRatio', 'defines', 'buttons', 'psram', 'flashFreq', 'display', 'sdkconfig'].includes(key)) fail(`Unknown setting ${where}.boards.${id}.${key}`)
|
|
132
132
|
boardDefines(board.defines, where + '.boards.' + id + '.defines')
|
|
133
133
|
flatten(board.build, where + '.boards.' + id + '.build')
|
|
134
134
|
if (board.cssDevicePixelRatio !== undefined) ratio(board.cssDevicePixelRatio, where + '.boards.' + id + '.cssDevicePixelRatio')
|
package/src/commands/apps.mjs
CHANGED
|
@@ -165,6 +165,7 @@ export function targetsCommand(ctx, parsed, rest, options) {
|
|
|
165
165
|
fail(error.message, ExitCode.missingDependency)
|
|
166
166
|
}
|
|
167
167
|
if (sub === 'list') {
|
|
168
|
+
if (Object.keys(targets).length === 0 && !flag(parsed, 'json')) fail(`No targets found: @geastack/targets is not installed in ${ctx.projectRoot}. Run this inside a GeaStack project after npm install.`, ExitCode.missingDependency)
|
|
168
169
|
if (flag(parsed, 'json')) options.stdout(JSON.stringify(targets, null, 2))
|
|
169
170
|
else for (const id of Object.keys(targets).sort()) options.stdout(`${id}\t${targets[id].adapter}\t${exists(targets[id].targetDir) ? targets[id].targetDir : '(not installed)'}`)
|
|
170
171
|
return 0
|
package/src/commands/board.mjs
CHANGED
|
@@ -324,6 +324,7 @@ export async function flashCommand(ctx, parsed, rest, options, { monitor = false
|
|
|
324
324
|
export async function otaCommand(ctx, parsed, rest, options) {
|
|
325
325
|
const transport = option(parsed, 'transport', '') || defaultOtaTransport(ctx, parsed, rest)
|
|
326
326
|
if (transport !== 'wifi' && transport !== 'ble') fail("--transport must be 'wifi' or 'ble'.", ExitCode.usage)
|
|
327
|
+
if (transport === 'wifi' && option(parsed, 'port', '')) fail('--port names a USB serial port; a Wi-Fi OTA takes the board address with --host.', ExitCode.usage)
|
|
327
328
|
const selection = selectBoard(ctx, parsed, transport === 'wifi' ? { otaHost: true } : {})
|
|
328
329
|
if (selection.bootMode === 'ram-only') {
|
|
329
330
|
if (transport !== 'wifi' || option(parsed, 'slot') || option(parsed, 'erase-slot') ||
|
package/src/commands/doctor.mjs
CHANGED
|
@@ -5,6 +5,7 @@ import { boardConfigPath, boardConfigTiers, loadBoardConfig } from '../boards/co
|
|
|
5
5
|
import { loadSerialport } from '../device/serial.mjs'
|
|
6
6
|
import { ExitCode } from '../errors.mjs'
|
|
7
7
|
import { findEspIdf, findIdfPythonEnv } from '../esp32/idf-env.mjs'
|
|
8
|
+
import { DEFAULT_ESP_IDF_VERSION } from '../esp32/idf-version.mjs'
|
|
8
9
|
import { exists } from '../fs-utils.mjs'
|
|
9
10
|
import { discoverApps, resolveRequestedApp, validateApp } from '../manifest.mjs'
|
|
10
11
|
import { commandVersion, nodeAtLeast, onPath } from '../toolchain.mjs'
|
|
@@ -29,7 +30,7 @@ export async function doctorCommand(ctx, parsed, rest, options) {
|
|
|
29
30
|
const add = (name, ok, detail, required) => checks.push({ name, ok: Boolean(ok), detail: String(detail ?? ''), required })
|
|
30
31
|
|
|
31
32
|
add('project root', exists(ctx.projectRoot), ctx.projectRoot, true)
|
|
32
|
-
add('Node >=
|
|
33
|
+
add('Node >= 22', nodeAtLeast(22, 0), process.version, true)
|
|
33
34
|
add('@geastack/targets', packageExists(ctx.targetsRoot), ctx.targetsRoot || 'not installed in this project', true)
|
|
34
35
|
add('@geastack/core', packageExists(ctx.corePackageDir), ctx.corePackageDir || 'not installed', true)
|
|
35
36
|
add('@geastack/compiler', packageExists(ctx.compilerPackageDir), ctx.compilerPackageDir || 'not installed', true)
|
|
@@ -39,14 +40,16 @@ export async function doctorCommand(ctx, parsed, rest, options) {
|
|
|
39
40
|
}
|
|
40
41
|
add('serialport (USB device access)', await serialportAvailable(), 'npm package', false)
|
|
41
42
|
|
|
42
|
-
|
|
43
|
+
// The install a build would pick: the pinned release, or whatever IDF_PATH names.
|
|
44
|
+
const idfDir = findEspIdf(env, undefined, { defaultVersion: DEFAULT_ESP_IDF_VERSION.slice(1) })
|
|
43
45
|
const pythonEnv = idfDir ? findIdfPythonEnv(idfDir, env) : ''
|
|
44
|
-
add(
|
|
46
|
+
add(`ESP-IDF ${DEFAULT_ESP_IDF_VERSION}`, Boolean(idfDir), idfDir || 'not found (gea setup --esp-idf, or set IDF_PATH)', false)
|
|
45
47
|
add('ESP-IDF python env', Boolean(pythonEnv), pythonEnv || 'run install.sh in ESP-IDF', false)
|
|
46
48
|
add('cmake', onPath('cmake', env) || Boolean(pythonEnv), commandVersion('cmake', ['--version'], env).split('\n')[0] || 'from ESP-IDF tools', false)
|
|
47
49
|
add('ninja', onPath('ninja', env), onPath('ninja', env) ? 'on PATH' : 'optional; Unix Makefiles used otherwise', false)
|
|
48
50
|
add('ccache', onPath('ccache', env), onPath('ccache', env) ? 'on PATH' : 'optional', false)
|
|
49
51
|
add('arm-none-eabi-gcc (RP2350)', onPath('arm-none-eabi-gcc', env) || Boolean(env.PICO_TOOLCHAIN_PATH), env.PICO_TOOLCHAIN_PATH || 'optional', false)
|
|
52
|
+
add('PICO_SDK_PATH (RP2350)', Boolean(env.PICO_SDK_PATH) && exists(env.PICO_SDK_PATH), env.PICO_SDK_PATH || 'optional; needed for RP2350 builds', false)
|
|
50
53
|
add('picotool (RP2350)', onPath('picotool', env), onPath('picotool', env) ? 'on PATH' : 'optional', false)
|
|
51
54
|
add('swift (BLE OTA)', onPath('swift', env), onPath('swift', env) ? 'on PATH' : 'optional; macOS only', false)
|
|
52
55
|
// gea simulate compiles the app with emcc and links with em++, and hashes
|
package/src/create-geastack.mjs
CHANGED
|
@@ -134,7 +134,9 @@ export async function runCreateGeastack(argv, io = {}) {
|
|
|
134
134
|
? `Example: fetched ${starter.example.name}`
|
|
135
135
|
: 'Starter: blank application'
|
|
136
136
|
])
|
|
137
|
-
|
|
137
|
+
// `gea setup` is the board and toolchain wizard; a web-only app has nothing for it to do.
|
|
138
|
+
const firstCommand = isWebOnly(targets) ? 'npx gea dev' : 'npx gea setup'
|
|
139
|
+
done.outro(installDependencies ? `Next: cd ${targetDir} && ${firstCommand}` : `Next: cd ${targetDir} && npm install && ${firstCommand}`)
|
|
138
140
|
return 0
|
|
139
141
|
}
|
|
140
142
|
|
|
@@ -520,7 +522,10 @@ function readme({ appId, displayName, starter, targets }) {
|
|
|
520
522
|
: starter.kind === 'bundled'
|
|
521
523
|
? `Started from bundled starter: \`${starter.starter.name}\` (\`${starter.starter.id}\`).`
|
|
522
524
|
: 'Started from a blank app.'
|
|
523
|
-
const commands = targets
|
|
525
|
+
const commands = isWebOnly(targets)
|
|
526
|
+
? `npx gea dev
|
|
527
|
+
npx gea build --target web`
|
|
528
|
+
: targets.web
|
|
524
529
|
? `npx gea setup
|
|
525
530
|
npx gea dev
|
|
526
531
|
npx gea build --target web`
|
|
@@ -554,6 +559,10 @@ ${commands}
|
|
|
554
559
|
`
|
|
555
560
|
}
|
|
556
561
|
|
|
562
|
+
function isWebOnly(targets) {
|
|
563
|
+
return targets.web === true && Object.entries(targets).every(([name, enabled]) => name === 'web' || enabled !== true)
|
|
564
|
+
}
|
|
565
|
+
|
|
557
566
|
function shouldInstallDependencies(parsed, io) {
|
|
558
567
|
const explicit = option(parsed, 'install')
|
|
559
568
|
if (explicit !== undefined) return explicit === true || explicit === 'true'
|
package/src/esp32/build.mjs
CHANGED
|
@@ -257,19 +257,6 @@ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities,
|
|
|
257
257
|
}
|
|
258
258
|
}
|
|
259
259
|
|
|
260
|
-
// A bare RGB panel is scanned out of PSRAM through bounce buffers refilled
|
|
261
|
-
// by the LCD interrupt. Its code must sit in IRAM: otherwise it is fetched
|
|
262
|
-
// over the same PSRAM bus rendering saturates (always so with XIP from
|
|
263
|
-
// PSRAM), the refill misses its slot, the FIFO underruns and every later
|
|
264
|
-
// line lands shifted -- the picture shreds on each repaint and stays slid.
|
|
265
|
-
// Restarting the transfer at each VSYNC puts a slipped frame back. In that
|
|
266
|
-
// mode the driver never resets the EOF count it picks each refill's buffer
|
|
267
|
-
// from, so one lost EOF would leave every refill a buffer out of step with
|
|
268
|
-
// the DMA (thin lines at each band's head); rgb_panel.cpp's refill reads the
|
|
269
|
-
// buffer and band from the DMA itself instead. A board whose display says
|
|
270
|
-
// `restartInVsync: false` skips the restart: it runs in the VSYNC interrupt,
|
|
271
|
-
// which waits out a refill in progress, and once that pushes it past the
|
|
272
|
-
// vertical blanking the restarted frame lands shifted sideways.
|
|
273
260
|
// A P4's hosted WiFi/BLE coprocessor: esp_hosted takes its SDIO bus and the
|
|
274
261
|
// coprocessor's reset line from these, so they are the board's wiring.
|
|
275
262
|
if (boardWireless) {
|
|
@@ -332,6 +319,19 @@ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities,
|
|
|
332
319
|
}
|
|
333
320
|
}
|
|
334
321
|
|
|
322
|
+
// A bare RGB panel is scanned out of PSRAM through bounce buffers refilled
|
|
323
|
+
// by the LCD interrupt. Its code must sit in IRAM: otherwise it is fetched
|
|
324
|
+
// over the same PSRAM bus rendering saturates (always so with XIP from
|
|
325
|
+
// PSRAM), the refill misses its slot, the FIFO underruns and every later
|
|
326
|
+
// line lands shifted -- the picture shreds on each repaint and stays slid.
|
|
327
|
+
// Restarting the transfer at each VSYNC puts a slipped frame back. In that
|
|
328
|
+
// mode the driver never resets the EOF count it picks each refill's buffer
|
|
329
|
+
// from, so one lost EOF would leave every refill a buffer out of step with
|
|
330
|
+
// the DMA (thin lines at each band's head); rgb_panel.cpp's refill reads the
|
|
331
|
+
// buffer and band from the DMA itself instead. A board whose display says
|
|
332
|
+
// `restartInVsync: false` skips the restart: it runs in the VSYNC interrupt,
|
|
333
|
+
// which waits out a refill in progress, and once that pushes it past the
|
|
334
|
+
// vertical blanking the restarted frame lands shifted sideways.
|
|
335
335
|
if (boardRgbPanel) {
|
|
336
336
|
board('CONFIG_LCD_RGB_ISR_IRAM_SAFE', 'y')
|
|
337
337
|
if (boardRgbPanel.restartInVsync) board('CONFIG_LCD_RGB_RESTART_IN_VSYNC', 'y')
|
|
@@ -365,7 +365,7 @@ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities,
|
|
|
365
365
|
// Flash and PSRAM share the MSPI core clock, so the flash clock must divide
|
|
366
366
|
// the one PSRAM runs from: octal PSRAM at 120MHz needs a 240MHz core, which
|
|
367
367
|
// 80MHz quad flash cannot share (ESP-IDF has no tuning table for it).
|
|
368
|
-
const flashFreq = Number(app
|
|
368
|
+
const flashFreq = (app ? Number(appTargetConfig(app, 'esp32', selection.target).flashFreq) : 0) || Number(selection.flashFreq) || 0
|
|
369
369
|
if (flashFreq) {
|
|
370
370
|
for (const mhz of [20, 26, 40, 80, 120]) {
|
|
371
371
|
if (mhz !== flashFreq) unset(`CONFIG_ESPTOOLPY_FLASHFREQ_${mhz}M`)
|
|
@@ -558,7 +558,7 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
|
|
|
558
558
|
// gea.targets.esp32.sdkconfig: the app's own Kconfig defaults, layered over
|
|
559
559
|
// the board's. IDF reads a ';'-separated SDKCONFIG_DEFAULTS list in order, so
|
|
560
560
|
// the app's file is last and wins wherever the two disagree.
|
|
561
|
-
const appEsp32Config = app ? appTargetConfig(app, 'esp32') : null
|
|
561
|
+
const appEsp32Config = app ? appTargetConfig(app, 'esp32', selection.target) : null
|
|
562
562
|
const appSdkconfigFile = appEsp32Config?.sdkconfig ? path.join(app.root, appEsp32Config.sdkconfig) : ''
|
|
563
563
|
// gea.targets.esp32.display: the RGB panel pipeline an app opts into.
|
|
564
564
|
// copyBack: 'dma' the strip copy-back runs on GDMA, freeing the worker core;
|
|
@@ -811,14 +811,11 @@ function runInTarget(command, args, { cwd, env, dryRun, verbose, label, logFile,
|
|
|
811
811
|
return runQuiet(command, args, { cwd, env, dryRun, verbose, label, logFile, stdout, stderr, failureCode })
|
|
812
812
|
}
|
|
813
813
|
|
|
814
|
-
// App capability flags are CMake cache entries. Reconfigure only when those
|
|
815
|
-
// inputs change; ordinary source/CMake dependency changes remain the build
|
|
816
|
-
// system's responsibility. This retains Ninja's sub-second no-op.
|
|
817
814
|
// A build directory belongs to the CMake project it was configured from, and
|
|
818
815
|
// CMake refuses to reuse it for another ("does not match the source used to
|
|
819
|
-
// generate cache").
|
|
820
|
-
//
|
|
821
|
-
//
|
|
816
|
+
// generate cache"). When a target's project changes (a board moved onto another
|
|
817
|
+
// base project, a renamed checkout), its cache goes and configure starts the
|
|
818
|
+
// directory afresh.
|
|
822
819
|
export function dropCacheFromOtherSource(buildDir, sourceDir) {
|
|
823
820
|
const cacheFile = path.join(buildDir, 'CMakeCache.txt')
|
|
824
821
|
if (!existsSync(cacheFile)) return false
|
|
@@ -830,6 +827,9 @@ export function dropCacheFromOtherSource(buildDir, sourceDir) {
|
|
|
830
827
|
return true
|
|
831
828
|
}
|
|
832
829
|
|
|
830
|
+
// App capability flags are CMake cache entries. Reconfigure only when those
|
|
831
|
+
// inputs change; ordinary source/CMake dependency changes remain the build
|
|
832
|
+
// system's responsibility. This retains Ninja's sub-second no-op.
|
|
833
833
|
export async function ensureConfigured({ idf, prepared, env, dryRun = false, verbose = false, stdout, stderr = console.error }) {
|
|
834
834
|
if (!dryRun) dropCacheFromOtherSource(prepared.binaryDir || prepared.buildDir, prepared.targetDir)
|
|
835
835
|
const signatureFile = path.join(prepared.buildDir, '.gea-configure-args')
|
|
@@ -1,17 +1,12 @@
|
|
|
1
1
|
// ESP-IDF target-version resolution.
|
|
2
2
|
//
|
|
3
|
-
// One pinned default in code, an env var / CLI option that overrides it
|
|
4
|
-
// outright (pin
|
|
5
|
-
// best-effort GitHub "latest release" lookup used only when nothing
|
|
6
|
-
// overrides the pin. The network call is injected (`fetchImpl`/`fetchLatest`)
|
|
7
|
-
// so real usage hits GitHub while tests supply a fake and never touch the
|
|
8
|
-
// network.
|
|
3
|
+
// One pinned default in code, and an env var / CLI option that overrides it
|
|
4
|
+
// outright (pin another release or try a release candidate).
|
|
9
5
|
|
|
10
6
|
const STABLE_TAG = /^v(\d+)\.(\d+)\.(\d+)$/
|
|
11
7
|
const VERSION_IN_TEXT = /v?(\d+)\.(\d+)\.(\d+)/i
|
|
12
8
|
|
|
13
|
-
// The version GeaStack targets when nothing overrides it
|
|
14
|
-
// release cannot be determined (offline, GitHub unreachable, rate limited).
|
|
9
|
+
// The version GeaStack targets when nothing overrides it.
|
|
15
10
|
// Bump this alongside board-script updates.
|
|
16
11
|
export const DEFAULT_ESP_IDF_VERSION = 'v6.0.2'
|
|
17
12
|
|
|
@@ -20,11 +15,8 @@ export function espIdfVersionForTarget(target) {
|
|
|
20
15
|
return target === 'esp32-s31-espressif-mosaico' ? '6.2-dev' : DEFAULT_ESP_IDF_VERSION.slice(1)
|
|
21
16
|
}
|
|
22
17
|
|
|
23
|
-
const GITHUB_LATEST_RELEASE_URL = 'https://api.github.com/repos/espressif/esp-idf/releases/latest'
|
|
24
|
-
|
|
25
18
|
// Parses a strict `vX.Y.Z` release tag. Returns null for anything else,
|
|
26
|
-
// including release candidates and betas (`v6.1.0-rc1`)
|
|
27
|
-
// filter those out of the "latest" lookup.
|
|
19
|
+
// including release candidates and betas (`v6.1.0-rc1`).
|
|
28
20
|
export function parseStableIdfTag(value) {
|
|
29
21
|
const match = STABLE_TAG.exec(String(value || '').trim())
|
|
30
22
|
if (!match) return null
|
|
@@ -39,42 +31,27 @@ export function extractIdfVersionFromText(text) {
|
|
|
39
31
|
return { majorMinor: `${match[1]}.${match[2]}`, full: `${match[1]}.${match[2]}.${match[3]}` }
|
|
40
32
|
}
|
|
41
33
|
|
|
42
|
-
// Best-effort lookup of the latest stable ESP-IDF release tag from GitHub.
|
|
43
|
-
// Never throws: returns '' when the request fails, times out (~4s default),
|
|
44
|
-
// the machine is offline, or the latest release is not a stable vX.Y.Z tag.
|
|
45
|
-
// `fetchImpl` defaults to the global fetch; tests inject a fake instead of
|
|
46
|
-
// touching the network.
|
|
47
|
-
export async function fetchLatestEspIdfVersion({ fetchImpl = globalThis.fetch, timeoutMs = 4000, log = () => {} } = {}) {
|
|
48
|
-
if (typeof fetchImpl !== 'function') return ''
|
|
49
|
-
const controller = new AbortController()
|
|
50
|
-
const timer = setTimeout(() => controller.abort(), timeoutMs)
|
|
51
|
-
try {
|
|
52
|
-
const response = await fetchImpl(GITHUB_LATEST_RELEASE_URL, {
|
|
53
|
-
signal: controller.signal,
|
|
54
|
-
headers: { Accept: 'application/vnd.github+json' }
|
|
55
|
-
})
|
|
56
|
-
if (!response?.ok) return ''
|
|
57
|
-
const body = await response.json()
|
|
58
|
-
return parseStableIdfTag(body?.tag_name)?.tag || ''
|
|
59
|
-
} catch (error) {
|
|
60
|
-
log(`Could not determine the latest ESP-IDF release (${error.message}); using ${DEFAULT_ESP_IDF_VERSION}.`)
|
|
61
|
-
return ''
|
|
62
|
-
} finally {
|
|
63
|
-
clearTimeout(timer)
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
|
|
67
34
|
// Resolves the ESP-IDF version tag to install/verify against, in order:
|
|
68
35
|
// 1. `override` (--idf-version) or GEA_ESP_IDF_VERSION -- explicit pin or
|
|
69
36
|
// a release candidate to test; used as-is (not required to be stable).
|
|
70
|
-
// 2.
|
|
71
|
-
//
|
|
72
|
-
|
|
37
|
+
// 2. DEFAULT_ESP_IDF_VERSION.
|
|
38
|
+
// Builds accept exactly the release espIdfVersionForTarget names, so setup
|
|
39
|
+
// installs that one: a newer stable release would install cleanly and then be
|
|
40
|
+
// refused by every build.
|
|
41
|
+
export async function resolveEspIdfVersion({ override, env = process.env } = {}) {
|
|
73
42
|
const requested = override || env.GEA_ESP_IDF_VERSION
|
|
74
43
|
// Only a bare version gains the tag's `v`; a branch (`master`) is cloned as named.
|
|
75
44
|
if (requested) return /^\d/.test(requested) ? `v${requested}` : requested
|
|
76
|
-
|
|
77
|
-
|
|
45
|
+
return DEFAULT_ESP_IDF_VERSION
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
// True when an installed ESP-IDF satisfies the setup target. For the pinned
|
|
49
|
+
// default that means being that exact release, because builds look for exactly
|
|
50
|
+
// it: reporting a newer release as "found" leaves a machine no build accepts.
|
|
51
|
+
// A version the user asked for by name keeps the major.minor floor.
|
|
52
|
+
export function idfVersionSatisfiesTarget(installedVersion, targetTag) {
|
|
53
|
+
if (targetTag !== DEFAULT_ESP_IDF_VERSION) return idfVersionMeetsTarget(installedVersion, targetTag)
|
|
54
|
+
return installedVersion?.full === DEFAULT_ESP_IDF_VERSION.slice(1)
|
|
78
55
|
}
|
|
79
56
|
|
|
80
57
|
// True when an installed ESP-IDF's version.cmake-derived version satisfies
|
package/src/gea.mjs
CHANGED
|
@@ -53,10 +53,8 @@ export async function runGea(argv, io = {}) {
|
|
|
53
53
|
|
|
54
54
|
const ctx = createContext(parsed, env, cwd)
|
|
55
55
|
const rest = parsed.positionals.slice(1)
|
|
56
|
-
// probeSerialDevice lets tests answer `gea boards discover` without a port
|
|
57
|
-
|
|
58
|
-
// "latest release" lookup without touching the network.
|
|
59
|
-
const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice, fetchEspIdfLatest: io.fetchEspIdfLatest }
|
|
56
|
+
// probeSerialDevice lets tests answer `gea boards discover` without a port.
|
|
57
|
+
const options = { stdout, stderr, env, stdin, output, prompt, probeSerialDevice: io.probeSerialDevice }
|
|
60
58
|
|
|
61
59
|
if (option(parsed, 'debug-fps') !== undefined && !flag(parsed, 'debug')) fail('--debug-fps requires --debug.', ExitCode.usage)
|
|
62
60
|
if (flag(parsed, 'debug-sources') && !flag(parsed, 'debug')) fail('--debug-sources requires --debug with macOS or an ESP32-S3 board.', ExitCode.usage)
|
|
@@ -117,11 +115,12 @@ export async function runGea(argv, io = {}) {
|
|
|
117
115
|
// selection for a bare `gea build`, so the command still reports which board
|
|
118
116
|
// it needs rather than quietly producing a .app in place of firmware. For those
|
|
119
117
|
// apps the Mac build is the documented `gea build --target macos`.
|
|
120
|
-
|
|
118
|
+
// `gea run` is the same selection followed by launching the built .app.
|
|
119
|
+
if ((command === 'build' || command === 'run') && (target === 'macos' || (!target && !option(parsed, 'board')))) {
|
|
121
120
|
const app = parsed.options.app || rest[0] ? findAppById(ctx, String(parsed.options.app || rest[0])) : findCurrentApp(cwd)
|
|
122
121
|
if (app?.targets?.macos && (target === 'macos' || (process.platform === 'darwin' && !declaresBoardTarget(app)))) {
|
|
123
122
|
const { runMacos } = await import('./macos/adapter.mjs')
|
|
124
|
-
return runMacos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout })
|
|
123
|
+
return runMacos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, run: command === 'run' })
|
|
125
124
|
}
|
|
126
125
|
if (target === 'macos') {
|
|
127
126
|
fail(app ? `'${app.id}' does not declare gea.targets.macos.` : 'No app selected. Pass --app <id> or run inside a Gea app folder.', ExitCode.usage)
|
|
@@ -301,6 +300,7 @@ ${heading('Run on this machine (no board needed):')}
|
|
|
301
300
|
${heading('Native desktop, mobile and watch apps (scripts ship in @geastack/apple, @geastack/windows and @geastack/pebble):')}
|
|
302
301
|
gea build --target raspberry-pi-os [app] build an SDL Linux native executable (no launch)
|
|
303
302
|
gea build --target macos [app] build a Mac .app (a bare gea build does this on a Mac for a Mac-only app)
|
|
303
|
+
gea run --target macos [app] build, then open the Mac .app
|
|
304
304
|
gea build --target ios [app] [--mode simulator|device] generate the Xcode project and build the iOS .app
|
|
305
305
|
gea build --target tvos [app] [--mode simulator|device] build the tvOS .app
|
|
306
306
|
gea run --target tvos [app] [--mode simulator|device] install and launch on Apple TV or its simulator
|
package/src/macos/adapter.mjs
CHANGED
|
@@ -13,19 +13,36 @@ import { formatCommand } from '../run.mjs'
|
|
|
13
13
|
// @geastack/apple -- which an apple-native app already depends on -- so the
|
|
14
14
|
// app's own module resolution is what finds it. An app declares `targets.macos`
|
|
15
15
|
// and nothing else; the script reads the rest from the same manifest.
|
|
16
|
-
export function runMacos({ app, env, dryRun = false, stdout }) {
|
|
16
|
+
export function runMacos({ app, env, dryRun = false, stdout, run = false }) {
|
|
17
17
|
const { script, require } = appleTargetScript(app, 'macos', 'build-macos.sh', env)
|
|
18
18
|
const childEnv = appleChildEnv(app, nativeScriptBuildEnv(app, 'macos', env, { dryRun }), require)
|
|
19
|
+
const bundle = macosAppBundle(app, env)
|
|
19
20
|
if (dryRun) {
|
|
20
21
|
stdout(formatCommand(['bash', script, app.id]))
|
|
22
|
+
if (run) stdout(formatCommand(['open', bundle]))
|
|
21
23
|
return 0
|
|
22
24
|
}
|
|
25
|
+
if (run && process.platform !== 'darwin') fail('gea run --target macos launches the app, which requires a Mac. Use gea build --target macos to build only.', ExitCode.usage)
|
|
23
26
|
const result = spawnSync('bash', [script, app.id], { cwd: app.root, env: childEnv, stdio: 'inherit' })
|
|
24
27
|
if (result.error) throw result.error
|
|
25
28
|
if (result.status !== 0) throw new CliError(`macOS build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
|
|
29
|
+
if (!run) return 0
|
|
30
|
+
if (!existsSync(bundle)) fail(`Built app not found: ${bundle}`, ExitCode.buildFailed)
|
|
31
|
+
const launched = spawnSync('open', [bundle], { cwd: app.root, stdio: 'inherit' })
|
|
32
|
+
if (launched.error) throw launched.error
|
|
33
|
+
if (launched.status !== 0) throw new CliError(`Could not launch ${bundle} (${launched.status ?? 1}).`, ExitCode.deployFailed)
|
|
26
34
|
return 0
|
|
27
35
|
}
|
|
28
36
|
|
|
37
|
+
// Where build-macos.sh leaves the bundle: <output root>/<app id>/<name>.app,
|
|
38
|
+
// with the same GEA_MACOS_OUTPUT_DIR / GEA_MACOS_OUTPUT_TAG overrides the
|
|
39
|
+
// script reads.
|
|
40
|
+
export function macosAppBundle(app, env = process.env) {
|
|
41
|
+
const outputRoot = path.resolve(app.root, env.GEA_MACOS_OUTPUT_DIR || 'dist/macos')
|
|
42
|
+
const subpath = env.GEA_MACOS_OUTPUT_TAG ? path.join('.namespaces', env.GEA_MACOS_OUTPUT_TAG, app.id) : app.id
|
|
43
|
+
return path.join(outputRoot, subpath, `${app.name}.app`)
|
|
44
|
+
}
|
|
45
|
+
|
|
29
46
|
// Both Apple targets ship as one script each inside @geastack/apple, and both
|
|
30
47
|
// resolve it the same way: through the app's own dependencies. iOS reuses this
|
|
31
48
|
// from src/ios/adapter.mjs rather than restating the resolution.
|
package/src/manifest.mjs
CHANGED
|
@@ -214,8 +214,21 @@ export function appCmakeDefines(app) {
|
|
|
214
214
|
return app.defines.join(';')
|
|
215
215
|
}
|
|
216
216
|
|
|
217
|
-
|
|
218
|
-
|
|
217
|
+
// A board's block (gea.targets.<target>.boards.<board-id>) may overrule the
|
|
218
|
+
// board settings an app picks for itself: psram and display merge over the
|
|
219
|
+
// target-wide value, a nonzero flashFreq replaces it, and a board's own
|
|
220
|
+
// `sdkconfig` file is used in place of the target-wide one.
|
|
221
|
+
export function appTargetConfig(app, target, boardId = '') {
|
|
222
|
+
const config = app.targetConfig?.[target] || emptyTargetConfig()
|
|
223
|
+
const board = boardId ? config.boardSettings?.[boardId] : null
|
|
224
|
+
if (!board) return config
|
|
225
|
+
return {
|
|
226
|
+
...config,
|
|
227
|
+
psram: board.psram ? { ...config.psram, ...board.psram } : config.psram,
|
|
228
|
+
flashFreq: board.flashFreq || config.flashFreq,
|
|
229
|
+
sdkconfig: board.sdkconfig || config.sdkconfig,
|
|
230
|
+
display: board.display ? { ...config.display, ...board.display } : config.display
|
|
231
|
+
}
|
|
219
232
|
}
|
|
220
233
|
|
|
221
234
|
// Paths a target's config names are relative to the app; absolute them once
|
|
@@ -417,7 +430,7 @@ export function normalizeDefines(raw) {
|
|
|
417
430
|
|
|
418
431
|
|
|
419
432
|
function emptyTargetConfig() {
|
|
420
|
-
return { nativeSources: [], providers: {}, tsconfig: '', nativeIncludeDirectories: [], nativeSystemLibraries: [], nativeResources: {}, nativeLibraries: [], frameworks: [], ldFragments: [], componentDirs: [], componentRequires: [], linkOptions: [], embedFiles: {}, partitions: null, partitionsByTarget: {}, sdkconfig: '', psram: null, flashFreq: 0, display: null, prebuild: '', output: '' }
|
|
433
|
+
return { nativeSources: [], providers: {}, tsconfig: '', nativeIncludeDirectories: [], nativeSystemLibraries: [], nativeResources: {}, nativeLibraries: [], frameworks: [], ldFragments: [], componentDirs: [], componentRequires: [], linkOptions: [], embedFiles: {}, partitions: null, partitionsByTarget: {}, sdkconfig: '', psram: null, flashFreq: 0, display: null, boardSettings: {}, prebuild: '', output: '' }
|
|
421
434
|
}
|
|
422
435
|
|
|
423
436
|
function normalizeStringList(raw) {
|
|
@@ -507,6 +520,7 @@ function normalizeTargetConfig(raw) {
|
|
|
507
520
|
// How the RGB panel's repaints reach PSRAM, for apps that redraw the whole
|
|
508
521
|
// screen every frame (games): { copyBack: 'dma', bounceRows, gridStrips }.
|
|
509
522
|
display: value.display && typeof value.display === 'object' && !Array.isArray(value.display) ? { ...value.display } : null,
|
|
523
|
+
boardSettings: normalizeBoardSettings(value.boards),
|
|
510
524
|
prebuild: typeof value.prebuild === 'string' ? value.prebuild.trim() : '',
|
|
511
525
|
output: typeof value.output === 'string' && value.output.trim() ? normalizeManifestRelativePath(value.output) : ''
|
|
512
526
|
}
|
|
@@ -514,6 +528,12 @@ function normalizeTargetConfig(raw) {
|
|
|
514
528
|
return configs
|
|
515
529
|
}
|
|
516
530
|
|
|
531
|
+
function normalizeBoardSettings(boards) {
|
|
532
|
+
if (!boards || typeof boards !== 'object' || Array.isArray(boards)) return {}
|
|
533
|
+
const object = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? { ...value } : null)
|
|
534
|
+
return Object.fromEntries(Object.entries(boards).filter(([, board]) => object(board)).map(([id, board]) => [id, { psram: object(board.psram), flashFreq: Number(board.flashFreq) || 0, sdkconfig: typeof board.sdkconfig === 'string' && board.sdkconfig.trim() ? normalizeManifestRelativePath(board.sdkconfig) : '', display: object(board.display) }]))
|
|
535
|
+
}
|
|
536
|
+
|
|
517
537
|
export function normalizeApp(root, packageJson) {
|
|
518
538
|
const gea = packageJson.gea || {}
|
|
519
539
|
const id = typeof gea.id === 'string' && gea.id ? gea.id : packageId(packageJson.name)
|
package/src/setup-wizard.mjs
CHANGED
|
@@ -10,9 +10,9 @@ import { configureChipSelection, loadChipCatalog, validateGpioAssignments } from
|
|
|
10
10
|
import { flag, option } from './args.mjs'
|
|
11
11
|
import { ExitCode, fail } from './errors.mjs'
|
|
12
12
|
import { espIdfVersion as readInstalledEspIdfVersion, findEspIdf, findIdfPythonEnv } from './esp32/idf-env.mjs'
|
|
13
|
-
import { espIdfVersionForTarget, extractIdfVersionFromText,
|
|
13
|
+
import { espIdfVersionForTarget, extractIdfVersionFromText, DEFAULT_ESP_IDF_VERSION, idfVersionMeetsTarget, idfVersionSatisfiesTarget, resolveEspIdfVersion } from './esp32/idf-version.mjs'
|
|
14
14
|
import { exists, readJson, writeJson } from './fs-utils.mjs'
|
|
15
|
-
import { BACK, ask, choose, confirm, createPrompt, ui } from './prompts.mjs'
|
|
15
|
+
import { BACK, ask, canPrompt, choose, confirm, createPrompt, ui } from './prompts.mjs'
|
|
16
16
|
import { runExternal, runQuiet } from './run.mjs'
|
|
17
17
|
import { detectSerialDevices } from './serial-devices.mjs'
|
|
18
18
|
import { commandVersion } from './toolchain.mjs'
|
|
@@ -26,6 +26,9 @@ const s31EspIdf = { version: '6.2-dev', ref: 'master', dir: path.join('esp32', '
|
|
|
26
26
|
|
|
27
27
|
export async function runSetupWizard(ctx, parsed, io) {
|
|
28
28
|
const stdout = io.stdout || console.log
|
|
29
|
+
if (!canPrompt(io) && option(parsed, 'esp-idf') !== true) {
|
|
30
|
+
fail('gea setup asks questions and needs a terminal. Without one, pass --board <alias>, --target <id> or --esp-idf.', ExitCode.usage)
|
|
31
|
+
}
|
|
29
32
|
const prompt = createPrompt(io)
|
|
30
33
|
try {
|
|
31
34
|
const targetIdfVersion = await resolveEspIdfVersionForWizard(parsed, io)
|
|
@@ -443,16 +446,12 @@ async function chooseAppForBoard(ctx, parsed, io, prompt, alias) {
|
|
|
443
446
|
}
|
|
444
447
|
|
|
445
448
|
// Resolves the ESP-IDF version target once for the whole wizard run:
|
|
446
|
-
// --idf-version / GEA_ESP_IDF_VERSION win outright; otherwise
|
|
447
|
-
//
|
|
448
|
-
// cannot be determined. `io.fetchEspIdfLatest` lets callers (tests) inject a
|
|
449
|
-
// fake fetch instead of touching the network -- mirrors `probeSerialDevice`.
|
|
449
|
+
// --idf-version / GEA_ESP_IDF_VERSION win outright; otherwise the pinned
|
|
450
|
+
// release, which is the one every build looks for.
|
|
450
451
|
async function resolveEspIdfVersionForWizard(parsed, io) {
|
|
451
452
|
return resolveEspIdfVersion({
|
|
452
453
|
override: option(parsed, 'idf-version'),
|
|
453
|
-
env: io.env || process.env
|
|
454
|
-
fetchLatest: io.fetchEspIdfLatest || fetchLatestEspIdfVersion,
|
|
455
|
-
log: io.stderr || (() => {})
|
|
454
|
+
env: io.env || process.env
|
|
456
455
|
})
|
|
457
456
|
}
|
|
458
457
|
|
|
@@ -564,8 +563,9 @@ function installEspIdf(ctx, parsed, io, { idfDir, ref, targets }) {
|
|
|
564
563
|
}
|
|
565
564
|
|
|
566
565
|
// Prefers the same conventional-directory detection the build path uses
|
|
567
|
-
// (`findEspIdf` + its version.cmake),
|
|
568
|
-
//
|
|
566
|
+
// (`findEspIdf` + its version.cmake), asking for the target release first so
|
|
567
|
+
// the answer is the directory a build would pick; falls back to a bare
|
|
568
|
+
// `idf.py --version` on PATH when no such directory is
|
|
569
569
|
// found but some ESP-IDF install has still put idf.py on PATH.
|
|
570
570
|
// An explicit --idf-dir is the only directory that counts: another install
|
|
571
571
|
// elsewhere is not the one asked for, and a branch target such as `master`
|
|
@@ -574,7 +574,13 @@ function detectEspIdf(env, targetVersion, explicitDir = '') {
|
|
|
574
574
|
if (explicitDir && !fs.existsSync(path.join(explicitDir, 'tools', 'idf.py'))) {
|
|
575
575
|
return { available: false, detail: '' }
|
|
576
576
|
}
|
|
577
|
-
|
|
577
|
+
// For the pinned default, "found" means the directory a build would pick:
|
|
578
|
+
// builds look for that exact release (IDF_PATH aside), so a newer one on
|
|
579
|
+
// its own is reported, not accepted.
|
|
580
|
+
const home = env.HOME || env.USERPROFILE || os.homedir()
|
|
581
|
+
const pinned = !explicitDir && targetVersion === DEFAULT_ESP_IDF_VERSION
|
|
582
|
+
const buildDir = pinned ? findEspIdf(env, home, { defaultVersion: DEFAULT_ESP_IDF_VERSION.slice(1) }) : ''
|
|
583
|
+
const idfDir = explicitDir ? path.resolve(explicitDir) : buildDir || findEspIdf(env, home)
|
|
578
584
|
if (idfDir) {
|
|
579
585
|
const installed = readInstalledEspIdfVersion(idfDir)
|
|
580
586
|
// A checkout is not an installation. `install.bat`/`install.sh` still has to
|
|
@@ -583,12 +589,12 @@ function detectEspIdf(env, targetVersion, explicitDir = '') {
|
|
|
583
589
|
// success and leaves nothing that can compile.
|
|
584
590
|
const toolsInstalled = Boolean(findIdfPythonEnv(idfDir, env))
|
|
585
591
|
const detail = `${installed?.full || 'unknown version'} at ${idfDir}${toolsInstalled ? '' : ' (tools not installed)'}`
|
|
586
|
-
return { available: toolsInstalled && idfVersionMeetsTarget(installed, targetVersion), detail }
|
|
592
|
+
return { available: toolsInstalled && (pinned ? Boolean(buildDir) : idfVersionMeetsTarget(installed, targetVersion)), detail }
|
|
587
593
|
}
|
|
588
594
|
const legacyOutput = commandVersion('idf.py', ['--version'], env)
|
|
589
595
|
if (legacyOutput) {
|
|
590
596
|
const installed = extractIdfVersionFromText(legacyOutput)
|
|
591
|
-
const available = !installed ||
|
|
597
|
+
const available = !installed || idfVersionSatisfiesTarget(installed, targetVersion)
|
|
592
598
|
return { available, detail: legacyOutput }
|
|
593
599
|
}
|
|
594
600
|
return { available: false, detail: '' }
|
package/src/web/adapter.mjs
CHANGED
|
@@ -170,7 +170,8 @@ async function startSimulatorServer({ ctx, app, env, simulatorDir, paths, port,
|
|
|
170
170
|
__GEA_WEB_DIST_FS_ROOT__: JSON.stringify(paths.dist)
|
|
171
171
|
},
|
|
172
172
|
server: {
|
|
173
|
-
port
|
|
173
|
+
// No --port leaves this an empty string; newer Node rejects that as a port.
|
|
174
|
+
...(port ? { port: Number(port) } : {}),
|
|
174
175
|
fs: { allow: [appRoot, paths.dist, paths.public] }
|
|
175
176
|
}
|
|
176
177
|
})
|