AI Device Definition import format
Purpose
The Elementic AI Device Definition is a source-backed JSON format for proposing a new hardware Device. It is designed so an AI assistant can research public hardware documentation and return one predictable document for validation and backend import.
This is an input format. It is separate from the read-only Device Registry API, which publishes reviewed Elementic catalogue records and server-assigned IDs.
Canonical public resources:
- Current schema (device data, artwork and pin geometry):
https://elementic.app/spec/device-definition/1.1/schema.json - Current example:
https://elementic.app/spec/device-definition/1.1/example.json - Public Microcontroller catalogue:
https://elementic.app/assets/microcontrollers.json - Legacy data-only schema:
https://elementic.app/spec/device-definition/1.0/schema.json - This guide:
https://elementic.app/docs/device-import/ai-device-definition
AI instruction
Give an AI assistant the following instruction:
Research this hardware Device using primary manufacturer documentation, official framework documentation and official repositories where possible. Read and obey the Elementic schema at
https://elementic.app/spec/device-definition/1.1/schema.jsonand the guide athttps://elementic.app/docs/device-import/ai-device-definition. Use the image supplied by the user as source artwork; never replace it with a guessed board image. Produce an import bundle containingdevice-definition.json, the unchanged source artwork and one pure-vector board SVG. Never invent a value. Usenullwhere permitted, record unresolved facts inresearch.unknowns, record every inference inresearch.assumptions, and connect factual sections to entries insourcesusingsource_refs. Treat PlatformIO settings, USB identities, electrical pin mappings, SVG geometry and SRAM boundaries as unverified candidates until reviewed and physically tested.
Append the exact device name, model and variant to that instruction. An AI may browse the internet, but the resulting JSON remains untrusted input.
Required behavior
- Use official sources before community sources.
- Use HTTPS source URLs and record the retrieval time.
- Express memory sizes in bytes.
- Express USB VID and PID as uppercase four-digit hexadecimal strings such as
0x0483. - Use
framework_pinfor framework symbols such asPC13; do not invent an integer GPIO number. - Give every Microcontroller a document-local
ref. MCU-connected pins refer to that value throughmicrocontroller_ref; usenullfor board-level power, ground or other contacts that do not map to one MCU pin. - Search the Elementic Microcontroller catalogue before defining a controller. If the exact physical part is represented, copy its
manufacturer,nameandmodelexactly. The catalogue helps identify an existing record but is not evidence for which part is fitted to the board; confirm that with official sources. - If no exact catalogue entry exists, keep the researched hardware identity and recommend a new inactive catalogue candidate for review. Never substitute a similar family member or rewrite a part number merely to make an import pass.
- For an existing Device update, the generated site prompt lists the Microcontrollers already assigned to that Device. Use those exact identities. If the fitted part differs, stop and correct the catalogue assignment before importing.
- Historical manifests may repeat an exact order code in both
nameandmodel, while an older catalogue record stores a shorter family inmodel. The importer accepts this only when manufacturer plus exact part name resolve one unique record and reports the alias in preview. AI should still emit the current catalogue fields exactly. - Supply exactly one primary Microcontroller. This cross-record rule is checked by the importer because JSON Schema cannot express it clearly.
- Keep
research.statusequal tounreviewed-draftandbuild_candidate.statusequal tounverified. - Do not include credentials, private URLs, executable scripts, binary data, inline SVG markup or server database IDs in the JSON document. Artwork is delivered as separately uploaded files referenced by safe bundle-local filenames and SHA-256 hashes.
Import bundle and user artwork
Version 1.1 adds artwork and pin geometry while leaving the 1.0 data-only contract available. A complete upload contains:
device-definition.json
<user-supplied-source-image>
<generated-device-name>.svg
The user supplies the source image and declares the right to use it. Prefer a sharp, top-down image with the complete board, all protruding connectors and all physical contacts visible. The source file remains unchanged and private unless the reviewer explicitly approves publication. Its filename, MIME type, byte size, dimensions and lowercase SHA-256 hash are recorded in artwork.source_artwork.
The JSON document is the manifest and electrical proposal; it does not carry base64 files. The backend must recalculate both hashes from the uploaded bytes, reject missing or extra files, reject directory paths in filenames and keep the upload in a draft quarantine area.
SVG contract
The generated file referenced by artwork.device_svg must:
- use
width="1000pt",height="1000pt"andviewBox="0 0 1000 1000"; - use one uniform scale, center the complete silhouette including connectors and retain a transparent background;
- contain vector primitives, editable text or paths only, with no embedded raster image;
- use stable named groups such as
pcb,contacts,components,silkscreen,debug-contactsandelementic-pin-hitboxeswhere applicable; - contain no scripts, event handlers,
foreignObject, external URLs, remote fonts or active content; - remain
pending-server-validationuntil the server independently parses, sanitizes and renders it.
The original upload is evidence and comparison material. It must never be silently substituted for the SVG in the Android device view.
artwork.geometry_provenance records how the vector was produced, the generator/version, a row-major 3×3 source-to-SVG transform when available, overall confidence and every manual geometry override. Confidence is review metadata, never proof of accuracy.
Pin allocation and hitboxes
pins is the authoritative structured pin map. Every physical contact receives a stable key, independent physical number or label, board/MCU mapping, electrical role, capabilities, alternate functions and source references. Power, ground, reset, analog-reference and debug contacts must not be represented as freely configurable GPIO.
For an existing Device, the update identity for an ordinary numbered contact is Device + Microcontroller + gpio_number. This is deliberately independent of the display label and pin_key: renaming a unique GPIO updates the existing row instead of creating a duplicate, and its database ID and project references survive. GPIO 0 is a valid key. If one GPIO is exposed at multiple physical contacts, the stable key disambiguates those contacts and their separate hitboxes. Contacts without a GPIO match by stable key.
Every pin also has:
hitbox:x,y,widthandheightin SVG viewBox user units from 0 through 1000, with the origin at the upper left;svg_hitbox_id: the matching SVG element ID, normallyhit-<pin-key>;side: physical placement on the board;configurable: whether the contact may be selected as ordinary user I/O;mapping_status:unverified,source-verifiedorphysically-verified.geometry_confidenceandmapping_confidence: independent 0–1 review hints for placement and electrical mapping.manual_override: whether a reviewer changed the proposed pin record.
The SVG must include one transparent rectangle per pin directly under elementic-pin-hitboxes. Its ID and geometry exactly match svg_hitbox_id and pins[].hitbox; hitboxes_embedded_in_svg is true. The JSON rectangle remains authoritative because Android consumes validated structured geometry instead of SVG DOM events or JavaScript. The importer rejects duplicate pin keys and hitbox IDs, rectangles outside the viewBox, overlaps, missing/mismatched SVG elements and unresolved MCU/source references. Alternate functions describe mutually exclusive mux choices and must not imply simultaneous use.
Backend import policy
The website backend supports this workflow under Catalog → Devices → Import device. Existing Devices expose Import/update JSON in their editor, with an explicit pin-difference preview. See Import a Device for upload, matching, SVG requirements, review, troubleshooting and publication instructions. Exact new-Device reimports preserve manual corrections. A JSON+SVG update is staged as one unpublished package. The Device editor selects the newest revision and projects its pending pin values, including all four hitbox coordinates, into read-only pin cards and the SVG overlay. Publish SVG and pin map then atomically activates the drawing and listed pin changes after a stale-state check. Omitted contacts remain. Legacy JSON-only updates still apply directly.
The backend must treat every submitted document as hostile, unreviewed data even when it passes JSON Schema validation.
Import must:
- Enforce request-size, JSON-depth and collection-count limits.
- Validate against the exact
format_versionschema. - Reject duplicate source IDs, Microcontroller refs and pin keys.
- Verify that every
source_refsand non-nullmicrocontroller_refvalue resolves inside the document. - Require exactly one primary Microcontroller.
- Normalize USB hex strings to unsigned 16-bit integers.
- Map only documented driver keys to compiled Android drivers; never load a class or execute code named by JSON.
- Create or update draft import records only. It must not publish a Device, approve a Flashing Method, compile, sign or flash firmware automatically.
- Show sources, assumptions, unknowns and field differences to a human reviewer.
- Allocate Elementic Device and database IDs on the server; imported JSON never chooses them.
- Recalculate asset hashes, inspect actual MIME content, enforce file/pixel/decompression limits and isolate image/vector decoding work.
- Parse SVG as XML, apply an allowlist sanitizer, render a safe preview and compare the source/SVG overlay before approval.
- Validate the exact 1000-unit coordinate contract, pin bounds, unique IDs and geometry-to-SVG correspondence.
- Keep source artwork private by default and verify artwork/logo publication rights separately from factual source citations.
VID/PID is a discovery hint, not proof of hardware identity. A runtime connection is confirmed using the Elementic protocol Device ID. Bootloader and programmer identities require the separate immutable, signed Flashing Method workflow.
Versioning
format_version uses MAJOR.MINOR syntax. Versions 1.0 and 1.1 are strict and reject unknown properties so AI spelling mistakes become visible. Version 1.0 contains researched device data only. Version 1.1 adds the separately uploaded source artwork, normalized SVG and pin hitboxes. A compatible additive change publishes a new minor schema URL. A breaking change publishes a new major URL. Importers must validate against the URL and version explicitly supplied by the document and must not silently reinterpret another version.
Example
The 1.1 public example describes an unreviewed Blue Pill candidate plus illustrative asset metadata and one pin hitbox. Placeholder hashes demonstrate the shape of the contract and are not downloadable board assets. A real bundle must contain files whose bytes match its manifest. The example deliberately includes assumptions and unknowns to demonstrate that research and geometry uncertainty remain visible. It is not a published compatibility approval.