# $Id$

packpay
=======

packpay --- प्रवाहित अग्निचित्रस्य कृते परिवर्तनयन्त्रम् (pravahit
agnichitrasya krute parivartanayantram, "transformation engine for
flowing fire diagram") --- is a netlist-driven schematic and
breadboard-diagram generation and auto-layout engine: given a real
KiCad netlist (component list, pin-to-net wiring, real pin
electrical types), it algorithmically produces a placed, wired KiCad
schematic and/or a connectivity-focused breadboard-style diagram,
with no hand-placed coordinates anywhere in the loop.

EXTRACTED 2026-08-14 from the dudhya project (old-smartphone
revival), where this same engine was originally built and refined
across many sessions against one real circuit (a Google Pixel 3a
battery-free power stage) and, later, two synthetic example circuits
built specifically to stress topology that one real circuit never
exercised. See Concept.org for the full motivation and ResearchJournal.org
for the complete extraction account and the engine's own prior
development history.

Documents
---------

Start at Index.org (Index.pdf / Index.html once built) for the full,
linked document set:
- Concept.org --- goal, scope, motivation.
- FutureResearch.org --- open questions and deferred work, including
  a real, confirmed limitation found during the extraction itself
  (the breadboard side's own row-capacity handling).
- DevelopmentStandard.org --- coding, documentation, build, and
  packaging rules, including the KiCad environment setup procedure
  (symbol and footprint library extraction) needed to actually run
  and verify this project's own code.
- ResearchJournal.org --- dated record of decisions and rationale,
  extracted from dudhya's own journal where this engine's history
  happened, plus this project's own entries going forward.

Two documents are deliberately not published: Constitution.org
(private) and SessionHandoff.org (an internal, terse, continuously
rewritten continuity note).

Layout
------

Deliberately flat: every source file lives at the project root, no
subdirectories at all (see ResearchJournal.org's own extraction entry
for why). The core modules:
- netlist.py --- loads a real KiCad netlist export into a plain,
  structured Netlist/Component/Net representation.
- kicad_gen.py --- a small domain-specific language for emitting
  valid KiCad schematic files: place a symbol, connect two pins,
  write the file.
- kicad_layout.py --- the generic, netlist-driven KiCad schematic
  PLACEMENT algorithm built on top of kicad_gen.py (ppkicad_layout(1)
  is its command-line entry point: an existing schematic or netlist
  in, a new one out, split across sheets when large): anchors in a
  row, passives attached to whatever they share a net with,
  PWR_FLAGs placed and nudged clear of real label/text reach, the
  whole result verified against sheet bounds, the title block, and
  component-to-component overlap.
- auto_layout.py --- the generic, netlist-driven BREADBOARD-style
  layout algorithm, and the netlist-classification helpers
  (anchor/passive/rail detection, connectivity-based ordering) both
  the KiCad and breadboard sides share.
- breadboard_lib.py, render.py --- real breadboard-diagram drawing
  primitives and the renderer built on them.
- footprint.py, render_footprints.py --- real KiCad footprint
  courtyard geometry extraction, used for realistic component sizing.
- example_pins.py, example_circuit1.py, example_circuit2.py --- this
  project's own self-contained example/test circuits (real, verified
  symbol pin geometry, no dependency on any downstream project).
- build_instructions.py --- converts a placed breadboard layout into
  a textual, step-by-step build guide a real person can follow by
  hand (ppbuild_instructions(1)).
- parse_instructions.py, resolve_components.py --- the reverse
  direction: reconstructs a netlist/placement from a build-
  instruction text file, then resolves every component against real,
  external component data (a real KiCad library, or an Eagle-format
  breakout schematic) to produce a working KiCad schematic
  (ppparse_instructions(1), ppresolve_components(1)).
- eagle_import.py, lcsc_import.py --- resolve_components.py's own
  two, real component-data backends: Eagle-format (.sch) design
  files, and a live LCSC/EasyEDA fetch via easyeda2kicad (`pip install
  easyeda2kicad`; a part that needs it is reported cleanly when it is
  missing).
- power_sources.py --- identifies which component in a circuit is
  genuinely supplying power to it (battery, USB, regulator output),
  so it can be placed and connected sensibly even with no other,
  direct connection to anything else.
- test_netlist.py, measure_labels.py, measure_value_text.py ---
  this project's own verification and empirical-measurement tools.

Every module above with a real, direct, standalone command-line
entry point (the `pp`-prefixed script of the same or a related name)
has its own manual page -- see `man ppnetlist` and work outward via
each page's own SEE ALSO section, or Index.org's own document set.

Build prerequisites
--------------------

Required (./configure fails without them):
- GNU Make (on FreeBSD this is usually `gmake`, not `make`).
- bash.
- python3.

Optional, needed only for the documentation build or for actually
running/verifying this project's own code (a missing one disables
just that target; ./configure warns, it does not fail):
- Emacs 29+ with Org 9.6+, for `make pdf`/`make html`.
- lualatex and a TeX Live install providing, beyond a base install,
  ulem (texlive-plain-generic) and lualatex-math (texlive-luatex).
