# Camera GPIO Interface PCB Agent Guidance This file is the canonical project guidance for agent sessions in this repository. ## Session Start Read this file first. If `AGENT_MEMORY_REPO` is set and points at a directory, read `$AGENT_MEMORY_REPO/AGENTS.md` before planning or editing. Then read, in this order: - `docs/rev0-plan.md`: the whole design record, with the resume checklist at the end. Its dated update notes at the top supersede older statements below them. - `docs/kicad-libs-handoff-2026-09-24.md`: what `kicad-libs` prepared for this board and which plan statements it corrected. - `docs/autoroute-log.md`: the layout record, run by run, with every hand repair; then `docs/session-handoff-2026-09-26.md`: where the routed board stands and what is left before fabrication. If sibling checkouts exist, also read: - `../orb-weaver-context/context/agent-index.md` - `../orb-weaver-context/context/kicad-agent-context.md` - `../board-interfaces/docs/instrument-port-digital.md` - `../kicad-libs/docs/design-blocks.md` - `../kicad-libs/docs/blackfly-s-gpio-channel-design-block.md` - `../kicad-libs/docs/instrument-port-netclasses.md` If `.agents/handoff.local.md` exists, read it before planning or editing. If the task is multi-step, risky, or likely to span more than one session, read `.agents/PLANS.md` and keep it updated as work progresses. ## Repository Purpose This repository owns the KiCad implementation and board-specific notes for `camera-gpio-interface-pcb`: three FLIR Blackfly S GPIO channels on pluggable screw terminals, two BNC inputs from a pyControl breakout, four 3.3 V BNC outputs to a Neuropixels OneBox, an InstrumentPort-Digital-50 with every camera line tapped, and USB power. No MCU, no firmware. ## Board Rules - `kicad-libs` owns the shared symbols, footprints, internal parts, vendor mappings and design blocks; `board-interfaces` owns the InstrumentPort contract. Do not copy library assets here. A placed block is a board-owned copy; re-annotate copies into 4-digit bands as `mouse-joystick-pcb` does. - Blocks placed, all from `orb_weaver_private`: `blackfly_s_gpio_channel_mcv6_vertical` three times, `logic_input_2ch_5v_schmitt_sn74lvc2g17` for the two BNC inputs, `usb2_vertical`, `5v_to_3v3_tps73733`, `instrument_port_digital_50_dut_ffc_boundary_vertical`. - Every BNC output is fixed at 3.3 V through 470 Ω. There is no 5 V option; the plan records why. - `USBLC6-2P6` is a two-line array: pins 1 and 6 are one node, 3 and 4 the other. Nine on the board: one for the two inputs, two for the four outputs, two inside each camera block. Use only `orb_weaver_smd:USBLC6-2P6_SOT-666`. - Instrument tap nets end in `_INST` and take the `INSTRUMENT` netclass from the `instrument-taps` profile. Every unused LV541A input is tied to ground at the board. - `+5V_USB` is the opto drive level and the ESD clamp reference. It must stay a 5 V rail. - Fab floors (0.1 mm clearance and track width) live in Board Setup > Constraints, never as unconditional `.kicad_dru` rules; such a rule replaces every netclass clearance instead of flooring it. `rule_severities.clearance` stays at error. Decided 2026-09-26: the 146 findings between 0.10 and 0.19 mm inherited from the InstrumentPort and USB block layouts (all against the 0.20 mm default class, none voltage-bearing) are accepted as fab-floor copper inside blocks. The `.kicad_dru` rule "Low-voltage block clearance is advisory" demotes every pair where neither side is a voltage-bearing class to warning, the mouse-joystick form, never severity ignore; `make fab`'s error-level DRC gate passes and `make clearance-check` (254 findings, 0 voltage-bearing, against the 256 baseline) is the gate for new or worsened findings. Delete the rule when kicad-libs re-routes the two blocks at 0.20 mm and they are re-placed here. - A JLCPCB placement rotation correction goes in `kicad-libs/vendor_specs/jlcpcb/footprint-rotations.csv`, never in a footprint. This board was the first to place the Phoenix MCV 6 vertical and the `LED_0402-1005_KNB` footprint at JLCPCB; the placement preview of the 2026-09-26 order showed both oriented correctly (MCV 6 at +180, LED at 0), which kicad-libs records as verified rows. - Mark unverified pinouts, cable orientation and electrical limits as open decisions. Record bench results in `docs/bringup-log.md`. ## Development Environment Prefer Makefile targets: - `make test`: guidance and scaffold presence check - `make kicad-edits`: open the project in the managed KiCad - `make kicad-shell`, `make kicad-version` - `make codex` / `make claude`: agent sessions with sibling checkouts added - `make agent-reflection` - `make validate-db`, `make check-kicad-libs` - `make fab`, `make docs`, `make docs-check` - `make clearance-baseline` before routing, then `make export-dsn` or `make freeroute`, `make import-ses`, `make clearance-check`: the shared kicad-libs routing helpers, described in `../kicad-libs/docs/freerouting-autorouting.md`. This board exports with `EXPORT_DSN_OPTIONS="--refill --protect-prerouted --power-layer In1.Cu"` because In1.Cu carries the `/GND` plane; the routed result and its checks are in `docs/autoroute-log.md` The pinned Guix channel in `.guix/channels.scm` carries KiCad 10.0.6, the version the design blocks were saved with, so this repository has no local KiCad overlay. The sibling `../kicad-libs` checkout is used through `ORB_WEAVER_KICAD_LIBS` when present; the `orb-weaver-kicad-libs` channel pin only selects the packaged helper commands. Bump pins deliberately, not as cleanup. `docs/generated/` and the block between the `` markers in `README.md` are written by `make docs`. Never hand-edit either. Netclass profiles applied 2026-09-25 with `../kicad-libs/bin/orb-weaver-kicad-apply-netclasses`: `instrument-taps` and `hv-power-24v` (its HV classes match nothing here; it supplies `PWR_5V`, `PWR_3V3` and the `_LOCAL` variants), plus the board-local `kicad/netclass-profiles/camera-gpio-narrow-rails.json`, which puts `PWR_5V_NARROW` and `PWR_3V3_NARROW` (0.20 mm track, 0.20 mm clearance, 0.6/0.3 mm via) one priority step above the shared rail classes so `/+5V` and `/+3.3V` can enter the 0.5 mm-pitch SOT-666 and DRY6 pads they feed. The shared widths cannot reach those pins (`docs/autoroute-log.md`, run 2); a class that is wider than the pin it must connect to gets a narrower local class rather than a hand-routed neck. Re-apply any of the three if `--check` reports drift; the helper preserves unrelated classes and patterns. ## Validation For schematic and layout work, run KiCad ERC and DRC through the managed environment once the design is mature enough for them to be meaningful, and compare the exported netlist against the plan's tables after edits; ERC alone did not catch earlier electrical findings on `mouse-joystick-pcb`. `ORB_WEAVER_KICAD_LIBS` must resolve for KiCad to find the database, footprint and design-block libraries. ## Board Manifest `kicad/board-manifest.yaml` is the board's manifest (kicad-libs decision D20, derived 2026-10-02): every placed block with its anchor from `docs/generated/mechanical-datums.json`, each port mapped to the label it meets in its parent sheet or `open` with a reason, the board-authored sheets, the netclass profiles and every net's class. After placing, wiring or moving a block run `make mechanical-datums`, then `make board-manifest-derive` (keeps the written meanings and reasons) and `make board-manifest-check`; `make board-manifest-render` regenerates the block between the markers at the top of `docs/interface-map.md`, which is a rendering of the manifest and is never edited by hand; the narrative below the block is. A port the manifest neither maps nor leaves open with a reason is an error, not a note. `make compose` makes the project agree with the manifest (D28), creating the sheet instances, pin connections and PCB groups it lacks and never moving or renaming; `make compose-check` is the dry run. `make refresh-block INSTANCE=` brings one placed block up to its library block and reports what changed (D22). `kicad/board.yaml` with subsystem recipes is the board's source (D27) when one is written: `make expand` writes the manifest from it and `make expand-check` compares. The Makefile targets come from kicad-libs `templates/kicad-repo/Makefile` and call the sibling checkout's launchers. ## Publication Layers This repository is mirrored to GitHub for the rig's researchers, so it has two layers (decided 2026-10-12): - **Citable layer**: `README.md`, `CITATION.cff`, `LICENSE`, `LICENSES/`, `kicad/`, `docs/generated/` and every document the README lists. It must open and read without any Orb Weaver checkout and must not refer to codeberg.org or to `orb-weaver-*` repositories. KiCad library identifiers (`orb_weaver_private:…`, `orb_weaver_smd:…`) and the generated-block comments are allowed; they are library references, not links. Files in other repositories are cited as `/` with no `../` and no URL; `docs/development.md` maps each repository name to its URL. - **Development layer**: `docs/development.md`, the documents it lists, `AGENTS.md`, `.agents/`, `.codex/`, `Makefile` and `.guix/`. These may name the sibling checkouts and the Orb Weaver repositories. A new document goes into exactly one of the two lists. `LICENSES/NOTICE.md` keeps its `kicad-libs` URL: it is the CC-BY-SA attribution for the embedded symbols, footprints and blocks.