@geastack/cli 0.1.52 → 0.1.53

package/src/ble/ble-ota.swift

@@ -0,0 +1,291 @@
+#!/usr/bin/env swift
+
+import CoreBluetooth
+import Darwin
+import Foundation
+
+// `gea` runs this helper with stdout connected to a pipe. Disable stdio
+// buffering so discovery, transport selection, and percentage updates remain
+// visible during a long first update from older firmware.
+setbuf(stdout, nil)
+
+private let otaService = CBUUID(string: "7F2E1001-6D8F-4A4F-A0E9-5B8892140001")
+private let otaControl = CBUUID(string: "7F2E1001-6D8F-4A4F-A0E9-5B8892140002")
+private let otaData = CBUUID(string: "7F2E1001-6D8F-4A4F-A0E9-5B8892140003")
+
+private func u32le(_ value: UInt32) -> [UInt8] {
+    [
+        UInt8(truncatingIfNeeded: value),
+        UInt8(truncatingIfNeeded: value >> 8),
+        UInt8(truncatingIfNeeded: value >> 16),
+        UInt8(truncatingIfNeeded: value >> 24),
+    ]
+}
+
+private func readU32le(_ bytes: [UInt8], _ offset: Int) -> UInt32 {
+    UInt32(bytes[offset])
+        | (UInt32(bytes[offset + 1]) << 8)
+        | (UInt32(bytes[offset + 2]) << 16)
+        | (UInt32(bytes[offset + 3]) << 24)
+}
+
+private func controlPacket(opcode: UInt8, imageSize: UInt32? = nil) -> Data {
+    var bytes = [opcode]
+    if let imageSize { bytes.append(contentsOf: u32le(imageSize)) }
+    return Data(bytes)
+}
+
+private final class BleOtaUpdater: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
+    private let image: Data
+    private let deviceName: String
+    private let statusOnly: Bool
+    private var central: CBCentralManager!
+    private var peripheral: CBPeripheral?
+    private var controlCharacteristic: CBCharacteristic?
+    private var dataCharacteristic: CBCharacteristic?
+    private var offset = 0
+    private var lastPrintedPercent = -1
+    private var sentFinish = false
+    private var finished = false
+    private var timeout: Timer?
+    private var transferStartedAt: Date?
+
+    init(image: Data, deviceName: String, statusOnly: Bool = false) {
+        self.image = image
+        self.deviceName = deviceName
+        self.statusOnly = statusOnly
+        super.init()
+    }
+
+    func start() {
+        print("Looking for \(deviceName)…")
+        central = CBCentralManager(delegate: self, queue: .main)
+        // Give discovery, transfer, flash validation, and reboot a bounded
+        // window. Data always uses CoreBluetooth's no-response flow control.
+        let timeoutSeconds = statusOnly ? 30 : max(300, Double(image.count) / 2048)
+        timeout = Timer.scheduledTimer(withTimeInterval: timeoutSeconds, repeats: false) { [weak self] _ in
+            self?.fail("Timed out waiting for the BLE update to complete.")
+        }
+    }
+
+    func centralManagerDidUpdateState(_ central: CBCentralManager) {
+        guard central.state == .poweredOn else {
+            if central.state == .unsupported || central.state == .unauthorized || central.state == .poweredOff {
+                fail("Bluetooth is unavailable (state \(central.state.rawValue)).")
+            }
+            return
+        }
+        // Bonded BLE peripherals may already be connected by macOS (for example
+        // because the firmware exposes a battery service). Connected peripherals
+        // no longer produce scan results, so claim an existing OTA connection
+        // before starting discovery.
+        if let connected = central.retrieveConnectedPeripherals(withServices: [otaService]).first {
+            connect(connected, advertisedName: connected.name)
+            return
+        }
+        central.scanForPeripherals(withServices: nil, options: [CBCentralManagerScanOptionAllowDuplicatesKey: false])
+    }
+
+    private func connect(_ peripheral: CBPeripheral, advertisedName: String?) {
+        central.stopScan()
+        self.peripheral = peripheral
+        peripheral.delegate = self
+        print("Connecting to \(advertisedName ?? peripheral.name ?? deviceName)…")
+        central.connect(peripheral)
+    }
+
+    func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral,
+                        advertisementData: [String: Any], rssi RSSI: NSNumber) {
+        let advertisedName = advertisementData[CBAdvertisementDataLocalNameKey] as? String
+        let advertisedServices = advertisementData[CBAdvertisementDataServiceUUIDsKey] as? [CBUUID] ?? []
+        let nameMatches = peripheral.name?.localizedCaseInsensitiveContains(deviceName) == true
+            || advertisedName?.localizedCaseInsensitiveContains(deviceName) == true
+        guard nameMatches || advertisedServices.contains(otaService) else { return }
+
+        connect(peripheral, advertisedName: advertisedName)
+    }
+
+    func centralManager(_ central: CBCentralManager, didFailToConnect peripheral: CBPeripheral,
+                        error: Error?) {
+        fail("Could not connect: \(error?.localizedDescription ?? "unknown error")")
+    }
+
+    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral,
+                        error: Error?) {
+        if !finished { fail("The board disconnected before the update completed: \(error?.localizedDescription ?? "no reason reported")") }
+    }
+
+    func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
+        print("Connected. Discovering the OTA service…")
+        peripheral.discoverServices([otaService])
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
+        if let error { return fail("Service discovery failed: \(error.localizedDescription)") }
+        guard let service = peripheral.services?.first(where: { $0.uuid == otaService }) else {
+            return fail("The board does not expose the Geastack OTA service. Flash a BLE-OTA-enabled app over USB first.")
+        }
+        peripheral.discoverCharacteristics([otaControl, otaData], for: service)
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService,
+                    error: Error?) {
+        if let error { return fail("Characteristic discovery failed: \(error.localizedDescription)") }
+        for characteristic in service.characteristics ?? [] {
+            if characteristic.uuid == otaControl { controlCharacteristic = characteristic }
+            if characteristic.uuid == otaData { dataCharacteristic = characteristic }
+        }
+        guard let controlCharacteristic, dataCharacteristic != nil else {
+            return fail("The OTA service is incomplete on this firmware.")
+        }
+        peripheral.setNotifyValue(true, for: controlCharacteristic)
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didUpdateNotificationStateFor characteristic: CBCharacteristic,
+                    error: Error?) {
+        if let error { return fail("Could not subscribe to OTA status: \(error.localizedDescription)") }
+        guard characteristic.uuid == otaControl, characteristic.isNotifying else { return }
+        if statusOnly {
+            peripheral.writeValue(controlPacket(opcode: 0x05), for: characteristic, type: .withResponse)
+            return
+        }
+        guard image.count <= Int(UInt32.max) else { return fail("Firmware image is too large for the OTA protocol.") }
+        print("Starting encrypted transfer of \(image.count) bytes…")
+        transferStartedAt = Date()
+        peripheral.writeValue(controlPacket(opcode: 0x01, imageSize: UInt32(image.count)),
+                              for: characteristic, type: .withResponse)
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic,
+                    error: Error?) {
+        if let error { return fail("OTA status read failed: \(error.localizedDescription)") }
+        guard characteristic.uuid == otaControl, let value = characteristic.value else { return }
+        let bytes = [UInt8](value)
+        guard bytes.count == 10 || bytes.count == 18 else { return fail("The board returned a malformed OTA status packet.") }
+        let opcode = bytes[0]
+        if opcode == 0x85 {
+            let error = Int32(bitPattern: readU32le(bytes, 2))
+            finished = true
+            timeout?.invalidate()
+            var details = "Wi-Fi BLE status: state=\(bytes[1]) error=\(error) enabled=\(bytes[6]) connected=\(bytes[7])"
+            if bytes.count == 18 && bytes[9] == 0xa5 {
+                let otaError = Int32(bitPattern: readU32le(bytes, 10))
+                details += " ota-started=\(bytes[8]) ota-error=\(otaError) live-dma-free=\(readU32le(bytes, 14))"
+            } else if bytes.count == 18 {
+                details += " dma-free=\(readU32le(bytes, 10)) dma-largest=\(readU32le(bytes, 14))"
+            }
+            print(details)
+            exit(EXIT_SUCCESS)
+        }
+        let result = bytes[1]
+        let received = readU32le(bytes, 2)
+        let expected = readU32le(bytes, 6)
+        guard result == 0 else {
+            return fail("The board rejected OTA command 0x\(String(opcode & 0x7f, radix: 16)) (result \(result), \(received)/\(expected) bytes).")
+        }
+
+        if opcode == 0x81 {
+            sendNextChunk(peripheral)
+        } else if opcode == 0x82 {
+            guard received == 0 && expected == 0 else {
+                return fail("The board completed OTA with unexpected residual state \(received)/\(expected).")
+            }
+            finished = true
+            timeout?.invalidate()
+            let elapsed = max(0.001, Date().timeIntervalSince(transferStartedAt ?? Date()))
+            let kibPerSecond = Double(image.count) / elapsed / 1024
+            let mibPerSecond = kibPerSecond / 1024
+            print(String(format: "BLE OTA complete in %.2fs (%.3f MiB/s, %.1f KiB/s). The board is rebooting into the new firmware.", elapsed, mibPerSecond, kibPerSecond))
+            exit(EXIT_SUCCESS)
+        }
+    }
+
+    func peripheral(_ peripheral: CBPeripheral, didWriteValueFor characteristic: CBCharacteristic,
+                    error: Error?) {
+        if let error { return fail("BLE write failed: \(error.localizedDescription)") }
+    }
+
+    func peripheralIsReady(toSendWriteWithoutResponse peripheral: CBPeripheral) {
+        sendNextChunk(peripheral)
+    }
+
+    private func sendNextChunk(_ peripheral: CBPeripheral) {
+        guard let dataCharacteristic, let controlCharacteristic else { return }
+        if offset == image.count {
+            guard !sentFinish else { return }
+            sentFinish = true
+            print("\nValidating firmware…")
+            peripheral.writeValue(controlPacket(opcode: 0x02), for: controlCharacteristic, type: .withResponse)
+            return
+        }
+        // OTA has its own BEGIN/FINISH control acknowledgements. Sending DATA as
+        // ATT write commands is correct even when a bonded CoreBluetooth cache
+        // still reports the flags from older firmware; waiting for an ATT write
+        // response per chunk makes a full image take many minutes.
+        let writeType: CBCharacteristicWriteType = .withoutResponse
+        let maximum = min(512, peripheral.maximumWriteValueLength(for: writeType))
+        guard maximum > 0 else { return fail("CoreBluetooth reported an invalid write size.") }
+        if offset == 0 {
+            print("BLE OTA data: write without response, \(maximum)-byte chunks")
+        }
+        while offset < image.count && peripheral.canSendWriteWithoutResponse {
+            let length = min(maximum, image.count - offset)
+            let chunk = image.subdata(in: offset..<(offset + length))
+            peripheral.writeValue(chunk, for: dataCharacteristic, type: writeType)
+            offset += length
+            printProgress()
+        }
+        if offset == image.count { sendNextChunk(peripheral) }
+    }
+
+    private func printProgress() {
+        let percent = image.isEmpty ? 100 : (offset * 100 / image.count)
+        guard percent != lastPrintedPercent else { return }
+        lastPrintedPercent = percent
+        print("Transferred \(offset)/\(image.count) bytes (\(percent)%)")
+    }
+
+    private func fail(_ message: String) {
+        guard !finished else { return }
+        finished = true
+        timeout?.invalidate()
+        if let peripheral, let controlCharacteristic {
+            peripheral.writeValue(controlPacket(opcode: 0x03), for: controlCharacteristic, type: .withResponse)
+        }
+        fputs("ERROR: \(message)\n", stderr)
+        exit(EXIT_FAILURE)
+    }
+}
+
+if CommandLine.arguments.dropFirst().first == "--self-test" {
+    precondition([UInt8](controlPacket(opcode: 0x01, imageSize: 0x78563412)) == [1, 0x12, 0x34, 0x56, 0x78])
+    precondition(readU32le([0, 0, 0x12, 0x34, 0x56, 0x78], 2) == 0x78563412)
+    print("BLE OTA protocol self-test passed")
+    exit(EXIT_SUCCESS)
+}
+
+private let updater: BleOtaUpdater = {
+    let arguments = Array(CommandLine.arguments.dropFirst())
+    if arguments.first == "--wifi-status" {
+        guard arguments.count <= 2 else {
+            fputs("Usage: ble-ota.swift --wifi-status [device name]\n", stderr)
+            exit(EXIT_FAILURE)
+        }
+        return BleOtaUpdater(
+            image: Data(),
+            deviceName: arguments.count == 2 ? arguments[1] : "Geastack OTA",
+            statusOnly: true)
+    }
+    guard arguments.count == 1 || arguments.count == 2 else {
+        fputs("Usage: ble-ota.swift <firmware.bin> [device name]\n", stderr)
+        exit(EXIT_FAILURE)
+    }
+    let imagePath = arguments[0]
+    guard let image = FileManager.default.contents(atPath: imagePath), !image.isEmpty else {
+        fputs("ERROR: Could not read firmware image at \(imagePath)\n", stderr)
+        exit(EXIT_FAILURE)
+    }
+    return BleOtaUpdater(image: image, deviceName: arguments.count == 2 ? arguments[1] : "Geastack OTA")
+}()
+updater.start()
+RunLoop.main.run()