- A Devanagari-capable font (Noto Sans Devanagari; on Debian/Ubuntu:
  `apt install fonts-noto-core`) for Concept.pdf, and only that one:
  this project's own name is a romanized abbreviation of a Sanskrit
  phrase, quoted in Devanagari script in Concept.org. Without the font
  `make pdf` fails on Concept.org and says why; every other document
  builds without it. A LaTeX error in any document fails `make pdf`.
- latexmk, for a properly multi-passed PDF (falls back to four
  explicit lualatex passes if absent).
- groff, for `make man-html` --- see Index.org's own "Manual pages"
  section for the real, generated result (netlist.1/render.1 as of
  0.1.0; more to follow, see FutureResearch.org).
- kicad-cli, kicad-symbols, and kicad-footprints, to actually
  generate and verify a real schematic (`make check`) --- see
  DevelopmentStandard.org's own environment setup procedure for how
  to obtain these (the KiCad AppImage route, if a system package
  isn't available or current enough).

Building
--------

    ./bootstrap          # regenerate configure/Makefile.in (only needed
                          # after a fresh checkout or editing configure.ac/
                          # Makefile.am)
    ./configure
    make pdf              # builds Index.pdf, Concept.pdf, FutureResearch.pdf,
                          # DevelopmentStandard.pdf, ResearchJournal.pdf
    make html             # builds the same five as a linked HTML set
    make check            # regenerates both example circuits and confirms
                          # each is electrically clean (0 ERC errors), plus
                          # runs the netlist loader's own direct test suite
    make clean            # removes the above and version.org
    make maintainer-clean # additionally removes configure, Makefile.in, etc.

Using packpay from another project
-----------------------------------

packpay is not (yet) installed to a system prefix in a way another
project's own Python code can `import` directly -- the intended
integration, until that changes, is: point a consuming project's own
scripts at packpay's own checkout directory via an environment
variable (the same pattern already established for KICAD_SYM_DIR/
KICAD_FOOTPRINT_DIR), e.g.:

    import sys, os
    sys.path.insert(0, os.environ["PACKPAY_DIR"])
    from kicad_layout import generate_schematic_auto

See dudhya's own build_pixel3a_power_autolayout.py for a real,
working example of exactly this integration (dudhya was, itself,
packpay's own first real-world caller, before this extraction).

Delivery
--------

The project's own delivery archive is produced by `./make-archive`,
which packages the whole source tree (per DevelopmentStandard.org's
Dewey-decimal versioning) as `packpay-VERSION.tar.xz`, honouring
`.tar-exclude`. Run it after a documentation build and a
`make maintainer-clean`, to verify and then package a pristine tree.

License
-------

GNU General Public License v3 or later. See COPYING.
