@geastack/cli 0.1.109 → 0.1.110

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
@@ -338,10 +338,10 @@ at call time, so never record a port path.
338
338
  A composed target is a JSON definition that extends the `esp32-s3` base and
339
339
  picks its chips from the `@geastack/chips` catalog (`gea chips list`). Every
340
340
  role is optional, so the definition describes the hardware that is there:
341
- `display`, `touch`, `power`, `imu`, `audio` and `expander`. Some boards are
341
+ `display`, `touch`, `power`, `imu`, `audio`, `rtc` and `expander`. Some boards are
342
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`.
343
+ for example `esp32-s3-devkit-n16r8` (a bare module),
344
+ `esp32-s3-waveshare-touch-lcd-7` and `esp32-s3-elecrow-crowpanel-advance-7.0`.
345
345
 
346
346
  Two kinds of display are understood. A QSPI controller (`co5300`) takes the
347
347
  `spiHost` and `cs`/`pclk`/`data0-3`/`reset`/`te` pins. A bare parallel RGB
@@ -388,7 +388,27 @@ I2C I/O expander instead of GPIOs. `outputs` names the expander pin that
388
388
  carries each line; a display with no `pins.backlight` lights up through
389
389
  `outputs.backlight`, and a touch controller with no `pins.reset` is reset
390
390
  through `outputs.touchReset`. `initialOutputs` is the level mask latched at
391
- boot.
391
+ boot. `ch422g`, `tca9554` and `pca9557` (TCA9554's register protocol at
392
+ 0x18-0x1f) are understood.
393
+
394
+ The `rtc` role (`bm8563`) is a battery-backed real-time clock on the I2C bus.
395
+ The system clock is restored from it at boot unless it reports a power loss,
396
+ and every wall-clock change made through the clock surface (the companion's
397
+ SETTIME, an app setting the time) is written back to it.
398
+
399
+ `audio` is either a codec (`es8311`, configured over I2C, with `mclk`/`bclk`/
400
+ `ws`/`dout`/`din`) or a bare I2S amplifier (`ns4168`) that takes `bclk`/`ws`/
401
+ `dout`, an optional separate I2S MEMS microphone on `micBclk`/`micWs`/`micDin`,
402
+ and optional `expander.shutdown` / `expander.mute` lines (high = off). The
403
+ amplifier's binding is compiled only into apps that use audio.
404
+
405
+ `storage.microSD` is `sdmmc-1bit` (`clk`/`cmd`/`data0`) or `spi` (`sck`/`mosi`/
406
+ `miso`, and `cs` unless the slot ties chip select active).
407
+
408
+ When a board multiplexes two peripherals onto the same GPIOs through a
409
+ hardware switch the firmware does not drive, `pinSharing` lists the roles that
410
+ may coincide, e.g. `[["audio", "microSD"]]`; every other pin must still belong
411
+ to one role. The CrowPanel Advance 7.0 definition uses all of these.
392
412
 
393
413
  ## Common Verification Flow
394
414
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geastack/cli",
3
- "version": "0.1.109",
3
+ "version": "0.1.110",
4
4
  "description": "Command-line front door for GeaStack apps, targets, and local toolchains.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -15,6 +15,11 @@ function object(value, label) {
15
15
  return value
16
16
  }
17
17
 
18
+ function array(value, label) {
19
+ if (!Array.isArray(value)) throw new Error(`${label} must be an array.`)
20
+ return value
21
+ }
22
+
18
23
  function text(value, label) {
19
24
  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} must be a non-empty string.`)
20
25
  return value.trim()
