Project Manifest

Field-by-field reference for embedr.yaml: project metadata, firmware targets, custom build and flash commands, components, datasheets, and how Embedr edits the file.

embedr.yaml sits at the root of every project. It names the project and tells Embedr how to build its firmware. The file is YAML; Embedr keeps keys it does not recognise, so you can add your own notes as extra keys.

Examples

A new Electronics + firmware project after a target has been picked:

manifest_version: 1
name: plant-monitor
version: 0.1.0
board:
  platform: espressif32
  board: esp32dev
  framework: arduino
build:
  build_flags: []
  lib_deps: []
  monitor_speed: 115200
capabilities:
  firmware:
    enabled: true
    provider: embedr-cli
    target_id: esp32
    environment: esp32
    active_target: esp32
    targets:
      esp32:
        label: ESP32 DevKit
        provider: embedr-cli
        target_id: esp32
        environment: esp32
        board:
          platform: espressif32
          board: esp32dev
          framework: arduino
components: []
connections: []

A new Electronics only project:

manifest_version: 1
name: sensor-breakout
version: 0.1.0
project:
  kind: electronics
components: []
connections: []

An existing Zephyr repository built with west:

manifest_version: 1
name: nrf-beacon
project:
  kind: custom
  language: c-cpp
source:
  source_dirs: [src]
  build_dir: build
capabilities:
  firmware:
    enabled: true
    provider: custom
    actions:
      build:
        command: west build -b nrf52840dk/nrf52840 app
      flash:
        command: west flash

Top-level fields

Field	Type	Default	Meaning
`manifest_version`	integer	none	Schema version. Use `1`. Must be 1 or higher.
`name`	string	required	Project identifier (see Name rules).
`version`	string	`0.1.0`	Your project's version.
`description`	string	none	Free text.
`author`	string	none	Free text.
`project`	map	none	Project metadata (`id`, `kind`, `language`).
`source`	map	none	Hints about where source lives.
`board`	map	none	The PlatformIO board, kept for older tools and simple projects.
`build`	map	see below	Build and serial settings.
`capabilities`	map	none	Firmware targets, custom commands and the PCB workspace.
`components`	list	`[]`	Parts from the component library used by the project.
`connections`	list	`[]`	Pin-to-pin wiring notes between components.
`datasheets`	list	none	Processed datasheets. Written by Embedr.
`discovery`	map	none	What `embedr manifest discover` detected. Written by the CLI.

Name rules

Embedr normalizes name to a safe identifier rather than rejecting the file:

Characters other than letters, digits, - and _ become -, and leading or trailing - and _ are dropped. 2 Parking Sensor becomes project-2-Parking-Sensor.
A name that does not start with a letter gets a project- prefix.
Words YAML could read as true, false or null (yes, no, on, off, true, false, null, y, n) also get the prefix.
An empty name becomes embedr-project.

The display name on the home screen comes from the folder, not from this field.

`project`

Field	Meaning
`id`	A UUID that identifies the project even if you rename or move the folder. Embedr adds it the first time you share the project or keep mechanical design history in the cloud, by inserting one line and leaving the rest of the file untouched. Do not copy it into another project; delete it from a copy that should be shared separately.
`kind`	`electronics` for electronics-only projects, which hides the firmware toolbar. `custom` is written by `embedr manifest discover`.
`language`	Primary language, for example `c-cpp`.

`source`

Optional hints that help the app and the agent find their way around a repository:

source:
  entry: src/main.cpp
  source_dirs: [src, components]
  include_dirs: [include]
  build_dir: build

`board` and `build`

board is the original way to name a PlatformIO target and is still written for compatibility:

Field	Example	Default
`platform`	`espressif32`	required
`board`	`esp32dev`	required
`framework`	`arduino`	`arduino`

build holds build and serial settings:

Field	Meaning	Default
`build_flags`	Extra compiler flags	`[]`
`lib_deps`	Extra PlatformIO library dependencies	`[]`
`upload_protocol`	PlatformIO upload protocol, for example `esptool`	board default
`upload_speed`	Upload baud rate	board default
`monitor_speed`	Serial monitor baud rate	`115200`
`debug_tool`	PlatformIO debug tool, for example `esp-prog`	board default

Where firmware settings really live

When a project has manifest_version: 1, the embedr-cli provider and a platformio.ini, platformio.ini is the source of truth for boards, environments and the four Target Settings. Embedr reads environments from it and writes Target Settings into its active [env:...] section, leaving board and build in the manifest as they were. Edit platformio.ini for flags, libraries and options in these projects.

Projects without that combination (older manifests, or no platformio.ini) keep the settings in embedr.yaml, and Embedr regenerates platformio.ini from it.

`capabilities.firmware`

Field	Meaning
`enabled`	`false` turns firmware actions off. Default `true`.
`provider`	`embedr-cli` for PlatformIO builds through Embedr's managed toolchain, `custom` for your own commands.
`target_id`	The target preset ID, for example `esp32`.
`environment`	The PlatformIO environment to build.
`device_port`	A default serial port for flash and monitor.
`active_target`	Which entry of `targets` is active.
`targets`	Named target profiles (see below).
`actions`	Custom commands (see below).

Picking a target in the toolbar fills in provider, target_id, environment, active_target and a targets entry, and keeps the top-level board in step.

Named targets

Each entry in targets is a profile you can make active:

