@geastack/cli 0.1.79 → 0.1.81

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/docs/SETUP.md CHANGED
@@ -14,7 +14,7 @@ npx gea doctor
14
14
  ## Minimum Setup
15
15
 
16
16
  ```sh
17
- npx @geastack/create-geastack my-app
17
+ npx create-geastack my-app
18
18
  cd my-app
19
19
  npx gea setup
20
20
  ```
@@ -333,6 +333,63 @@ at call time, so never record a port path.
333
333
  - `targetDefinition` points at a custom target composed by `gea setup` /
334
334
  `gea chips`, relative to the file the alias lives in.
335
335
 
336
+ ### Composed targets
337
+
338
+ A composed target is a JSON definition that extends the `esp32-s3` base and
339
+ picks its chips from the `@geastack/chips` catalog (`gea chips list`). Every
340
+ role is optional, so the definition describes the hardware that is there:
341
+ `display`, `touch`, `power`, `imu`, `audio` and `expander`. Some boards are
342
+ shipped composed in `@geastack/targets` and need no definition of your own,
343
+ for example `esp32-s3-devkit-n16r8` (a bare module) and
344
+ `esp32-s3-waveshare-touch-lcd-7`.
345
+
346
+ Two kinds of display are understood. A QSPI controller (`co5300`) takes the
347
+ `spiHost` and `cs`/`pclk`/`data0-3`/`reset`/`te` pins. A bare parallel RGB
348
+ panel (`rgb_panel`) has no controller: it takes the panel geometry, the pixel
349
+ clock and sync timings, and the `de`/`hsync`/`vsync`/`pclk` plus sixteen
350
+ `data0-15` pins (blue in 0-4, green in 5-10, red in 11-15). The Waveshare
351
+ 7-inch board is the reference:
352
+
353
+ ```json
354
+ {
355
+ "id": "my-rgb-board",
356
+ "extends": "esp32-s3",
357
+ "adapter": "esp32-idf",
358
+ "mcu": "esp32s3",
359
+ "flashSize": "16MB",
360
+ "psram": { "mode": "octal", "speed": 80 },
361
+ "buses": { "i2c": { "sda": 8, "scl": 9 } },
362
+ "chips": {
363
+ "display": {
364
+ "driver": "rgb_panel", "interface": "rgb",
365
+ "width": 800, "height": 480, "pclkHz": 16000000,
366
+ "hsyncPulseWidth": 4, "hsyncBackPorch": 8, "hsyncFrontPorch": 8,
367
+ "vsyncPulseWidth": 4, "vsyncBackPorch": 8, "vsyncFrontPorch": 8,
368
+ "pclkActiveNeg": true,
369
+ "pins": {
370
+ "de": 5, "hsync": 46, "vsync": 3, "pclk": 7,
371
+ "data0": 14, "data1": 38, "data2": 18, "data3": 17, "data4": 10,
372
+ "data5": 39, "data6": 0, "data7": 45, "data8": 48, "data9": 47, "data10": 21,
373
+ "data11": 1, "data12": 2, "data13": 42, "data14": 41, "data15": 40
374
+ }
375
+ },
376
+ "touch": { "driver": "gt911", "interface": "i2c", "pins": { "interrupt": 4 } },
377
+ "expander": {
378
+ "driver": "ch422g", "interface": "i2c",
379
+ "initialOutputs": 30,
380
+ "outputs": { "touchReset": 1, "backlight": 2, "displayReset": 3 }
381
+ }
382
+ }
383
+ }
384
+ ```
385
+
386
+ The `expander` role is for boards that route slow control lines through an
387
+ I2C I/O expander instead of GPIOs. `outputs` names the expander pin that
388
+ carries each line; a display with no `pins.backlight` lights up through
389
+ `outputs.backlight`, and a touch controller with no `pins.reset` is reset
390
+ through `outputs.touchReset`. `initialOutputs` is the level mask latched at
391
+ boot.
392
+
336
393
  ## Common Verification Flow
337
394
 
338
395
  After installing tools:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/cli",
3
- "version": "0.1.79",
3
+ "version": "0.1.81",
4
4
  "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -38,12 +38,14 @@
38
38
  "dependencies": {
39
39
  "@clack/prompts": "^1.8.0",
40
40
  "@geastack/simulator": "^0.1.6",
41
+ "@geastack/targets": "^0.1.80",
41
42
  "picocolors": "^1.1.1",
42
43
  "serialport": "^13.0.0"
43
44
  },
44
45
  "starterDependencies": {
45
46
  "@geastack/core": "^0.1.23",
46
- "@geastack/targets": "^0.1.77"
47
+ "@geastack/targets": "^0.1.77",
48
+ "@geastack/apple": "^0.2.9"
47
49
  },
