プロジェクトマニフェスト
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と一致しているか確認してください。」
