soldermaskdocs

Projects

The projects page lists every board on this machine. Start a new board here, or pick one to open, fork, export or archive it.

A project is one board and its history of versions.

The page has three parts, and only the list scrolls:

PartWhereWhat it holds
The ledgerLeftEvery board, one row each, with the command line at the top
The discRightThe selected board: its picture, its checks, its versions and its actions
The footBottomWhat this machine can do, and what it is building now

Click a row to select it, and the disc follows.

Keys

KeyDoes
J / K or ↓ / ↑Select the next or previous board
Enter, or double-click a rowOpen the selected board
FFork the selected board
/, or Space twiceGo to the command line
EscLeave the command line. On a phone, shut the disc.

Making one

There are five ways to start a project.

Start fromHowWhat happens
A sentenceType it on the command line and press Enter (Shift+Enter for a new line)The workbench opens with the build running
A design.jsonOpen a file, or drop it anywhere on the pageBuilt without calling the model
A finished .kicad_pcbOpen a file, or drop itRead and shown. Nothing is designed, priced or routed.
A project .zipOpen a file, or drop itThe whole project comes back. Nothing is built.
NothingFill in Name and leave the prompt emptyAn empty project. Its first message builds v001.

From a sentence. Without a name, the project is named from the first words of your prompt. When the first board arrives, it takes the board's own name from the model.

From a design.json. The file is in the design format, for example one saved by the command line or edited by hand. Use it when no model is set up, or to rebuild a board exactly.

From a .kicad_pcb. The parts, their positions and the nets come across. The traces do not. It answers in about a fifth of a second. What did not happen shows on the board:

  • The checks say ERC not run and Route off, and the cost says not priced.
  • The gaps say the parts are this file's footprints, not orderable parts.
  • The notes list each choice made on the way in, such as parts brought up from the back or rotations snapped to a quarter turn.

A board this pipeline cannot build is refused, with the reason:

Refused whenLimit
Copper layersNot two
SizeUnder 8 mm or over 150 mm on a side
FootprintsFewer than 3 or more than 120
NetsFewer than 2
PackagesAny ball grid array

From a project .zip. Use a project exported from another machine, with Export .zip on the disc or Every version and the thread in the workbench's Export menu. Every version, the draft and the conversation come back. See Exports and files.

Fork. Fork from the disc, with F on a selected row, or from any version in the workbench's version menu. The fork starts at v001 with a copy of the chosen version, and records parent: <project>/<version>.

Pinning the microcontroller

Pin the board's microcontroller module before you describe the board. The build then uses exactly that module.

  1. Type @ on the command line, or press @ MCU. The roster opens: five modules, each with its family, LCSC code, price and stock.
  2. Type to filter it. ↑ / ↓ move, and Enter or Tab pins. Esc closes the roster.
  3. The pinned module shows as a token in front of your words. The line under it says what the token resolves to.
  4. Check the module on the disc: its 3D model (drag to turn it), size, price, stock, power rails, antenna keepout and mount.
  5. Choose the mount: soldered down on its own pads, or on headers where the module allows it.
  6. Type the rest of your prompt and press Enter.

Click the token to see the module again. Its × unpins it.

Why a list and not a search. Every other part is found by searching JLCPCB, which suits a 10 kΩ resistor: forty of them will do. A module's exact identity decides the pinout, the footprint, the power rails and half the layout. It is also the part the search loses most often. Pinning it turns that search into a lookup by LCSC code.

soldermask/platforms.py holds only what no CAD data carries:

  • which symbol has the pin names
  • how the module may be mounted
  • what its rails can supply
  • where copper may not go

Geometry, price, stock and the 3D model come from the same live lookup as every other part.

The roster stays off until GET /api/platforms answers.

The ledger

Each row is one board. It shows the name and its flags (example, archived), and the current version's summary. It also shows the build's state, the version, the cost of one board and when it last changed.

The build state is the verdict, in the workbench poll's words and colours. After the word comes the first station that did not pass. Hover it for the full sentence.

StateMeans
GOThe build's own check passed
NO-GO · Copper 4 errThe build's own check failed. The station that holds is named.
UNJUDGED · ERC not runNothing failed, but a check the verdict needs did not run
UNJUDGED · no verdictBuilt before verdicts existed. Rebuild it to judge it.
unjudged · from a fileRead from a file. Nothing was checked, routed or priced.
no build yetAn empty project
A phase and secondsA build is running on this board now

Gaps and ERC warnings do not change the state. They are advisories, and the disc counts them.

Facets, filter and sort

Above the rows, the facets filter the list: All, GO, NO-GO, Unjudged and Examples, each with its count. Archived is a separate toggle. Archived boards stay hidden until it is on.

  • The filter matches name, summary, description and tags.
  • Sort by recent, name, cost or number of versions.

Examples

Examples are rows with an example flag and their own facet. On the disc, an example's first action is Fork & edit. Your fork is your own board, and it does not keep the flag.

Flag a board you have checked yourself with PATCH /api/projects/<slug> {"example": true}.

Live builds

A build running on any project, from any device, shows in its row as the phase and the seconds. A build whose row is hidden by a filter shows as a row above the list. The page checks GET /api/app every 3 seconds while a build runs, and every 30 seconds otherwise. The list reloads when a build finishes.

The disc

The disc shows the selected board.

  • The picture is the current version's board, drawn in one colour: outline, pads, copper, silkscreen and the pour's edge. The back layer is dimmer, and unrouted connections are dashed.
  • The corners show the build state, the version, the date and the part count.
  • The readout lists the verdict, any station that holds or did not run, the advisories, the parts and the cost.
  • The versions list, newest first, links each version into the workbench, with its state and cost.

The actions:

ActionDoes
OpenOpens the board in the workbench. An example offers Fork & edit first.
ForkStarts a new project from the current version
Export .zipDownloads the whole project as one file
RenameChanges the name and the description
Archive / UnarchiveHides the board unless the Archived toggle is on
DeleteMoves the project to the trash. The foot's trash chip restores it, or empties the trash for good.

The row's state, the picture's state and each version's mark come from one rule, so they always agree.

The verdict is the build's, not a fresh check

The verdict is what the build's own check said when the version was saved. A version built before verdicts existed, or read from a file, reads unjudged. Rebuild it to judge it. Nothing on this page re-runs KiCad's DRC. soldermask projects rejudge runs KiCad's DRC again on saved versions' copper, and the page then shows the new verdict. See Versions and history.

On a phone, the disc is a sheet along the bottom. Tap its grip to open it.

The foot

The foot shows this machine as a row of chips. Each has a line under it in its state's colour. Hover a chip for what it means, or why it is not green.

ChipShows
LightcycleThe version of Lightcycle, the default router, or missing
A*Whether the A* router is ready. It routes a board that names it, or when Lightcycle is not built.
kicad-cliThe version of KiCad's command line, the DRC judge and renderer
modelThe model that will design boards, or none
catalogueParts on disk, and the day the catalogue was built
runningBuilds under way
boardsHow many projects there are
trashDeleted projects. Click to restore one, or to empty the trash.

All of it comes from GET /api/app.

The note under the command line

It names the model that will design boards, such as claude-code · claude-fable-5-2, or says why there is none. Without a model you can still open a design.json. If no router is ready, it says boards will save unrouted.

On this page