48
50
  "scripts": {
49
51
  "check": "node --check bin/gea.mjs && node --check bin/create-geastack.mjs && find src test packages -name '*.mjs' -print0 | xargs -0 -n1 node --check",
@@ -27,6 +27,14 @@ function integer(value, label, { min = 0, max = 48 } = {}) {
27
27
  return value
28
28
  }
29
29
 
30
+ function boolean(value, label, fallback) {
31
+ if (value === undefined || value === null) return fallback
32
+ if (typeof value === 'boolean') return value
33
+ if (value === 'true' || value === 1 || value === '1' || value === 'yes') return true
34
+ if (value === 'false' || value === 0 || value === '0' || value === 'no') return false
35
+ throw new Error(`${label} must be true or false.`)
36
+ }
37
+
30
38
  function pin(value, label, { optional = false } = {}) {
31
39
  if (optional && (value === null || value === undefined || value === 'none')) return -1
32
40
  return integer(value, label)
@@ -70,7 +78,10 @@ function selectedChip(chips, role, category, adapter, mcu, catalog) {
70
78
  driver,
71
79
  interface: interfaceName,
72
80
  nativeSources: Array.isArray(descriptor.sources) ? descriptor.sources : [],
73
- bindingSources: Array.isArray(adapterInfo.bindingSources) ? adapterInfo.bindingSources : []
81
+ bindingSources: Array.isArray(adapterInfo.bindingSources) ? adapterInfo.bindingSources : [],
82
+ // ESP-IDF components the binding includes headers from beyond what the
83
+ // base already links (the LEDC driver for a PWM backlight, say).
84
+ requires: Array.isArray(adapterInfo.requires) ? adapterInfo.requires : []
74
85
  }
75
86
  }
76
87
 
@@ -122,6 +133,10 @@ export function normalizeCustomTarget(raw, catalog) {
122
133
  const power = optionalChip(chips, 'power', 'power', adapter, mcu, catalog)
123
134
  const imu = optionalChip(chips, 'imu', 'imu', adapter, mcu, catalog)
124
135
  const audio = optionalChip(chips, 'audio', 'audio', adapter, mcu, catalog)
136
+ // An I/O expander is not a peripheral of its own: it is where a board puts
137
+ // the slow control lines (backlight enable, touch reset, panel reset) it ran
138
+ // out of GPIOs for. The chips that need those lines look them up here.
139
+ const expander = optionalChip(chips, 'expander', 'expander', adapter, mcu, catalog)
125
140
  const buses = absent(definition.buses) ? {} : object(definition.buses, 'buses')
126
141
  const storage = absent(definition.storage) ? {} : object(definition.storage, 'storage')
127
142
  const controls = absent(definition.controls) ? {} : object(definition.controls, 'controls')
@@ -133,7 +148,8 @@ export function normalizeCustomTarget(raw, catalog) {
133
148
  const i2cChips = [
134
149
  [touch, 'chips.touch'],
135
150
  [power, 'chips.power'],
136
- [imu, 'chips.imu']
151
+ [imu, 'chips.imu'],
152
+ [expander, 'chips.expander']
137
153
  ].filter(([chip]) => chip && chip.interface === 'i2c')
138
154
  if (absent(buses.i2c) && i2cChips.length > 0) {
139
155
  throw new Error(`buses.i2c is required because ${i2cChips.map(([, label]) => label).join(', ')} ${i2cChips.length > 1 ? 'are' : 'is'} on the I2C bus.`)
@@ -141,12 +157,21 @@ export function normalizeCustomTarget(raw, catalog) {
141
157
  const i2c = absent(buses.i2c) ? null : object(buses.i2c, 'buses.i2c')
142
158
 
143
159
  const displayPins = display ? object(display.pins, 'chips.display.pins') : null
144
- const touchPins = touch ? object(touch.pins, 'chips.touch.pins') : null
160
+ const touchPins = touch ? (absent(touch.pins) ? {} : object(touch.pins, 'chips.touch.pins')) : null
145
161
  const audioPins = audio ? object(audio.pins, 'chips.audio.pins') : null
146
162
  const storagePins = microSD ? object(microSD.pins, 'storage.microSD.pins') : null
147
163
 
148
- const spiHost = display ? String(display.spiHost).toLowerCase() : 'spi2'
149
- if (display && !['spi2', 'spi3'].includes(spiHost)) throw new Error("chips.display.spiHost must be 'spi2' or 'spi3'.")
164
+ // Two kinds of panel: a controller-driven QSPI AMOLED (the base's own kind)
165
+ // and a bare parallel RGB panel scanned out by the S3's LCD peripheral. They
166
+ // share nothing but a size, so each carries its own pins and parameters.
167
+ const displayInterface = display ? display.interface : ''
168
+ if (display && !['qspi', 'rgb'].includes(displayInterface)) {
169
+ throw new Error(`chips.display.interface '${displayInterface}' is not supported by the ${supportedBase} base. Supported values: qspi, rgb.`)
170
+ }
171
+ const spiHost = display && displayInterface === 'qspi' ? String(display.spiHost ?? 'spi2').toLowerCase() : 'spi2'
172
+ if (display && displayInterface === 'qspi' && !['spi2', 'spi3'].includes(spiHost)) throw new Error("chips.display.spiHost must be 'spi2' or 'spi3'.")
173
+ const expanderOutputs = expander ? (absent(expander.outputs) ? {} : object(expander.outputs, 'chips.expander.outputs')) : null
174
+ const expanderPin = (value, label) => (absent(value) ? -1 : integer(value, label, { min: 0, max: 15 }))
150
175
 
151
176
  // Flash size and the partition table are board geometry, not app policy: a
152
177
  // module with 16MB of flash cannot borrow its base's 32MB layout, and every
@@ -201,14 +226,40 @@ export function normalizeCustomTarget(raw, catalog) {
201
226
  // No panel: the board draws into an offscreen canvas and transmits nothing.
202
227
  canvas: display ? null : headlessCanvas(definition),
203
228
  chips: {
204
- display: display === null ? null : {
229
+ display: display === null ? null : displayInterface === 'rgb' ? {
230
+ driver: display.driver,
231
+ interface: 'rgb',
232
+ width: integer(display.width, 'chips.display.width', { min: 1, max: 4096 }),
233
+ height: integer(display.height, 'chips.display.height', { min: 1, max: 4096 }),
234
+ pclkHz: integer(display.pclkHz ?? 16000000, 'chips.display.pclkHz', { min: 1000000, max: 40000000 }),
235
+ hsyncPulseWidth: integer(display.hsyncPulseWidth ?? 4, 'chips.display.hsyncPulseWidth', { min: 1, max: 1024 }),
236
+ hsyncBackPorch: integer(display.hsyncBackPorch ?? 8, 'chips.display.hsyncBackPorch', { min: 0, max: 1024 }),
237
+ hsyncFrontPorch: integer(display.hsyncFrontPorch ?? 8, 'chips.display.hsyncFrontPorch', { min: 0, max: 1024 }),
238
+ vsyncPulseWidth: integer(display.vsyncPulseWidth ?? 4, 'chips.display.vsyncPulseWidth', { min: 1, max: 1024 }),
239
+ vsyncBackPorch: integer(display.vsyncBackPorch ?? 8, 'chips.display.vsyncBackPorch', { min: 0, max: 1024 }),
240
+ vsyncFrontPorch: integer(display.vsyncFrontPorch ?? 8, 'chips.display.vsyncFrontPorch', { min: 0, max: 1024 }),
241
+ pclkActiveNeg: boolean(display.pclkActiveNeg, 'chips.display.pclkActiveNeg', true),
242
+ nativeSources: display.nativeSources,
243
+ bindingSources: display.bindingSources,
244
+ requires: display.requires,
245
+ pins: {
246
+ de: pin(displayPins.de, 'chips.display.pins.de'),
247
+ hsync: pin(displayPins.hsync, 'chips.display.pins.hsync'),
248
+ vsync: pin(displayPins.vsync, 'chips.display.pins.vsync'),
249
+ pclk: pin(displayPins.pclk, 'chips.display.pins.pclk'),
250
+ data: Array.from({ length: 16 }, (_, index) => pin(displayPins[`data${index}`], `chips.display.pins.data${index}`)),
251
+ disp: pin(displayPins.disp, 'chips.display.pins.disp', { optional: true }),
252
+ backlight: pin(displayPins.backlight, 'chips.display.pins.backlight', { optional: true })
253
+ }
254
+ } : {
205
255
  driver: display.driver,
206
- interface: exact(display.interface, 'qspi', 'chips.display.interface'),
256
+ interface: 'qspi',
207
257
  width: integer(display.width, 'chips.display.width', { min: 1, max: 4096 }),
208
258
  height: integer(display.height, 'chips.display.height', { min: 1, max: 4096 }),
209
259
  spiHost,
210
260
  nativeSources: display.nativeSources,
211
261
  bindingSources: display.bindingSources,
262
+ requires: display.requires,
212
263
  pins: {
213
264
  cs: pin(displayPins.cs, 'chips.display.pins.cs'),
214
265
  pclk: pin(displayPins.pclk, 'chips.display.pins.pclk'),
@@ -225,28 +276,47 @@ export function normalizeCustomTarget(raw, catalog) {
225
276
  interface: exact(touch.interface, 'i2c', 'chips.touch.interface'),
226
277
  nativeSources: touch.nativeSources,
227
278
  bindingSources: touch.bindingSources,
279
+ requires: touch.requires,
280
+ // Both lines are optional: a board may route reset through its I/O
281
+ // expander and leave INT unwired, in which case the binding polls.
228
282
  pins: {
229
- reset: pin(touchPins.reset, 'chips.touch.pins.reset'),
230
- interrupt: pin(touchPins.interrupt, 'chips.touch.pins.interrupt')
283
+ reset: pin(touchPins.reset, 'chips.touch.pins.reset', { optional: true }),
284
+ interrupt: pin(touchPins.interrupt, 'chips.touch.pins.interrupt', { optional: true })
285
+ }
286
+ },
287
+ expander: expander === null ? null : {
288
+ driver: expander.driver,
289
+ interface: exact(expander.interface, 'i2c', 'chips.expander.interface'),
290
+ nativeSources: expander.nativeSources,
291
+ bindingSources: expander.bindingSources,
292
+ requires: expander.requires,
293
+ initialOutputs: integer(expander.initialOutputs ?? 255, 'chips.expander.initialOutputs', { min: 0, max: 255 }),
294
+ outputs: {
295
+ backlight: expanderPin(expanderOutputs.backlight, 'chips.expander.outputs.backlight'),
296
+ touchReset: expanderPin(expanderOutputs.touchReset, 'chips.expander.outputs.touchReset'),
297
+ displayReset: expanderPin(expanderOutputs.displayReset, 'chips.expander.outputs.displayReset')
231
298
  }
232
299
  },
233
300
  power: power === null ? null : {
234
301
  driver: power.driver,
235
302
  interface: exact(power.interface, 'i2c', 'chips.power.interface'),
236
303
  nativeSources: power.nativeSources,
237
- bindingSources: power.bindingSources
304
+ bindingSources: power.bindingSources,
305
+ requires: power.requires
238
306
  },
239
307
  imu: imu === null ? null : {
240
308
  driver: imu.driver,
241
309
  interface: exact(imu.interface, 'i2c', 'chips.imu.interface'),
242
310
  nativeSources: imu.nativeSources,
243
- bindingSources: imu.bindingSources
311
+ bindingSources: imu.bindingSources,
312
+ requires: imu.requires
244
313
  },
245
314
  audio: audio === null ? null : {
246
315
  driver: audio.driver,
247
316
  interface: exact(audio.interface, 'i2s', 'chips.audio.interface'),
248
317
  nativeSources: audio.nativeSources,
249
318
  bindingSources: audio.bindingSources,
319
+ requires: audio.requires,
250
320
  pins: {
251
321
  mclk: pin(audioPins.mclk, 'chips.audio.pins.mclk'),
252
322
  bclk: pin(audioPins.bclk, 'chips.audio.pins.bclk'),
@@ -287,7 +357,16 @@ function validatePinAssignments(target) {
287
357
  // role owns no GPIO and so can never collide with one.
288
358
  const pins = [
289
359
  ...(i2c ? [['I2C SDA', i2c.sda], ['I2C SCL', i2c.scl]] : []),
290
- ...(display ? [
360
+ ...(display && display.interface === 'rgb' ? [
361
+ ['display DE', display.pins.de],
362
+ ['display HSYNC', display.pins.hsync],
363
+ ['display VSYNC', display.pins.vsync],
364
+ ['display PCLK', display.pins.pclk],
365
+ ...display.pins.data.map((value, index) => [`display DATA${index}`, value]),
366
+ ['display DISP', display.pins.disp],
367
+ ['display backlight', display.pins.backlight]
368
+ ] : []),
369
+ ...(display && display.interface === 'qspi' ? [
291
370
  ['display CS', display.pins.cs],
292
371
  ['display PCLK', display.pins.pclk],
293
372
  ['display DATA0', display.pins.data0],
@@ -337,7 +416,9 @@ const noPins = new Proxy({}, { get: () => -1 })
337
416
 
338
417
  export function renderBoardHeader(target) {
339
418
  const i2c = target.buses.i2c || noPins
340
- const { display, touch, audio } = target.chips
419
+ const { display, touch, audio, expander } = target.chips
420
+ const rgb = display && display.interface === 'rgb' ? display : null
421
+ const qspi = display && display.interface === 'qspi' ? display : null
341
422
  const displayPins = display ? display.pins : noPins
342
423
  const touchPins = touch ? touch.pins : noPins
343
424
  const audioPins = audio ? audio.pins : noPins
@@ -350,7 +431,7 @@ export function renderBoardHeader(target) {
350
431
  const includes = [
351
432
  '#include "driver/gpio.h"',
352
433
  audio ? '#include "driver/i2s_types.h"' : '',
353
- display ? '#include "driver/spi_master.h"' : ''
434
+ qspi ? '#include "driver/spi_master.h"' : ''
354
435
  ].filter(Boolean).join('\n')
355
436
  return `#pragma once
356
437
 
@@ -366,6 +447,7 @@ ${includes}
366
447
  #define GEA_BOARD_HAS_AUDIO ${audio ? 1 : 0}
367
448
  #define GEA_BOARD_HAS_MICROSD ${target.storage.microSD ? 1 : 0}
368
449
  #define GEA_BOARD_HAS_LAUNCHER_BUTTON ${target.controls.launcherButton ? 1 : 0}
450
+ #define GEA_BOARD_HAS_EXPANDER ${expander ? 1 : 0}
369
451
 
370
452
  namespace gea::platform::board {
371
453
 
@@ -378,18 +460,31 @@ namespace gea::platform::board {
378
460
  struct I2cBusConfig { gpio_num_t sda; gpio_num_t scl; };
379
461
  struct SdMmcConfig { gpio_num_t clk; gpio_num_t cmd; gpio_num_t data0; };
380
462
  struct LauncherButtonConfig { gpio_num_t pin; int activeLevel; };
381
- ${display ? 'struct Co5300DisplayConfig { spi_host_device_t spiHost; gpio_num_t cs; gpio_num_t pclk; gpio_num_t data0; gpio_num_t data1; gpio_num_t data2; gpio_num_t data3; gpio_num_t reset; gpio_num_t te; };' : ''}${touch ? '\nstruct Ft3168TouchConfig { gpio_num_t reset; gpio_num_t interrupt; };' : ''}${audio ? '\nstruct Es8311AudioConfig { int i2sPort; gpio_num_t mclk; gpio_num_t bclk; gpio_num_t ws; gpio_num_t dout; gpio_num_t din; gpio_num_t powerAmplifier; };' : ''}
463
+ ${qspi ? 'struct Co5300DisplayConfig { spi_host_device_t spiHost; gpio_num_t cs; gpio_num_t pclk; gpio_num_t data0; gpio_num_t data1; gpio_num_t data2; gpio_num_t data3; gpio_num_t reset; gpio_num_t te; };' : ''}${rgb ? `// A bare parallel RGB panel: no controller, the LCD peripheral scans the
464
+ // framebuffer out with these timings. data[0..4] are blue, [5..10] green,
465
+ // [11..15] red (RGB565 lane order). backlight is a PWM-capable GPIO, or
466
+ // GPIO_NUM_NC when the expander drives it.
467
+ struct RgbPanelDisplayConfig { gpio_num_t de; gpio_num_t hsync; gpio_num_t vsync; gpio_num_t pclk; gpio_num_t disp; gpio_num_t backlight; gpio_num_t data[16]; int pclkHz; int hsyncPulseWidth; int hsyncBackPorch; int hsyncFrontPorch; int vsyncPulseWidth; int vsyncBackPorch; int vsyncFrontPorch; bool pclkActiveNeg; };` : ''}${touch ? '\nstruct Ft3168TouchConfig { gpio_num_t reset; gpio_num_t interrupt; };' : ''}${expander ? '\n// Expander pin numbers (0-based, the chip\'s own), -1 where a line is not routed through it.\nstruct IoExpanderConfig { int initialOutputs; int backlight; int touchReset; int displayReset; };' : ''}${audio ? '\nstruct Es8311AudioConfig { int i2sPort; gpio_num_t mclk; gpio_num_t bclk; gpio_num_t ws; gpio_num_t dout; gpio_num_t din; gpio_num_t powerAmplifier; };' : ''}
382
468
 
383
469
  inline constexpr I2cBusConfig i2c{ .sda = ${gpio(i2c.sda)}, .scl = ${gpio(i2c.scl)} };
384
470
  inline constexpr SdMmcConfig storage{ .clk = ${gpio(sdPins.clk)}, .cmd = ${gpio(sdPins.cmd)}, .data0 = ${gpio(sdPins.data0)} };
385
471
  inline constexpr LauncherButtonConfig launcherButton{ .pin = ${gpio(launcher.pin)}, .activeLevel = ${launcher.activeLevel} };
386
- ${display ? `inline constexpr Co5300DisplayConfig display{
472
+ ${rgb ? `inline constexpr RgbPanelDisplayConfig display{
473
+ .de = ${gpio(rgb.pins.de)}, .hsync = ${gpio(rgb.pins.hsync)}, .vsync = ${gpio(rgb.pins.vsync)}, .pclk = ${gpio(rgb.pins.pclk)},
474
+ .disp = ${gpio(rgb.pins.disp)}, .backlight = ${gpio(rgb.pins.backlight)},
475
+ .data = { ${rgb.pins.data.map(gpio).join(', ')} },
476
+ .pclkHz = ${rgb.pclkHz},
477
+ .hsyncPulseWidth = ${rgb.hsyncPulseWidth}, .hsyncBackPorch = ${rgb.hsyncBackPorch}, .hsyncFrontPorch = ${rgb.hsyncFrontPorch},
478
+ .vsyncPulseWidth = ${rgb.vsyncPulseWidth}, .vsyncBackPorch = ${rgb.vsyncBackPorch}, .vsyncFrontPorch = ${rgb.vsyncFrontPorch},
479
+ .pclkActiveNeg = ${rgb.pclkActiveNeg ? 'true' : 'false'}
480
+ };` : ''}${qspi ? `inline constexpr Co5300DisplayConfig display{
387
481
  .spiHost = ${display.spiHost === 'spi3' ? 'SPI3_HOST' : 'SPI2_HOST'}, .cs = ${gpio(displayPins.cs)}, .pclk = ${gpio(displayPins.pclk)},
388
482
  .data0 = ${gpio(displayPins.data0)}, .data1 = ${gpio(displayPins.data1)},
389
483
  .data2 = ${gpio(displayPins.data2)}, .data3 = ${gpio(displayPins.data3)},
390
484
  .reset = ${gpio(displayPins.reset)}, .te = ${gpio(displayPins.te)}
391
485
  };` : ''}${touch ? `
392
- inline constexpr Ft3168TouchConfig touch{ .reset = ${gpio(touchPins.reset)}, .interrupt = ${gpio(touchPins.interrupt)} };` : ''}${audio ? `
486
+ inline constexpr Ft3168TouchConfig touch{ .reset = ${gpio(touchPins.reset)}, .interrupt = ${gpio(touchPins.interrupt)} };` : ''}${expander ? `
487
+ inline constexpr IoExpanderConfig expander{ .initialOutputs = ${expander.initialOutputs}, .backlight = ${expander.outputs.backlight}, .touchReset = ${expander.outputs.touchReset}, .displayReset = ${expander.outputs.displayReset} };` : ''}${audio ? `
393
488
  inline constexpr Es8311AudioConfig audio{
394
489
  .i2sPort = I2S_NUM_AUTO, .mclk = ${gpio(audioPins.mclk)}, .bclk = ${gpio(audioPins.bclk)},
395
490
  .ws = ${gpio(audioPins.ws)}, .dout = ${gpio(audioPins.dout)}, .din = ${gpio(audioPins.din)},
@@ -405,7 +500,7 @@ function cmakeQuote(value) {
405
500
  }
406
501
 
407
502
  export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
408
- const { display, touch, power, imu, audio } = target.chips
503
+ const { display, touch, power, imu, audio, expander } = target.chips
409
504
  const chipSource = (source) => ` "\${GEA_CHIPS}/${source}"`
410
505
  const bindingSource = (source) => ` "\${GEA_EMBEDDED_ROOT}/targets/esp32/${source}"`
411
506
  const sourcesFor = (chip) => (chip ? [...chip.nativeSources.map(chipSource), ...chip.bindingSources.map(bindingSource)] : [])
@@ -423,8 +518,10 @@ export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
423
518
  ...(power ? sourcesFor(power) : absentBinding('power_absent.cpp')),
424
519
  ...(imu ? sourcesFor(imu) : absentBinding('imu_absent.cpp')),
425
520
  ...(touch ? sourcesFor(touch) : absentBinding('touch_absent.cpp')),
426
- ...sourcesFor(audio)
521
+ ...sourcesFor(audio),
522
+ ...sourcesFor(expander)
427
523
  ]
524
+ const requires = [...new Set([display, touch, power, imu, audio, expander].flatMap((chip) => (chip ? chip.requires : [])))]
428
525
  const surface = display || target.canvas
429
526
  const hasSurface = Boolean(surface)
430
527
  // An app that declares a display size has said something more specific than
@@ -445,12 +542,19 @@ export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
445
542
  // module that has no such chip. board.h says the same thing, but only board
446
543
  // sources include it; this reaches the app's own sources, which is where
447
544
  // the board-specific configuration actually lives.
448
- boardDefine('GEA_BOARD_HAS_POWER', power ? 1 : 0)
545
+ boardDefine('GEA_BOARD_HAS_POWER', power ? 1 : 0),
546
+ // The QSPI panels take byte-swapped RGB565 over the wire and the base
547
+ // stores it that way; an RGB panel's DMA reads the framebuffer as-is, so
548
+ // it stores native order -- exactly what the Elecrow rotary target does.
549
+ display && display.interface === 'rgb' ? boardDefine('GEA_EMBEDDED_PIXEL_PANEL_ENDIAN', 0) : ''
449
550
  ].join('')
450
551
  return `set(GEA_CUSTOM_TARGET_ACTIVE 1)
451
552
  set(GEA_CUSTOM_TARGET_INCLUDE_DIR ${cmakeQuote(includeDir)})
452
553
  set(GEA_CUSTOM_TARGET_HAS_DISPLAY ${display ? 1 : 0})
453
554
  set(GEA_CUSTOM_TARGET_HAS_TOUCH ${touch ? 1 : 0})
555
+ set(GEA_CUSTOM_TARGET_DISPLAY_INTERFACE "${display ? display.interface : ''}")
556
+ set(GEA_CUSTOM_TARGET_TOUCH_DRIVER "${touch ? touch.driver : ''}")
557
+ set(GEA_CUSTOM_TARGET_HAS_EXPANDER ${expander ? 1 : 0})
454
558
  set(GEA_CUSTOM_TARGET_HAS_MICROSD ${target.storage.microSD ? 1 : 0})
455
559
  set(GEA_CUSTOM_TARGET_DISPLAY_SOURCES
456
560
  ${displaySources.join('\n')}
@@ -458,6 +562,7 @@ ${displaySources.join('\n')}
458
562
  set(GEA_CUSTOM_TARGET_PERIPHERAL_SOURCES
459
563
  ${peripheralSources.join('\n')}
460
564
  )
565
+ set(GEA_CUSTOM_TARGET_REQUIRES${requires.map((name) => ` ${name}`).join('')})
461
566
  set(GEA_CUSTOM_TARGET_COMPILE_DEFINITIONS${displayDefines}
462
567
  )
463
568
  `
package/src/chips.mjs CHANGED
@@ -252,15 +252,23 @@ function parseSetOptions(parsed) {
252
252
  return out
253
253
  }
254
254
 
255
+ const trueWords = ['true', 'yes', '1', 'on']
256
+ const falseWords = ['false', 'no', '0', 'off']
257
+
255
258
  function parseFieldValue(value, field) {
256
259
  if (field.optional && (value === '' || value === 'none' || value === 'null')) return null
257
260
  if (field.type === 'integer' || field.type === 'pin') return Number.parseInt(value, 10)
261
+ if (field.type === 'boolean') return typeof value === 'boolean' ? value : trueWords.includes(String(value).toLowerCase())
258
262
  return String(value)
259
263
  }
260
264
 
261
265
  function validateFieldValue(value, field) {
262
266
  if (field.optional && value === '') return ''
263
267
  if (field.type === 'choice') return field.values.includes(value) ? '' : `choose one of ${field.values.join(', ')}`
268
+ if (field.type === 'boolean') {
269
+ if (typeof value === 'boolean') return ''
270
+ return [...trueWords, ...falseWords].includes(String(value).toLowerCase()) ? '' : 'enter true or false'
271
+ }
264
272
  if (field.type !== 'integer' && field.type !== 'pin') return ''
265
273
  if (!/^-?\d+$/.test(String(value))) return 'enter an integer'
266
274
  const number = Number(value)
@@ -348,7 +348,8 @@ function packageJson({ appId, displayName, targets, entry, coreDependency, cliDe
348
348
  '@geastack/core': coreDependency,
349
349
  '@geastack/cli': cliDependency,
350
350
  ...(needsTargetsPackage(targets) ? { '@geastack/targets': sourcePackage.dependencies?.['@geastack/targets'] || targetsDependencyDefault } : {}),
351
- ...(targets.windows ? { '@geastack/windows': sourcePackage.dependencies?.['@geastack/windows'] || windowsDependencyDefault } : {})
351
+ ...(targets.windows ? { '@geastack/windows': sourcePackage.dependencies?.['@geastack/windows'] || windowsDependencyDefault } : {}),
352
+ ...(targets.macos || targets.ios ? { '@geastack/apple': sourcePackage.dependencies?.['@geastack/apple'] || appleDependencyDefault } : {})
352
353
  },
353
354
  devDependencies: {
354
355
  ...(sourcePackage.devDependencies || {}),
@@ -370,6 +371,11 @@ function needsTargetsPackage(targets) {
370
371
  // own dependencies by `gea build --target windows`.
371
372
  const windowsDependencyDefault = '^0.1.0'
372
373
 
374
+ // The macOS and iOS targets ship inside @geastack/apple, resolved the same way
375
+ // by `gea build --target macos` and `gea build --target ios`. An app that
376
+ // declares either target without the package has nothing to build with.
377
+ const appleDependencyDefault = starterDependencies['@geastack/apple'] || '^0.2.9'
378
+
373
379
  function indexTsx(displayName) {
374
380
  return `import { ReactiveComponent, mount } from '@geastack/core'
375
381
  import './styles.css'
@@ -509,7 +515,11 @@ npx gea flash --monitor`
509
515
  ? `npx gea setup
510
516
  npx gea build --target windows
511
517
  npx gea run --target windows`
512
- : `npx gea setup
518
+ : targets.ios && !targets.macos
519
+ ? `npx gea setup
520
+ npx gea build --target ios
521
+ npx gea run --target ios`
522
+ : `npx gea setup
513
523
  npx gea build`
514
524
  return `# ${displayName}
515
525
 
@@ -347,6 +347,10 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
347
347
  idfArgs.push(`-DGEA_BOARD_DEFINITION=${cmakeValue(selection.targetDefinition)}`, `-DGEA_CUSTOM_TARGET_DIR=${cmakeValue(outDir)}`)
348
348
  childEnv.GEA_BOARD_DEFINITION = selection.targetDefinition
349
349
  childEnv.GEA_CUSTOM_TARGET_DIR = outDir
350
+ // IDF's requirement-extraction pass (cmake -P) runs before the -D cache
351
+ // arguments exist, so the base target reads both from the environment
352
+ // there; otherwise a composed chip's extra REQUIRES never reach the build.
353
+ childEnv.GEA_BOARD_DEFINITION = selection.targetDefinition
350
354
  boardPartitionCsv = generated.partitionCsv
351
355
  boardConsole = generated.target.console
352
356
  boardPsram = generated.target.psram
package/src/gea.mjs CHANGED
@@ -95,11 +95,24 @@ export async function runGea(argv, io = {}) {
95
95
  // this host is not (a Windows-only app on a Mac, a Mac-only app on Linux)
96
96
  // has nothing to select: falling into board selection would report a
97
97
  // missing --board for an app that declares no board at all.
98
- if (command === 'build' && !target && app && !declaresBoardTarget(app) && (app.targets?.macos || app.targets?.windows)) {
99
- const desktop = ['macos', 'windows'].filter((platform) => app.targets?.[platform])
98
+ if (command === 'build' && !target && app && !declaresBoardTarget(app) && (app.targets?.macos || app.targets?.windows || app.targets?.ios)) {
99
+ const desktop = ['macos', 'windows', 'ios'].filter((platform) => app.targets?.[platform])
100
100
  fail(`'${app.id}' declares no target that builds on this host by default. Pass --target ${desktop.join(' or --target ')}.`, ExitCode.usage)
101
101
  }
102
102
  }
103
+ // iOS is the third platform driven by one script inside @geastack/apple,
104
+ // resolved like macOS from the app's own dependencies. It never has a host
105
+ // default: a bare `gea build` cannot know simulator from device, so the iOS
106
+ // build is always the documented `gea build --target ios [--mode simulator|device]`,
107
+ // and `gea run --target ios` builds, installs and launches it.
108
+ if ((command === 'build' || command === 'run') && target === 'ios') {
109
+ const app = parsed.options.app || rest[0] ? findAppById(ctx, String(parsed.options.app || rest[0])) : findCurrentApp(cwd)
110
+ if (!app?.targets?.ios) {
111
+ fail(app ? `'${app.id}' does not declare gea.targets.ios.` : 'No app selected. Pass --app <id> or run inside a Gea app folder.', ExitCode.usage)
112
+ }
113
+ const { runIos } = await import('./ios/adapter.mjs')
114
+ return runIos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, mode: option(parsed, 'mode', ''), run: command === 'run' })
115
+ }
103
116
  // `web` names two targets, and both are driven by gea, so it leaves the
104
117
  // refusal below the way macos does above. `gea simulate` is the WASM device
105
118
  // simulator; `gea {dev,build} --target web` is a real DOM/CSS web app. A bare
@@ -217,6 +230,12 @@ ${heading('Run on this machine (no board needed):')}
217
230
  gea dev [app] [--port N] real DOM + CSS dev server with HMR (same as --target web)
218
231
  gea build --target web [app] [--out-dir d] build the app as a real web app
219
232
 
233
+ ${heading('Native desktop and mobile apps (scripts ship in @geastack/apple and @geastack/windows):')}
234
+ gea build --target macos [app] build a Mac .app (a bare gea build does this on a Mac for a Mac-only app)
235
+ gea build --target ios [app] [--mode simulator|device] generate the Xcode project and build the iOS .app
236
+ gea run --target ios [app] [--mode simulator|device] build, then install and launch on a simulator or iPhone
237
+ gea build|run --target windows [app] build (and launch) the Windows executable
238
+
220
239
  ${heading('Build and deploy (device commands take --board <alias>, see gea boards list; with one registered board it can be left out):')}
221
240
  gea build --board <alias> [--app <id>] build firmware (ESP-IDF / Pico SDK / geaos) [--verbose] [--output file.bin]
222
241
  gea flash --board <alias> [--app <id>] build + flash over USB [--monitor] [--manual-boot] [--no-reset] [--flash-baud N]
@@ -0,0 +1,30 @@
1
+ import { spawnSync } from 'node:child_process'
2
+
3
+ import { CliError, ExitCode, fail } from '../errors.mjs'
4
+ import { appleChildEnv, appleTargetScript } from '../macos/adapter.mjs'
5
+ import { formatCommand } from '../run.mjs'
6
+
7
+ // iOS mirrors macOS: a platform, not a board, driven by one script shipped
8
+ // inside @geastack/apple and resolved from the app's own dependencies. The
9
+ // script takes a destination -- `simulator` (the default) or `device` -- which
10
+ // `--mode` selects. `gea build --target ios` compiles the .app and stops;
11
+ // `gea run --target ios` also installs and launches it on the picked simulator
12
+ // or attached iPhone, which is the script's own default behaviour. The script
13
+ // reads GEA_IOS_SKIP_LAUNCH, so a caller who already set it keeps their choice.
14
+ export function runIos({ app, env, dryRun = false, stdout, mode = '', run = false }) {
15
+ const destination = mode || 'simulator'
16
+ if (destination !== 'simulator' && destination !== 'device') {
17
+ fail(`--mode ${mode} is not an iOS destination; expected simulator or device.`, ExitCode.usage)
18
+ }
19
+ const { script, require } = appleTargetScript(app, 'ios', 'build-ios.sh')
20
+ const childEnv = appleChildEnv(app, env, require)
21
+ if (!run && childEnv.GEA_IOS_SKIP_LAUNCH === undefined) childEnv.GEA_IOS_SKIP_LAUNCH = '1'
22
+ if (dryRun) {
23
+ stdout(formatCommand(['bash', script, app.id, destination]))
24
+ return 0
25
+ }
26
+ const result = spawnSync('bash', [script, app.id, destination], { cwd: app.root, env: childEnv, stdio: 'inherit' })
27
+ if (result.error) throw result.error
28
+ if (result.status !== 0) throw new CliError(`iOS build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
29
+ return 0
30
+ }
@@ -13,31 +13,48 @@ import { formatCommand } from '../run.mjs'
13
13
  // app's own module resolution is what finds it. An app declares `targets.macos`
14
14
  // and nothing else; the script reads the rest from the same manifest.
15
15
  export function runMacos({ app, env, dryRun = false, stdout }) {
16
+ const { script, require } = appleTargetScript(app, 'macos', 'build-macos.sh')
17
+ const childEnv = appleChildEnv(app, env, require)
18
+ if (dryRun) {
19
+ stdout(formatCommand(['bash', script, app.id]))
20
+ return 0
21
+ }
22
+ const result = spawnSync('bash', [script, app.id], { cwd: app.root, env: childEnv, stdio: 'inherit' })
23
+ if (result.error) throw result.error
24
+ if (result.status !== 0) throw new CliError(`macOS build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
25
+ return 0
26
+ }
27
+
28
+ // Both Apple targets ship as one script each inside @geastack/apple, and both
29
+ // resolve it the same way: through the app's own dependencies. iOS reuses this
30
+ // from src/ios/adapter.mjs rather than restating the resolution.
31
+ export function appleTargetScript(app, platform, scriptName) {
16
32
  const require = createRequire(path.join(app.root, 'package.json'))
17
33
  let appleRoot = ''
18
34
  try {
19
35
  appleRoot = path.dirname(require.resolve('@geastack/apple/package.json'))
20
36
  } catch {
21
- fail(`'${app.id}' targets macOS but @geastack/apple is not installed in ${app.root} — run npm install there.`, ExitCode.missingDependency)
37
+ fail(`'${app.id}' targets ${platformLabel(platform)} but @geastack/apple is not installed in ${app.root} — run npm install there.`, ExitCode.missingDependency)
22
38
  }
23
- const script = path.join(appleRoot, 'targets', 'macos', 'build-macos.sh')
24
- if (!existsSync(script)) fail(`macOS build script not found: ${script}`, ExitCode.missingDependency)
25
- // The script resolves the app through this CLI again. It is spawned with the
26
- // app's own folder as its cwd and that is the whole handoff: `createContext`
27
- // resolves a project from cwd, and a root's own package.json is one of the
28
- // places discovery looks, so an app outside the examples workspace resolves
29
- // like any other. Nothing announces the path a second time.
39
+ const script = path.join(appleRoot, 'targets', platform, scriptName)
40
+ if (!existsSync(script)) fail(`${platformLabel(platform)} build script not found: ${script}`, ExitCode.missingDependency)
41
+ return { script, require }
42
+ }
43
+
44
+ // The script resolves the app through this CLI again. It is spawned with the
45
+ // app's own folder as its cwd and that is the whole handoff: `createContext`
46
+ // resolves a project from cwd, and a root's own package.json is one of the
47
+ // places discovery looks, so an app outside the examples workspace resolves
48
+ // like any other. Nothing announces the path a second time.
49
+ export function appleChildEnv(app, env, require) {
30
50
  const childEnv = { ...env }
31
51
  const plugins = geatscPluginsOf(app, require)
32
52
  if (plugins.length > 0) childEnv.GEA_EXTRA_GEATSC_PLUGINS = plugins.join(path.delimiter)
33
- if (dryRun) {
34
- stdout(formatCommand(['bash', script, app.id]))
35
- return 0
36
- }
37
- const result = spawnSync('bash', [script, app.id], { cwd: app.root, env: childEnv, stdio: 'inherit' })
38
- if (result.error) throw result.error
39
- if (result.status !== 0) throw new CliError(`macOS build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
40
- return 0
53
+ return childEnv
54
+ }
55
+
56
+ function platformLabel(platform) {
57
+ return platform === 'ios' ? 'iOS' : 'macOS'
41
58
  }
42
59
 
43
60
  // Compiler plugins come from the packages the app depends on.
@@ -194,12 +194,15 @@ async function setupCustomBoard(ctx, parsed, io, prompt) {
194
194
  }
195
195
 
196
196
  const catalog = loadChipCatalog(ctx)
197
+ // The third field marks a role the review never reports as missing: an I/O
198
+ // expander is wiring a board may or may not have, not a capability it lacks.
197
199
  const roles = [
198
200
  ['display', 'Display controller'],
199
201
  ['touch', 'Touch controller'],
200
202
  ['power', 'Power-management controller'],
201
203
  ['imu', 'Inertial measurement unit'],
202
- ['audio', 'Audio codec']
204
+ ['audio', 'Audio codec'],
205
+ ['expander', 'I/O expander (backlight, reset lines)', true]
203
206
  ]
204
207
  renderStep(io, 'Chips', ['Choose each controller from @geastack/chips. Pin questions come from the installed catalog.'])
205
208
  for (const [role, label] of roles) {
@@ -260,7 +263,7 @@ async function setupCustomBoard(ctx, parsed, io, prompt) {
260
263
  usbSerial: compactObject(usbIdentity)
261
264
  })
262
265
  })
263
- const requiredRoles = roles.map(([role]) => role)
266
+ const requiredRoles = roles.filter(([, , optional]) => !optional).map(([role]) => role)
264
267
  const missingRoles = requiredRoles.filter((role) => !definition.chips[role])
265
268
  validateGpioAssignments(definition)
266
269
  renderCustomBoardReview(io, { alias, definition, definitionPath, configPath, entry, missingRoles })
@@ -316,6 +319,7 @@ function renderCustomBoardReview(io, { alias, definition, definitionPath, config
316
319
  ['Power', describeObject(definition.chips.power)],
317
320
  ['IMU', describeObject(definition.chips.imu)],
318
321
  ['Audio', describeObject(definition.chips.audio)],
322
+ ['Expander', describeObject(definition.chips.expander)],
319
323
  ['I2C', describeObject(definition.buses.i2c)],
320
324
  ['USB identity', usbIdentityLabel(entry, 'auto / pass --port')],
321
325
  ['Missing roles', missingRoles.join(', ') || 'none'],
@@ -152,7 +152,7 @@ export function buildSimulatorApp({ app, env, dryRun = false, stdout }) {
152
152
 
153
153
  export async function runSimulate({ ctx, app, env, dryRun = false, stdout, port, open = true, view = {} }) {
154
154
  const { simulatorDir, paths } = buildSimulatorApp({ app, env, dryRun, stdout })
155
- const url = await startSimulatorServer({ ctx, app, env, simulatorDir, paths, port, dryRun, stdout })
155
+ const url = await startSimulatorServer({ ctx, app, env, simulatorDir, paths, port, dryRun, stdout, view })
156
156
  if (dryRun) return 0
157
157
  stdout(`Simulating ${app.id}: ${url}`)
158
158
  if (open) openBrowser(url, env)
@@ -166,7 +166,7 @@ export async function runSimulate({ ctx, app, env, dryRun = false, stdout, port,
166
166
  // the relocated dist root be passed as inline config that vite merges over the
167
167
  // package's own vite.config.ts, instead of being smuggled through env vars the
168
168
  // config would have to read back.
169
- async function startSimulatorServer({ ctx, app, env, simulatorDir, paths, port, dryRun, stdout }) {
169
+ async function startSimulatorServer({ ctx, app, env, simulatorDir, paths, port, dryRun, stdout, view = {} }) {
170
170
  const appRoot = path.join(simulatorDir, 'simulator')
171
171
  const configFile = path.join(appRoot, 'vite.config.ts')
172
172
  if (dryRun) {
@@ -182,7 +182,11 @@ async function startSimulatorServer({ ctx, app, env, simulatorDir, paths, port,
182
182
  // Vite's default cacheDir is <root>/node_modules/.vite -- inside the
183
183
  // installed package, which may be read-only and is not this app's to dirty.
184
184
  cacheDir: paths.viteCache,
185
- define: { __GEA_APP_INDEX__: JSON.stringify(appIndexFor(ctx, app)) },
185
+ publicDir: path.dirname(paths.public),
186
+ define: {
187
+ __GEA_APP_INDEX__: JSON.stringify(appIndexFor(ctx, app)),
188
+ __GEA_WEB_DIST_FS_ROOT__: JSON.stringify(paths.dist)
189
+ },
186
190
  server: {
187
191
  port,
188
192
  fs: { allow: [appRoot, paths.dist, paths.public] }