package/src/boards/config.mjs

@@ -0,0 +1,32 @@
+import path from 'node:path'
+
+import { ExitCode, fail } from '../errors.mjs'
+import { exists, readJson } from '../fs-utils.mjs'
+
+// Board aliases: an explicit --boards-config, else the project's
+// .gea/boards.json, else the boards.json shipped by @geastack/targets.
+export function boardConfigPath(ctx) {
+  if (ctx.boardsConfig) return ctx.boardsConfig
+  if (ctx.projectBoardsConfig && exists(ctx.projectBoardsConfig)) return ctx.projectBoardsConfig
+  return ctx.targetsRoot ? path.join(ctx.targetsRoot, 'boards.json') : ''
+}
+
+export function loadBoardConfig(ctx) {
+  const file = boardConfigPath(ctx)
+  if (!file || !exists(file)) return {}
+  try {
+    return normalizeBoardConfig(readJson(file))
+  } catch (error) {
+    fail(`Could not read board config ${file}: ${error.message}`, ExitCode.usage)
+  }
+}
+
+export function normalizeBoardConfig(raw) {
+  if (!raw || typeof raw !== 'object') return {}
+  if (raw.boards && typeof raw.boards === 'object') return raw.boards
+  const out = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (!key.startsWith('$') && value && typeof value === 'object') out[key] = value
+  }
+  return out
+}

