ShiboSoftwareDev/linux-gameboy-advance

scripts/verify.mjs

import assert from "node:assert/strict"
import fs from "node:fs"

const circuitPath = "dist/index/circuit.json"
const circuit = JSON.parse(fs.readFileSync(circuitPath, "utf8"))
const of = (type) => circuit.filter((record) => record.type === type)
const nearly = (actual, expected, tolerance = 1e-6) =>
  Math.abs(actual - expected) <= tolerance
const pointToSegmentDistance = (point, start, end) => {
  const dx = end.x - start.x
  const dy = end.y - start.y
  const lengthSquared = dx * dx + dy * dy
  const position = lengthSquared === 0 ? 0 : Math.max(0, Math.min(1,
    ((point.x - start.x) * dx + (point.y - start.y) * dy) / lengthSquared))
  return Math.hypot(point.x - (start.x + position * dx), point.y - (start.y + position * dy))
}

const errors = circuit.filter((record) => record.type.endsWith("_error"))
assert.equal(errors.length, 0, `expected zero emitted DRC/electrical errors; got ${errors.length}`)

const board = of("pcb_board")[0]
assert.ok(board, "PCB board exists")
assert.equal(board.num_layers, 4, "four copper layers")
assert.ok(board.outline?.length >= 4, "custom board outline is present")
assert.ok(nearly(board.width, 144.5) && nearly(board.height, 82), "144.5 x 82 mm envelope")
assert.ok(nearly(board.min_via_hole_diameter, 0.3), "board via drill rule is 0.30 mm")
assert.ok(nearly(board.min_via_pad_diameter, 0.45), "board via pad rule is 0.45 mm")
assert.ok(nearly(board.min_via_hole_edge_to_via_hole_edge_clearance, 0.2), "finished-hole spacing rule is 0.20 mm")

const cutouts = of("pcb_cutout")
assert.equal(cutouts.length, 1, "one battery-cable edge cutout exists")
const batteryCableCutout = cutouts[0]
assert.equal(batteryCableCutout.shape, "polygon", "battery-cable cutout uses fabrication-safe outline geometry")
assert.ok(batteryCableCutout.points.length >= 15, "battery-cable cutout has a rounded closed end")
const cutoutXs = batteryCableCutout.points.map(({ x }) => x)
const cutoutYs = batteryCableCutout.points.map(({ y }) => y)
const cutoutBounds = {
  minX: Math.min(...cutoutXs), maxX: Math.max(...cutoutXs),
  minY: Math.min(...cutoutYs), maxY: Math.max(...cutoutYs),
}
assert.ok(nearly(cutoutBounds.maxX - cutoutBounds.minX, 5), "battery-cable cutout is 5 mm wide")
assert.ok(nearly(cutoutBounds.maxY - cutoutBounds.minY, 11), "battery-cable cutout is 11 mm long")
const boardBottomY = Math.min(...board.outline.map(({ y }) => y))
assert.ok(cutoutBounds.minY < boardBottomY && nearly(cutoutBounds.maxY - boardBottomY, 9.5),
  "battery-cable cutout opens through the bottom edge and extends 9.5 mm into the PCB")

const vias = of("pcb_via")
assert.ok(vias.length > 0, "routed board contains vias")
for (const via of vias) {
  assert.ok(nearly(via.hole_diameter, 0.3), `${via.pcb_via_id}: drill is exactly 0.30 mm`)
  assert.ok(nearly(via.outer_diameter, 0.45), `${via.pcb_via_id}: pad is exactly 0.45 mm`)
}

let minimumFinishedHoleGap = Infinity
let closestViaPair = []
for (let index = 0; index < vias.length; index++) {
  for (let other = index + 1; other < vias.length; other++) {
    const a = vias[index]
    const b = vias[other]
    const centerDistance = Math.hypot(a.x - b.x, a.y - b.y)
    const gap = centerDistance - a.hole_diameter / 2 - b.hole_diameter / 2
    if (gap < minimumFinishedHoleGap) {
      minimumFinishedHoleGap = gap
      closestViaPair = [a.pcb_via_id, b.pcb_via_id]
    }
  }
}
assert.ok(minimumFinishedHoleGap >= 0.2 - 1e-6,
  `minimum via finished-hole gap ${minimumFinishedHoleGap.toFixed(6)} mm is at least 0.20 mm`)

