Development Project Data

Unreleased development workflow: Project Data is part of the reviewed 1.5.20 checkout. It is not a feature of stable 1.4.1. It maintains a project-local record and an explicit synchronization boundary with KiCad.

Create the first record

1. Save the active board as a KiCad project before opening Project Data.
2. Enter Project details such as project name, board name, project number and PCB part number.
3. Fill in the Revision draft: revision, hardware version, issue date, status, change summary, issued by and reviewed/approved by.
4. Choose Save project details to save the local record.
5. Inspect the generated KiCad variables list.
6. Use Preview KiCad changes to review exactly what synchronization would alter.
7. Choose Sync to KiCad when those values are ready to be written.

Changes are saved when you choose Save or Sync. Typing into the form alone is not evidence that either the local record or KiCad has been updated.

Data locations and scopes

The project-local kobee-project.json lives beside the KiCad project. Keep it in the project’s version control and backup with the .kicad_pro and board files. The personal library holds reusable field definitions and global defaults separately.

Scope	Typical data	Reuse behaviour
Global	Company name and website	Defaults available across projects
Project	Project/board names and part/project numbers	Values belong to this project
Revision	Revision, issue date, status and change summary	Draft values can become checkpoints

A reusable field definition can appear in many projects while each project’s value stays local. Reusing a field is different from sharing one mutable value across every board.

Save, sync and checkpoint are different actions

Action	Outcome
Save project details	Saves the local Project Data record
Preview KiCad changes	Shows proposed variable changes before applying them
Sync to KiCad	Saves/synchronizes the managed variable values into KiCad
Create checkpoint & sync	Creates a revision snapshot and synchronizes its values

Sync updates the generated managed names listed by the tool. Other KiCad text variables and native title-block fields are preserved. Do not expect a custom field to overwrite a native title-block property automatically.

If the status says KiCad sync pending, the local and KiCad states may not yet match. Retry synchronization after resolving the reported problem and inspect the preview again. A local save is not a successful KiCad sync.

Use the generated tokens

Select an entry and choose Copy selected token. Use that exact expression in a native KiCad text field or in Labels → Variables.

The reviewed naming scheme includes:

• ${KOBEE_GLOBAL_COMPANY_NAME} for the global company name.
• ${KOBEE_PROJECT_BOARD_NAME} for the project’s board name.
• ${KOBEE_REVISION} for the built-in revision.
• ${KOBEE_REVISION_YOUR_KEY} for an additional revision-scoped custom field.

Copy from the UI rather than guessing a prefix. Built-in revision fields have established names that differ from the general custom-field prefix pattern.

Add a custom field

1. In the relevant project or revision section, choose Add custom field….
2. Set a readable label and a valid, unique KiCad key.
3. Choose its type: text, multiline, date, URL, number, checkbox or choice.
4. For a choice field, supply the allowed choices. Add a useful default and help text.
5. Save it, enter the project-specific value and review the generated token.
6. Save/sync explicitly when ready.

Use Save local field as reusable… when the definition should appear in future projects. Remove reusable field… removes that reusable field from this project’s active use; check the resulting variable preview before synchronizing. Keep keys stable once artwork uses their tokens.

Revision checkpoints

Enter the current revision draft and choose Create checkpoint & sync when you want a recorded snapshot. The history list shows saved checkpoints and the active marker.

Use View selected details to inspect a past checkpoint. Restore selected to draft brings its values back for editing; it is not an automatic board rollback. Review and explicitly save/sync the restored draft. Delete selected… removes a history entry after confirmation, so retain a project backup before deleting important release history.

Statuses such as Draft, Prototype, Validation, Pre-production, Released, Superseded and Obsolete describe your record. Selecting Released in Project Data does not publish a package, deploy a site or verify a manufactured board.

Import and existing variables

If no Project Data record exists, use Import an existing Project Data record… to bring in one deliberately. A project with recognizable existing KOBEE_* variables can offer to adopt those values into a record. Review the resulting local fields and generated variables before synchronizing.

Import/adoption is not permission to replace unrelated KiCad variables. Always use the change preview, especially on a project that already uses text variables for other tooling.

Conflicts and damaged records

If a record changed outside the editor, follow the conflict/reload workflow instead of overwriting it blindly. If the file cannot be read safely, the UI stops normal writes and offers Back up unreadable record and start new…. Preserve the recovery copy and inspect it before discarding any project history.

Development Settings → Data & backup also includes a data-health scan and Back up listed files. Use it to preserve malformed/untrusted local records before repair. A health scan is diagnostic; it is not proof that all project metadata or KiCad variables are current.

Finish a revision

Save the local record, preview and complete KiCad sync, update placed variable artwork so its geometry matches current values, save the PCB, and inspect the final fabrication outputs. Commit the board/project files and kobee-project.json together when they describe the same revision. Keep the release’s Gerbers and screenshots as separate evidence of what was actually delivered.