プロジェクトマニフェスト

embedr.yamlの項目別リファレンス。メタデータ、ファームウェアターゲット、カスタムコマンド、部品、データシート。

embedr.yamlはすべてのプロジェクトのルートにあります。プロジェクトに名前を付け、ファームウェアのビルド方法をEmbedrに伝えます。形式はYAMLです。Embedrは認識しないキーも保持するため、独自のメモを追加のキーとして書けます。

例

ターゲットを選んだあとの、新しいElectronics + firmwareプロジェクト:

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: []

新しいElectronics onlyプロジェクト:

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

westでビルドする既存のZephyrリポジトリ:

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

トップレベルのフィールド

フィールド 型 既定値 意味
manifest_version 整数 なし スキーマのバージョン。1を使います。1以上である必要があります。
name 文字列 必須 プロジェクトの識別子(名前のルールを参照)。
version 文字列 0.1.0 プロジェクトのバージョン。
description 文字列 なし 自由記述。
author 文字列 なし 自由記述。
project マップ なし プロジェクトのメタデータ(id、kind、language)。
source マップ なし ソースの場所についてのヒント。
board マップ なし PlatformIOのボード。古いツールや単純なプロジェクトのために保持されます。
build マップ 下記参照 ビルドとシリアルの設定。
capabilities マップ なし ファームウェアターゲット、カスタムコマンド、PCBワークスペース。
components リスト [] プロジェクトで使う部品ライブラリの部品。
connections リスト [] 部品間のピン同士の配線メモ。
datasheets リスト なし 処理済みのデータシート。Embedrが書き込みます。
discovery マップ なし embedr manifest discoverが検出した内容。CLIが書き込みます。

名前のルール

Embedrは、ファイルを拒否するのではなく、nameを安全な識別子に正規化します。

  • 英字、数字、-、_以外の文字は-になり、先頭と末尾の-と_は削除されます。2 Parking Sensorはproject-2-Parking-Sensorになります。
  • 英字で始まらない名前にはproject-の接頭辞が付きます。
  • YAMLがtrue、false、nullとして読みうる単語(yes、no、on、off、true、false、null、y、n)にも接頭辞が付きます。
  • 空の名前はembedr-projectになります。

ホーム画面の表示名は、このフィールドではなくフォルダ名から決まります。

project

フィールド 意味
id フォルダの名前を変えたり移動したりしてもプロジェクトを識別できるUUID。プロジェクトを初めて共有したときや、機構設計の履歴をクラウドに保持するときに、Embedrが1行を挿入して追加します。ファイルのほかの部分には触れません。別のプロジェクトにコピーしないでください。別に共有すべきコピーからは削除してください。
kind エレクトロニクスのみのプロジェクトではelectronicsで、ファームウェアのツールバーが非表示になります。customはembedr manifest discoverが書き込みます。
language 主な言語。例: c-cpp。

source

アプリとエージェントがリポジトリ内で迷わないようにするための、任意のヒントです。

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

boardとbuild

boardはPlatformIOのターゲットを指定する従来の方法で、互換性のために今も書き込まれます。

フィールド 例 既定値
platform espressif32 必須
board esp32dev 必須
framework arduino arduino

buildはビルドとシリアルの設定を保持します。

フィールド 意味 既定値
build_flags 追加のコンパイラフラグ []
lib_deps 追加のPlatformIOライブラリ依存関係 []
upload_protocol PlatformIOの書き込みプロトコル。例: esptool ボードの既定値
upload_speed 書き込みのボーレート ボードの既定値
monitor_speed シリアルモニターのボーレート 115200
debug_tool PlatformIOのデバッグツール。例: esp-prog ボードの既定値

ファームウェアの設定が実際にある場所

プロジェクトにmanifest_version: 1、embedr-cliプロバイダー、platformio.iniがそろっている場合、ボード、環境、4つのTarget Settingsについてはplatformio.iniが正です。Embedrは環境をそこから読み、Target Settingsをそのアクティブな[env:...]セクションに書き込み、マニフェストのboardとbuildはそのままにします。このようなプロジェクトでは、フラグ、ライブラリ、オプションをplatformio.iniで編集してください。

この組み合わせがないプロジェクト(古いマニフェスト、またはplatformio.iniがないもの)は設定をembedr.yamlに保持し、Embedrはそこからplatformio.iniを再生成します。

capabilities.firmware

フィールド 意味
enabled falseにするとファームウェアの操作が無効になります。既定はtrue。
provider Embedrの管理するツールチェーンでPlatformIOビルドを行う場合はembedr-cli、独自のコマンドを使う場合はcustom。
target_id ターゲットのプリセットID。例: esp32。
environment ビルドするPlatformIOの環境。
device_port 書き込みとモニターの既定のシリアルポート。
active_target targetsのどのエントリがアクティブか。
targets 名前付きのターゲットプロファイル(下記参照)。
actions カスタムコマンド(下記参照)。