capabilities:
  firmware:
    provider: embedr-cli
    active_target: esp32
    targets:
      esp32:
        label: ESP32 DevKit
        provider: embedr-cli
        target_id: esp32
        environment: esp32
        board:
          platform: espressif32
          board: esp32dev
          framework: arduino
      bench-rig:
        label: Bench rig (custom flasher)
        provider: custom
        actions:
          build:
            command: make
          flash:
            command: ./tools/flash.sh "$EMBEDR_DEVICE_PORT"

A target entry accepts label, provider, target_id, environment, device_port, board, build and actions. The active target's provider and actions take precedence over the ones directly under firmware.

Custom firmware actions

With provider: custom (or any provider other than embedr-cli), Compile and Flash run the commands you declare instead of PlatformIO:

capabilities:
  firmware:
    enabled: true
    provider: custom
    actions:
      build:
        command: cmake -S . -B build && cmake --build build
        cwd: .
        timeout_ms: 900000
        artifacts:
          - build/app.bin
      flash:
        command: openocd -f board/stm32f4discovery.cfg -c "program build/app.elf verify reset exit"
        env:
          OPENOCD_LOG: "1"

Action	Run by
`build`	Compile in the toolbar, the agent's builds, and `embedr compile`
`flash`	Flash in the toolbar and `embedr upload`
`monitor`	`embedr run`, after build and flash
`clean`, `test`	Accepted and kept; not run by the app

Each action accepts:

Field	Meaning	Default
`command`	The shell command	required
`cwd`	Working directory, relative to the project root	`.`
`env`	Extra environment variables	none
`timeout_ms`	Time limit in milliseconds	600000 (10 minutes)
`artifacts`	Paths of expected outputs, for reference	none

How commands run:

On macOS and Linux, through your login shell ($SHELL -lc), so your PATH and toolchain setup apply. On Windows, through cmd.exe; write Windows commands there.
Output streams into the Output tab. Exit code 0 is success.
Embedr passes what is selected in the toolbar: EMBEDR_DEVICE_PORT (the Device), EMBEDR_TARGET_ID and EMBEDR_ENVIRONMENT, each only when set.

In custom projects the Target and Environment pickers are disabled, and Device is enabled only when a flash action exists. Without a build action, Compile says "Add capabilities.firmware.actions.build to embedr.yaml to enable compiling".

Detecting commands for an existing repository

Opening a folder without embedr.yaml offers Initialise Agent, which has the agent write the manifest. From a terminal you can also run:

embedr manifest discover          # show what would be written
embedr manifest discover --write  # write it into embedr.yaml
embedr manifest inspect           # show how Embedr reads the manifest

discover recognises Zephyr (west.yml or prj.conf: west build, plus west flash when west is installed), Make (make, plus make flash, make test and make clean when those targets exist), CMake, Cargo and npm projects with a build script, and records what it found under discovery.

`capabilities.pcb`

capabilities:
  pcb:
    enabled: true
    workspace: pcb

Field	Meaning	Default
`enabled`	Whether the PCB workspace is active	`true`
`workspace`	The folder holding `pcb.toml` and the `.zen` sources	`pcb`

You rarely need this block: a project with a pcb/ folder is treated as having a PCB workspace. Which board file is active is set in pcb/pcb.toml, not here. See Project anatomy.

`components` and `connections`

components lists parts from the Embedr component library:

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

connections:
  - from: { component: status_led, pin: anode }
    to: { component: mcu, pin: D13 }
    wire_color: red

Field	Meaning	Default
`id`	Component ID in the library	required
`version`	Component version	`latest`
`instance`	A name for this copy, for projects that use the same part more than once	the `id`

The CLI manages the list: embedr add <id>, embedr list, embedr remove <id>, and embedr validate reports IDs it cannot find in the library.

connections record pin-to-pin wiring between component instances, each with from and to (component, pin) and an optional wire_color. They are notes for you and the agent. The schematic itself comes from the .zen sources in pcb/.

`datasheets`

When you process a datasheet, Embedr adds it to .embedr/datasheets.json and copies the list into the manifest so it travels with the project:

datasheets:
  - id: <datasheet id>
    name: BME280
    originalFilename: BST-BME280-DS002.pdf
    chunkCount: 142
    imageCount: 18
    processedAt: "2026-10-20T09:14:02.000Z"

Entries can also carry pageUrl, markdownUrl and searchUrl links to the processed copy. Embedr rewrites this list each time the set of datasheets changes, so do not edit it by hand. See Datasheets.

Editing the manifest

Embedr rewrites embedr.yaml when you pick a target, change Target Settings in an older project, or process a datasheet. Comments and custom formatting in the file are not kept when that happens. Keep long notes in a README instead.
If you add or rename environments in platformio.ini by hand, pick the target again in the toolbar so the manifest's target_id and environment match.
Do not delete board or capabilities.firmware from a PlatformIO project unless you replace them with custom actions.
Compile after any change to target or build settings.
Check the manifest with embedr validate, or ask the agent: "Explain each block of embedr.yaml and check it matches platformio.ini."

Examples

Top-level fields

Name rules

`project`

`source`

`board` and `build`

Where firmware settings really live

`capabilities.firmware`

Named targets

Custom firmware actions

Detecting commands for an existing repository

`capabilities.pcb`

`components` and `connections`

`datasheets`

Editing the manifest

Product

Resources

Support

Legal

Project Manifest

Examples

Top-level fields

Name rules

project

source

board and build

Where firmware settings really live

capabilities.firmware

Named targets

Custom firmware actions

Detecting commands for an existing repository

capabilities.pcb

components and connections

datasheets

Editing the manifest

`project`

`source`

`board` and `build`

`capabilities.firmware`

`capabilities.pcb`

`components` and `connections`

`datasheets`