Import a Device with artwork and pin allocation
Prepare the bundle
Ask your AI assistant to use the Device Definition guide and version 1.1 schema. Supply your own clear, top-down photograph and the exact board model and hardware revision.
Ask for these three separate files:
device-definition.json: researched hardware details, pin allocation, artwork metadata and source references.- Your unchanged original image, for example
board-top.png. board.svg: the generated pure-vector drawing, including the matching physical contacts.
Keep these files together. The source and SVG filenames must exactly match artwork.source_artwork.file_name and artwork.device_svg.file_name. Use simple filenames without spaces or directories. Upload the files separately; a ZIP is not required.
The manifest must contain real file sizes and SHA-256 hashes calculated after the files have been generated. Example manifests contain illustrative hashes and cannot be imported with unrelated artwork. In PowerShell, you can check a file with:
(Get-FileHash -LiteralPath '.\board.svg' -Algorithm SHA256).Hash.ToLowerInvariant()
(Get-Item -LiteralPath '.\board.svg').Length
If you edit the SVG afterwards, recalculate its hash and byte size in the JSON.
Copy the complete AI bundle prompt
Both Import device and Import/update JSON contain one Generate device JSON and board SVG with AI panel. Optionally enter a preferred official product page or datasheet URL, click Copy complete bundle prompt, paste it into an AI assistant and attach your clear top-down board picture in that conversation. Uploading the picture to Elementic does not send it to an AI service.
For an existing Device, the prompt already embeds the exact Device identity, assigned Microcontrollers and current contacts, including GPIO numbers, stable contact keys and existing hitboxes. The AI must return matching device-definition.json and board.svg files in one response. The public complete bundle prompt contains all matching and geometry rules.
Import in the backend
- Sign in to the website backend and open Catalog → Devices.
- Click Import device at the top of the list.
- Select the Device Definition JSON, Original source artwork and Generated board SVG.
- Click Validate and preview.
- Compare the original artwork with the vector drawing and orange pin rectangles. Hover over a rectangle to see its pin label and key. When the manifest supplies an affine source-to-SVG transform, the opacity slider overlays the source image at the recorded coordinates. Perspective transforms remain available in the manifest for external review; the web preview only overlays affine transforms.
- Check the pin table, electrical roles, GPIO/framework mappings, source links, assumptions and unresolved details.
- Click Save as draft. The normal Device editor opens.
The button is available to the site administrator and user groups that can create Devices, edit SVG content and edit pins. Creating a previously unknown Microcontroller additionally requires permission to create Microcontrollers.
The importer assigns the internal Device ID. The JSON must not choose a database or firmware Device ID.
SVG requirements
The SVG root must be:
<svg xmlns="http://www.w3.org/2000/svg"
width="1000pt" height="1000pt"
viewBox="0 0 1000 1000">
<!-- Pure vector board drawing and mandatory pin hitboxes -->
</svg>
Keep the background transparent. Center the complete board including connectors, preserve aspect ratio, and use SVG viewBox units for the pin rectangles. The import preview overlays the JSON hitboxes on the drawing.
hitboxes_embedded_in_svg must be true. Every pin has a direct rect child in the group elementic-pin-hitboxes, with its matching svg_hitbox_id. Its x/y/width/height exactly matches the authoritative pins[].hitbox value. Hitboxes and their ancestors cannot have transforms; transforms can still be used in visual board groups. Rectangles must be within the canvas and cannot overlap.
Export Plain SVG. The importer accepts vector shapes, text, groups, clipping and gradients from its allowlist. Remove scripts, embedded raster images, foreign objects, CSS/style blocks or attributes, animations, external resources and editor-specific elements/attributes. Use explicit presentation attributes such as fill, stroke and font-size. Recalculate the file hash after re-exporting.
The generated SVG may be up to 2 MiB through this upload form; the source artwork may be up to 10 MiB and raster sources may contain up to 40 megapixels. The manifest may be up to 1 MiB. PHP/web-server upload limits can impose smaller limits. PNG, JPEG and WebP sources are previewed. PDF and original SVG sources are retained privately and compared externally.
Review and publish
New Device imports map true device.connectivity.wifi, ethernet and mqtt declarations to the latest published matching feature revisions in Available project features. Those three capabilities are no longer stored as separate Device booleans. A missing published feature or MQTT without a declared network transport is rejected. USB serial, Bluetooth hardware and PoE remain physical board properties. Existing-Device pin updates leave feature assignments unchanged.
The import creates a Draft Device with an unpublished first SVG revision. Imported drafts are not included in the public Device Registry. New Microcontroller records start inactive; existing matching Microcontrollers are reused without overwriting their specifications.
The AI prompt provides the public Microcontroller catalogue. For a new Device, an exact entry is reused; an unknown part is proposed as a new inactive candidate that requires review. For an existing Device update, the prompt also contains the exact assigned controller identities. A similar name is not accepted as a replacement because package, memory and pin availability may differ.
Some historical catalogue records use an exact order code as name and a shorter product family as model. A legacy manifest that repeats the exact order code in both fields may be resolved only when manufacturer and exact part name identify one unique assigned/catalogue record. The preview reports this controlled alias. Partial, family-only or ambiguous name matches remain rejected.
In the Device editor:
- Review the Device details, connectivity and SRAM boundaries.
- Review each imported pin and its rectangle. Power, ground, reference, reset and debug contacts remain non-configurable. Pins with an unknown numeric GPIO keep their framework label and remain unavailable in Android until a reviewed numeric mapping is entered.
- Check the imported research through Download JSON manifest. The Imported device bundle section also lets authorized importers download the original artwork and original SVG.
- In SVG pin map, select the imported revision and review it. The pin cards show the pending imported values, including Left, Top, Width and Height, and the preview overlays those rectangles on the draft SVG. These pending values are read-only until publication. Click Publish SVG and pin map to activate the drawing and its matching interaction geometry atomically.
- Review any new Microcontroller in the catalogue and activate it when its details have been verified.
- Configure available project features, the build configuration and flashing method using their existing validation workflows. Imported USB identities and build settings are retained as research candidates; they do not approve a driver, compiler target or flashing method automatically.
- Set the Device status to Active and save when approved.
Physical contacts without usable GPIO mappings are retained for documentation and excluded from the Android-selectable registry ports. Fractional SVG coordinates are preserved.
Reimport and corrections
Uploading the exact same bundle again opens the previously imported Device. It does not duplicate contacts or overwrite subsequent manual corrections.
A different bundle with the same definition_id is rejected in the new-Device importer. To deliberately update existing contacts, use Import/update JSON in that Device's editor as described below.
Update pins on an existing Device
- Open Catalog → Devices, then edit the intended Device.
- Click Import/update JSON. The page shows the target Device name.
- Prefer a complete Device Definition 1.1 bundle: JSON manifest, unchanged source artwork and generated SVG. Its
pinsarray may contain only the contacts you intend to update or add. Legacy JSON-only 1.0 updates remain supported, but they cannot provide a jointly reviewed drawing and hitbox package. Uploaded files must match the declared hashes, dimensions and filenames. - Click Validate and preview. Review the Add, Update and Unchanged rows and every before/after field. Omitted existing contacts are counted and retained.
- Click Apply update. With an SVG bundle, this creates one unpublished SVG/pin-map draft and does not yet change active pins. A JSON-only legacy update applies the reviewed pin changes immediately.
- For a bundle, review the new revision under SVG pin map. Its pending pin cards and rectangle fields are shown without changing the active pins. Click Publish SVG and pin map to activate both in one transaction.
Updates match numbered contacts by Device + assigned Microcontroller + GPIO number. GPIO 0 is valid. Legacy pins without a controller assignment can be matched when the Device has exactly one assigned Microcontroller; multiple-controller Devices require explicit assignments. The manifest MCU manufacturer/model must match an existing assignment; an update does not create or replace Microcontrollers. On a mismatch, the site reports both the incoming identity and all assigned identities so the manifest or catalogue assignment can be corrected deliberately.
When a GPIO has multiple physical contacts, stable pin_key / manifest key values distinguish them. Ambiguous legacy contacts must be assigned stable keys before an update can proceed. Contacts without GPIO numbers, such as ground and supply contacts, match by stable pin key. A key that already belongs to a different GPIO/controller is rejected rather than silently remapping that contact.
Existing pin row IDs are preserved, maintaining project references. Missing contacts are not deleted. An omitted hitbox in a 1.0 manifest preserves existing coordinates. Device name, firmware Device ID, status, features, SRAM limits, build configuration, flashing method and MCU specifications are kept as configured. Use their normal editors to change them.
For a 1.1 bundle, the active SVG and active pin rows remain untouched until Publish SVG and pin map succeeds. Publication verifies that the live pin map has not changed since preview, preserves existing pin row IDs, overwrites listed fields by Device + Microcontroller + GPIO, adds new contacts and retains omitted contacts. A stale package is rejected and must be imported and reviewed again. Without an uploaded SVG, the legacy JSON-only update applies directly and the current drawing remains in use.
Troubleshooting an update import
No exact assigned Microcontroller match
This message means that the manifest describes a different Microcontroller from the one assigned to the Device being edited. It is an intentional identity guard, not a pin or SVG error. For example, a manifest containing STMicroelectronics STM32F103C8T6 cannot update a Device assigned to Espressif ESP8266EX.
- Generate the bundle from Import/update JSON on the intended Device so the copied prompt contains its exact assigned identities.
- Verify that the JSON file selected in the upload belongs to that Device; filenames alone are not proof of identity.
- Do not rewrite an MCU name merely to satisfy validation. If the physical Device really contains another controller, first add or assign the correct catalogue record and review that hardware change.
- The importer never silently replaces or adds a controller during an existing-Device pin update.
Rectangle fields are empty
Select the newest imported revision under SVG pin map. The editor automatically overlays its pending pin rows on the active pin list and fills Left, Top, Width and Height from pins[].hitbox. The selected pending package is read-only until publication. If values remain empty, verify that every version-1.1 pin has a complete hitbox and that its matching direct SVG rect has identical coordinates and ID. Reimport the corrected JSON and SVG together; do not repair only one half of the package.
The updater checks that neither the target Device nor the files changed since preview. If they changed, preview again. Repeating the same completed request does not apply it twice. A new, deliberate preview can reapply JSON values over later manual edits.
Each update retains its full manifest, field differences, prior Device/pin snapshot, actor and optional files in private update history. The Device editor shows the latest update and download links. Update access requires both pin-edit and SVG-edit permissions; permission to create Devices is not required. Application rollback keeps this audit history. Restoring prior pin values is a separate, reviewed operation.
Version 1.0 data-only manifests remain supported. They can optionally include a separately selected board SVG that meets the same vector/canvas checks. Use version 1.1 for a source image, file hashes and pin hitboxes.
The original files and full manifest are retained on the private device-imports disk. Downloads require authentication and import permission. Source files are never automatically copied into public storage.
Installation and rollback
Deploy the application files and the bundled schemas, then run the additive migration:
php artisan migrate --force
php artisan route:clear
php artisan view:clear
php artisan config:cache
The migration adds import provenance and pin identity/role fields, permits contacts without GPIO numbers and preserves fractional rectangle coordinates. It preserves existing Device and pin data.
Build the configuration cache on the destination host using its existing .env. This preserves its application encryption key and avoids leaving the web application dependent on uncached environment loading. Do not generate a new application key for this deployment.
If the application needs rollback, restore the previous application files and clear the application caches. Keep the additive database changes and the private import files. Do not run a destructive database rollback: imported contacts and source evidence must remain recoverable.