package/src/boards/custom-target.mjs

@@ -0,0 +1,309 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// A composed board: a JSON definition (chips from @geastack/chips plus pins
+// and buses) that extends a built-in base target. The CLI turns it into a
+// generated board.h + target.cmake inside the app's build directory before
+// IDF configures, so the target project only ever includes generated files.
+
+const supportedBase = 'esp32-s3'
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object.`)
+  return value
+}
+
+function text(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} must be a non-empty string.`)
+  return value.trim()
+}
+
+function integer(value, label, { min = 0, max = 48 } = {}) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`${label} must be an integer from ${min} through ${max}.`)
+  }
+  return value
+}
+
+function pin(value, label, { optional = false } = {}) {
+  if (optional && (value === null || value === undefined || value === 'none')) return -1
+  return integer(value, label)
+}
+
+function exact(value, expected, label) {
+  const actual = text(value, label).toLowerCase()
+  if (actual !== expected) {
+    throw new Error(`${label} '${actual}' is not supported by the ${supportedBase} base. Supported value: ${expected}.`)
+  }
+  return actual
+}
+
+export function loadChipCatalogFromDir(chipsDir) {
+  const packageDir = text(chipsDir, 'chips package directory')
+  const catalogPath = path.join(packageDir, 'catalog.json')
+  if (!existsSync(catalogPath)) throw new Error(`Chip catalog not found: ${catalogPath}`)
+  const catalog = object(JSON.parse(readFileSync(catalogPath, 'utf8')), 'Chip catalog')
+  if (catalog.schemaVersion !== 1) throw new Error(`Unsupported chip catalog schema: ${catalog.schemaVersion}`)
+  return object(catalog.chips, 'Chip catalog entries')
+}
+
+function selectedChip(chips, role, category, adapter, mcu, catalog) {
+  const selection = object(chips[role], `chips.${role}`)
+  const driver = text(selection.driver || selection.controller, `chips.${role}.driver`).toLowerCase()
+  const descriptor = object(catalog[driver], `Catalog entry for '${driver}'`)
+  if (descriptor.category !== category) {
+    throw new Error(`Chip '${driver}' is a ${descriptor.category}, so it cannot fill the ${role} role.`)
+  }
+  const interfaceName = text(selection.interface, `chips.${role}.interface`).toLowerCase()
+  if (!Array.isArray(descriptor.interfaces) || !descriptor.interfaces.includes(interfaceName)) {
+    throw new Error(`Chip '${driver}' does not support the '${interfaceName}' interface.`)
+  }
+  const adapterInfo = descriptor.adapters?.[adapter]
+  if (!adapterInfo) throw new Error(`Chip '${driver}' has no ${adapter} binding in the installed catalog.`)
+  if (Array.isArray(adapterInfo.mcus) && !adapterInfo.mcus.includes(mcu)) {
+    throw new Error(`Chip '${driver}' does not support MCU '${mcu}' through ${adapter}.`)
+  }
+  return {
+    ...selection,
+    driver,
+    interface: interfaceName,
+    nativeSources: Array.isArray(descriptor.sources) ? descriptor.sources : [],
+    bindingSources: Array.isArray(adapterInfo.bindingSources) ? adapterInfo.bindingSources : []
+  }
+}
+
+export function normalizeCustomTarget(raw, catalog) {
+  const definition = object(raw, 'Target definition')
+  const id = text(definition.id, 'id')
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) throw new Error('id may contain lowercase letters, digits, dots, underscores, and hyphens.')
+  const base = exact(definition.extends, supportedBase, 'extends')
+  const mcu = exact(definition.mcu, 'esp32s3', 'mcu')
+  const adapter = definition.adapter ? exact(definition.adapter, 'esp32-idf', 'adapter') : 'esp32-idf'
+  const chips = object(definition.chips, 'chips')
+  const display = object(selectedChip(chips, 'display', 'display', adapter, mcu, catalog), 'chips.display')
+  const touch = object(selectedChip(chips, 'touch', 'touch', adapter, mcu, catalog), 'chips.touch')
+  const power = object(selectedChip(chips, 'power', 'power', adapter, mcu, catalog), 'chips.power')
+  const imu = object(selectedChip(chips, 'imu', 'imu', adapter, mcu, catalog), 'chips.imu')
+  const audio = object(selectedChip(chips, 'audio', 'audio', adapter, mcu, catalog), 'chips.audio')
+  const buses = object(definition.buses, 'buses')
+  const i2c = object(buses.i2c, 'buses.i2c')
+  const storage = object(definition.storage, 'storage')
+  const microSD = object(storage.microSD, 'storage.microSD')
+  const controls = object(definition.controls, 'controls')
+  const launcherButton = object(controls.launcherButton, 'controls.launcherButton')
+
+  const displayPins = object(display.pins, 'chips.display.pins')
+  const touchPins = object(touch.pins, 'chips.touch.pins')
+  const audioPins = object(audio.pins, 'chips.audio.pins')
+  const storagePins = object(microSD.pins, 'storage.microSD.pins')
+
+  const spiHost = String(display.spiHost).toLowerCase()
+  if (!['spi2', 'spi3'].includes(spiHost)) throw new Error("chips.display.spiHost must be 'spi2' or 'spi3'.")
+
+  const target = {
+    id,
+    extends: base,
+    adapter,
+    mcu,
+    buses: {
+      i2c: {
+        sda: pin(i2c.sda, 'buses.i2c.sda'),
+        scl: pin(i2c.scl, 'buses.i2c.scl')
+      }
+    },
+    chips: {
+      display: {
+        driver: display.driver,
+        interface: exact(display.interface, 'qspi', 'chips.display.interface'),
+        width: integer(display.width, 'chips.display.width', { min: 1, max: 4096 }),
+        height: integer(display.height, 'chips.display.height', { min: 1, max: 4096 }),
+        spiHost,
+        nativeSources: display.nativeSources,
+        bindingSources: display.bindingSources,
+        pins: {
+          cs: pin(displayPins.cs, 'chips.display.pins.cs'),
+          pclk: pin(displayPins.pclk, 'chips.display.pins.pclk'),
+          data0: pin(displayPins.data0, 'chips.display.pins.data0'),
+          data1: pin(displayPins.data1, 'chips.display.pins.data1'),
+          data2: pin(displayPins.data2, 'chips.display.pins.data2'),
+          data3: pin(displayPins.data3, 'chips.display.pins.data3'),
+          reset: pin(displayPins.reset, 'chips.display.pins.reset'),
+          te: pin(displayPins.te, 'chips.display.pins.te', { optional: true })
+        }
+      },
+      touch: {
+        driver: touch.driver,
+        interface: exact(touch.interface, 'i2c', 'chips.touch.interface'),
+        nativeSources: touch.nativeSources,
+        bindingSources: touch.bindingSources,
+        pins: {
+          reset: pin(touchPins.reset, 'chips.touch.pins.reset'),
+          interrupt: pin(touchPins.interrupt, 'chips.touch.pins.interrupt')
+        }
+      },
+      power: {
+        driver: power.driver,
+        interface: exact(power.interface, 'i2c', 'chips.power.interface'),
+        nativeSources: power.nativeSources,
+        bindingSources: power.bindingSources
+      },
+      imu: {
+        driver: imu.driver,
+        interface: exact(imu.interface, 'i2c', 'chips.imu.interface'),
+        nativeSources: imu.nativeSources,
+        bindingSources: imu.bindingSources
+      },
+      audio: {
+        driver: audio.driver,
+        interface: exact(audio.interface, 'i2s', 'chips.audio.interface'),
+        nativeSources: audio.nativeSources,
+        bindingSources: audio.bindingSources,
+        pins: {
+          mclk: pin(audioPins.mclk, 'chips.audio.pins.mclk'),
+          bclk: pin(audioPins.bclk, 'chips.audio.pins.bclk'),
+          ws: pin(audioPins.ws, 'chips.audio.pins.ws'),
+          dout: pin(audioPins.dout, 'chips.audio.pins.dout'),
+          din: pin(audioPins.din, 'chips.audio.pins.din'),
+          powerAmplifier: pin(audioPins.powerAmplifier, 'chips.audio.pins.powerAmplifier')
+        }
+      }
+    },
+    storage: {
+      microSD: {
+        interface: exact(microSD.interface, 'sdmmc-1bit', 'storage.microSD.interface'),
+        pins: {
+          clk: pin(storagePins.clk, 'storage.microSD.pins.clk', { optional: true }),
+          cmd: pin(storagePins.cmd, 'storage.microSD.pins.cmd', { optional: true }),
+          data0: pin(storagePins.data0, 'storage.microSD.pins.data0', { optional: true })
+        }
+      }
+    },
+    controls: {
+      launcherButton: {
+        pin: pin(launcherButton.pin, 'controls.launcherButton.pin', { optional: true }),
+        activeLevel: integer(launcherButton.activeLevel, 'controls.launcherButton.activeLevel', { min: 0, max: 1 })
+      }
+    }
+  }
+  validatePinAssignments(target)
+  return target
+}
+
+function validatePinAssignments(target) {
+  const pins = [
+    ['I2C SDA', target.buses.i2c.sda],
+    ['I2C SCL', target.buses.i2c.scl],
+    ['display CS', target.chips.display.pins.cs],
+    ['display PCLK', target.chips.display.pins.pclk],
+    ['display DATA0', target.chips.display.pins.data0],
+    ['display DATA1', target.chips.display.pins.data1],
+    ['display DATA2', target.chips.display.pins.data2],
+    ['display DATA3', target.chips.display.pins.data3],
+    ['display reset', target.chips.display.pins.reset],
+    ['display TE', target.chips.display.pins.te],
+    ['touch reset', target.chips.touch.pins.reset],
+    ['touch interrupt', target.chips.touch.pins.interrupt],
+    ['audio MCLK', target.chips.audio.pins.mclk],
+    ['audio BCLK', target.chips.audio.pins.bclk],
+    ['audio WS', target.chips.audio.pins.ws],
+    ['audio DOUT', target.chips.audio.pins.dout],
+    ['audio DIN', target.chips.audio.pins.din],
+    ['audio amplifier', target.chips.audio.pins.powerAmplifier],
+    ['microSD CLK', target.storage.microSD.pins.clk],
+    ['microSD CMD', target.storage.microSD.pins.cmd],
+    ['microSD DATA0', target.storage.microSD.pins.data0],
+    ['launcher button', target.controls.launcherButton.pin]
+  ]
+  const used = new Map()
+  for (const [label, value] of pins) {
+    if (value < 0) continue
+    const previous = used.get(value)
+    if (previous) throw new Error(`GPIO ${value} is assigned to both ${previous} and ${label}.`)
+    used.set(value, label)
+  }
+}
+
+function gpio(value) {
+  return value < 0 ? 'GPIO_NUM_NC' : `GPIO_NUM_${value}`
+}
+
+export function renderBoardHeader(target) {
+  const { i2c } = target.buses
+  const { display, touch, audio } = target.chips
+  const sd = target.storage.microSD
+  const launcher = target.controls.launcherButton
+  return `#pragma once
+
+#include "driver/gpio.h"
+#include "driver/i2s_types.h"
+#include "driver/spi_master.h"
+
+namespace gea::platform::board {
+
+struct I2cBusConfig { gpio_num_t sda; gpio_num_t scl; };
+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; };
+struct Ft3168TouchConfig { gpio_num_t reset; gpio_num_t interrupt; };
+struct 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; };
+struct SdMmcConfig { gpio_num_t clk; gpio_num_t cmd; gpio_num_t data0; };
+struct LauncherButtonConfig { gpio_num_t pin; int activeLevel; };
+
+inline constexpr I2cBusConfig i2c{ .sda = ${gpio(i2c.sda)}, .scl = ${gpio(i2c.scl)} };
+inline constexpr Co5300DisplayConfig display{
+  .spiHost = ${display.spiHost === 'spi3' ? 'SPI3_HOST' : 'SPI2_HOST'}, .cs = ${gpio(display.pins.cs)}, .pclk = ${gpio(display.pins.pclk)},
+  .data0 = ${gpio(display.pins.data0)}, .data1 = ${gpio(display.pins.data1)},
+  .data2 = ${gpio(display.pins.data2)}, .data3 = ${gpio(display.pins.data3)},
+  .reset = ${gpio(display.pins.reset)}, .te = ${gpio(display.pins.te)}
+};
+inline constexpr Ft3168TouchConfig touch{ .reset = ${gpio(touch.pins.reset)}, .interrupt = ${gpio(touch.pins.interrupt)} };
+inline constexpr Es8311AudioConfig audio{
+  .i2sPort = I2S_NUM_AUTO, .mclk = ${gpio(audio.pins.mclk)}, .bclk = ${gpio(audio.pins.bclk)},
+  .ws = ${gpio(audio.pins.ws)}, .dout = ${gpio(audio.pins.dout)}, .din = ${gpio(audio.pins.din)},
+  .powerAmplifier = ${gpio(audio.pins.powerAmplifier)}
+};
+inline constexpr SdMmcConfig storage{ .clk = ${gpio(sd.pins.clk)}, .cmd = ${gpio(sd.pins.cmd)}, .data0 = ${gpio(sd.pins.data0)} };
+inline constexpr LauncherButtonConfig launcherButton{ .pin = ${gpio(launcher.pin)}, .activeLevel = ${launcher.activeLevel} };
+
+}  // namespace gea::platform::board
+`
+}
+
+function cmakeQuote(value) {
+  return `"${String(value).replace(/\\/g, '/').replace(/"/g, '\\"')}"`
+}
+
+export function renderTargetCmake(target, includeDir) {
+  const { display, touch, power, imu, audio } = target.chips
+  const chipSource = (source) => `    "\${GEA_CHIPS}/${source}"`
+  const bindingSource = (source) => `    "\${GEA_EMBEDDED_ROOT}/targets/esp32/${source}"`
+  const displaySources = [...display.nativeSources.map(chipSource), ...display.bindingSources.map(bindingSource)]
+  const peripheralSources = [power, imu, touch, audio]
+    .flatMap((chip) => [...chip.nativeSources.map(chipSource), ...chip.bindingSources.map(bindingSource)])
+  return `set(GEA_CUSTOM_TARGET_ACTIVE 1)
+set(GEA_CUSTOM_TARGET_INCLUDE_DIR ${cmakeQuote(includeDir)})
+set(GEA_CUSTOM_TARGET_DISPLAY_SOURCES
+${displaySources.join('\n')}
+)
+set(GEA_CUSTOM_TARGET_PERIPHERAL_SOURCES
+${peripheralSources.join('\n')}
+)
+set(GEA_CUSTOM_TARGET_COMPILE_DEFINITIONS
+    GEA_EMBEDDED_DISPLAY_WIDTH=${display.width}
+    GEA_EMBEDDED_DISPLAY_HEIGHT=${display.height}
+)
+`
+}
+
+export function writeCustomTarget({ definitionPath, outDir, catalog }) {
+  const target = normalizeCustomTarget(JSON.parse(readFileSync(definitionPath, 'utf8')), catalog)
+  mkdirSync(outDir, { recursive: true })
+  const headerPath = path.join(outDir, 'board.h')
+  const cmakePath = path.join(outDir, 'target.cmake')
+  writeIfChanged(headerPath, renderBoardHeader(target))
+  writeIfChanged(cmakePath, renderTargetCmake(target, outDir))
+  return { target, headerPath, cmakePath }
+}
+
+function writeIfChanged(file, contents) {
+  if (existsSync(file) && readFileSync(file, 'utf8') === contents) return
+  writeFileSync(file, contents)
+}