// Regression for the fabrication review's exact failure: the former via at
// (8.399, 11.013) had only 0.177 mm from its finished-hole edge to an inner2
// module trace. Its repaired position must retain JLCPCB's 0.20 mm minimum.
const reviewedVia = vias.find((via) => via.pcb_via_id === "pcb_via_385")
assert.ok(reviewedVia, "reviewed V3V3 transition via exists")
let reviewedViaCopperGap = Infinity
let reviewedViaNearestTrace = null
for (const trace of of("pcb_trace")) {
  if (trace.pcb_trace_id === reviewedVia.pcb_trace_id ||
      trace.subcircuit_connectivity_map_key === reviewedVia.subcircuit_connectivity_map_key) continue
  for (let index = 1; index < (trace.route?.length ?? 0); index++) {
    const start = trace.route[index - 1]
    const end = trace.route[index]
    if (start.route_type !== "wire" || end.route_type !== "wire") continue
    const gap = pointToSegmentDistance(reviewedVia, start, end) -
      reviewedVia.hole_diameter / 2 - Math.max(start.width, end.width) / 2
    if (gap < reviewedViaCopperGap) {
      reviewedViaCopperGap = gap
      reviewedViaNearestTrace = trace.pcb_trace_id
    }
  }
}
assert.ok(reviewedViaCopperGap >= 0.2 - 1e-6,
  `reviewed via finished-hole-to-copper gap ${reviewedViaCopperGap.toFixed(3)} mm is at least 0.20 mm`)

const sourceComponents = of("source_component")
const sourceById = new Map(sourceComponents.map((component) => [component.source_component_id, component]))
const pcbComponents = of("pcb_component")
const fitted = pcbComponents
  .map((pcb) => ({ pcb, source: sourceById.get(pcb.source_component_id) }))
  .filter(({ pcb, source }) => source && !pcb.do_not_place && source.ftype !== "simple_test_point")
const missingJlcpcb = fitted
  .filter(({ source }) => !source.supplier_part_numbers?.jlcpcb?.some((id) => /^C\d+$/.test(id)))
  .map(({ source }) => source.name)
assert.deepEqual(missingJlcpcb, [], `all fitted parts have explicit JLCPCB/LCSC IDs: ${missingJlcpcb.join(", ")}`)

const uniqueJlcpcbParts = new Set(fitted.flatMap(({ source }) => source.supplier_part_numbers.jlcpcb))
const componentByName = new Map(sourceComponents.map((component) => [component.name, component]))
const pcbByName = new Map(pcbComponents.map((pcb) => [sourceById.get(pcb.source_component_id)?.name, pcb]))
const cadByName = new Map(of("cad_component").map((cad) => [sourceById.get(cad.source_component_id)?.name, cad]))
for (const name of [
  "U1", "J_LCD", "J_SD", "U_FLASH", "U_IO", "J_USB", "J_BAT",
  "U_BUCK_3V3", "U_2V5", "U_1V2", "U_2V8", "U_SPK_AMP", "J_SPK",
  "J_UART", "J_I2C", "J_SPI",
  "U_LCD_BL", "L_LCD_BL", "D_LCD_BL", "C_LCD_BL_IN", "C_LCD_BL_OUT",
  "R_LCD_BL_SET_A", "R_LCD_BL_SET_B",
]) assert.ok(componentByName.has(name), `critical component ${name} exists`)

const hasRenderableCad = (cad) => Boolean(cad && (
  cad.model_step_url || cad.model_obj_url || cad.jscad || cad.footprinter_string
)) && !cad.show_as_bounding_box
const missingCadModels = fitted
  .filter(({ source }) => !hasRenderableCad(cadByName.get(source.name)))
  .map(({ source }) => source.name)
assert.deepEqual(missingCadModels, [],
  `every fitted PCB part has a renderable non-placeholder 3D model: ${missingCadModels.join(", ")}`)

assert.equal(componentByName.get("U_LCD_BL").manufacturer_part_number, "AP3031KTR-G1",
  "LCD uses a regulated AP3031 boost/current driver")
assert.deepEqual(componentByName.get("U_LCD_BL").supplier_part_numbers.jlcpcb, ["C82636"],
  "LCD current driver has an explicit JLCPCB part")