@@ -133,6 +138,8 @@ export function normalizeCustomTarget(raw, catalog) {
133
138
  const power = optionalChip(chips, 'power', 'power', adapter, mcu, catalog)
134
139
  const imu = optionalChip(chips, 'imu', 'imu', adapter, mcu, catalog)
135
140
  const audio = optionalChip(chips, 'audio', 'audio', adapter, mcu, catalog)
141
+ // A battery-backed real-time clock: the system clock's source at boot.
142
+ const rtc = optionalChip(chips, 'rtc', 'rtc', adapter, mcu, catalog)
136
143
  // An I/O expander is not a peripheral of its own: it is where a board puts
137
144
  // the slow control lines (backlight enable, touch reset, panel reset) it ran
138
145
  // out of GPIOs for. The chips that need those lines look them up here.
@@ -149,9 +156,13 @@ export function normalizeCustomTarget(raw, catalog) {
149
156
  [touch, 'chips.touch'],
150
157
  [power, 'chips.power'],
151
158
  [imu, 'chips.imu'],
159
+ [rtc, 'chips.rtc'],
152
160
  [expander, 'chips.expander']
153
161
  ].filter(([chip]) => chip && chip.interface === 'i2c')
154
- if (audio) i2cChips.push([audio, 'chips.audio (codec control)'])
162
+ // A codec is configured over I2C; a bare I2S amplifier (NS4168) has no
163
+ // control bus at all, only the I2S lines and an enable.
164
+ const audioHasCodec = audio !== null && audio.driver === 'es8311'
165
+ if (audioHasCodec) i2cChips.push([audio, 'chips.audio (codec control)'])
155
166
  if (absent(buses.i2c) && i2cChips.length > 0) {
156
167
  throw new Error(`buses.i2c is required because ${i2cChips.map(([, label]) => label).join(', ')} ${i2cChips.length > 1 ? 'are' : 'is'} on the I2C bus.`)
157
168
  }
@@ -172,8 +183,14 @@ export function normalizeCustomTarget(raw, catalog) {
172
183
  const spiHost = display && displayInterface === 'qspi' ? String(display.spiHost ?? 'spi2').toLowerCase() : 'spi2'
173
184
  if (display && displayInterface === 'qspi' && !['spi2', 'spi3'].includes(spiHost)) throw new Error("chips.display.spiHost must be 'spi2' or 'spi3'.")
174
185
  const expanderOutputs = expander ? (absent(expander.outputs) ? {} : object(expander.outputs, 'chips.expander.outputs')) : null
175
- const expanderMaxPin = expander?.driver === 'tca9554' ? 7 : expander?.driver === 'ch422g' ? 11 : 15
186
+ const expanderMaxPin = ['tca9554', 'pca9557', 'elecrow_board_control'].includes(expander?.driver) ? 7 : expander?.driver === 'ch422g' ? 11 : 15
176
187
  const expanderPin = (value, label) => (absent(value) ? -1 : integer(value, label, { min: 0, max: expanderMaxPin }))
188
+ const audioExpanderLines = audio && !audioHasCodec && !absent(audio.expander) ? object(audio.expander, 'chips.audio.expander') : {}
189
+ if (Object.keys(audioExpanderLines).length > 0 && !expander) throw new Error('chips.audio.expander names expander lines, but the board has no chips.expander.')
190
+ const audioExpander = {
191
+ shutdown: expanderPin(audioExpanderLines.shutdown, 'chips.audio.expander.shutdown'),
192
+ mute: expanderPin(audioExpanderLines.mute, 'chips.audio.expander.mute')
193
+ }
177
194
 
178
195
  // Flash size and the partition table are board geometry, not app policy: a
179
196
  // module with 16MB of flash cannot borrow its base's 32MB layout, and every
@@ -181,6 +198,16 @@ export function normalizeCustomTarget(raw, catalog) {
181
198
  // stay optional — a board whose flash matches its base needs neither.
182
199
  const flashSize = absent(definition.flashSize) ? '' : text(definition.flashSize, 'flashSize')
183
200
  if (flashSize && !/^\d+MB$/i.test(flashSize)) throw new Error(`flashSize must look like '16MB', not '${flashSize}'.`)
201
+ // How the flash chip is wired: a module with all four data lines routed
202
+ // (most WROOM parts) runs QIO, which fetches code twice as fast as DIO.
203
+ const flashModes = ['qio', 'qout', 'dio', 'dout']
204
+ const flashMode = absent(definition.flashMode) ? '' : text(definition.flashMode, 'flashMode').toLowerCase()
205
+ if (flashMode && !flashModes.includes(flashMode)) throw new Error(`flashMode must be one of ${flashModes.join(', ')}, not '${flashMode}'.`)
206
+ // The flash clock in MHz. Optional: a board leaves it to its base unless
207
+ // its PSRAM clock needs a flash clock that divides the shared MSPI core.
208
+ const flashFreqs = [20, 26, 40, 80, 120]
209
+ const flashFreq = absent(definition.flashFreq) ? 0 : Number(definition.flashFreq)
210
+ if (flashFreq && !flashFreqs.includes(flashFreq)) throw new Error(`flashFreq must be one of ${flashFreqs.join(', ')}, not '${definition.flashFreq}'.`)
184
211
  const partitions = absent(definition.partitions) ? null : object(definition.partitions, 'partitions')
185
212
 
186
213
  // Which physical port the log comes out of is the module's wiring, not the
@@ -206,6 +233,11 @@ export function normalizeCustomTarget(raw, catalog) {
206
233
  throw new Error(`psram.mode must be one of ${psramModes.join(', ')}, not '${psramMode}'.`)
207
234
  }
208
235
  const psramSpeed = psram && !absent(psram.speed) ? integer(psram.speed, 'psram.speed', { min: 40, max: 120 }) : 0
236
+ // Run code and read-only data from PSRAM instead of flash. Flash and PSRAM
237
+ // share one bus on the S3, so an instruction-cache miss holds PSRAM off; a
238
+ // parallel RGB panel's scanout (which reads PSRAM in real time) then drifts.
239
+ if (psram && !absent(psram.xip) && typeof psram.xip !== 'boolean') throw new Error('psram.xip must be true or false.')
240
+ const psramXip = Boolean(psram?.xip)
209
241
  if (psramSpeed && ![40, 80, 120].includes(psramSpeed)) {
210
242
  throw new Error(`psram.speed must be 40, 80 or 120 MHz, not ${psramSpeed}.`)
211
243
  }
@@ -265,9 +297,23 @@ export function normalizeCustomTarget(raw, catalog) {
265
297
  adapter,
266
298
  mcu,
267
299
  flashSize: flashSize.toUpperCase(),
300
+ flashMode,
301
+ flashFreq,
268
302
  partitions,
303
+ // Peripherals a board multiplexes onto the same GPIOs with a hardware
304
+ // switch (a DIP switch or analog mux the firmware does not drive): only
305
+ // one of each listed group is connected at a time, so their pins may
306
+ // coincide. Anything not listed still has to own its pins outright.
307
+ pinSharing: absent(definition.pinSharing) ? [] : array(definition.pinSharing, 'pinSharing').map((group, index) => {
308
+ const roles = array(group, `pinSharing[${index}]`).map((role) => text(role, `pinSharing[${index}]`))
309
+ for (const role of roles) {
310
+ if (!pinRoles.includes(role)) throw new Error(`pinSharing[${index}] names '${role}'; the shareable roles are ${pinRoles.join(', ')}.`)
311
+ }
312
+ if (roles.length < 2) throw new Error(`pinSharing[${index}] needs at least two roles.`)
313
+ return roles
314
+ }),
269
315
  console: consoleTransport ? { transport: consoleTransport, baud: consoleBaud, uart: consoleUart } : null,
270
- psram: psramMode ? { mode: psramMode, speed: psramSpeed } : null,
316
+ psram: psramMode ? { mode: psramMode, speed: psramSpeed, xip: psramXip } : null,
271
317
  buses: {
272
318
  i2c: i2c === null ? null : {
273
319
  sda: pin(i2c.sda, 'buses.i2c.sda'),
@@ -290,7 +336,11 @@ export function normalizeCustomTarget(raw, catalog) {
290
336
  vsyncBackPorch: integer(display.vsyncBackPorch ?? 8, 'chips.display.vsyncBackPorch', { min: 0, max: 1024 }),
291
337
  vsyncFrontPorch: integer(display.vsyncFrontPorch ?? 8, 'chips.display.vsyncFrontPorch', { min: 0, max: 1024 }),
292
338
  pclkActiveNeg: boolean(display.pclkActiveNeg, 'chips.display.pclkActiveNeg', true),
339
+ scanFramebuffers: integer(display.scanFramebuffers ?? 3, 'chips.display.scanFramebuffers', { min: 1, max: 3 }),
293
340
  backlightActiveLow: boolean(display.backlightActiveLow, 'chips.display.backlightActiveLow', false),
341
+ bounceRows: integer(display.bounceRows ?? 0, 'chips.display.bounceRows', { min: 0, max: 120 }),
342
+ // Restart the DMA at every VSYNC (CONFIG_LCD_RGB_RESTART_IN_VSYNC; see build.mjs).
343
+ restartInVsync: boolean(display.restartInVsync, 'chips.display.restartInVsync', true),
294
344
  controller: controllerConfig,
295
345
  nativeSources: display.nativeSources,
296
346
  bindingSources: display.bindingSources,
@@ -369,8 +419,16 @@ export function normalizeCustomTarget(raw, catalog) {
369
419
  bindingSources: imu.bindingSources,
370
420
  requires: imu.requires
371
421
  },
372
- audio: audio === null ? null : {
422
+ rtc: rtc === null ? null : {
423
+ driver: rtc.driver,
424
+ interface: exact(rtc.interface, 'i2c', 'chips.rtc.interface'),
425
+ nativeSources: rtc.nativeSources,
426
+ bindingSources: rtc.bindingSources,
427
+ requires: rtc.requires
428
+ },
429
+ audio: audio === null ? null : audioHasCodec ? {
373
430
  driver: audio.driver,
431
+ kind: 'codec',
374
432
  interface: exact(audio.interface, 'i2s', 'chips.audio.interface'),
375
433
  es7210Address: integer(audio.es7210Address ?? 0, 'chips.audio.es7210Address', { min: 0, max: 119 }),
376
434
  nativeSources: audio.nativeSources,
@@ -384,10 +442,57 @@ export function normalizeCustomTarget(raw, catalog) {
384
442
  din: pin(audioPins.din, 'chips.audio.pins.din'),
385
443
  powerAmplifier: pin(audioPins.powerAmplifier, 'chips.audio.pins.powerAmplifier', { optional: true })
386
444
  }
445
+ } : {
446
+ // An I2S amplifier: the S3 is the I2S master and sends PCM straight to
447
+ // it. A separate I2S MEMS microphone, when the board has one, runs on
448
+ // its own pins and controller. The amplifier's shutdown and mute lines
449
+ // may sit on the I/O expander.
450
+ driver: audio.driver,
451
+ kind: 'i2s-amplifier',
452
+ interface: exact(audio.interface, 'i2s', 'chips.audio.interface'),
453
+ nativeSources: audio.nativeSources,
454
+ bindingSources: audio.bindingSources,
455
+ requires: audio.requires,
456
+ pins: {
457
+ mclk: -1,
458
+ bclk: pin(audioPins.bclk, 'chips.audio.pins.bclk'),
459
+ ws: pin(audioPins.ws, 'chips.audio.pins.ws'),
460
+ dout: pin(audioPins.dout, 'chips.audio.pins.dout'),
461
+ din: -1,
462
+ powerAmplifier: -1,
463
+ micBclk: pin(audioPins.micBclk, 'chips.audio.pins.micBclk', { optional: true }),
464
+ micWs: pin(audioPins.micWs, 'chips.audio.pins.micWs', { optional: true }),
465
+ micDin: pin(audioPins.micDin, 'chips.audio.pins.micDin', { optional: true })
466
+ },
467
+ // 'i2s' (a standard-I2S MEMS mic on micBclk/micWs/micDin), 'pdm' (clock
468
+ // on micBclk, data on micDin), or 'auto': chosen at boot from the board
469
+ // controller the expander binding found, for boards whose revisions
470
+ // differ only in that part.
471
+ microphone: (() => {
472
+ const value = absent(audio.microphone) ? 'i2s' : text(audio.microphone, 'chips.audio.microphone').toLowerCase()
473
+ if (!['i2s', 'pdm', 'auto'].includes(value)) throw new Error(`chips.audio.microphone must be i2s, pdm or auto, not '${value}'.`)
474
+ if (value === 'auto' && !expander) throw new Error("chips.audio.microphone 'auto' needs a chips.expander to ask.")
475
+ return value
476
+ })(),
477
+ expander: audioExpander
387
478
  }
388
479
  },
389
480
  storage: {
390
- microSD: microSD === null ? null : {
481
+ // SD_MMC 1-bit, or SPI for a slot wired as one: SPI's chip select may be
482
+ // hard-wired (-1), which SD_MMC cannot use, since DAT3 low at CMD0 drops
483
+ // the card into SPI mode.
484
+ microSD: microSD === null ? null : text(microSD.interface, 'storage.microSD.interface').toLowerCase() === 'spi' ? {
485
+ interface: 'spi',
486
+ pins: {
487
+ clk: -1,
488
+ cmd: -1,
489
+ data0: -1,
490
+ sck: pin(storagePins.sck, 'storage.microSD.pins.sck'),
491
+ mosi: pin(storagePins.mosi, 'storage.microSD.pins.mosi'),
492
+ miso: pin(storagePins.miso, 'storage.microSD.pins.miso'),
493
+ cs: pin(storagePins.cs, 'storage.microSD.pins.cs', { optional: true })
494
+ }
495
+ } : {
391
496
  interface: exact(microSD.interface, 'sdmmc-1bit', 'storage.microSD.interface'),
392
497
  pins: {
393
498
  clk: pin(storagePins.clk, 'storage.microSD.pins.clk', { optional: true }),
@@ -407,6 +512,18 @@ export function normalizeCustomTarget(raw, catalog) {
407
512
  return target
408
513
  }
409
514
 
515
+ const pinRoles = ['i2c', 'display', 'touch', 'audio', 'microphone', 'microSD', 'launcherButton']
516
+
517
+ function pinRoleOf(label) {
518
+ if (label.startsWith('I2C ')) return 'i2c'
519
+ if (label.startsWith('display ')) return 'display'
520
+ if (label.startsWith('touch ')) return 'touch'
521
+ if (label.startsWith('audio ')) return 'audio'
522
+ if (label.startsWith('microphone ')) return 'microphone'
523
+ if (label.startsWith('microSD ')) return 'microSD'
524
+ return 'launcherButton'
525
+ }
526
+
410
527
  function validatePinAssignments(target) {
411
528
  const { display, touch, audio } = target.chips
412
529
  const { i2c } = target.buses
@@ -415,7 +532,7 @@ function validatePinAssignments(target) {
415
532
  // Only the peripherals this board actually has contribute pins; an absent
416
533
  // role owns no GPIO and so can never collide with one.
417
534
  const pins = [
418
- ...(i2c ? [['I2C SDA', i2c.sda], ['I2C SCL', i2c.scl]] : []),
535
+ ...(i2c ? [['I2C SDA', i2c.sda, 'i2c'], ['I2C SCL', i2c.scl, 'i2c']] : []),
419
536
  ...(display && display.interface === 'rgb' ? [
420
537
  ['display DE', display.pins.de],
421
538
  ['display HSYNC', display.pins.hsync],
@@ -445,21 +562,34 @@ function validatePinAssignments(target) {
445
562
  ['audio WS', audio.pins.ws],
446
563
  ['audio DOUT', audio.pins.dout],
447
564
  ['audio DIN', audio.pins.din],
448
- ['audio amplifier', audio.pins.powerAmplifier]
565
+ ['audio amplifier', audio.pins.powerAmplifier],
566
+ ...(audio.kind === 'i2s-amplifier' ? [
567
+ ['microphone BCLK', audio.pins.micBclk],
568
+ ['microphone WS', audio.pins.micWs],
569
+ ['microphone DIN', audio.pins.micDin]
570
+ ] : [])
449
571
  ] : []),
450
572
  ...(sd ? [
451
573
  ['microSD CLK', sd.pins.clk],
452
574
  ['microSD CMD', sd.pins.cmd],
453
- ['microSD DATA0', sd.pins.data0]
575
+ ['microSD DATA0', sd.pins.data0],
576
+ ...(sd.interface === 'spi' ? [
577
+ ['microSD SCK', sd.pins.sck],
578
+ ['microSD MOSI', sd.pins.mosi],
579
+ ['microSD MISO', sd.pins.miso],
580
+ ['microSD CS', sd.pins.cs]
581
+ ] : [])
454
582
  ] : []),
455
583
  ...(launcher ? [['launcher button', launcher.pin]] : [])
456
584
  ]
585
+ const shared = (a, b) => a !== b && target.pinSharing.some((group) => group.includes(a) && group.includes(b))
457
586
  const used = new Map()
458
587
  for (const [label, value] of pins) {
459
588
  if (value < 0) continue
589
+ const role = pinRoleOf(label)
460
590
  const previous = used.get(value)
461
- if (previous) throw new Error(`GPIO ${value} is assigned to both ${previous} and ${label}.`)
462
- used.set(value, label)
591
+ if (previous && !shared(previous.role, role)) throw new Error(`GPIO ${value} is assigned to both ${previous.label} and ${label}.`)
592
+ if (!previous) used.set(value, { label, role })
463
593
  }
464
594
  }
465
595
 
@@ -503,8 +633,10 @@ ${includes}
503
633
  #define GEA_BOARD_HAS_TOUCH ${touch ? 1 : 0}
504
634
  #define GEA_BOARD_HAS_POWER ${target.chips.power ? 1 : 0}
505
635
  #define GEA_BOARD_HAS_IMU ${target.chips.imu ? 1 : 0}
636
+ #define GEA_BOARD_HAS_RTC ${target.chips.rtc ? 1 : 0}
506
637
  #define GEA_BOARD_HAS_AUDIO ${audio ? 1 : 0}
507
638
  #define GEA_BOARD_HAS_MICROSD ${target.storage.microSD ? 1 : 0}
639
+ #define GEA_BOARD_MICROSD_SPI ${target.storage.microSD?.interface === 'spi' ? 1 : 0}
508
640
  #define GEA_BOARD_HAS_LAUNCHER_BUTTON ${target.controls.launcherButton ? 1 : 0}
509
641
  #define GEA_BOARD_HAS_EXPANDER ${expander ? 1 : 0}
510
642
  #define GEA_BOARD_HAS_RGB_CONTROLLER ${rgb?.controller ? 1 : 0}
@@ -524,10 +656,13 @@ ${qspi ? 'struct Co5300DisplayConfig { spi_host_device_t spiHost; gpio_num_t cs;
524
656
  // framebuffer out with these timings. data[0..4] are blue, [5..10] green,
525
657
  // [11..15] red (RGB565 lane order). backlight is a PWM-capable GPIO, or
526
658
  // GPIO_NUM_NC when the expander drives it.
527
- 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; bool backlightActiveLow; };` : ''}${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; int address; int initialDirections; int powerAmplifier; };' : ''}${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; int es7210Address; };' : ''}
659
+ 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; int scanFramebuffers; bool backlightActiveLow; int bounceRows; };` : ''}${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; int address; int initialDirections; int powerAmplifier; };' : ''}${audio?.kind === 'codec' ? '\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; int es7210Address; };' : ''}${audio?.kind === 'i2s-amplifier' ? '\n// An I2S amplifier and an optional separate I2S microphone; expander lines are -1 when not routed through it.\nstruct I2sAmplifierAudioConfig { gpio_num_t bclk; gpio_num_t ws; gpio_num_t dout; gpio_num_t micBclk; gpio_num_t micWs; gpio_num_t micDin; int expanderShutdown; int expanderMute; int micFormat; };\n// micFormat: 0 standard I2S, 1 PDM, 2 decided at boot by the board controller.' : ''}
528
660
 
529
661
  inline constexpr I2cBusConfig i2c{ .sda = ${gpio(i2c.sda)}, .scl = ${gpio(i2c.scl)} };
530
- inline constexpr SdMmcConfig storage{ .clk = ${gpio(sdPins.clk)}, .cmd = ${gpio(sdPins.cmd)}, .data0 = ${gpio(sdPins.data0)} };
662
+ inline constexpr SdMmcConfig storage{ .clk = ${gpio(sdPins.clk)}, .cmd = ${gpio(sdPins.cmd)}, .data0 = ${gpio(sdPins.data0)} };${target.storage.microSD?.interface === 'spi' ? `
663
+ // The card slot is wired for SPI; cs is GPIO_NUM_NC when chip select is hard-wired.
664
+ struct SdSpiConfig { gpio_num_t sck; gpio_num_t mosi; gpio_num_t miso; gpio_num_t cs; };
665
+ inline constexpr SdSpiConfig storageSpi{ .sck = ${gpio(sdPins.sck)}, .mosi = ${gpio(sdPins.mosi)}, .miso = ${gpio(sdPins.miso)}, .cs = ${gpio(sdPins.cs)} };` : ''}
531
666
  inline constexpr LauncherButtonConfig launcherButton{ .pin = ${gpio(launcher.pin)}, .activeLevel = ${launcher.activeLevel} };
532
667
  ${rgb ? `inline constexpr RgbPanelDisplayConfig display{
533
668
  .de = ${gpio(rgb.pins.de)}, .hsync = ${gpio(rgb.pins.hsync)}, .vsync = ${gpio(rgb.pins.vsync)}, .pclk = ${gpio(rgb.pins.pclk)},
@@ -537,7 +672,9 @@ ${rgb ? `inline constexpr RgbPanelDisplayConfig display{
537
672
  .hsyncPulseWidth = ${rgb.hsyncPulseWidth}, .hsyncBackPorch = ${rgb.hsyncBackPorch}, .hsyncFrontPorch = ${rgb.hsyncFrontPorch},
538
673
  .vsyncPulseWidth = ${rgb.vsyncPulseWidth}, .vsyncBackPorch = ${rgb.vsyncBackPorch}, .vsyncFrontPorch = ${rgb.vsyncFrontPorch},
539
674
  .pclkActiveNeg = ${rgb.pclkActiveNeg ? 'true' : 'false'},
540
- .backlightActiveLow = ${rgb.backlightActiveLow ? 'true' : 'false'}
675
+ .scanFramebuffers = ${rgb.scanFramebuffers},
676
+ .backlightActiveLow = ${rgb.backlightActiveLow ? 'true' : 'false'},
677
+ .bounceRows = ${rgb.bounceRows}
541
678
  };` : ''}${qspi ? `inline constexpr Co5300DisplayConfig display{
542
679
  .spiHost = ${display.spiHost === 'spi3' ? 'SPI3_HOST' : 'SPI2_HOST'}, .cs = ${gpio(displayPins.cs)}, .pclk = ${gpio(displayPins.pclk)},
543
680
  .data0 = ${gpio(displayPins.data0)}, .data1 = ${gpio(displayPins.data1)},
@@ -545,7 +682,13 @@ ${rgb ? `inline constexpr RgbPanelDisplayConfig display{
545
682
  .reset = ${gpio(displayPins.reset)}, .te = ${gpio(displayPins.te)}
546
683
  };` : ''}${touch ? `
547
684
  inline constexpr Ft3168TouchConfig touch{ .reset = ${gpio(touchPins.reset)}, .interrupt = ${gpio(touchPins.interrupt)} };` : ''}${expander ? `
548
- inline constexpr IoExpanderConfig expander{ .initialOutputs = ${expander.initialOutputs}, .backlight = ${expander.outputs.backlight}, .touchReset = ${expander.outputs.touchReset}, .displayReset = ${expander.outputs.displayReset}, .address = ${expander.address}, .initialDirections = ${expander.initialDirections}, .powerAmplifier = ${expander.outputs.powerAmplifier} };` : ''}${audio ? `
685
+ inline constexpr IoExpanderConfig expander{ .initialOutputs = ${expander.initialOutputs}, .backlight = ${expander.outputs.backlight}, .touchReset = ${expander.outputs.touchReset}, .displayReset = ${expander.outputs.displayReset}, .address = ${expander.address}, .initialDirections = ${expander.initialDirections}, .powerAmplifier = ${expander.outputs.powerAmplifier} };` : ''}${audio?.kind === 'i2s-amplifier' ? `
686
+ inline constexpr I2sAmplifierAudioConfig audio{
687
+ .bclk = ${gpio(audioPins.bclk)}, .ws = ${gpio(audioPins.ws)}, .dout = ${gpio(audioPins.dout)},
688
+ .micBclk = ${gpio(audioPins.micBclk)}, .micWs = ${gpio(audioPins.micWs)}, .micDin = ${gpio(audioPins.micDin)},
689
+ .expanderShutdown = ${audio.expander.shutdown}, .expanderMute = ${audio.expander.mute},
690
+ .micFormat = ${{ i2s: 0, pdm: 1, auto: 2 }[audio.microphone]}
691
+ };` : ''}${audio?.kind === 'codec' ? `
549
692
  inline constexpr Es8311AudioConfig audio{
550
693
  .i2sPort = I2S_NUM_AUTO, .mclk = ${gpio(audioPins.mclk)}, .bclk = ${gpio(audioPins.bclk)},
551
694
  .ws = ${gpio(audioPins.ws)}, .dout = ${gpio(audioPins.dout)}, .din = ${gpio(audioPins.din)},
@@ -588,7 +731,7 @@ function cmakeQuote(value) {
588
731
  }
589
732
 
590
733
  export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
591
- const { display, touch, power, imu, audio, expander } = target.chips
734
+ const { display, touch, power, imu, audio, expander, rtc } = target.chips
592
735
  const chipSource = (source) => ` "\${GEA_CHIPS}/${source}"`
593
736
  const bindingSource = (source) => ` "\${GEA_EMBEDDED_ROOT}/targets/esp32/${source}"`
594
737
  const sourcesFor = (chip) => (chip ? [...chip.nativeSources.map(chipSource), ...chip.bindingSources.map(bindingSource)] : [])
@@ -606,10 +749,11 @@ export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
606
749
  ...(power ? sourcesFor(power) : absentBinding('power_absent.cpp')),
607
750
  ...(imu ? sourcesFor(imu) : absentBinding('imu_absent.cpp')),
608
751
  ...(touch ? sourcesFor(touch) : absentBinding('touch_absent.cpp')),
609
- ...sourcesFor(audio),
610
- ...sourcesFor(expander)
752
+ ...(audio?.kind === 'codec' ? sourcesFor(audio) : []),
753
+ ...sourcesFor(expander),
754
+ ...sourcesFor(rtc)
611
755
  ]
612
- const requires = [...new Set([display, touch, power, imu, audio, expander].flatMap((chip) => (chip ? chip.requires : [])))]
756
+ const requires = [...new Set([display, touch, power, imu, audio, expander, rtc].flatMap((chip) => (chip ? chip.requires : [])))]
613
757
  const surface = display || target.canvas
614
758
  const hasSurface = Boolean(surface)
615
759
  // An app that declares a display size has said something more specific than
@@ -631,6 +775,8 @@ export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
631
775
  // sources include it; this reaches the app's own sources, which is where
632
776
  // the board-specific configuration actually lives.
633
777
  boardDefine('GEA_BOARD_HAS_POWER', power ? 1 : 0),
778
+ // app_main restores the system clock from the RTC before anything reads it.
779
+ boardDefine('GEA_BOARD_HAS_RTC', rtc ? 1 : 0),
634
780
  // The QSPI panels take byte-swapped RGB565 over the wire and the base
635
781
  // stores it that way; an RGB panel's DMA reads the framebuffer as-is, so
636
782
  // it stores native order -- exactly what the Elecrow rotary target does.
@@ -638,7 +784,14 @@ export function renderTargetCmake(target, includeDir, appDefines = new Set()) {
638
784
  display?.panel?.minChunkRows ? boardDefine('GEA_EMBEDDED_DISPLAY_FLUSH_CHUNK_MIN', display.panel.minChunkRows) : '',
639
785
  display && display.interface === 'rgb' ? boardDefine('GEA_EMBEDDED_PIXEL_PANEL_ENDIAN', 0) : ''
640
786
  ].join('')
787
+ // The board's own identity and pixel order reach geatsc too: the base project
788
+ // is another board's, and its defaults (name, viewport, byte-swapped RGB565)
789
+ // would otherwise decide how this board's fonts and colour literals are baked.
641
790
  return `set(GEA_CUSTOM_TARGET_ACTIVE 1)
791
+ set(GEA_CUSTOM_TARGET_BOARD_ID "${target.id}")
792
+ set(GEA_CUSTOM_TARGET_PIXEL_PANEL_ENDIAN ${display && display.interface === 'rgb' ? 0 : 1})
793
+ set(GEA_CUSTOM_TARGET_VIEWPORT_WIDTH "${hasSurface ? surface.width : ''}")
794
+ set(GEA_CUSTOM_TARGET_VIEWPORT_HEIGHT "${hasSurface ? surface.height : ''}")
642
795
  ${display?.panel?.transferMode ? `set(GEA_CUSTOM_QSPI_TRANSFER_MODE \"${display.panel.transferMode}\")` : ''}
643
796
  ${display?.interface === 'qspi' && display.pclkHz ? `set(GEA_CUSTOM_QSPI_PCLK_HZ ${display.pclkHz})` : ''}
644
797
  set(GEA_CUSTOM_TARGET_INCLUDE_DIR ${cmakeQuote(includeDir)})
@@ -648,6 +801,10 @@ set(GEA_CUSTOM_TARGET_DISPLAY_INTERFACE "${display ? display.interface : ''}")
648
801
  set(GEA_CUSTOM_TARGET_TOUCH_DRIVER "${touch ? touch.driver : ''}")
649
802
  set(GEA_CUSTOM_TARGET_HAS_EXPANDER ${expander ? 1 : 0})
650
803
  set(GEA_CUSTOM_TARGET_HAS_MICROSD ${target.storage.microSD ? 1 : 0})
804
+ set(GEA_CUSTOM_TARGET_AUDIO_DRIVER "${audio ? audio.driver : ''}")
805
+ set(GEA_CUSTOM_TARGET_AUDIO_SOURCES
806
+ ${audio?.kind === 'i2s-amplifier' ? sourcesFor(audio).join('\n') : ''}
807
+ )
651
808
  set(GEA_CUSTOM_TARGET_DISPLAY_SOURCES
652
809
  ${displaySources.join('\n')}
653
810
  )
@@ -168,6 +168,8 @@ export function resolveBoardSelection({
168
168
  // The definition outranks the base it extends: a composed board's flash is
169
169
  // its own module's, not the flash of the board whose stack it borrows.
170
170
  flashSize: board?.flashSize || definition?.flashSize || targetInfo.flashSize || '',
171
+ flashMode: board?.flashMode || definition?.flashMode || targetInfo.flashMode || '',
172
+ flashFreq: board?.flashFreq || definition?.flashFreq || targetInfo.flashFreq || 0,
171
173
  appPlatform: board?.appPlatform || targetInfo.appPlatform || '',
172
174
  compatibleAppPlatforms: Array.isArray(targetInfo.compatibleAppPlatforms) ? targetInfo.compatibleAppPlatforms : [],
173
175
  idfTarget: board?.idfTarget || targetInfo.idfTarget || '',
@@ -36,8 +36,16 @@ export function serialPortCandidates(env = process.env) {
36
36
  }
37
37
 
38
38
  // Windows port names are case-insensitive, so compare them that way.
39
+ export function isNetworkSerialPort(port) {
40
+ return /^(rfc2217|socket):\/\//.test(String(port || ''))
41
+ }
42
+
39
43
  export function serialPortPresent(port, env = process.env) {
40
44
  if (!port) return false
45
+ // esptool and pyserial open network ports (an RFC 2217 server such as
46
+ // scripts/ch34x-rfc2217.py, or a raw socket) by URL; there is no device
47
+ // node to look for.
48
+ if (isNetworkSerialPort(port)) return true
41
49
  if (process.platform !== 'win32') return existsSync(port)
42
50
  return serialPortCandidates(env).some((candidate) => candidate.toUpperCase() === port.toUpperCase())
43
51
  }
@@ -25,6 +25,8 @@ export const buildOptions = {
25
25
  'renderer.recordInlinePositions': { type: 'boolean', macro: 'GEA_EMBEDDED_SKIP_POSITION_INLINE_RECORD', encode: v => Number(!v) },
26
26
  'renderer.adaptiveCoalescing': { type: 'boolean', macro: 'GEA_EMBEDDED_FLUSH_ADAPTIVE_COALESCE' },
27
27
  'renderer.broadDirtyBounds': { type: 'boolean', macro: 'GEA_EMBEDDED_BROAD_DIRTY_BBOX' },
28
+ 'display.width': { type: 'integer', min: 1 },
29
+ 'display.height': { type: 'integer', min: 1 },
28
30
  'display.framebufferStream': { values: ['independent', 'continuous'], macro: 'GEA_EMBEDDED_DISPLAY_CO5300_FRAMEBUFFER_CS_HELD_STREAM', encode: v => Number(v === 'continuous') },
29
31
  'display.presentStream': { boardScoped: true, values: ['independent', 'continuous'], macro: 'GEA_EMBEDDED_DISPLAY_CO5300_PRESENT_CS_HELD_STREAM', encode: v => Number(v === 'continuous') },
30
32
  'display.flushPoolBytes': { type: 'integer', macro: 'GEA_EMBEDDED_DISPLAY_FLUSH_POOL_BYTES' },
@@ -169,7 +169,7 @@ export function requireEspIdf(env, log, selection = null) {
169
169
 
170
170
  // The per-app sdkconfig policy: development logging, the board's stack
171
171
  // sizes, the S3 instruction cache and the BLE host exactly as the app needs.
172
- export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities, bleOta, partitionCsv, boardConsole, boardPsram }) {
172
+ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities, bleOta, partitionCsv, boardConsole, boardPsram, boardRgbPanel }) {
173
173
  const set = (key, value) => sdkconfig.set(key, value)
174
174
  const unset = (key) => sdkconfig.unset(key)
175
175
  // A board value the app's own defaults may replace. Every value this policy
@@ -239,10 +239,39 @@ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities,
239
239
  }
240
240
  board(`CONFIG_SPIRAM_SPEED_${boardPsram.speed}M`, 'y')
241
241
  board('CONFIG_SPIRAM_SPEED', String(boardPsram.speed))
242
+ // Octal PSRAM at 120MHz is gated behind ESP-IDF's experimental
243
+ // features. Its live re-tuning from the temperature sensor is left
244
+ // off: it aborts at boot on any flash model Espressif has not listed.
245
+ if (boardPsram.speed === 120 && boardPsram.mode === 'octal') board('CONFIG_IDF_EXPERIMENTAL_FEATURES', 'y')
246
+ unset('CONFIG_SPIRAM_TIMING_TUNING_POINT_VIA_TEMPERATURE_SENSOR')
247
+ }
248
+ if (boardPsram.xip) {
249
+ board('CONFIG_SPIRAM_XIP_FROM_PSRAM', 'y')
250
+ board('CONFIG_SPIRAM_FETCH_INSTRUCTIONS', 'y')
251
+ board('CONFIG_SPIRAM_RODATA', 'y')
242
252
  }
243
253
  }
244
254
  }
245
255
 
256
+ // A bare RGB panel is scanned out of PSRAM through bounce buffers refilled
257
+ // by the LCD interrupt. Its code must sit in IRAM: otherwise it is fetched
258
+ // over the same PSRAM bus rendering saturates (always so with XIP from
259
+ // PSRAM), the refill misses its slot, the FIFO underruns and every later
260
+ // line lands shifted -- the picture shreds on each repaint and stays slid.
261
+ // Restarting the transfer at each VSYNC puts a slipped frame back. In that
262
+ // mode the driver never resets the EOF count it picks each refill's buffer
263
+ // from, so one lost EOF would leave every refill a buffer out of step with
264
+ // the DMA (thin lines at each band's head); rgb_panel.cpp's refill reads the
265
+ // buffer and band from the DMA itself instead. A board whose display says
266
+ // `restartInVsync: false` skips the restart: it runs in the VSYNC interrupt,
267
+ // which waits out a refill in progress, and once that pushes it past the
268
+ // vertical blanking the restarted frame lands shifted sideways.
269
+ if (boardRgbPanel) {
270
+ board('CONFIG_LCD_RGB_ISR_IRAM_SAFE', 'y')
271
+ if (boardRgbPanel.restartInVsync) board('CONFIG_LCD_RGB_RESTART_IN_VSYNC', 'y')
272
+ else unset('CONFIG_LCD_RGB_RESTART_IN_VSYNC')
273
+ }
274
+
246
275
  // Flash size follows the board, not the base target it extends: a composed
247
276
  // board declares its own, and without this a 16MB module would inherit its
248
277
  // base's 32MB and build a bootloader that maps flash it does not have.
@@ -256,6 +285,28 @@ export function applySdkconfigPolicy(sdkconfig, { selection, app, capabilities,
256
285
  board('CONFIG_ESPTOOLPY_FLASHSIZE', `"${flashSizeMb}MB"`)
257
286
  }
258
287
 
288
+ // Flash mode follows the board's module too. Only the choice is written:
289
+ // ESP-IDF derives CONFIG_ESPTOOLPY_FLASHMODE from it (QIO images still carry
290
+ // DIO in their header; the bootloader switches the chip to QIO itself).
291
+ const flashMode = (selection.flashMode || '').toUpperCase()
292
+ if (flashMode) {
293
+ for (const mode of ['QIO', 'QOUT', 'DIO', 'DOUT']) {
294
+ if (mode !== flashMode) unset(`CONFIG_ESPTOOLPY_FLASHMODE_${mode}`)
295
+ }
296
+ board(`CONFIG_ESPTOOLPY_FLASHMODE_${flashMode}`, 'y')
297
+ }
298
+
299
+ // Flash and PSRAM share the MSPI core clock, so the flash clock must divide
300
+ // the one PSRAM runs from: octal PSRAM at 120MHz needs a 240MHz core, which
301
+ // 80MHz quad flash cannot share (ESP-IDF has no tuning table for it).
302
+ const flashFreq = Number(app?.targetConfig?.esp32?.flashFreq) || Number(selection.flashFreq) || 0
303
+ if (flashFreq) {
304
+ for (const mhz of [20, 26, 40, 80, 120]) {
305
+ if (mhz !== flashFreq) unset(`CONFIG_ESPTOOLPY_FLASHFREQ_${mhz}M`)
306
+ }
307
+ board(`CONFIG_ESPTOOLPY_FLASHFREQ_${flashFreq}M`, 'y')
308
+ }
309
+
259
310
  // These four are all internal-DRAM decisions, which is the memory an app's
260
311
  // own DMA buffers and real-time arenas come from: the two task stacks are
261
312
  // allocated from it, and the two PSRAM settings decide how much of the rest
@@ -443,6 +494,19 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
443
494
  // the app's file is last and wins wherever the two disagree.
444
495
  const appEsp32Config = app ? appTargetConfig(app, 'esp32') : null
445
496
  const appSdkconfigFile = appEsp32Config?.sdkconfig ? path.join(app.root, appEsp32Config.sdkconfig) : ''
497
+ // gea.targets.esp32.display: the RGB panel pipeline an app opts into.
498
+ // copyBack: 'dma' the strip copy-back runs on GDMA, freeing the worker core;
499
+ // it cannot wait out bounce refills, so partial UI repaints tear
500
+ // bounceRows: N bounce-buffer height, overriding the board's
501
+ // gridStrips: true staged strips sit on a fixed grid (per-band 3D underlays)
502
+ const appDisplay = appEsp32Config?.display
503
+ if (appDisplay) {
504
+ if (appDisplay.copyBack === 'dma') resolvedBuild.defines.push('GEA_EMBEDDED_RGB_COPYBACK_DMA=1')
505
+ else if (appDisplay.copyBack && appDisplay.copyBack !== 'cpu') throw new Error(`gea.targets.esp32.display.copyBack must be 'cpu' or 'dma', not '${appDisplay.copyBack}'.`)
506
+ const bounceRows = Number(appDisplay.bounceRows) || 0
507
+ if (bounceRows) resolvedBuild.defines.push(`GEA_EMBEDDED_RGB_BOUNCE_ROWS=${bounceRows}`)
508
+ if (appDisplay.gridStrips === true) resolvedBuild.defines.push('GEA_EMBEDDED_STAGE_GRID_STRIPS=1')
509
+ }
446
510
  const { file: sdkconfigFile, defaultsFile, regenerated } = prepareBuildLocalSdkconfig(selection.targetDir, binaryDir, appSdkconfigFile)
447
511
  if (regenerated) log('sdkconfig defaults changed; the generated sdkconfig was rebuilt from them')
448
512
  log(`Using ESP32 target '${selection.target}' at ${selection.targetDir} (idf=${idfTarget} chip=${selection.esptoolChip || idfTarget} flash=${selection.flashSize})`)
@@ -462,6 +526,7 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
462
526
  let boardPartitionCsv = ''
463
527
  let boardConsole = null
464
528
  let boardPsram = null
529
+ let boardRgbPanel = false
465
530
  // Physical buttons: the board's JSON list with the app's changes, generated
466
531
  // into a header the firmware's button service includes.
467
532
  const buttons = resolveButtons({ board: selection.buttons || [], app, platform: 'esp32', boardId: selection.target })
@@ -495,6 +560,9 @@ export function prepareEsp32Build({ ctx, selection, app = null, env = ctx.env ||
495
560
  boardPartitionCsv = generated.partitionCsv
496
561
  boardConsole = generated.target.console
497
562
  boardPsram = generated.target.psram
563
+ if (boardPsram && appEsp32Config?.psram) boardPsram = { ...boardPsram, ...appEsp32Config.psram }
564
+ const display = generated.target.chips?.display
565
+ boardRgbPanel = display?.interface === 'rgb' ? { restartInVsync: display.restartInVsync !== false } : false
498
566
  log(`Generated custom board files in ${outDir} (${path.basename(generated.headerPath)}, ${path.basename(generated.cmakePath)})`)
499
567
  }
500
568
 
@@ -625,7 +693,8 @@ function preparePartitions(app, config, buildDir, targetId) {
625
693
  // apps that declare none, because the board is what knows its flash layout.
626
694
  partitionCsv: appPartitionCsv || boardPartitionCsv,
627
695
  boardConsole,
628
- boardPsram
696
+ boardPsram,
697
+ boardRgbPanel
629
698
  }).save()
630
699
 
631
700
  const defaultsArg = [defaultsFile, appSdkconfigFile].filter(Boolean).join(';')
@@ -98,6 +98,9 @@ const nodeFeatureDefines = [['node-images', 'GEA_UI_IMAGE_NODES'], ['node-inputs
98
98
  // A separate marker: analyzers older than it never report node-videos.
99
99
  const videoNodeAnalysis = 'node-video-analysis-v1'
100
100
  const videoNodeMacro = 'GEA_UI_VIDEO_NODES'
101
+ // Inline SVG follows the same marker contract as video.
102
+ const svgNodeAnalysis = 'node-svg-analysis-v1'
103
+ const svgNodeMacro = 'GEA_UI_SVG'
101
104
  const rangeMacro = family => `GEA_CSS_U8_${family.replaceAll('-', '_').toUpperCase()}`
102
105
 
103
106
  export function withRendererFeatureDefines(defines, features, { devicePixelRatio } = {}) {
@@ -106,12 +109,14 @@ export function withRendererFeatureDefines(defines, features, { devicePixelRatio
106
109
  const generatedNames = new Set([...rendererFeatureDefines, ...cssFeatureVersions.flat(), ...nodeFeatureDefines, ...nodeAuxFeatureDefines, ...compactStyleDefines].map(([, name]) => name).concat(triangleOcclusionMacro, circleCacheMacros, rangeFamilies.map(rangeMacro), ['GEA_UI_CLASS_INLINE_TOKENS', 'GEA_UI_CLASS_OVERFLOW']))
107
110
  generatedNames.add('GEA_RUNTIME_REALMS')
108
111
  generatedNames.add(videoNodeMacro)
112
+ generatedNames.add(svgNodeMacro)
109
113
  const result = defines.split(';').filter((define) => define && !generatedNames.has(define.split('=')[0]))
110
114
  if (features.includes('worker-realms')) result.push('GEA_RUNTIME_REALMS=1')
111
115
  if (features.includes('node-analysis-v1')) {
112
116
  for (const [feature, name] of nodeFeatureDefines) result.push(`${name}=${features.includes(feature) ? 1 : 0}`)
113
117
  }
114
118
  if (features.includes(videoNodeAnalysis)) result.push(`${videoNodeMacro}=${features.includes('node-videos') ? 1 : 0}`)
119
+ if (features.includes(svgNodeAnalysis)) result.push(`${svgNodeMacro}=${features.includes('node-svg') ? 1 : 0}`)
115
120
  const storageProofs = features.filter(feature => feature.startsWith('css-storage-'))
116
121
  if (storageProofs.length && storageProofs.every(proof => proof === 'css-storage-v1')) {
117
122
  for (const [feature, name] of compactStyleDefines)
@@ -33,8 +33,13 @@ export function nativeVideoSourceNeedsSupport(text) {
33
33
  return /#\s*include\s*[<"](?:[^>"\n]*\/)?(?:video|video_\w+|mjpeg|mjpeg_parser|rtc_h264|h264_\w+)\.h[>"]|\b(?:HTMLVideoElement|VideoElement|presentFrames|esp_h264_\w+)\b|\bvideo::/.test(text)
34
34
  }
35
35
 
36
+ // Native code can build SVG through createElement("svg") or the engine header.
37
+ export function nativeSvgSourceNeedsSupport(text) {
38
+ return /#\s*include\s*[<"](?:[^>"\n]*\/)?svg_\w+\.h[>"]|"svg"|\bsvg::/.test(text)
39
+ }
40
+
36
41
  export function withNativeCssFeatures(app, features) {
37
- if (!features.includes('renderer-occlusion-v1') && !features.includes('node-analysis-v1') && !features.includes('node-video-analysis-v1') && !features.includes('node-aux-v1') && !features.includes('css-storage-v1') && !features.some(feature => /^node-class-capacity-v1-[123]$/.test(feature)) && !features.some(feature => /^css-analysis-v(?:[1-9]|1[0123456789])$/.test(feature))) return features
42
+ if (!features.includes('renderer-occlusion-v1') && !features.includes('node-analysis-v1') && !features.includes('node-video-analysis-v1') && !features.includes('node-svg-analysis-v1') && !features.includes('node-aux-v1') && !features.includes('css-storage-v1') && !features.some(feature => /^node-class-capacity-v1-[123]$/.test(feature)) && !features.some(feature => /^css-analysis-v(?:[1-9]|1[0123456789])$/.test(feature))) return features
38
43
  const sources = app.nativeSources || []
39
44
  const components = app.targetConfig?.esp32?.componentDirs || []
40
45
  if (!sources.length && !components.length) return features
@@ -44,7 +49,7 @@ export function withNativeCssFeatures(app, features) {
44
49
  // Opaque native CSS writes can supply gradient/transform values even when
45
50
  // every source-visible custom property is a literal colour. Keep their
46
51
  // renderer caches as well as semantic fields.
47
- const retain = () => [...new Set([...features.filter(feature => !feature.startsWith('node-class-capacity-') && !feature.startsWith('node-class-storage-')), ...families, 'node-images', 'node-inputs', 'node-videos', 'css-ranges-unknown', 'css-circle-cache-unbounded', 'renderer-circles', 'renderer-occlusion-triangles', 'renderer-transforms', 'renderer-linear-gradients', 'renderer-radial-gradients'])].sort()
52
+ const retain = () => [...new Set([...features.filter(feature => !feature.startsWith('node-class-capacity-') && !feature.startsWith('node-class-storage-')), ...families, 'node-images', 'node-inputs', 'node-videos', 'node-svg', 'css-ranges-unknown', 'css-circle-cache-unbounded', 'renderer-circles', 'renderer-occlusion-triangles', 'renderer-transforms', 'renderer-linear-gradients', 'renderer-radial-gradients'])].sort()
48
53
  const root = path.resolve(app.root)
49
54
  const headers = new Map()
50
55
  const seen = new Set()
@@ -87,6 +92,7 @@ export function withNativeCssFeatures(app, features) {
87
92
  // Native code can drive the video host directly; only code that names it
88
93
  // keeps the H.264/MJPEG decoders.
89
94
  if (nativeVideoSourceNeedsSupport(text)) features = [...new Set([...features, 'node-videos'])]
95
+ if (nativeSvgSourceNeedsSupport(text)) features = [...new Set([...features, 'node-svg'])]
90
96
  // Follow app headers, including headers provided by another component's
91
97
  // include directory. ESP-IDF and C/C++ platform headers do not depend on
92
98
  // the UI engine. An external native package is opaque above.
package/src/gea.mjs CHANGED
@@ -145,23 +145,20 @@ export async function runGea(argv, io = {}) {
145
145
  // this host is not (a Windows-only app on a Mac, a Mac-only app on Linux)
146
146
  // has nothing to select: falling into board selection would report a
147
147
  // missing --board for an app that declares no board at all.
148
- if (command === 'build' && !target && app && !declaresBoardTarget(app) && (app.targets?.macos || app.targets?.windows || app.targets?.ios)) {
149
- const desktop = ['macos', 'windows', 'ios'].filter((platform) => app.targets?.[platform])
148
+ if (command === 'build' && !target && app && !declaresBoardTarget(app) && (app.targets?.macos || app.targets?.windows || app.targets?.ios || app.targets?.tvos)) {
149
+ const desktop = ['macos', 'windows', 'ios', 'tvos'].filter((platform) => app.targets?.[platform])
150
150
  fail(`'${app.id}' declares no target that builds on this host by default. Pass --target ${desktop.join(' or --target ')}.`, ExitCode.usage)
151
151
  }
152
152
  }
153
- // iOS is the third platform driven by one script inside @geastack/apple,
154
- // resolved like macOS from the app's own dependencies. It never has a host
155
- // default: a bare `gea build` cannot know simulator from device, so the iOS
156
- // build is always the documented `gea build --target ios [--mode simulator|device]`,
157
- // and `gea run --target ios` builds, installs and launches it.
158
- if ((command === 'build' || command === 'run') && target === 'ios') {
153
+ // iOS and tvOS share the UIKit build script in @geastack/apple.
154
+ // Both use an explicit target and default to the platform's simulator.
155
+ if ((command === 'build' || command === 'run') && ['ios', 'tvos'].includes(target)) {
159
156
  const app = parsed.options.app || rest[0] ? findAppById(ctx, String(parsed.options.app || rest[0])) : findCurrentApp(cwd)
160
- if (!app?.targets?.ios) {
161
- 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)
157
+ if (!app?.targets?.[target]) {
158
+ fail(app ? `'${app.id}' does not declare gea.targets.${target}.` : 'No app selected. Pass --app <id> or run inside a Gea app folder.', ExitCode.usage)
162
159
  }
163
160
  const { runIos } = await import('./ios/adapter.mjs')
164
- return runIos({ app, env, dryRun: flag(parsed, 'dry-run'), stdout, mode: option(parsed, 'mode', ''), run: command === 'run' })
161
+ return runIos({ app, platform: target, env, dryRun: flag(parsed, 'dry-run'), stdout, mode: option(parsed, 'mode', ''), run: command === 'run' })
165
162
  }
166
163
  // Pebble is driven by one script inside @geastack/pebble, like iOS inside
167
164
  // @geastack/apple, and like iOS it is never a host default. `gea build
@@ -305,6 +302,8 @@ ${heading('Native desktop, mobile and watch apps (scripts ship in @geastack/appl
305
302
  gea build --target raspberry-pi-os [app] build an SDL Linux native executable (no launch)
306
303
  gea build --target macos [app] build a Mac .app (a bare gea build does this on a Mac for a Mac-only app)
307
304
  gea build --target ios [app] [--mode simulator|device] generate the Xcode project and build the iOS .app
305
+ gea build --target tvos [app] [--mode simulator|device] build the tvOS .app
306
+ gea run --target tvos [app] [--mode simulator|device] install and launch on Apple TV or its simulator
308
307
  gea run --target ios [app] [--mode simulator|device] build, then install and launch on a simulator or iPhone
309
308
  gea build|run --target windows [app] build (and launch) the Windows executable
310
309
  gea build --target pebble [app] build a Pebble Time 2 app (.pbw); needs the Pebble SDK
@@ -5,27 +5,23 @@ import { CliError, ExitCode, fail } from '../errors.mjs'
5
5
  import { appleChildEnv, appleTargetScript } from '../macos/adapter.mjs'
6
6
  import { formatCommand } from '../run.mjs'
7
7
 
8
- // iOS mirrors macOS: a platform, not a board, driven by one script shipped
9
- // inside @geastack/apple and resolved from the app's own dependencies. The
10
- // script takes a destination -- `simulator` (the default) or `device` -- which
11
- // `--mode` selects. `gea build --target ios` compiles the .app and stops;
12
- // `gea run --target ios` also installs and launches it on the picked simulator
13
- // or attached iPhone, which is the script's own default behaviour. The script
14
- // reads GEA_IOS_SKIP_LAUNCH, so a caller who already set it keeps their choice.
15
- export function runIos({ app, env, dryRun = false, stdout, mode = '', run = false }) {
8
+ // The UIKit script builds a simulator or device .app and optionally deploys it.
9
+ export function runIos({ app, env, dryRun = false, stdout, platform = 'ios', mode = '', run = false }) {
10
+ const platformName = platform === 'tvos' ? 'tvOS' : 'iOS'
16
11
  const destination = mode || 'simulator'
17
12
  if (destination !== 'simulator' && destination !== 'device') {
18
- fail(`--mode ${mode} is not an iOS destination; expected simulator or device.`, ExitCode.usage)
13
+ fail(`--mode ${mode} is not a valid destination for ${platformName}; expected simulator or device.`, ExitCode.usage)
19
14
  }
20
15
  const { script, require } = appleTargetScript(app, 'ios', 'build-ios.sh', env)
21
- const childEnv = appleChildEnv(app, nativeScriptBuildEnv(app, 'ios', env, { dryRun }), require)
16
+ const childEnv = appleChildEnv(app, nativeScriptBuildEnv(app, platform, env, { dryRun }), require)
17
+ const platformArg = platform === 'tvos' ? [platform] : []
22
18
  if (!run && childEnv.GEA_IOS_SKIP_LAUNCH === undefined) childEnv.GEA_IOS_SKIP_LAUNCH = '1'
23
19
  if (dryRun) {
24
- stdout(formatCommand(['bash', script, app.id, destination]))
20
+ stdout(formatCommand(['bash', script, app.id, destination, ...platformArg]))
25
21
  return 0
26
22
  }
27
- const result = spawnSync('bash', [script, app.id, destination], { cwd: app.root, env: childEnv, stdio: 'inherit' })
23
+ const result = spawnSync('bash', [script, app.id, destination, ...platformArg], { cwd: app.root, env: childEnv, stdio: 'inherit' })
28
24
  if (result.error) throw result.error
29
- if (result.status !== 0) throw new CliError(`iOS build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
25
+ if (result.status !== 0) throw new CliError(`${platformName} build failed (${result.status ?? 1}).`, ExitCode.deployFailed)
30
26
  return 0
31
27
  }
package/src/manifest.mjs CHANGED
@@ -161,7 +161,7 @@ export function assertTargetEnabled(ctx, app, targetOrPlatform) {
161
161
  fail(`App '${app.id}' does not enable target '${platform}'.`, ExitCode.targetUnavailable)
162
162
  }
163
163
 
164
- export const knownPlatforms = Object.freeze(['web', 'esp32', 'rp2350', 'geaos', 'raspberry-pi-os', 'macos', 'ios', 'android', 'windows', 'xbox', 'pebble'])
164
+ export const knownPlatforms = Object.freeze(['web', 'esp32', 'rp2350', 'geaos', 'raspberry-pi-os', 'macos', 'ios', 'tvos', 'android', 'windows', 'xbox', 'pebble'])
165
165
 
166
166
  export function appPlatformForTarget(ctx, targetOrBoard) {
167
167
  return appPlatformsForTarget(ctx, targetOrBoard)[0] || ''
@@ -416,7 +416,7 @@ export function normalizeDefines(raw) {
416
416
 
417
417
 
418
418
  function emptyTargetConfig() {
419
- return { nativeSources: [], providers: {}, tsconfig: '', nativeIncludeDirectories: [], nativeSystemLibraries: [], nativeResources: {}, nativeLibraries: [], frameworks: [], ldFragments: [], componentDirs: [], componentRequires: [], linkOptions: [], embedFiles: {}, partitions: null, partitionsByTarget: {}, sdkconfig: '', prebuild: '', output: '' }
419
+ 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: '' }
420
420
  }
421
421
 
422
422
  function normalizeStringList(raw) {
@@ -499,6 +499,13 @@ function normalizeTargetConfig(raw) {
499
499
  partitions: normalizePartitions(value.partitions),
500
500
  partitionsByTarget: normalizePartitionsByTarget(value.partitionsByTarget),
501
501
  sdkconfig: typeof value.sdkconfig === 'string' && value.sdkconfig.trim() ? normalizeManifestRelativePath(value.sdkconfig) : '',
502
+ // Board settings an app may overrule for itself: its PSRAM wiring and
503
+ // clock (merged over the board's `psram`), and the flash clock.
504
+ psram: value.psram && typeof value.psram === 'object' && !Array.isArray(value.psram) ? { ...value.psram } : null,
505
+ flashFreq: Number(value.flashFreq) || 0,
506
+ // How the RGB panel's repaints reach PSRAM, for apps that redraw the whole
507
+ // screen every frame (games): { copyBack: 'dma', bounceRows, gridStrips }.
508
+ display: value.display && typeof value.display === 'object' && !Array.isArray(value.display) ? { ...value.display } : null,
502
509
  prebuild: typeof value.prebuild === 'string' ? value.prebuild.trim() : '',
503
510
  output: typeof value.output === 'string' && value.output.trim() ? normalizeManifestRelativePath(value.output) : ''
504
511
  }