ツールバーでターゲットを選ぶと、provider、target_id、environment、active_target、targetsのエントリが埋まり、トップレベルのboardも合わせて更新されます。

名前付きターゲット

targetsの各エントリは、アクティブにできるプロファイルです。

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"

ターゲットのエントリには、label、provider、target_id、environment、device_port、board、build、actionsを書けます。アクティブなターゲットのproviderとactionsは、firmwareの直下にあるものより優先されます。

カスタムのファームウェア操作

provider: custom(またはembedr-cli以外の任意のプロバイダー)では、CompileとFlashは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"
操作 実行するもの
build ツールバーのCompile、エージェントのビルド、embedr compile
flash ツールバーのFlashとembedr upload
monitor embedr run(ビルドと書き込みのあと)
clean、test 受け付けて保持されますが、アプリは実行しません

各操作に書けるもの:

フィールド 意味 既定値
command シェルコマンド 必須
cwd 作業ディレクトリ(プロジェクトルートからの相対パス) .
env 追加の環境変数 なし
timeout_ms ミリ秒単位の制限時間 600000(10分)
artifacts 期待される出力のパス(参考用) なし

コマンドの実行方法:

  • macOSとLinuxでは、ログインシェル($SHELL -lc)を通して実行されるため、PATHとツールチェーンの設定が適用されます。Windowsではcmd.exeを通して実行されるため、Windowsのコマンドを書いてください。
  • 出力はOutputタブに流れます。終了コード0が成功です。
  • Embedrはツールバーで選択している内容を渡します: EMBEDR_DEVICE_PORT(Device)、EMBEDR_TARGET_ID、EMBEDR_ENVIRONMENT。それぞれ設定されている場合のみです。

カスタムのプロジェクトではTargetとEnvironmentの選択は無効になり、Deviceはflash操作がある場合にのみ有効になります。build操作がない場合、Compileには「Add capabilities.firmware.actions.build to embedr.yaml to enable compiling」と表示されます。

既存リポジトリのコマンドを検出する

embedr.yamlのないフォルダを開くとInitialise Agentが表示され、エージェントがマニフェストを書きます。ターミナルから次のように実行することもできます。

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は、Zephyr(west.ymlまたはprj.conf: west buildと、westがインストールされていればwest flash)、Make(makeと、該当するターゲットがあればmake flash、make test、make clean)、CMake、Cargo、buildスクリプトを持つnpmのプロジェクトを認識し、見つけた内容をdiscoveryに記録します。

capabilities.pcb

capabilities:
  pcb:
    enabled: true
    workspace: pcb
フィールド 意味 既定値
enabled PCBワークスペースが有効かどうか true
workspace pcb.tomlと.zenソースを置くフォルダ pcb

このブロックが必要になることはほとんどありません。pcb/フォルダのあるプロジェクトはPCBワークスペースを持つものとして扱われます。どの基板ファイルがアクティブかは、ここではなくpcb/pcb.tomlで設定します。プロジェクトの構造を参照してください。

componentsとconnections

componentsには、Embedrのコンポーネントライブラリの部品を記載します。

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
フィールド 意味 既定値
id ライブラリ内の部品ID 必須
version 部品のバージョン latest
instance この部品の名前。同じ部品を複数回使うプロジェクト向けです idの値

一覧はCLIで管理します: embedr add <id>、embedr list、embedr remove <id>。embedr validateはライブラリに見つからないIDを報告します。

connectionsは部品インスタンス間のピン同士の配線を記録します。各エントリにはfromとto(component、pin)と、任意のwire_colorがあります。これはあなたとエージェントのためのメモです。回路図そのものはpcb/の.zenソースから作られます。

datasheets

データシートを処理すると、Embedrはそれを.embedr/datasheets.jsonに追加し、プロジェクトと一緒に持ち運べるよう一覧をマニフェストにコピーします。

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

エントリには、処理済みのコピーへのpageUrl、markdownUrl、searchUrlのリンクが含まれることもあります。Embedrはデータシートの構成が変わるたびにこの一覧を書き直すため、手で編集しないでください。データシートを参照してください。

マニフェストの編集

  • Embedrは、ターゲットを選んだとき、古いプロジェクトでTarget Settingsを変更したとき、データシートを処理したときにembedr.yamlを書き直します。その際、ファイル内のコメントや独自の書式は保持されません。長いメモはREADMEに書いてください。
  • platformio.iniの環境を手で追加したり名前を変えたりした場合は、マニフェストのtarget_idとenvironmentが一致するよう、ツールバーでターゲットを選び直してください。
  • カスタム操作で置き換える場合を除き、PlatformIOプロジェクトからboardやcapabilities.firmwareを削除しないでください。
  • ターゲットやビルドの設定を変えたら、コンパイルしてください。
  • マニフェストはembedr validateで確認するか、エージェントに依頼します: 「embedr.yamlの各ブロックを説明し、platformio.iniと一致しているか確認してください。」