assert.deepEqual(componentByName.get("L_LCD_BL").supplier_part_numbers.jlcpcb, ["C2997603"],
  "LCD boost inductor has an explicit JLCPCB part")
assert.deepEqual(componentByName.get("D_LCD_BL").supplier_part_numbers.jlcpcb, ["C5444012"],
  "LCD boost diode has an explicit JLCPCB part")
for (const name of ["R_LCD_BL_SET_A", "R_LCD_BL_SET_B"]) {
  assert.ok(nearly(componentByName.get(name).resistance, 1), `${name} is 1 ohm`)
  assert.deepEqual(componentByName.get(name).supplier_part_numbers.jlcpcb, ["C17928"],
    `${name} has an explicit JLCPCB part`)
  assert.equal(pcbByName.get(name).layer, "bottom", `${name} is on the bottom side`)
}
const lcdBacklightCurrentMa = 0.2 / (1 + 1) * 1000
assert.ok(nearly(lcdBacklightCurrentMa, 100), "AP3031 sense network regulates the LCD backlight to 100 mA")

const expectedButtons = ["UP", "DOWN", "LEFT", "RIGHT", "A", "B", "X", "Y", "SELECT", "START", "L", "R"]
for (const label of expectedButtons)
  assert.ok(componentByName.has(`SW_${label}`), `${label} control exists`)
assert.equal(sourceComponents.filter((component) => component.name?.startsWith("SW_")).length, 13,
  "twelve game controls plus reset switch")

const placement = (name, x, y, rotation) => {
  const pcb = pcbByName.get(name)
  assert.ok(pcb, `${name} has a PCB placement`)
  assert.ok(nearly(pcb.center.x, x) && nearly(pcb.center.y, y), `${name} placement is ${x}, ${y}`)
  assert.ok(nearly(pcb.rotation, rotation), `${name} rotation is ${rotation} degrees`)
}

placement("SW_SELECT", -52, -19, 0)
placement("SW_START", 52, -19, 0)
for (const name of ["SW_SELECT", "SW_START"])
  assert.deepEqual(componentByName.get(name).supplier_part_numbers.jlcpcb, ["C18186519"],
    `${name} uses the same long-plunger JLC button as the reference Game Boy`)
placement("SW_L", -45, 36.65593325, 0)
placement("SW_R", 45, 36.65593325, 0)
for (const name of ["SW_L", "SW_R"]) {
  assert.deepEqual(componentByName.get(name).supplier_part_numbers.jlcpcb, ["C33543626"],
    `${name} is the long-stem variant of the original low-profile shoulder-switch family`)
  assert.match(cadByName.get(name)?.model_step_url ?? "", /C33543626\.step/,
    `${name} has the real JLC 3D model`)
}
const shoulderBoardEdgeY = 41
const shoulderBodyEdgeY = 36.65593325 + 4.34406675
const shoulderActuatorTipY = 36.65593325 + 13.95999875
assert.ok(Math.abs(shoulderBodyEdgeY - shoulderBoardEdgeY) < 0.01,
  "shoulder switch housings finish flush with the top board edge")
assert.ok(shoulderActuatorTipY - shoulderBoardEdgeY >= 9.6 - 1e-6,
  "shoulder actuators extend at least 9.6 mm beyond the top board edge")

placement("J_LCD", 40.8, 15, 270)
placement("J_SD", 58.5, 22, 90)
placement("JP_BOOT", -55, 23, 0)
placement("J_BAT", -40, -37.4, 270)
placement("J_PWR_SW", -61.5, -32.5, 270)
placement("J_UART", -18, 37, 180)
placement("J_I2C", -28, 37, 180)
placement("J_SPI", 22, 37, 180)
for (const name of ["J_UART", "J_I2C", "J_SPI"])
  assert.equal(pcbByName.get(name).layer, "bottom", `${name} is on the bottom-side rear service edge`)

const microSdBayEdgeX = board.outline
  .filter(({ x, y }) => x > 0 && y >= 12 && y <= 30)
  .reduce((nearest, { x }) => Math.min(nearest, x), Infinity)
const microSdFootprintRightX = pcbByName.get("J_SD").center.x + pcbByName.get("J_SD").width / 2
const microSdEdgeClearanceMm = microSdBayEdgeX - microSdFootprintRightX
assert.ok(nearly(microSdBayEdgeX, 65), "microSD access bay pulls the right PCB edge in to x=65 mm")
assert.ok(microSdEdgeClearanceMm >= 0.3 && microSdEdgeClearanceMm <= 0.5,
  "microSD socket is within 0.3-0.5 mm of its recessed board edge")

