Skip to content

Engineering portal — one place for the design projects

Status: built 2026-09-15, live at https://engineering.embeddedera.com (Engineering + Administration). Plan written 2026-09-13. Angel's ask: the EmbeddedEra GitHub will hold many KiCad projects, and home should have an engineering subdomain gathering everything about design work, with projects added over time.

What it is

engineering.embeddedera.com, behind the same gate, listing every design project the shop has, and for each one the things you actually go looking for:

  • the schematic and board, viewable in a browser — KiCanvas renders KiCad files directly, no install, no export step, so a project page shows the real thing rather than a stale PDF
  • the BOM, and an InteractiveHtmlBom for the bench: click a line, the part highlights on the board. This is the one that earns its keep during assembly
  • the latest checks: ERC, DRC and library conformance, with the date they last ran
  • links out to the ERP parts, the build orders, and the SOPs that govern the work

Where the content comes from

Nothing is hand-maintained. Each project repo under github.com/EmbeddedEra is the source; CI produces the artefacts on every push (see task-board for how failures become tasks):

push → kicad-cli: ERC, DRC, gerbers, BOM → InteractiveHtmlBom → publish

The portal is then a thin index over those artefacts, built the same way the notebook is — MkDocs or a small static build, published to Pages, gated by Access, listed in departments.yml as a tile for Engineering and Administration.

Why it waits for the checks

The checks come first and the portal second, deliberately. A portal that shows a board is nice; a portal that shows a board and tells you its last DRC was clean on this commit is the thing worth having. Build kicad-cli in CI first, then wrap a page around what it produces.

