Project Manifest

embedr.yaml is the contract between your project folder and Embedr.

It tells the app:

project name and metadata,
source hints,
firmware target or custom actions,
build settings,
components and connections,
PCB capability state.

Minimal PlatformIO-backed manifest

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

This is enough for a normal Embedr CLI project.

Source hints

Use source when the main file is not obvious:

source:
  entry: src/main.cpp
  source_dirs:
    - src
  include_dirs:
    - include

Hints help the app and agent orient themselves.

Firmware capability

Manifest v1 can describe firmware more explicitly:

capabilities:
  firmware:
    enabled: true
    provider: embedr-cli
    target_id: esp32
    environment: esp32dev
    device_port: /dev/cu.usbserial-0001

provider: embedr-cli means Embedr should use its managed CLI and PlatformIO-backed build flow.

Named firmware targets

Use named targets when one project supports multiple build profiles:

capabilities:
  firmware:
    provider: embedr-cli
    active_target: esp32-devkit
    targets:
      esp32-devkit:
        label: ESP32 DevKit
        provider: embedr-cli
        target_id: esp32
        board:
          platform: espressif32
          board: esp32dev
          framework: arduino
        build:
          monitor_speed: 115200

The toolbar and CLI can resolve the active target and environment from this data.

Custom firmware actions

Not every embedded repo is a PlatformIO project. A custom project can declare shell actions:

capabilities:
  firmware:
    enabled: true
    provider: custom
    actions:
      build:
        command: make
        cwd: .
        timeout_ms: 600000
      flash:
        command: make flash
        cwd: .

When provider is not embedr-cli, Embedr runs the configured action instead of assuming PlatformIO.

Use custom actions for Zephyr, Make, CMake, Rust embedded, vendor SDKs, or internal build systems.

PCB capability

A PCB workspace can be described as:

capabilities:
  pcb:
    enabled: true
    workspace: pcb

If pcb/ exists, Embedr can also infer PCB capability during runtime inspection.

User-facing work happens through the app, CLI, agent, .zen source, generated KiCad files, and PCB automation.

Components and connections

components and connections are for project-level hardware references:

components:
  - id: led-5mm
    version: latest
    instance: status_led

connections:
  - from:
      component: status_led
      pin: anode
    to:
      component: arduino
      pin: D13
    wire_color: red

This model is useful because it gives the app and agent a project-level hardware map. It can describe parts before a schematic exists, keep examples understandable for students, and connect docs, firmware, and hardware intent.

Use component ids from the component library when possible. Free-form names are readable, but library-backed ids are easier for the agent to connect to datasheets, footprints, symbols, and .zen snippets.

Editing the manifest safely

Rules:

keep name stable and valid,
do not delete board unless a custom action replaces PlatformIO,
keep platformio.ini and manifest target values consistent,
review generated YAML after agent edits,
compile after changes to target or build settings.

When in doubt, ask the agent to inspect the manifest and explain what each block does before editing it.