Concepts, if you come from hardware

You already know what a resistor, a net, and a design rule are. This page covers the handful of software ideas the tool introduces instead, each mapped back to something on your bench so the words stop being jargon, along with what it changes when you run the tool.

Agni is a software engineer’s attempt to learn hardware design by building tooling for it, so it leans on ordinary software ideas throughout. For the reverse map, circuit ideas explained to a software engineer, see the software analogy.

IR (the internal representation) ¶

The tool calls it the IR, or “the design model.” Every EDA export collapses into one normalized netlist-plus-BOM. KiCad, Allegro, OrCAD, and an EDIF dump all read into the same shape, the way a bench multimeter reads volts the same whichever of them drew the board.

So a rule you write, or a report you read, behaves identically no matter which tool exported the design. You learn the tool once, not once per CAD package. When a finding looks wrong, the question is “did the IR capture my design faithfully,” and the tool tells you which parts of the source it read and which it dropped.

Tiers (what the tool actually has to work with) ¶

The tool speaks of the Model and its tiers: a netlist tier, a board tier, a parameters tier. Each tier is a fact source you either connected or didn’t. No .kicad_pcb loaded means there is no copper to run clearance against, the same way a DNP footprint contributes no connection to the circuit. The tier is empty rather than broken.

So silence is not a pass. A quiet board tier means “I had no layout to check,” not “your layout is clean.” The report names which tiers were live, so you can tell a real all-clear from a check that never ran. Feed it more inputs (a board file, a datasheet set) and more tiers go live.

Checks and rules ¶

The tool calls it the check catalog, and each entry is a rule. Think ERC and DRC, except the catalog is open. The built-in rules cover the general electrical cases (decoupling present, supply exceeds a part’s abs-max, copper clearance, ESD protection on exposed nets). You can add your own house rules on top without touching the engine.

Your team argues about some rules in review, such as “every regulator gets a bulk cap” and “USB nets get ESD.” Those rules stop being tribal knowledge, and every export is checked against them automatically.

Findings, severity, and provenance ¶

The tool reports a finding, with a severity and its provenance. It reads like a DRC violation with a callout, except that every finding also carries a paper trail. Provenance is the finding pointing back at exactly what it saw: which net, which component pin, and for a datasheet check, which page and table of the vendor PDF it read the limit from.

You never have to take a finding on faith. “Supply exceeds abs-max” cites your +24V rail and “SNOS412Q page 4, Absolute Maximum Ratings,” so you can open the datasheet to that page and confirm it yourself. Severity tells you what blocks a build versus what is a note.

Datasheets as checkable data ¶

The tool calls it a parameter set (PartSpec values), and a datasheet becomes a doc-IR. It holds the abs-max and operating limits as numbers, so the tool can compare them against your design. Without it you would read those limits off a PDF by eye. Think of it as transcribing the “Absolute Maximum Ratings” table once, with the conditions attached, so it is checked on every run.

The tool can then catch “you are driving 24V into a part rated for 20V” before the board is built, and show you the exact row it read. A limit that has only a text condition (“at 25°C ambient”) is flagged for a human rather than auto-compared.

Diff (comparing two revisions) ¶

agni diff is a redline between two schematic or board revisions. Component added, removed, value changed. Net created, deleted, renamed. It understands that a net kept its connections under a new name and calls that a rename, not a delete-plus-add.

You review “what actually changed between rev A and rev B” as a precise list instead of eyeballing two prints side by side.

Naming conventions as patterns ¶

The tool reads naming conventions from a project’s project.yaml or a --conventions file. A convention is a set of allow and exempt regexes. It writes down your net and ref-des house style once, as patterns instead of a wiki page nobody reads. “Power nets look like +3V3,” “diff pairs end in _P/_N,” “no ref des reused.”

The style is then enforced on every export automatically. CAD tools generate stub names such as the N$… autonames, and those are exempt by default, so you are only flagged on names a human chose.

Where to go next ¶

• Run these ideas for real in Getting started.
• The deeper design rationale behind each concept lives in the developer docs. You do not need them to use the tool, but they are there when you want the why.