const powerFootprintBottomY = pcbByName.get("J_PWR_SW").center.y - pcbByName.get("J_PWR_SW").height / 2
const powerSwitchEdgeRecessMm = powerFootprintBottomY - boardBottomY
assert.ok(powerSwitchEdgeRecessMm >= 7,
  "power switch is recessed behind the lower-left enclosure wall instead of being directly exposed")
assert.ok(Math.abs(pcbByName.get("J_BAT").center.y - boardBottomY) < 5,
  "battery connector is beside the bottom cable cutout")
const landscapePanelHalfWidthMm = 84.96 / 2
const bootHeaderRightEdge = pcbByName.get("JP_BOOT").center.x + pcbByName.get("JP_BOOT").width / 2
assert.ok(bootHeaderRightEdge < -landscapePanelHalfWidthMm,
  "boot header is fully outside the landscape LCD module envelope")
const batteryConnectorCourtyardRightX = pcbByName.get("J_BAT").center.x + 6.5492
const batteryCableBendCorridorMm = cutoutBounds.minX - batteryConnectorCourtyardRightX
assert.ok(batteryCableBendCorridorMm >= 5.9,
  "battery connector leaves at least 5.9 mm for the cable to bend before the cutout")

assert.match(cadByName.get("U1")?.model_step_url ?? "", /C1511928\.step/,
  "F1C100S uses the real JLC 3D model")
assert.match(cadByName.get("U_FLASH")?.model_step_url ?? "", /C97521\.step/,
  "SPI flash uses the real JLC 3D model")
assert.equal(cadByName.get("U1")?.show_as_bounding_box, undefined, "F1C100S is not a placeholder box")
assert.equal(cadByName.get("U_FLASH")?.show_as_bounding_box, undefined, "SPI flash is not a placeholder box")

const screenComponent = componentByName.get("ER_TFT035IPS_6")
const screenCad = cadByName.get("ER_TFT035IPS_6")
const screenModelFile = "er-tft035ips-6-realistic.glb"
assert.ok(screenComponent, "ER-TFT035IPS-6 assembly screen exists")
assert.ok(screenCad, "ER-TFT035IPS-6 has a 3D assembly model")
assert.match(screenCad.model_glb_url ?? "", new RegExp(`${screenModelFile}$`),
  "screen uses the manufacturer-dimensioned GLB assembly rather than a generic slab")
assert.ok(nearly(screenCad.position.x, 40.8) && nearly(screenCad.position.y, 15),
  "screen 3D model is anchored to J_LCD")
assert.ok(nearly(screenCad.rotation.z, 90),
  "screen 3D model extends left from the right-side J_LCD cable-entry axis")

for (const traceName of ["SPK_POS_OUT", "SPK_NEG_OUT"])
  assert.ok(of("source_trace").some((trace) => trace.name === traceName),
    `J_SPK carries ${traceName} from the PAM8403 bridge output`)

const traces = of("pcb_trace")
assert.ok(traces.length >= 250, "dense routed design contains its expected copper traces")
assert.ok(!circuit.some((record) => /unrouted|trace_missing/i.test(record.type)), "no unrouted/missing-trace records")

const traceEndingWith = (suffix) => {
  const matches = traces.filter((trace) => trace.pcb_trace_id.endsWith(suffix))
  assert.equal(matches.length, 1, `one PCB trace ends with ${suffix}`)
  return matches[0]
}
const assertMinimumWireWidth = (trace, width, label) => {
  const wireWidths = trace.route.filter((point) => point.route_type === "wire").map((point) => point.width)
  assert.ok(wireWidths.length > 0 && wireWidths.every((actual) => actual >= width - 1e-6),
    `${label} is physically routed at least ${width.toFixed(2)} mm wide`)
}
assertMinimumWireWidth(traceEndingWith("source_net_6_mst14_0"), 0.5, "buck output capacitor A link")
assertMinimumWireWidth(traceEndingWith("source_net_6_mst23_0"), 0.5, "buck output capacitor B link")
for (const id of ["source_trace_361_0", "source_trace_363_0", "source_trace_364_0", "source_trace_365_0", "source_trace_367_0"])
  assertMinimumWireWidth(traces.find((trace) => trace.pcb_trace_id === id), 0.5, `${id} backlight power link`)

