Build a knowledge pack

For machine builders: ship a signed pack of a machine type's code, documents and fault library to every site that runs it.

A knowledge pack holds what a machine builder knows about one machine type and version: the code export, the documents tagged with the type, the tag, alarm and interlock lists and the fault library. A receiving site adds it to every asset of that type, and answers cite it with the pack's name and version. Work orders, parts, journal records and process data are never put in a pack.

Make a signing key, once

python -m edge.knowledge_pack keygen --private builder.key --public builder.pub

Keep builder.key off every customer site. Give builder.pub to the sites that will trust your packs.

Tag what belongs to the machine type

In the builder's own site.yaml, list the machine type with its assets, code projects and fault library; in the documents manifest, add machine_types: [HP-800] to each document that belongs in the pack.

machine_types:
  HP-800:
    builder: Hydra Presses
    assets: [HP-800]
    projects: [hp800-beckhoff]
    fault_library: fault_library.yaml

Export and sign the pack

python -m edge.knowledge_pack export HP-800 --pack hp800-kp --version 2.1 --key builder.key --out pack.zip

The pack is a zip with pack.yaml (the pack, version, machine type, builder, the code's vendor and every file with its SHA-256) and pack.sig, your Ed25519 signature of it.

At the receiving site

The site trusts your public key and maps its assets to the type:

machine_types:
  HP-800: {builder: Hydra Presses, assets: [PRESS-3]}
machine_builders:
  Hydra Presses: {public_key: keys/hydra.pub, share_fixes: false}

python -m edge.knowledge_pack import pack.zip

The import refuses a pack that is unsigned, changed after signing, or signed by a key the site does not trust for that builder, and audits the signer key's fingerprint. Pack sources are cited as plc://<site>/hp800-kp~2.1/… and doc://<site>/hp800-kp~2.1~<doc>@<rev>#<section>.

Field fixes back to the builder

Where the site turns it on (share_fixes: true for that builder), an administrator can export the confirmed fixes for the builder's machines, anonymised:

python -m edge.knowledge_pack share-fixes "Hydra Presses" --out fixes.json

Sharing is the site's decision, off by default, and each run is audited. The file goes to the builder only if the site sends it.