Project Anatomy

An Embedr project is a normal folder with one extra contract: embedr.yaml tells the app how to reason about the folder.

The canonical firmware project

A new PlatformIO-backed project created by Embedr looks like this:

blink/
  embedr.yaml
  platformio.ini
  .gitignore
  src/
    main.cpp
  lib/

embedr.yaml is the Embedr manifest. platformio.ini is the PlatformIO workspace file used by the firmware runtime. src/ contains source code. lib/ is for project-local libraries.

The .pio/ directory appears after builds. It is generated output and should not be committed.

embedr.yaml

The manifest contains project metadata and capability declarations. For a simple firmware project it includes:

manifest_version: 1
name: blink
version: 0.1.0
board:
  platform: atmelavr
  board: uno
  framework: arduino
build:
  monitor_speed: 115200
components: []
connections: []

The top-level board block is kept for compatibility and simple projects. Newer projects can also use capabilities.firmware to describe explicit targets and actions.

platformio.ini

PlatformIO performs the actual firmware build. For simple projects, Embedr generates or updates platformio.ini from the selected target and target settings.

Example:

[env:uno]
platform = atmelavr
board = uno
framework = arduino
monitor_speed = 115200

If the project uses platformio.ini as workspace truth, changing the active environment can change which board config Embedr reads.

Source files

Embedr supports common firmware and project files, including:

• .ino, .c, .cpp, .h, .hpp,
• .md, .json, .yaml, .yml, .toml,
• .zen for hardware source,
• images such as .png, .jpg, .webp, .svg.

The editor uses Monaco for code, a markdown preview for markdown, and image preview for image files.

Datasheets

When you import a PDF datasheet, Embedr writes processed files into the project, usually under:

datasheets/
  Component-Name/
    Component-Name.md
    images/
      pinout.png

The datasheet index used by the agent is stored in app data, but the actual markdown and images stay in the project. Commit those files if they are useful project documentation.

PCB workspace

The schematic and PCB workflow uses a pcb/ workspace inside the project. It is the hardware design layer of the same embedded stack.

pcb/
  pcb.toml
  boards/
    main.zen
    layout/
      layout.kicad_pcb
      layout.kicad_pro

The .zen file is the source you edit and review. Generated KiCad layout files are produced when the workspace is built, synced, placed, or routed.

Managed versus linked projects

You can create a project from Embedr or open an existing folder. A created project is managed by Embedr in the sense that the app knows where it created it. A linked project is an existing folder you choose.

Either way, the source of truth is the folder on disk. Embedr does not require a private project database to open your code.

Legacy projects

Older Embedr projects may have a root .ino file and no embedr.yaml. The toolbar can show Migrate Project when it detects that shape.

Migration creates embedr.yaml, moves or copies the source into src/, creates a PlatformIO-compatible structure, and removes the legacy root .ino when requested. Review the result with version control if the project matters.

What to commit

Commit:

• embedr.yaml,
• platformio.ini,
• src/, include/, lib/,
• project docs,
• useful datasheet markdown and images,
• .zen hardware source,
• reviewed KiCad board files when they are part of your handoff or fabrication flow,
• hand-edited hardware or project metadata.

Usually do not commit:

• .pio/,
• build artifacts,
• temporary logs,
• OS files such as .DS_Store.

A useful rule

If a file describes intent, commit it. If a file is produced by a tool from other files, check whether it is reproducible before committing it.