# $Id: README 123 2026-09-05 17:27:55Z peter $

dudhya
======

dudhya researches, and implements where possible, the resuscitation
of older smartphones: giving them a second life running an
open-source operating system (preferably GNU/Linux), so they can be
repurposed as embedded systems and sources of sensor telemetry rather
than discarded. See Concept.org for the full goal and motivation, and
Dudhya.org for the resuscitation procedures themselves as they are
developed.

This delivery includes the project's documentation and build-system
scaffold (the concept, constitution, development standard, and
research-journal documents, plus the autotools/Org-mode toolchain
that turns them into PDF and HTML); dudhya-sensord, a compiled sensor-
to-MQTT daemon (see dudhya-sensord.c); WiFi mode-switching and
device-provisioning scripts; and a real, netlist-driven KiCad
schematic and breadboard-style diagram for a Google Pixel 3a battery-
free power circuit, generated via packpay (see "External
dependency" below).

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.
- DevelopmentStandard.org --- coding, documentation, build, and
  packaging rules.
- ResearchJournal.org --- dated record of decisions and rationale.
- Dudhya.org --- the resuscitation procedures themselves.

kicad_gen.py's own scripting language reference (KicadGen.org) moved
to packpay, along with the module it documents -- see
DevelopmentStandard.org's own "This project's own real workflow"
subsection for what remains genuinely dudhya's own to know.

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

External dependency: packpay
-----------------------------

This project's own generic, netlist-driven schematic/breadboard
auto-layout engine was surgically extracted into its own project,
packpay (see ResearchJournal.org's own entry for that
extraction). Every real KiCad/breadboard generation target in this project
(`make kicad-regen`, `breadboard-regen`, `netlist-verify`, and
everything that depends on them) now requires a real packpay checkout,
located via the `PACKPAY_DIR` environment variable -- the same
pattern already established for `KICAD_SYM_DIR`/`KICAD_FOOTPRINT_DIR`:

    ./configure PACKPAY_DIR=/path/to/packpay
    # or: make PACKPAY_DIR=/path/to/packpay kicad-regen

See DevelopmentStandard.org's own "Depending on packpay" subsection
for the full account, and packpay's own README for how to obtain and
build it.

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

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

Optional, needed only for the documentation build or a specific
target (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) ---
  both were missing from a fresh TeX Live install during an early
  session's own build verification and had to be added explicitly.
- A Devanagari-capable font (Noto Sans Devanagari; on Debian/Ubuntu:
  `apt install fonts-noto-core`) for `make pdf`: Concept.org quotes a
  Sanskrit phrase in Devanagari script, and without this font
  `lualatex` produces the PDF anyway but with a "Missing character(s)"
  warning where that phrase should render.
- A C compiler and libmosquitto (pkg-config module `libmosquitto`),
  for `make` to build `dudhya-sensord` (the Nexus 5 sensor-to-MQTT
  daemon, see dudhya-sensord.c). Missing either skips just this
  target. On the target device itself (Alpine/postmarketOS):
  `apk add build-base autoconf automake mosquitto-dev` --- see
  Dudhya.org's "Sensor telemetry: dudhya-sensord" section for the
  full on-device build and deployment steps, including runtime
  prerequisites (the `mosquitto` broker package itself) and the
  OpenRC service setup.
- latexmk, for a properly multi-passed PDF (falls back to four
  explicit lualatex passes if absent).
- groff, for `make man-html` (not yet exercised: dudhya ships no
  manual pages yet).
- kicad-cli, kicad-symbols, and kicad-footprints, plus a real packpay
  checkout (PACKPAY_DIR, see above), to actually regenerate and verify
  the real KiCad schematic and breadboard diagram (`make kicad-erc`,
  `breadboard-verify`, `netlist-verify`).

Building
--------

    ./bootstrap          # regenerate configure/Makefile.in (only needed
                          # after a fresh checkout or editing configure.ac/
                          # Makefile.am)
    ./configure PACKPAY_DIR=/path/to/packpay
    make                  # builds dudhya-sensord, if libmosquitto is present
    make pdf              # builds Index.pdf, Concept.pdf, FutureResearch.pdf,
                          # DevelopmentStandard.pdf, ResearchJournal.pdf,
                          # Dudhya.pdf
    make html             # builds the same set as a linked HTML set
    make kicad-erc        # regenerates and verifies the real KiCad schematic
    make breadboard-verify # regenerates and verifies the breadboard diagram
    make clean            # removes the above and version.org
    make maintainer-clean # additionally removes configure, Makefile.in, etc.

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 `dudhya-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.

Automake's own `make dist` also works, but is not this project's
delivery mechanism: it produces a differently-versioned `.tar.gz`
(the package version plus an SVN-revision suffix, e.g.
`dudhya-1.53.0.2.tar.gz`) rather than the plain Dewey `VERSION` used
by `make-archive` and described in DevelopmentStandard.org.

License
-------

GNU General Public License v3 or later. See COPYING.
