soldermaskdocs

Projects on disk

A project is a plain directory you can read, copy and back up. Nothing in it needs the app to make sense.

projects/
  sensor-rail/
    project.json                 name, format, current version, the version table, the chat
    draft.json                   constraints edited but not yet built; not a version
    proposal.json, .proposal/    a change built and not yet accepted; not a version
    v001/
      design.json                the design
      board.json                 everything the viewer draws
      board.json.before-rejudge  the first board.json, kept when a rejudge rewrote it
      inspector.html             the standalone viewer
      sim.json                   the simulation, when one ran
      meshes.json                vendor 3D models for the viewer
      models/C7593.wrl …         the same models for KiCad (.step when asked for)
      sensor-rail.kicad_pcb, .kicad_pro, .kicad_sch
      sensor-rail-F_Cu.gtl … -Edge_Cuts.gm1, .drl, -NPTH.drl
      sensor-rail-In1_Cu.g1, -In2_Cu.g2   inner copper, on a four-layer board
      sensor-rail-BOM.csv, -CPL.csv
      sensor-rail.dsn
      board.svg
      source/board.kicad_pcb     on a version read from a file: the file as it came
    v002/ …
    .work/                       the router's scratch files; not part of a version
  .trash/
    old-board-1788254009/        a deleted project, until the trash is emptied

projects/ sits next to the code in a checkout. Set SOLDERMASK_HOME or SOLDERMASK_PROJECTS to move it (see Configuration). It is your data, and it is not in git.

project.json

{
  "format": 2,
  "name": "Sensor rail",
  "description": "",
  "tags": [],
  "archived": false,
  "created": 1788102305.5,
  "touched": 1788102889.6,
  "current": "v004",
  "versions": [
    {"id": "v001", "created": 1788102305.5, "summary": "…", "prompt": "…",
     "parts": 8, "erc_errors": 1, "gaps": 4, "cost": 3.41,
     "parent": "LDO breakout/v002", "app_version": "0.1.0", "label": "", "notes": "",
     "passed": true}
  ],
  "variations": [
    {"id": "3f9c2a1b", "name": "wide tracks", "macros": {"rules": {"min_track_mm": 1.0}}, "when": 1788102500.1}
  ],
  "chat": [
    {"t": 1788102310.2, "you": "a 3.3V LDO breakout", "bot": "Built it around an AMS1117-3.3 …", "version": "v001"},
    {"t": 1788102400.7, "you": "what is C1 for?", "bot": "C1 is the input bulk capacitor …", "version": ""}
  ]
}
FieldWhat it holds
formatThe on-disk layout's version. See The format number.
currentThe version the app shows and edits. Restoring a version moves only this.
versions[]One row per version, oldest first. Rows are never removed. See Rejudging a version for what can change.
versions[].parentThe version an edit was built from. For a fork's v001, it is <project>/<version>.
versions[].app_versionWhich soldermask built the version
versions[].passedThe verdict: true, false, or null when the board was not judged
versions[].label, notesA name and notes you give the version. Changing them builds nothing.
variations[]Saved sets of the rack's knobs: {id, name, macros, when}, in the order they were saved
chat[]The conversation, one entry per turn. The last 200 turns are kept.
importedOn a project read from a bundle: {at, from, app_version}
auto_nameThe project is named from its prompt, and is renamed after its first board
exampleThe project is shown under Examples on the projects page

The chat

Each turn records what was said (you), the answer (bot) and the version it made. A question makes no version, so its version is "".

Extra fieldMeaning
kind: "note"The app started the turn: a rebuild, a route-again, or a file read in
error: trueThe turn failed before it answered. bot holds the reason.
firstA revised build made two versions. The entry keeps the revision as version and the first as first.
stepsThe build log the page showed: each stage as {phase, at, s}, with s its seconds