const batteryRangeText = of("pcb_silkscreen_text").find((text) => text.text === "4xAAA 4.8-6.4V")
assert.ok(batteryRangeText, "battery silkscreen states the corrected 4.8-6.4 V input range")

const report = {
  circuitPath,
  generatedAt: new Date().toISOString(),
  board: {
    title: "F1C100S Linux Game Boy Advance",
    widthMm: board.width,
    heightMm: board.height,
    copperLayers: board.num_layers,
  },
  routing: {
    pcbTraces: traces.length,
    pcbVias: vias.length,
    viaHoleDiameterMm: 0.3,
    viaPadDiameterMm: 0.45,
    minimumFinishedHoleGapMm: Number(minimumFinishedHoleGap.toFixed(6)),
    closestViaPair,
    reviewedViaHoleToCopperGapMm: Number(reviewedViaCopperGap.toFixed(3)),
    reviewedViaNearestTrace,
    buckOutputCapLinksMm: 0.5,
    backlightPowerLinksMm: 0.5,
  },
  mechanical: {
    batteryCableEdgeCut: {
      widthMm: Number((cutoutBounds.maxX - cutoutBounds.minX).toFixed(3)),
      overallLengthMm: Number((cutoutBounds.maxY - cutoutBounds.minY).toFixed(3)),
      depthIntoBoardMm: Number((cutoutBounds.maxY - boardBottomY).toFixed(3)),
      closedEnd: "rounded",
    },
    shoulderSwitches: "TS66135ZJ 022 low-profile right-angle housing, 13.5 mm switch height, 9.6 mm board-edge stem protrusion",
    bootHeader: {
      center: { x: -55, y: 23 },
      outsideLandscapeLcdEnvelope: true,
    },
    startSelectYmm: -19,
    microSdEdge: "right recessed access bay",
    microSdEdgeClearanceMm: Number(microSdEdgeClearanceMm.toFixed(3)),
    batteryConnectorFacesCutout: true,
    batteryCableBendCorridorMm: Number(batteryCableBendCorridorMm.toFixed(3)),
    powerSwitch: {
      center: { x: -61.5, y: -32.5 },
      side: "lower-left, matching AGB-001 bottom control strip",
      edgeRecessMm: Number(powerSwitchEdgeRecessMm.toFixed(3)),
      enclosureActuation: "guarded slider",
    },
    rearServiceConnectors: {
      uart: { center: { x: -18, y: 37 }, layer: "bottom", pinout: ["RX", "GND", "TX"] },
      i2c: { center: { x: -28, y: 37 }, layer: "bottom", pinout: ["GND", "3V3", "SDA", "SCL"] },
      spi: { center: { x: 22, y: 37 }, layer: "bottom", pinout: ["GND", "3V3", "SCLK", "MOSI", "MISO", "CS"] },
    },
  },
  display: {
    part: "ER-TFT035IPS-6",
    widthMm: 84.96,
    heightMm: 55.5,
    orientation: "landscape",
    fpcConnectorSide: "right",
    connectorRotationDeg: 270,
    assemblyModel: screenModelFile,
    backlightDriver: "AP3031KTR-G1",
    regulatedBacklightCurrentMa: lcdBacklightCurrentMa,
  },
  power: {
    labeledBatteryRangeV: [4.8, 6.4],
  },
  models: {
    f1c100s: "C1511928",
    spiFlash: "C97521",
    shoulderSwitch: "C33543626",
    screen: screenModelFile,
    fittedPartsWithRenderableModels: fitted.length - missingCadModels.length,
    missingRenderableModels: missingCadModels,
  },
  audio: {
    speakerConnector: "J_SPK",
    output: "PAM8403 mono bridge SPK+/SPK- for an internal 4-8 ohm speaker",
  },
  assembly: {
    fittedComponents: fitted.length,
    uniqueJlcpcbPartNumbers: uniqueJlcpcbParts.size,
    missingJlcpcbPartNumbers: missingJlcpcb,
  },
  controls: expectedButtons.length,
  errorsByType: {},
  emittedErrors: 0,
}

fs.writeFileSync("verification.json", `${JSON.stringify(report, null, 2)}\n`)
console.log(JSON.stringify(report, null, 2))