Open

  • Next Robot Cow PCB revision (Angel, 2026-09-18; task #149): review and resolve the Robot-Cow-004B findings observed while verifying #148: 4 ERC errors, 3 DRC errors, 10 DRC warnings (0 ERC warnings). Evidence: /home/angel/engineering/codex-test/task148/checked-board.json, validated KiCad run on an isolated copy at 2026-09-18 16:09. Re-run ERC/DRC on Cow_Robot_Board/hardware/Robot-Cow-004B to obtain individual violation details before making design changes; the saved summary contains counts, not diagnoses. Keep the current revision unchanged for this portal task and continue displaying its findings honestly. Deferral is not a waiver or manufacturing approval.

  • Under #149, finish or explicitly retire the empty draft layouts: Remote_Universal/Hardware/Remote_Universal.kicad_pcb, Cow_Robot_Board/hardware/Robot_Tester/Robot_Tester.kicad_pcb, and Universal_Tester/hardware/portable-universal-tester.kicad_pcb. They have no footprints or outline primitives; the first two are 78-byte placeholders and the third is 2,115 bytes. Angel explicitly excluded them from #148 on 2026-09-18. Their portal pages must continue showing the real BOM failure; exclusion is not design approval.

  • Confirm finish, solder-mask colour and copper weights from the last JLCPCB orders for production boards Robot-Cow-004B, Cow_Remote_006 and Cow_finger_003. As verified 2026-09-18, 004B now has its own hardware/Robot-Cow-004B/fab.yml, but its finish/mask/copper remain explicitly unconfirmed defaults.

  • Verify Robot Cow firmware compatibility in Cow_Robot_Board/product.yml: 004B now declares EE-P-0002-A, but firmware[].builds_for still names retired 4.0.1. Production status alone does not establish firmware compatibility.
  • Verify 004B fabrication specifications and SOP-021 release checks against the existing hw/Robot-Cow-004B/A release (2026-09-16), which the live GitHub inventory confirms exists. Its existence is not manufacturing approval; the older 4.0.1 pack remains historical.

Open questions

  • One page per project, or per revision? Probably per project with a revision history, because "which one did we build" is the question that actually gets asked.
  • How large do the artefacts get, and do they belong in the repo, in Pages, or in R2.
  • Whether the portal replaces or complements the ERP's own part and build pages. It should complement: the ERP owns numbers and stock, the portal owns drawings and checks.

Related: engineering-portal-handoff (where everything is, for another engineer or AI), task-board, notebook-site, KiCad, ai-across-departments.

  • Robot Cow: leftovers from the wrong-folder mix-up (2026-09-19). Production is now hardware/Robot Cow (the board actually ordered; PR #8, merge 93d9425), and hardware/Robot-Cow-004B is listed as a prototype ("never ordered"). Still pointing at the never-ordered edit: the GitHub release hw/Robot-Cow-004B/A (built 09-16 from the edit; delete it, or keep it as a record of the edit, then tag hw/Robot_Cow/A from hardware/Robot Cow once fab.yml's finish/mask/copper are confirmed), the IPN properties added on 09-16 (they're in the edit's schematic, not Robot Cow.kicad_sch), and task #149's ERC/DRC counts (measured on the edit; the ordered board has 93 DRC errors / 98 warnings, unchanged by the 09-19 value sync). Firmware builds_for still says 4.0.1.

Log

  • 2026-09-18: Angel explicitly approved excluding the three empty draft layouts from #148 while retaining their hardware follow-up under #149. Updated both task descriptions, recorded the scope decision and verification evidence, and closed #148 with API read-back confirming closed. #149 remains open; existing 004B findings remain for the next revision. Next software task: #218 social analytics reviews.
  • 2026-09-18: Portal hardening deployed: assistant sandbox 30f3a11, main 9d258aa; preview 309344a7, production 72b9ff91 on embeddedera-engineering.pages.dev. 60 offline portal/deploy tests plus 3 checker tests passed under OS network denial. Fresh validated KiCad checks across 12 isolated repo copies; 32 board pages, 29 BOMs, all four shipping boards covered. Browser checks at 375/1440 px load both 004B KiCanvas canvases without JS errors or page overflow; tablet-sized BOM click highlights 8 components. Cloudflare Access challenges verified on production, preview and immutable deployment URLs; registry dry-run in sync; surfaces-check passed. No authenticated live-browser or physical-tablet claim. Exact paths/SHA now bind metadata and check results, legacy unsafe check caches regenerate, unknown status is Unclassified, deployment failures retain previous docs/hash. Source control now owns scripts, site config and phone CSS. #148 remains open for the three empty-layout BOM inputs above, not for the implemented software fixes. Evidence and worker records: /home/angel/engineering/codex-test/task148/; details in engineering-portal-handoff. Sonnet (claude-sonnet-5) used for two bounded implementation passes, independently reviewed; CLI-reported cost estimates $1.5926766 and $1.5660064, not subscription charges. Native usage after work: 3% session / 66% shared weekly, observed 2026-09-18 17:23 EDT.
  • 2026-09-18: Angel requested that the Robot Cow 004B ERC/DRC findings from task #148 be recorded for fixing in the next hardware revision. Added the scoped follow-up under Open and to task #149; no board changes or design approval. Portal task #148 remains separate and unfinished.
  • 2026-09-18: Task147 manufacturer comparison passed for nominal ESP32-C6-LCD-1.47 footprint geometry and 18-pin mapping. Fixed IO3 label and portable 3D-model path, added regression test and source-backed design-use limits in the KiCad repo. KiCad export and diff checks passed. Physical carrier fit/clearance is not manufacturing-approved.
  • 2026-09-13: written, after Angel asked for an engineering subdomain over the GitHub projects.

  • 2026-09-15: built. engineering-build (python, ~/.local/bin) lists the org's repos with gh, skips templates/archived/the library/forks, shallow-clones into ~/engineering/repos/, and for each .kicad_pro (skipping Archive/production/panelized copies) writes a page under ~/engineering/site/docs/boards/<repo>/<board dir>/ with the KiCad files for KiCanvas (vendored docs/assets/kicanvas.js), an InteractiveHtmlBom (kicad-ibom), top + iso renders (kicad-cli pcb render), ERC/DRC from kicad-check --json (cached per commit under ~/engineering/cache/), the last "KiCad checks" CI run, and hw/ releases with fab packs. engineering-deploy builds with MkDocs Material (SOP theme, brand css, Home link) and pushes to Cloudflare Pages project embeddedera-engineering only when the tree hash changed; cron hourly at :20, log ~/.local/state/engineering-deploy.log. Access app "EmbeddedEra Engineering" (+ pages.dev previews) gated to engineering + admin; engineering tile in departments.yml. Open: a first full build takes ~40 min because every repo's ERC/DRC runs once; after that only changed commits rebuild.

  • 2026-09-16: Gotcha: Material's navigation.instant feature breaks KiCanvas (the <kicanvas-embed> reports "No valid sources" and shows a cyan box). The portal's mkdocs.yml leaves that feature off; keep it off. Source file names with spaces must be URL-encoded in kicanvas-source src, and kicanvas.js is loaded as type: module. A board page id is the board's directory name (several boards share the file stem "Robot Cow").

  • 2026-09-16: Production/In development/Archive sections from boards[].status in each repo's product.yml (Cow_Robot_Board and Cow_Remote now have manifests). Separate Schematic and Board viewers per page. Renders show components: kicad-3dmodels fetches only the .3dshapes dirs a board references from the KiCad packages3D GitLab archive into ~/engineering/3dmodels (1.6 GB after the first full pass); CI does the same with actions/cache. Fab packs live for the three production boards (hw/Robot_Cow_4.0.1/A, hw/Cow_finger_003/A, hw/Cow_Remote_006/A) and now include the schematic PDF and NeoDen YY1 job files made by kicad-lib/scripting/neoden/kicad_to_yy1.py from neoden_yy1_machine_setup.toml in the same folder (moved there from PNP-Neoden so CI can read it; that file is the bench's source of truth for loaded feeders). Verified against the proven Remote 006 top job: identical rows. Open: finish/mask/copper in the three fab.yml files are defaults marked "confirm"; 4.0.1 vs 004B assumed 4.0.1.
  • 2026-09-16: Render and IBOM files are named with the commit (iso-<sha8>.png) because Cloudflare and phones cached the old image under the same name. Four renders per board (top, bottom, both isometrics) and an "Assembly: top only / both sides" line counted from the layout (fiducials, mounting holes, test points, solder jumpers excluded); a mismatch with fab.yml assembly_sides is flagged on the page. Cow Remote 006 is both sides (95 parts on the bottom); its fab.yml was corrected.
  • 2026-09-16: Interactive 3D on every board page: kicad-cli pcb export glb (tracks, zones, no DNP) → gltfpack -cc (meshopt, ~15× smaller, 0.6 MB for the Remote) → <model-viewer> (Google, BSD-3, vendored in docs/assets/ with the meshopt decoder; init module assets/mv-init.js). gltfpack lives in the nvm global bin, linked at ~/.local/bin/gltfpack. GLB is cached per commit like the renders and named board-<sha8>.glb.

  • 2026-09-16: 3D viewer colours matched to the raytraced renders. KiCad's GLB gives every STEP part metallic=1/roughness=1 (dull grey) and writes the mask and silk as translucent BLEND layers over an olive substrate (pale mint). ~/.local/share/glbfix/fix-materials.mjs (gltf-transform, node from nvm) runs between the export and gltfpack: plastics matte non-metal, gold/grey parts metallic 0.35, mask opaque #0d2617, silk opaque white, substrate opaque brown. Viewer: exposure 0.8, shadow 1, dark surface background.

  • 2026-09-16: Angel confirmed Robot-Cow-004B is the production board and Robot Cow 4.0.1 belongs in Archive. Updated product.yml statuses in EmbeddedEra/Cow_Robot_Board commit 6a43367 and pushed main after validating the actual portal builder’s manifest mapping and generated Production/Archive sections in isolation. Hourly portal deployment will pick up the change; no manual deploy performed. IPN/firmware mappings remain unverified; the sole existing Robot Cow fab release is for 4.0.1.

  • 2026-09-16: Completed template-to-portal audit with Sonnet and Haiku CLI workers and independent verification; report engineering-workflow-audit-2026-09-16. The earlier 004B helper validation missed duplicate-project discovery: generated portal still puts 004B in Archive. No pipeline/hardware fixes applied in the audit. Saved persistent Codex orchestration/delegation preferences at ~/.codex/AGENTS.md.

  • 2026-09-16: Gotcha: the box runs near its 16 GB (Postiz alone holds 2.2 GB idle) and the Claude session's memory guard kills long background shells; run engineering-deploy in the foreground with a timeout and rerun if it stops — every step is cached per commit so the second pass finishes. A board directory that carries older revisions' project files beside the current one (Cricket 008 holds 005 and 006 copies) is shown once, under the project named like the directory; same rule in the CI tag lookup.

  • 2026-09-16: Gotcha: kicad-cli's GLB is glTF Y-up (board thickness along Y) while FreeCAD/trimesh output is Z-up; merge-assembly.mjs now rotates the board +90° about X before aligning it to the enclosure. The first version mirrored the wrong axis and showed the shell rotated 90° about the board's length (grille on a side wall) — caught by Angel on the phone, not by the numeric checks, which only looked at bounds. check-assembly.mjs in ~/.local/share/glbfix prints the merged bounds per node for the next time.

  • 2026-09-19: Portal corrected: Production shows Robot Cow 004B from hardware/Robot Cow (the ordered board), and the never-ordered edit hardware/Robot-Cow-004B moves to In development. Checked with engineering-build's own select_projects/board_metadata before merging Cow_Robot_Board PR #8 (Angel approved the merge).

2026-09-25 — the KiCad library no longer invalidates every board's checks

Symptom Angel spotted: kicad-check running ERC and DRC on Cricket, a project nobody had touched in weeks. Traced to cron → engineering-deploy (hourly at :20) → engineering-build → kicad-check, which checks every repo in the org so the portal can show current results. That part is by design.

Why it was re-checking everything: checker_fingerprint() included the KiCad library's git HEAD, diff and untracked files. A one-property commit to EmbeddedEra.kicad_sym at 06:18 — repointing the STM32 symbol's IPN during the duplicate fix — invalidated the cache for every board in the org, causing a full re-verification.

Why that was wrong, not just expensive. kicad-check runs only sch erc and pcb drc, and neither can see the external library: KiCad embeds lib_symbols in every .kicad_sch and the complete footprint definitions in every .kicad_pcb. Verified — Cricket carries 55 embedded footprints, Universal_Tester_003 carries 188, and no schematic references EmbeddedEra.kicad_sym at all. A committed project is self-contained for these two checks, so the library could never change a result. It was an hour of CPU for information that provably could not differ.

Change: the fingerprint is now {KiCad image, kicad-check script} only. Repo commits still re-check that repo, a checker change still re-checks everything, a KiCad image bump still re-checks everything — only the library coupling is gone. Verified stable across calls and still sensitive to a checker change. Backup at engineering-build.bak.20260925-163353; note ~/.local/bin is not a git repo, so backups are the only history there.

Left in the docstring for whoever comes next: if a check is ever added that compares a board against the library — "does the embedded symbol still match the library version?" — the library must go back into the hash, because that coupling would be real.

Both cache keys corrected, 2026-09-25. The library fix earlier had a twin one level down.

Key Was Now
checker_fingerprint() KiCad image + checker + KiCad library commit/diff/untracked KiCad image + checker
check cache file _check-{repo_sha}.json _check-hw-{hash of .kicad_sch + .kicad_pcb}.json, schema 3

The second meant a README or firmware commit re-ran ERC and DRC on every board in that repo. The commit sha is still recorded for provenance but no longer decides reuse. Schema 2 records are ignored and regenerated once, which the existing legacy-cache rule already covered. Both fail closed: an unreadable input yields no fingerprint and the cache is neither trusted nor written.

Verified on a copy of Cricket — a docs-only change leaves the hardware fingerprint untouched, a schematic edit moves it.

~/.local/bin is now a git repository (c37d9ce). About forty tools run from there on cron and timers with no history until today; an edit was recoverable only if someone remembered a .bak first. Backups are gitignored. Scanned before the first commit: two files match secret patterns and both are false positives (notebook-build carries its own scanner regexes, key-escrow-sheet matches the literal AGE-SECRET-KEY- prefix it searches for). No key material is tracked — credentials live in ~/.config, outside this directory.

The rule worth keeping: a cache key contains exactly what can change the result, and nothing that merely feels related. Both of today's bugs were the same instinct — including something adjacent because it seemed prudent — and both cost real time while providing no information.

  • 2026-10-13: engineering-build (~/.local/bin, commits ab851ba, bf20333) also writes docs/boards/boards.json (each board's status, IPN, sha, ERC/DRC counts, CI, file names, last 5 hw/ releases), with no timestamp so unchanged docs still skip the deploy. The home app's Make › Boards reads it plus the board files from ~/engineering/site/docs (assistant boards.py); design in FigCraft at ~/design/boards-ui/ (build.py regenerates boards.figcraft). Gotcha: ~/assistant/scripts/engineering-build is an old copy; the live one is ~/.local/bin/engineering-build.
  • 2026-10-13: 3D models: boards reference KiCad .wrl models but kicad-3dmodels fetches the .step tree; kicad-cli pcb export glb silently dropped those parts (Robot Cow GLB 13 meshes → 68 with the fix). engineering-build now renders and exports from a temp copy (_models_<name>.kicad_pcb, deleted with its .kicad_prl) whose missing .wrl paths point at an existing .step; RENDER_REV = 2 re-renders every board once and puts r2 in the file names. Parts marked DNP (Robot Cow J5/J6/J7/J9/J12) are left out of renders and GLB on purpose. Still truly missing models: Robot Cow J10 (850-10-005-10-003000.STEP, wrong ${KICAD_3D_MODELS_DIR} path) and L1 (Taiyo-Yuden NR-60xx), plus 1–11 per board elsewhere (BuzzBand 5, PSU 4, UT-002 11).
  • 2026-10-13: Owner decision: DNP parts stay hidden in renders and the 3D model; parts whose model is missing from the library are simply not shown (no placeholder, no library fix needed for the portal).
  • 2026-10-13: Owner decision: the interactive BOM has no Sourced/Placed checkbox columns by default (kicad-ibom --checkboxes ""); they can still be added in the page's settings. IBOM_REV in engineering-build rebuilds every board's BOM when kicad-ibom options change (bump it with any option change). In the app (v2026.10.38) the sandboxed iBOM keeps its settings through a storage shim boards.py injects; phones start top-bottom, front side only.
  • 2026-11-07: GLBs keep part names: KiCad names each footprint's node by its reference and gltfpack dropped them; now -kn (ops 8779ee7). Size barely changes (Cow Remote 590 → 593 KB; PSU +19%). GLB_REV = 2 + a glb_rev marker in each board cache re-exports GLBs once without re-rendering the PNGs; site names become board-<sha8>r2g2.glb. Used by the app's Boards part picking (embeddedera-app).