プロジェクトの構造
マニフェスト、ファームウェア、PCBソース、機構設計、仕様書、ローカル状態、コミットすべきもの。
Embedrプロジェクトは普通のフォルダです。ルートにある embedr.yaml がプロジェクトであることを示し、どのような要素を持つかをEmbedrに伝えます。それ以外はすべて普通のファイルなので、どのエディタでも開け、Gitで管理でき、マシン間で移動できます。
プロジェクトの全体像
Electronics + firmware として作成し、基板、筐体、計画が加わったプロジェクトは次のようになります。
plant-monitor/
├── embedr.yaml # project manifest
├── platformio.ini # firmware build environments
├── .gitignore
├── src/
│ └── main.cpp # firmware entry point
├── include/ # optional headers
├── lib/ # project-local libraries
├── pcb/
│ ├── pcb.toml # PCB workspace settings
│ ├── main.zen # schematic source
│ ├── .gitignore
│ └── layout/
│ ├── layout.kicad_pcb # board layout
│ └── layout.kicad_pro # KiCad project and design rules
├── mechanical/
│ ├── enclosure.cad.json # mechanical design manifest
│ ├── enclosure.py # generator source
│ ├── imports/ # STEP and other files designs import
│ └── assembly/
│ └── enclosure-v1.json # assembly guide
├── specs/
│ └── plant-monitor.md # Plan Mode spec
└── .embedr/ # Embedr's local project state
すべてのプロジェクトがこれらをすべて含む必要はありません。各要素は、あなたかエージェントが作成したときに現れます。
プロジェクトの種類ごとの初期ファイル
| 作成方法 | ファイル |
|---|---|
| Electronics + firmware | embedr.yaml、platformio.ini、src/main.cpp(または main.c)、lib/、.gitignore、pcb/ ワークスペース |
| Electronics only | embedr.yaml(project.kind: electronics 付き)、.gitignore、pcb/ ワークスペース |
| Import KiCad | KiCadデザインから変換したZenソースを pcb/ に持つエレクトロニクスプロジェクト |
| Open Folder / Clone Repository | 既存のファイル。embedr.yaml がない場合は、チャットで Initialise Agent をクリックすると、エージェントがソースを置き換えずにマニフェストを書きます。 |
新しいプロジェクトは ~/EmbedrProjects/<name>/ に作成されます。名前に使えるのは英字、数字、-、_ です。
ファームウェアのエントリーファイルは、ターゲットのフレームワークによって異なります。
| フレームワーク | ファイル | エントリーポイント |
|---|---|---|
| Arduino | src/main.cpp |
setup() と loop() |
| ESP-IDF | src/main.c |
app_main() |
| Zephyr | src/main.c |
main() |
| Mbed | src/main.cpp |
main() |
| STM32Cube、CMSIS、libopencm3、SPL | src/main.c |
main() |
embedr.yaml
マニフェストは、プロジェクトの名前を定め、ファームウェアのターゲット、カスタムビルドコマンド、部品の一覧を記述します。新しいArduino Unoのプロジェクトは次の内容で始まります。
manifest_version: 1
name: plant-monitor
version: 0.1.0
board:
platform: atmelavr
board: uno
framework: arduino
build:
build_flags: []
lib_deps: []
monitor_speed: 115200
components: []
connections: []
作業を進めると、Embedrが内容を追加します。ターゲットを選ぶと capabilities.firmware ブロックが書き込まれ、データシートを処理すると datasheets の一覧が加わり、プロジェクトを共有すると project.id が加わります。すべての項目はプロジェクトマニフェストを参照してください。
ファームウェア:platformio.ini、src/、include/、lib/
ファームウェアのビルドにはPlatformIOを使います。platformio.ini にはビルド環境ごとに [env:...] セクションが1つずつあり、default_envs でツールバーが選択する環境を指定します。
[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
[platformio]
default_envs = esp32
ツールバーでターゲットを選ぶと、ここにその環境が追加または更新されます。Target Settings(書き込み速度、モニター速度など)は有効な環境に書き込まれます。ファイルを手動で編集することもできます。PlatformIOプロジェクトでは、Embedrはこのファイルを正として読み込みます。ターゲットと環境を参照してください。
src/:ファームウェアのソース。include/:ヘッダーを分けて置く場合のフォルダ。lib/:このプロジェクト専用のライブラリ。PlatformIOレジストリのライブラリは代わりにlib_depsに記載します。依存関係とライブラリを参照してください。.pio/:最初のビルドで作成されます。ダウンロードしたライブラリとビルドの出力が入り、Gitでは無視されます。
PlatformIOではなくMake、CMake、Zephyrの west などのツールでビルドするプロジェクトは、embedr.yaml にコマンドを宣言します。カスタムファームウェアアクションを参照してください。
ハードウェア:pcb/
pcb/ フォルダはエレクトロニクスのワークスペースです。
| ファイル | 用途 |
|---|---|
pcb.toml |
ワークスペースの設定。どの .zen ファイルがボードか([board] の path)も含みます |
main.zen |
Embedrのハードウェア記述言語Zenで書いた回路。Schematics タブがこれを描画します。新しいワークスペースは Board(name="main", layout_path="layout", layers=2) で始まります。 |
その他の .zen ファイル |
ボードが読み込むモジュールやサブ回路 |
layout/layout.kicad_pcb |
回路図から生成され、その後に配置と配線を行った基板レイアウト。Board タブまたはKiCadで開きます。 |
layout/layout.kicad_pro |
KiCadのプロジェクト設定。基板メーカー向けのデザインルールを含みます |
.pcb/ |
PCBツールのビルドキャッシュ。Gitでは無視されます。 |
大きなプロジェクトでは、ボードをサブフォルダに置けます(例:pcb/boards/main/)。どれが有効かは pcb.toml で指定します。回路図とPCBとボードとKiCadを参照してください。
ボードファイルの隣には .embedr-board/ フォルダがあり、チェック結果、キャッシュされた3Dモデル、生成したドキュメント(deliverables/)、製造準備の状態が保存されます。必要に応じて再生成され、Gitでは無視されます。注文用に書き出す製造ファイルについては、製造と注文で説明しています。
機構設計:mechanical/
| パス | 用途 |
|---|---|
mechanical/<design>.cad.json |
設計のマニフェスト。名前、パラメーター(単位と範囲付き)、前提、チェック、設計の基準となる基板やファイル |
mechanical/<design>.py |
3Dモデルを作成するジェネレーター |
mechanical/imports/ |
ジェネレーターが読み込むSTEP、STL、DXF、画像などのファイル、またはそのまま使う取り込み済みのSTEPモデル |
mechanical/assembly/<guide>-v<N>.json |
手順ごとの組立ガイド。新しいバージョンは新しいファイルになり、古いバージョンも残ります。 |
設計のビルド済みリビジョン(STEP、プレビュー、図面)はアカウントに保存されるため、プロジェクトフォルダを圧迫せずに Mechanical タブで履歴を表示できます。機構設計を参照してください。
計画:specs/
プランモードでは、計画ごとに1つのMarkdownの仕様書を specs/ に保存します。内容は、意図、確定・仮定・未決の印が付いた要件、決定事項、対象外の範囲、作成計画です。プランモード中にエージェントが書き込むのはここだけです。仕様書は、それが記述するコードと一緒にコミットしてください。プランモードを参照してください。
Embedrのローカル状態:.embedr/
プロジェクト内の .embedr/ には、Embedrとエージェントがこのプロジェクトのために保持する状態が入ります。
| パス | 内容 |
|---|---|
.embedr/datasheets.json |
このプロジェクトで処理したデータシートの一覧 |
.embedr/component-assets.json |
インストールした部品のシンボル、フットプリント、3Dモデルの入手元 |
.embedr/agents/ |
このプロジェクト用の独自のヘルパープロファイル。ヘルパーを参照してください。 |
.embedr/agent-artifacts/ |
エージェントが自分用に保存したファイル。長い貼り付けの依頼や、編集前に作ったバックアップなど |
既定の .gitignore は .embedr/ 全体を無視します。チームでヘルパープロファイルや部品の入手元ファイルを共有したい場合は、例外を追加します。
.embedr/
!.embedr/agents/
!.embedr/component-assets.json
チャットスレッドはプロジェクトフォルダには入りません。デスクトップでは、どのプロジェクトの外でもある ~/EmbedrProjects/.embedr/<project-name>/ に保存されます。
コミットするもの
コミットするもの:
embedr.yaml、platformio.ini、src/、include/、lib/pcb/のソース:pcb.toml、.zenファイル、layout/*.kicad_pcb、layout/*.kicad_pro、.kicad_druルールファイルmechanical/:マニフェスト、ジェネレーター、imports/、assembly/specs/と自分で書いたドキュメント
除外するもの(既定の .gitignore で除外済み):
.pio/、.pcb/、.embedr/、.embedr-board/- KiCadのローカルファイル:
*.kicad_prl、*.lck、fp-info-cache、*-backups/、*.bak .envファイル(.env.exampleと.env.templateは残ります)- エディタやOSのファイル:
.vscode/、.idea/、.DS_Store build/、dist/、out/、node_modules/
プロジェクトを共有するときは、秘密情報らしいファイルと、.gitignore で除外されたものもEmbedrが省きます。プロジェクトの共有を参照してください。
管理プロジェクトとリンクプロジェクト
ホーム画面では2種類のプロジェクトを扱います。
| 種類 | 追加のされ方 | ホーム画面での名前変更 | ゴミ箱ボタン |
|---|---|---|---|
| 管理 | Embedrが ~/EmbedrProjects/ に作成 |
可能(Rename project) | Delete project:フォルダをディスクから削除します。元に戻せません。 |
| リンク | 既存のフォルダで Open Folder | 不可 | Remove from Embedr:一覧から外します。"The folder will stay where it is on disk." |
どちらの場合も、Embedrからプロジェクトを外すと、そのチャット履歴も削除されます。必要なものは先にコミットするかコピーしてください。
ブラウザでは、プロジェクトはフォルダではなくクラウド上のコピーです。ブラウザ版Embedrを参照してください。
古いプロジェクト
初期のEmbedrで作ったプロジェクトには、ルートに .ino ファイルがあり、embedr.yaml がありません。この場合、ツールバーに Migrate Project("Migrate legacy .ino project to embedr.yaml")が表示され、移行するまで Compile と Flash は表示されません。移行すると、embedr.yaml と、PlatformIOでビルドできる src/ の構成が作成されます。変更をレビューできるよう、先にコミットしておいてください。
古いプロジェクトには、変換済みのMarkdownデータシートが入った datasheets/ フォルダや、古いチャットの記録が入った .embedr_chat/ フォルダがあることもあります。どちらも残しておいて問題ありません。
