gizmogit/v1

gizmo.yaml

One file at the root of a hardware repo, describing what the thing is and what it is made of. That is the whole trick: once a project is machine-readable, it can be indexed, priced, rendered, diffed, forked — and remixed by an agent that never opens your CAD tool.

Indexable

Search by platform, license, cost, difficulty, process.

Renderable

Viewers know which file is the board, the schematic, the mesh.

Reproducible

A BOM with distributor references resolves to a real cart.

Fields

Field	Type	Required	Notes
apiVersion	"gizmogit/v1"	required	Pins the manifest to a schema version.
name	string	required	URL slug inside the owner namespace. Lowercase, digits, dashes.
title	string	required	Human name shown on the project card.
version	string	required	Design revision. Reproduction reports are keyed to it.
summary	string ≤280	optional	One line. This is what search results show.
license	SPDX id	optional	Defaults to CERN-OHL-S-2.0.
tags	string[]	optional	Free-form facets: platform, function, process.
difficulty	beginner \| intermediate \| advanced	optional	Sets expectations before someone orders parts.
build_time_minutes	int	optional	Your estimate. Reproduction logs replace it with the real median.
mechanical	object	optional	Master CAD, printable meshes, process, material.
electronics	object	optional	PCB, schematic, gerbers, layer count, board size.
firmware	object	optional	Platform, toolchain, source directory, flash command.
bom	BomLine[]	optional	Every part, with distributor references and unit price.
manufacturing	object	optional	Fab preferences: vendor, finish, thickness, assembly.
media	object	optional	Cover image, gallery, demo video.
forked_from	owner/name@version	optional	Set automatically when you fork.
links	record<string, url>	optional	Repository, docs, papers, store pages.

gizmo.yaml

apiVersion: gizmogit/v1
name: sidekick
title: Elato Sidekick
version: 2.1.0
summary: Pocket-sized always-listening AI companion.
license: CERN-OHL-S-2.0
tags: [esp32-s3, audio, ai, 3d-printable]
difficulty: intermediate
build_time_minutes: 120

mechanical:
  enclosure: mechanical/sidekick-shell.step
  printable:
    - mechanical/shell-base.stl
    - mechanical/shell-lid.stl
  process: FDM
  material: PETG

electronics:
  pcb: electronics/sidekick.kicad_pcb
  schematic: electronics/sidekick.kicad_sch
  board: electronics/board.json      # normalized geometry for the 3D viewer
  gerbers: electronics/gerbers/
  layers: 4
  size_mm: [46, 32]

firmware:
  platform: esp32-s3
  toolchain: esp-idf
  source: firmware/
  flash: idf.py -p /dev/ttyACM0 flash monitor
  language: C

bom:
  - ref: [U1]
    mpn: ESP32-S3-WROOM-1-N8R2
    manufacturer: Espressif
    description: Wi-Fi + BLE module, 8MB flash, 2MB PSRAM
    qty: 1
    price_usd: 3.60
    package: SMD-41
    sources:
      lcsc: C2913202
      digikey: 1965-ESP32-S3-WROOM-1-N8R2CT-ND
      mouser: 356-ESPS3WROOM1N8R2
  - ref: [U5]
    mpn: W25Q128JVSIQ
    qty: 1
    price_usd: 1.02
    optional: true                    # excluded from the headline build cost

manufacturing:
  pcb:
    vendor: JLCPCB
    finish: ENIG
    thickness_mm: 1.6
    copper_weight_oz: 1
    assembly: true
  enclosure:
    process: FDM
    material: PETG

media:
  cover: media/cover.png
  gallery: [media/exploded.png]

links:
  repository: https://github.com/elato/sidekick
  docs: https://elato.io/sidekick

Board geometry

EDA formats are not viewer formats. An importer normalizes a .kicad_pcb (or Altium, or EasyEDA) once into a neutral JSON description — outline, stackup, copper, pads, vias, silkscreen, placed parts and DRC results. Every viewer, thumbnailer and agent then reads the same thing, and adding a new EDA tool means writing one importer rather than one renderer.

electronics/board.json