GET /api/projects/<slug> merges the chat with the version table, so the thread reads back whole. Older projects work too:

  • A project from before replies were kept reads back from its versions.
  • A note from before the kind tag is recognised by its wording, such as rebuilt with…, routed again from… or imported….

How writes stay safe

  • project.json, draft.json and a rejudged board.json are written to a temporary file, which then replaces the old one.
  • A new version's files are written into a fresh directory, and the version table names it only once they are all there.
  • Every change re-reads project.json under a per-project lock first. The app and the command line cannot lose each other's updates.
  • A version id counts the versions on disk, under the lock. A directory already standing at the next id is left over from a build that died, and it is deleted first.
  • A project.json that cannot be read is still listed, with the reason. Nothing writes to that project until the file is restored.

The format number

format is the layout's version, separate from the app's version. The app reads projects up to its own FORMAT, which is 2.

  • An older project is migrated the first time it is read. The original is kept beside it as project.json.pre-format1.
  • A newer project is refused with a message and left out of the list.

Each migration step is one function in soldermask/projects.py.

FormatWhat changed
1The original layout: name, created, current, versions
2description, tags and archived on the project; app_version, label and notes on each version

Files in a version

The app sorts a version's files into kinds:

KindFiles
appdesign.json, board.json, inspector.html
gerber.gtl .gbl .gts .gbs .gto .gbo .gtp .gbp .gm1 .gko .drl .gbr, and inner copper (.g1, .g2 and so on)
assembly-BOM.csv, -CPL.csv (and any .xlsx)
kicad.kicad_pcb
router.dsn, .ses
previewboard.svg
otherEverything else, including meshes.json, sim.json, .kicad_pro and .kicad_sch

gerbers.zip holds the gerber and assembly kinds only.

Rejudging a version

A version's files never change, with one exception: its verdict. soldermask projects rejudge checks every stored version's copper again with kicad-cli's DRC. Name a project after it to check only that one.

  1. Where the answer moved, it writes a new board.json with the new verdict and a rejudged record.
  2. The first board.json is kept as board.json.before-rejudge, and never overwritten.
  3. The version's row in project.json takes the new passed.

Add --dry-run to see what would change and write nothing. Naming a version (label, notes) is the only other change to a row.

draft.json

draft.json is the one file in a project that changes in place. It is why a drag on the board does not cost a version.

{ "base": "v004", "constraints": { "pinned": { "J1": { "x": 4, "y": 22.5, "rot": 90, "by": "human" } } },
  "touched": 1788451932.35 }
  1. You drag a part. About a second later, the new pin is saved here.
  2. You rebuild. The build writes the constraints into the new version's design.json.
  3. The draft is deleted.

base is the version the edits amend. A pin dragged onto v004 does not follow you to v002: v002 keeps the constraints it was built with. A fork copies a version directory, so it takes the built constraints and none of the draft.

Bundles

export.zip is the project's directory, zipped as it is: project.json, draft.json if there is one, and every version the table names.

Left out of a bundle: .work/, proposal.json, .proposal/, *.tmp and project.json.pre-format*.

Importing checks the whole zip before writing anything:

  1. Every file must be one of those names, or under a vNNN/ the table lists.
  2. Every listed version must have a design.json and a board.json that parse.
  3. current must be in the table, and a draft.json must amend a version that is there.
  4. The zip may hold at most 10,000 files and 1 GB unpacked, counted as it unpacks.
  5. The zip unpacks to projects/.import-*, then moves into place. A refused zip leaves nothing behind.

Files inside a version whose names start with a dot are skipped, as are __MACOSX, .DS_Store and Thumbs.db.

A zip you made by hand, with one wrapper folder (and the Mac's __MACOSX beside it), is accepted and the wrapper removed.

Trash

  • Delete moves the project to projects/.trash/<slug>-<timestamp>.
  • Restore moves it back under its slug, with a suffix if the slug is taken.
  • Empty trash deletes for good. It is the only destructive action in the app.

On this page