プロジェクトの構造

マニフェスト、ファームウェア、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/ フォルダがあることもあります。どちらも残しておいて問題ありません。