{
  "version": 1,
  "units": "mm",
  "outline": { "shape": "rect", "width": 46, "height": 32, "corner_radius": 3 },
  "thickness": 1.6,
  "layers": 4,
  "stackup": "Standard 4 Layer",
  "colors": { "soldermask": "#0f7a48", "silkscreen": "#eef1ee" },
  "tracks": [{ "layer": "top", "width": 0.25, "points": [[-8, 4], [-2, 4], [2, 0]] }],
  "pads":   [{ "x": -9, "y": 2, "w": 1.5, "h": 0.6, "shape": "rect", "layer": "top" }],
  "vias":   [{ "x": 3, "y": -2, "d": 0.7, "drill": 0.35 }],
  "holes":  [{ "x": -20, "y": 12.5, "d": 2.2, "pad": 4 }],
  "silk":   [{ "type": "text", "x": 0, "y": 15, "text": "SIDEKICK", "size": 2.4 }],
  "components": [
    { "ref": "U1", "model": "rf-module", "x": -9, "y": 2, "rotation": 90,
      "layer": "top", "size": [25.5, 18, 3.1], "mpn": "ESP32-S3-WROOM-1" }
  ],
  "checks": [
    { "level": "warning", "code": "clearance",
      "message": "Track to board edge 0.18 mm", "x": -21, "y": -4 }
  ]
}

Components carry a model archetype — chip, soic, qfp, module, rf-module, electrolytic, header, terminal, tactile, usb-c, to220, oled, led, crystal… — so a board renders recognisably before anyone has uploaded a single STEP model. Real per-MPN models replace the archetypes as a parts backend fills in.

Sourcing and fabrication

A BOM line without a distributor reference is a dead end. Each line carries an MPN plus whatever distributor part numbers you know, and the registry resolves them into a cart, flags obsolete parts, and re-prices against live stock.

bom line

- ref: [C1, C2, C3]
  mpn: CL05B104KO5NNNC
  manufacturer: Samsung
  description: 0402 100nF X7R 16V
  qty: 3
  price_usd: 0.01
  package: "0402"
  sources:
    lcsc: C1525
    digikey: 1276-1006-1-ND

manufacturing

manufacturing:
  pcb:
    vendor: JLCPCB
    finish: ENIG
    thickness_mm: 1.6
    copper_weight_oz: 1
    assembly: true
  enclosure:
    vendor: Craftcloud
    process: SLA
    material: Resin

Reproductions

Stars measure interest. Reproductions measure whether a design works. After a build, report what it cost, how long it took, and whether it ended up functioning — the aggregate is the single most useful number on a project page.

terminal

gizmogit build log elato/sidekick \
  --version 2.1.0 \
  --cost 34.20 \
  --time 3h10m \
  --ok \
  --note "swapped the LDO for an AP2112K"

Failed builds count too, and are more valuable than successes — they are how errata get written.

HTTP API

The web app and the CLI use the same endpoints. Point GIZMOGIT_API_URL at a service and the registry layer proxies to it instead of the built-in store.

GET	/api/v1/devices	Search, filter and facet the registry
POST	/api/v1/devices	Register a project
GET	/api/v1/devices/:owner/:name	Full project record, manifest included
GET	/api/v1/devices/:owner/:name/manifest	gizmo.yaml, as a download
GET	/api/v1/devices/:owner/:name/bom.csv	BOM in fab-house column order
POST	/api/v1/devices/:owner/:name/fork	Fork into a new namespace
POST	/api/v1/import	Read a public GitHub repo and draft a manifest

Licensing

Hardware licenses are not software licenses. The manifest takes an SPDX identifier and the registry surfaces it everywhere, because “can I sell this?” is the first question anyone asks about a design they want to build on.

CERN-OHL-S-2.0Strongly reciprocal. Share your modifications the same way.
CERN-OHL-W-2.0Weakly reciprocal. Fine for a component inside a closed product.
CERN-OHL-P-2.0Permissive. Do what you like.
TAPR-OHL-1.0The older reciprocal hardware license, common in ham and robotics.

Publish a project