Arduino公式文書の翻訳

2024年1月16日

2024年2月9日

この文書のオリジナルはarduino-cliにあるPlatform specificationです。

下訳にChatGPT 4.0を使った関係で、元ドキュメントにない余分な説明を追加してしまっています。面白いのとよりわかりやすくなったので、特に削除しないで訳や体裁の問題だけ修正してあります。

プラットフォーム仕様

これは、Arduino IDE 1.5.x シリーズ以降のArduino開発ソフトウェアで使用するためのArduinoプラットフォームの仕様です。

プラットフォームは、新しいボードをArduino開発ソフトウェアに追加するサポートを提供します。これらは、ボードマネージャを介して、またはArduinoのスケッチブックフォルダ(別名「ユーザーディレクトリ」)の hardware フォルダに手動でインストールすることもできます。

プラットフォームは、単一の構成ファイルだけで構成されます。

ハードウェアフォルダの構造

新しいハードウェアフォルダには、2つのレベルで構成された階層的な構造があります:

最初のレベルは、ベンダー/メンテナーです
2番目のレベルは、サポートされるアーキテクチャです

ベンダー/メンテナーは複数のサポートされるアーキテクチャを持つことができます。例えば、以下に"arduino", “yyyyy”, "xxxxx"という3つのハードウェアベンダーがあります：

hardware/arduino/avr/...     - Arduino - AVRボード
hardware/arduino/sam/...     - Arduino - SAM (32ビットARM)ボード
hardware/yyyyy/avr/...       - Yyy - AVR
hardware/xxxxx/avr/...       - Xxx - AVR

ベンダー"arduino"は2つのサポートされるアーキテクチャ(AVRとSAM)を持ち、一方で"xxxxx"と"yyyyy"はAVRのみを持っています。

アーキテクチャの値は大文字と小文字を区別します(例: AVR と avr は異なります)。

可能であれば、ハードウェアパッケージを作成する際には、既存のアーキテクチャ名の命名規則に従ってください。パッケージを区別するためにはベンダーフォルダ名を使用します。アーキテクチャフォルダ名は、ライブラリの互換性を判断し、同じアーキテクチャの別のコアからリソースを参照することを許可するために使用されるので、非標準のアーキテクチャ名を使用すると有害な影響を及ぼすかも知れません。

アーキテクチャの構成

各アーキテクチャは、一連の構成ファイルを通じて構成する必要があります:

platform.txtは使用されるCPUアーキテクチャの定義を含んでいます(コンパイラ、ビルドプロセスのパラメータ、アップロードに使用されるツールなど)。
boards.txtはボードの定義を含んでいます(ボード名、スケッチのビルドとアップロードのためのパラメータなど)。
programmers.txtは外部プログラマーの定義を含んでいます(通常、ブートローダーまたはスケッチを空のCPU/ボードに書き込むために使用されます)。

構成ファイルの形式

構成ファイルは “key=value” のプロパティのリストです。プロパティの値は、別のプロパティの値を中括弧 “{” “}” で囲むことによって表現できます。例えば:

compiler.path=/tools/g++_arm_none_eabi/bin/
compiler.c.cmd=arm-none-eabi-gcc
[....]
recipe.c.o.pattern={compiler.path}{compiler.c.cmd}

この例では、プロパティ recipe.c.o.pattern は /tools/g++_arm_none_eabi/bin/arm-none-eabi-gcc に設定されます。これはプロパティ compiler.path と compiler.c.cmd の組み合わせです。

# で始まる行はコメントとして扱われ、無視されます。

# Like in this example
# --------------------
# I'm a comment!

特定のOSのプロパティの自動オーバーライド

特定のOSに特有のプロパティ値を指定することが可能です。例えば、以下のファイルでは:

tools.bossac.cmd=bossac
tools.bossac.cmd.windows=bossac.exe

プロパティ tools.bossac.cmd は Linux と macOS では bossac として設定され、Windows では bossac.exe として設定されます。サポートされているサフィックスは .linux、.windows、.macosx です。

グローバルな事前定義プロパティ

以下の自動生成されたプロパティは、すべての構成ファイルでグローバルに使用できます:

{runtime.platform.path}: ボードプラットフォームフォルダ(つまり、boards.txtを含むフォルダ)の絶対パス
{runtime.hardware.path}: ハードウェアフォルダ(つまり、ボードプラットフォームフォルダを含むフォルダ)の絶対パス
{runtime.ide.path}: Arduino IDEまたはArduino CLIフォルダの絶対パス
{runtime.ide.version}: Arduino IDEのバージョン番号(バージョン番号の各コンポーネントに2桁を使用し、点と先行するゼロを除去するため、Arduino IDE 1.8.3は01.08.03になり、それがruntime.ide.version=10803になります）。Arduino IDE以外のArduino開発ソフトウェアを使用している場合、意味のないバージョン番号に設定されます
{ide_version}: {runtime.ide.version}の互換性エイリアス
{runtime.os}: 実行中のOS（“linux”, “windows”, “macosx”）
{software}: "ARDUINO"に設定
{name}: プラットフォームベンダー名
{_id}: コンパイル対象のボードのボードID
{build.fqbn}: コンパイル対象のボードのFQBN(完全修飾ボード名)。FQBNは以下の形式に従います: VENDOR:ARCHITECTURE:BOARD_ID[:MENU_ID=OPTION_ID[,MENU2_ID=OPTION_ID ...]]
{build.source.path}: コンパイルされるスケッチのパス。スケッチが未保存の状態の場合、一時フォルダのパスとなります
{build.library_discovery_phase}: ライブラリ検出中は1に設定され、通常のビルド中は0に設定されます。このプロパティで定義されたマクロは、検出中のコンパイル時間を短縮するために重たいヘッダーの含まれないようにするために使用できます。このプロパティはArduino IDE 1.8.14/Arduino Builder 1.6.0/Arduino CLI 0.12.0で追加されました。同じ目的で、ライブラリ検出中にArduino Builder 1.5.3/Arduino CLI 0.10.0でrecipe.preproc.macrosに-DARDUINO_LIB_DISCOVERY_PHASEが追加されました。そのフラグは、より柔軟な{build.library_discovery_phase}プロパティに置き換えられました
{compiler.optimization_flags}: 詳細は"スケッチのデバッグ構成"を参照
{extra.time.utc}: ビルドが実行されるマシンによるUnix時間（1970-01-01T00:00:00Zからの秒数）
{extra.time.local}: ローカルタイムゾーンとDSTオフセットを加えたUnix時間
{extra.time.zone}: DSTコンポーネントを除いたローカルタイムゾーンオフセット
{extra.time.dst}: ローカル夏時間オフセット

互換性に関する注意: Arduino IDE 1.6.0より前のバージョンでは、{runtime.ide.version}のバージョン番号の各コンポーネントに1桁のみが使用されていました(従って1.5.9は10509ではなく159でした)。

platform.txt

platform.txtファイルには、プラットフォームの特定の側面に関する情報(コンパイラのコマンドラインフラグ、パス、システムライブラリなど)が含まれています。

以下のメタデータを定義する必要があります:

name=Arduino AVR Boards
version=1.5.3

name は、Arduino IDEのボードメニューのセクションタイトルまたはarduino-cli core listの出力でのプラットフォームの名前フィールドとして表示されます。 version は現在使用されていませんが、将来的に(おそらくボードマネージャーと一緒にコアへの依存関係を扱う際に)使用するために予約されています。

ビルドプロセス

platform.txtファイルは、ビルドプロセスを設定するために使用されます。これは、一連のレシピを通じて行われます。各レシピは、コンパイラ(または他のツール)をビルドの各ステップでどのように呼び出し、どのパラメータを渡すべきかを説明するコマンドライン表現です。

Arduino開発ソフトウェアはビルドを開始する前に、コンパイルするファイルのリストを決定します。このリストは以下から構成されます：

ユーザーのスケッチ
選択されたボードのコアにあるソースコード
スケッチで使用されるライブラリのソースコード

ビルド成果物を保存するための一時フォルダが作成され、そのパスはグローバルプロパティ {build.path} を通じて取得できます。プロジェクト名を示すプロパティ {build.project_name} と、アーキテクチャ名を示すプロパティ {build.arch} も設定されます。

{build.path}: ビルド成果物を保存するための一時フォルダへのパス
{build.project_name}: プロジェクト名
{build.arch}: MCUアーキテクチャ(avr、samなど…)

他にもいくつかの {build.xxx} プロパティがあり、これらはこのガイドのboards.txtセクションで説明されます。

セキュリティ資格情報プロパティ

いくつかのプロパティは、“セキュアブート” システムで使用できる信頼されたセキュリティ資格情報(署名鍵や暗号化鍵)を指定するために使用されます:

build.keys.keychain: 鍵が含まれるディレクトリ用
build.keys.sign_key: 署名鍵用
build.keys.encrypt_key: 暗号化鍵用

これらのプロパティのいずれかが定義されている場合、他のプロパティも必要です。

これらのプロパティは、Arduino CLIのcompileフラグである--keys-keychain、--sign-key、--encrypt-keyを使用してそれぞれ上書きすることができます。

ソースコードをコンパイルするためのレシピ

Arduino開発ソフトウェアはコンパイルするファイルのリストを決定します。各ファイルは、C言語(.cファイル)、C++(.cpp/.cxx/.ccファイル)、アセンブリ言語(.Sファイル)で書かれたソースコードです。各言語はそれぞれのレシピを使用してコンパイルされます:

recipe.c.o.pattern: Cファイル(.c)用
recipe.cpp.o.pattern: CPPファイル(.cpp/.cxx/.cc)用
recipe.S.o.pattern: アセンブリファイル(.S)用

(.cxx または .cc が特別な扱いを必要とする場合には、オプションで recipe.cxx.o.pattern や recipe.cc.o.pattern を提供される場合がありますが、必須ではないため推奨されません)

このレシピは、コンパイルされる各ファイルに対して自動生成される以下のプロパティを連結して構築することができます:

{includes}: インクルードパスのリストを “-I/include/path -I/another/path…” の形式で
{source_file}: ソースファイルへのパス
{object_file}: 出力ファイルへのパス

たとえば、AVR用には以下のように使用されます:

## コンパイラのグローバル定義
compiler.path={runtime.ide.path}/tools/avr/bin/
compiler.c.cmd=avr-gcc
compiler.c.flags=-c -g -Os -w -ffunction-sections -fdata-sections -MMD

[......]

## Cファイルのコンパイル
recipe.c.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.c.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {build.extra_flags} {includes} "{source_file}" -o "{object_file}"

{build.mcu} などの一部のプロパティはこの仕様の後半で説明するboards.txt ファイルから取得されます。

core.aアーカイブファイルのビルド用レシピ

選択されたボードのコアは前の段落で説明されたようにコンパイルされますが、コンパイルによって得られたオブジェクトファイルは、recipe.ar.pattern を使用して core.a という名前の静的ライブラリにアーカイブされます。

このレシピは、以下の自動生成されるプロパティを連結することで構築できます:

{object_file}: アーカイブに含めるオブジェクトファイル
{archive_file_path}: 完全修飾されたアーカイブファイル(例：“/path/to/core.a”)。このプロパティはArduino IDE 1.6.6/arduino builder 1.0.0-beta12で {build.path}/{archive_file} の代わりに追加されました。
{archive_file}: 結果として得られるアーカイブの名前(例： “core.a”)

たとえば、ArduinoはAVR用に以下を提供しています:

compiler.ar.cmd=avr-ar
compiler.ar.flags=rcs

[......]

## アーカイブの作成
recipe.ar.pattern="{compiler.path}{compiler.ar.cmd}" {compiler.ar.flags} "{archive_file_path}" "{object_file}"

リンク用レシピ

前のステップで生成された成果物(スケッチのオブジェクトファイル、ライブラリのオブジェクトファイル、core.aアーカイブ)は、recipe.c.combine.pattern を使用してリンクされます。

レシピは、以下の自動生成されるプロパティを連結することで構築できます:

{object_files}: アーカイブに含めるオブジェクトファイルのリスト(“file1.o file2.o …”)
{archive_file_path}: 完全修飾されたアーカイブファイル(例：“/path/to/core.a”)。このプロパティはArduino IDE 1.6.6/arduino builder 1.0.0-beta12で {build.path}/{archive_file} の代わりに追加されました
{archive_file}: コアアーカイブファイルの名前(例： “core.a”)
{compiler.libraries.ldflags}: プリコンパイルされたライブラリのリンクフラグ。これには、ライブラリパスのための自動生成された -L フラグと、ライブラリファイルのための -l フラグ、ならびに library.properties の ldflags フィールドを通じて提供されるカスタムフラグが含まれます。プリコンパイルされたライブラリをサポートするためには、platform.txt に compiler.libraries.ldflags の定義が含まれていなければなりません。これには、自動生成されたフラグが追加されます。プリコンパイルされたライブラリのサポートは Arduino IDE 1.8.6/arduino-builder 1.4.0 で追加されました

たとえば、AVR用に以下が使用されます:

compiler.c.elf.flags=-Os -Wl,--gc-sections
compiler.c.elf.cmd=avr-gcc

compiler.libraries.ldflags=

[......]

## gc-sections、アーカイブ、オブジェクトの結合
recipe.c.combine.pattern="{compiler.path}{compiler.c.elf.cmd}" {compiler.c.elf.flags} -mmcu={build.mcu} -o "{build.path}/{build.project_name}.elf" {object_files} {compiler.libraries.ldflags} "{archive_file_path}" "-L{build.path}" -lm

実行可能ファイルとその他のバイナリデータの抽出用レシピ

オブジェクトのリンクの最後に、任意の数の追加ステップを実行できます。これらのステップは、アップロード用のバイナリデータを抽出するために使用され、以下の形式で一連のレシピによって定義されます:

recipe.objcopy.FILE_EXTENSION_1.pattern=[.....]
recipe.objcopy.FILE_EXTENSION_2.pattern=[.....]
[.....]

FILE_EXTENSION_x は抽出されるファイルの拡張子に置き換える必要があります。例えば、AVRプラットフォームでは .hex ファイルと .eep ファイルの二つが必要なため、以下のように二つのレシピを作成しました：

recipe.objcopy.eep.pattern=[.....]
recipe.objcopy.hex.pattern=[.....]

ここでは、Arduino開発ソフトウェアによって設定される特定のプロパティはありません。

AVRプラットフォームの完全な例は以下のようになります：

## EEPROMの作成
recipe.objcopy.eep.pattern="{compiler.path}{compiler.objcopy.cmd}" {compiler.objcopy.eep.flags} "{build.path}/{build.project_name}.elf" "{build.path}/{build.project_name}.eep"

## HEXの作成
recipe.objcopy.hex.pattern="{compiler.path}{compiler.elf2hex.cmd}" {compiler.elf2hex.flags} "{build.path}/{build.project_name}.elf" "{build.path}/{build.project_name}.hex"

バイナリスケッチサイズを計算するためのレシピ

ビルドの最後に、Arduino開発ソフトウェアは最終的なバイナリスケッチのサイズをユーザーに表示します。サイズはレシピ recipe.size.pattern を使用して計算されます。このレシピを使用して実行されたコマンドの出力は、以下のプロパティに設定された正規表現によって解析されます:

recipe.size.regex: プログラムストレージスペースの使用量
recipe.size.regex.data: グローバル変数によって使用される動的メモリ

AVRの場合、以下のようになります:

compiler.size.cmd=avr-size
[....]
## サイズの計算
recipe.size.pattern="{compiler.path}{compiler.size.cmd}" -A "{build.path}/{build.project_name}.hex"
recipe.size.regex=^(?:\.text|\.data|\.bootloader)\s+([0-9]+).*
recipe.size.regex.data=^(?:\.data|\.bss|\.noinit)\s+([0-9]+).*

利用可能なメモリの合計を定義するために、以下の2つのプロパティが使用できます:

{upload.maximum_size}: 利用可能なプログラムストレージスペース
{upload.maximum_data_size}: グローバル変数のための利用可能な動的メモリ

バイナリスケッチのサイズがこれらのプロパティの値を超えると、コンパイルプロセスは失敗します。

この情報は、スケッチのコンパイル後に、相対的なメモリ使用量の値とともにコンソール出力に表示されます:

Sketch uses 924 bytes (2%) of program storage space. Maximum is 32256 bytes.
Global variables use 9 bytes (0%) of dynamic memory, leaving 2039 bytes for local variables. Maximum is 2048 bytes.

より複雑なシステムのバイナリスケッチサイズ計算用レシピ(Arduino CLIバージョン>=0.21.0以降)

プラットフォームは、バイナリを分析し、スケッチのサイズとメモリ使用統計を計算する特定の目的のためのツールを提供することがあります。これは、クラシックな正規表現ベースのアプローチでは不十分なメモリレイアウトが複雑なボードに特に有用です。

実行するコマンドラインは、レシピ recipe.advanced_size.pattern で指定されます。

このツールが期待する出力は、以下の形式のJSONオブジェクトです:

{
  "output": "Your sketch uses 2200 bytes of program memory out of 8192 (27%)\nThe static RAM used is 200 bytes (of 2048 max)",
  "severity": "info",
  "sections": [
    { "name": "text", "size": 2200, "max_size": 8192 },
    { "name": "data", "size": 200, "max_size": 2048 }
  ]
}

各フィールドの意味は以下の通りです:

output: コンソールにそのまま表示されるフォーマット済みのテキストです
severity: 出力メッセージの警告レベルを示し、info、warning、または error である必要があります。警告とエラーは赤色(または通常の出力とは異なる色)で表示されます。エラーはビルド/アップロードが失敗します
sections: メモリセクションとその使用レベルを含む配列です。この配列は、ユーザーからの要求に応じて、メモリ使用量を機械可読形式で報告するために使用されます。各項目はメモリセクションを表し、次のフィールドを含む場合があります
- name: セクションの識別子
- size: セクションのスケッチサイズ
- max_size: セクションの最大サイズ

severity が error に設定された場合、ビルド/アップロードは中断され、呼び出し元プロセスに例外が返されます。この場合、error フィールドを介して追加の例外メッセージを提供する必要があります。例:

{
  "output": "Your sketch uses 12200 bytes of program memory out of 8192 (149%))\nThe static RAM used is 200 bytes (of 2048 max)",
  "severity": "error",
  "error": "Sketch is too big!",
  "sections": [
    { "name": "text", "size": 12200, "max_size": 8192 },
    { "name": "data", "size": 200, "max_size": 2048 }
  ]
}

これは、sections 部分はスケッチサイズが利用可能なメモリを超えるかどうかを自動的にチェックするために使用されないことを意味します。このチェックは、ツールに委任され、ツールは severity: error を意味のあるエラーメッセージとして報告する必要があります。

もし recipe.size.pattern と recipe.advanced_size.pattern の両方が存在する場合、recipe.advanced_size.pattern が使用されます。 recipe.advanced_size.pattern 機能は Arduino CLI >= 0.21.0 から利用可能ですので、後方互換性を最大限に確保するために、可能であれば recipe.size.pattern と recipe.advanced_size.pattern の両方を提供することをお勧めします。これにより、(詳細なメモリ使用状況レポートがなくても)古いバージョンのIDE/CLIでも動作します。

コンパイルされたバイナリのエクスポート用レシピ

Arduino IDEで Sketch > Export compiled Binary を実行すると、コンパイルされたバイナリがビルドフォルダからスケッチフォルダにコピーされます。 2つのバイナリがコピーされます: 標準のバイナリと、ブートローダーファイルと結合されたバイナリ(ファイル名に .with_bootloader が含まれます)。

Export compiled Binary の動作に影響を与える2つのレシピがあります:

recipe.output.tmp_file: ビルドフォルダ内のバイナリのファイル名を定義します
recipe.output.save_file: バイナリファイルをスケッチフォルダにコピーする際に使用するファイル名を定義します

他のプロセスと同様に、Export compiled Binary にはビルド前およびビルド後のフックがあります。

recipe.hooks.savehex.presavehex.NUMBER.pattern および recipe.hooks.savehex.postsavehex.NUMBER.pattern フック(ただし recipe.output.tmp_file および recipe.output.save_file ではない)は、次の自動生成プロパティを結合して構築できます:

{sketch_path}: スケッチフォルダの絶対パス

プリプロセッサの実行用レシピ

ビルドに含めるライブラリを検出し、関数プロトタイプを生成するために(のみ)プリプロセッサが実行されます。このために、recipe.preproc.macros レシピが存在します。このレシピは、指定されたソースファイルでプリプロセッサを実行し、プリプロセスされた出力を指定された出力ファイルに書き込み、プリプロセッサのエラーのみを標準出力に生成する必要があります。このプリプロセッサの実行は、通常のソースファイルのコンパイルと同じ定義と他のプリプロセッサに影響を与えるオプションで実行される必要があります。

レシピは、コンパイルされる各ファイルごとに、他の自動生成プロパティを結合して構築できます:

{includes}: “-I/含まれる/パス -I/別の/パス…” フォーマットのインクルードパスのリスト
{source_file}: ソースファイルへのパス
{preprocessed_file_path}: 出力ファイルへのパス

例えば、AVR向けには以下のように使われます:

preproc.macros.flags=-w -x c++ -E -CC
recipe.preproc.macros="{compiler.path}{compiler.cpp.cmd}" {compiler.cpp.flags} {preproc.macros.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {compiler.cpp.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{preprocessed_file_path}"

{preprocessed_file_path}が/dev/null のような場所を指すことがあります(使っているオペレーティングシステムの同等のもの)。この場合、gccに-MMDを渡すのも問題です。なぜなら、通常は{compiler.cpp.flags}を含むため、それには-MMDも含まれており、これにより通常は許可エラーが発生する/dev/null.dという名前の依存ファイルを生成しようとします。これを防ぐために、通常、recipe.preproc.macrosレシピから-MMDオプションが自動的に除外されます。

recipe.preproc.macrosが定義されていない場合、それは自動的にrecipe.cpp.o.patternから生成されます。

注意: 古いバージョンのArduino IDEでは、recipe.preproc.includes レシピ(ここでは文書化されていない)を使用してインクルードを決定していました。しかし、Arduino IDE 1.6.7(arduino-builder 1.2.0)以降では、これが変更され、recipe.preproc.includes は今は使用されなくなりました。

ビルド前およびビルド後のフック(Arduino IDE 1.6.5 以降)

各レシピの前後にアクションを指定することができます。これらは「フック(hooks)」と呼ばれます。以下は利用可能なフックの完全なリストです:

recipe.hooks.prebuild.NUMBER.pattern (スケッチの前処理とライブラリの検出の前に呼び出されます)
recipe.hooks.sketch.prebuild.NUMBER.pattern (スケッチのコンパイルの前に呼び出されます)
recipe.hooks.sketch.postbuild.NUMBER.pattern (スケッチのコンパイルの後に呼び出されます)
recipe.hooks.libraries.prebuild.NUMBER.pattern (ライブラリのコンパイルの前に呼び出されます)
recipe.hooks.libraries.postbuild.NUMBER.pattern (ライブラリのコンパイルの後に呼び出されます)
recipe.hooks.core.prebuild.NUMBER.pattern (コアのコンパイルの前に呼び出されます)
recipe.hooks.core.postbuild.NUMBER.pattern (コアのコンパイルの後に呼び出されます)
recipe.hooks.linking.prelink.NUMBER.pattern (リンクの前に呼び出されます)
recipe.hooks.linking.postlink.NUMBER.pattern (リンクの後に呼び出されます)
recipe.hooks.objcopy.preobjcopy.NUMBER.pattern (objcopy レシピの実行前に呼び出されます)
recipe.hooks.objcopy.postobjcopy.NUMBER.pattern (objcopy レシピの実行後に呼び出されます)
recipe.hooks.savehex.presavehex.NUMBER.pattern (savehex レシピの実行前に呼び出されます)
recipe.hooks.savehex.postsavehex.NUMBER.pattern (savehex レシピの実行後に呼び出されます)

例: スケッチのコンパイル前に2つのコマンドを実行し、リンキング後に1つのコマンドを実行したい場合、platform.txt に以下のように追加します:

recipe.hooks.sketch.prebuild.1.pattern=echo sketch compilation started at
recipe.hooks.sketch.prebuild.2.pattern=date

recipe.hooks.linking.postlink.1.pattern=echo linking is complete

警告: フックのレシピは実行前にソートされます。1つのフックに10以上のレシピを書く必要がある場合は、次のように番号をゼロで埋めます:

recipe.hooks.sketch.prebuild.01.pattern=echo 1
recipe.hooks.sketch.prebuild.02.pattern=echo 2
...
recipe.hooks.sketch.prebuild.11.pattern=echo 11

注: すべての pre* フックは、“compilation database”(スケッチをコンパイルするために実行するコマンドのリストを含むJSONファイル)を生成する際に実行されますが、post* フックおよびすべてのコンパイルコマンドはスキップされます。詳細については arduino-cli compile コマンドリファレンスを参照してください。

グローバルな platform.txt

Arduino IDEインストールフォルダの hardware サブフォルダ内に作成された platform.txt に定義されたプロパティは、すべてのプラットフォームに使用され、ローカルプロパティを上書きします。この機能は、現在、Arduino IDEを使用している場合にのみ利用可能です。

platform.local.txt

Arduino IDE 1.5.7 で導入されました。このファイルは、platform.txt で定義されたプロパティを上書きしたり、platform.txt を変更せずに新しいプロパティを定義したりするために使用できます(たとえば、platform.txt がバージョン管理システムで追跡されている場合など)。このファイルは、それを補完するplatform.txt と同じフォルダに配置する必要があります。

boards.txt

このファイルには、プラットフォームでサポートされているボードの定義とメタデータが含まれています。ボードはその短い名前であるボードIDで参照されます。ボードの設定は、ボードIDをプレフィックスとするキーを持つプロパティのセットを通じて定義されます。

たとえば、Arduino Unoボードに選ばれたボードIDは “uno” です。 boards.txt内のUnoボードの設定の一部は次のようになります：

[......]
uno.name=Arduino Uno
uno.build.mcu=atmega328p
uno.build.f_cpu=16000000L
uno.build.board=AVR_UNO
uno.build.core=arduino
uno.build.variant=standard
[......]

注意: すべての関連するキーは、ボードID uno.xxxxx で始まります。

uno.name プロパティには人間に分かりやすいボードの名前が含まれます。これはIDEのボードメニューや、Arduino CLIのテキスト出力の "Board Name"フィールド、またはArduino CLIのJSON出力の"name"キーに表示されます。

uno.build.board プロパティは、コンパイル時のマクロ ARDUINO_{build.board} を設定するために使用され、#ifdef を使った条件付きコードを使用できるようにします。定義されていない場合、build.board 値が自動的に生成され、Arduino開発ソフトウェアは警告を出力します。この場合、コンパイル時に定義されるマクロは ARDUINO_AVR_UNO になります。

ユーザーがボードを選択すると、その他のプロパティは対応するグローバルプロパティを上書きします。これらのプロパティは、ボードIDプレフィックスなしで、他の構成ファイルでもグローバルに利用可能になります。つまり、以下のようになります:

uno.build.mcu => build.mcu
uno.build.f_cpu => build.f_cpu
uno.build.board => build.board
uno.build.core => build.core
uno.build.variant => build.variant

これは、platform.txt レシピ内で {build.mcu} または {build.board} が存在することを説明しています。 Uno ボードが選択されたると、それぞれ {uno.build.mcu} および {uno.build.board} によって値が上書きされます！さらに、以下のプロパティが自動生成されます:

{build.core.path}: 選択したボードのコアフォルダへのパス（コアプラットフォーム内にあります、例: hardware/arduino/avr/core/arduino）
{build.system.path}: コアプラットフォームのシステムフォルダへのパス（利用可能な場合、例: hardware/arduino/sam/system）
{build.variant.path}: 選択したボードのバリアントフォルダへのパス（バリアントプラットフォーム内にあります、例: hardware/arduino/avr/variants/micro）

もしプラットフォームがプラグイン型のディスカバリをサポートしている場合、一連の upload_port.* プロパティを宣言することもできます。これらのプロパティは、ボードが接続されたときのディスカバリプロセスによってボードを識別するために使用されます。

例えば、Unoに対して次のように upload_port.vid と upload_port.pid の一連のプロパティを宣言できます:

uno.upload_port.vid.0=0x2341
uno.upload_port.pid.0=0x0043
uno.upload_port.vid.1=0x2341
uno.upload_port.pid.1=0x0001
uno.upload_port.vid.2=0x2A03
uno.upload_port.pid.2=0x0043
uno.upload_port.vid.3=0x2341
uno.upload_port.pid.3=0x0243

この場合、ボードのUSB VID/PIDペアを使用してボードを識別していますが、upload_port.* プロパティは、特定のボードを識別するのに役立つ任意の情報にすることができます。詳細な情報については、プラグイン可能なディスカバリのドキュメンテーションの board identification セクションを参照してください。

コア

コアは cores サブフォルダー内に配置されます。 1つのプラットフォーム内に複数の異なるコアを提供できます。たとえば、以下は有効なプラットフォームのレイアウトの例です：

hardware/arduino/avr/cores/: “avr” アーキテクチャ、パッケージ “arduino” のコアフォルダー
hardware/arduino/avr/cores/arduino: Arduinoコア
hardware/arduino/avr/cores/rtos: 架空のRTOSコア

ボードのプロパティ build.core は、ボードが選択されたときにコンパイルとリンクされる必要があるコアを見つけるために使用されます。たとえば、ボードがArduinoコアを必要とする場合、build.core 変数は次のように設定されるべきです:

uno.build.core=arduino

RTOSコアが必要な場合は、次のように設定します:

uno.build.core=rtos

いずれの場合も、選択したコアフォルダの内容がコンパイルされ、コアフォルダのパスがインクルードファイルの検索パスに追加されます。

ArduinoCore-API

コアの実装の多くはアーキテクチャ固有ですが、標準化されたコアAPIとハードウェアに依存しないコンポーネントは、すべてのArduinoプラットフォームで同じであるべきです。個々のプラットフォームの作成者がこの共通のコードの重複を個別に管理する手間を省くために、Arduinoはそれを専用のリポジトリに公開し、すべてのプラットフォームで簡単に共有できるようにしました。 ArduinoCore-APIはコアを開発およびメンテナンスするために必要な作業を大幅に削減するだけでなく、プラットフォーム間での高度なポータビリティを提供するコアの著者を支援します。これはArduinoプロジェクトの特徴であり、異なるプラットフォーム間での高いポータビリティを確保します。

詳細については、arduino/ArduinoCore-APIリポジトリをご覧ください。

コアバリアント

時折、ボードはデフォルトのコア設定を調整する必要があります(ピンマッピングの違いは典型的な例です)。コアバリアントフォルダは、コアと一緒にコンパイルされる追加のフォルダで、プラットフォーム開発者が特定の設定を簡単に追加できるようにします。

バリアントは、現在のアーキテクチャ内のvariantsフォルダに配置する必要があります。たとえば、Arduino AVRボードは以下のように使用します:

hardware/arduino/avr/cores: “avr"アーキテクチャのコアフォルダ、パッケージ"arduino”
hardware/arduino/avr/cores/arduino: Arduinoコア
hardware/arduino/avr/variants/: “avr"アーキテクチャのバリアントフォルダ、パッケージ"arduino”
hardware/arduino/avr/variants/standard: ATmega328ベースのバリアント
hardware/arduino/avr/variants/leonardo: ATmega32U4ベースのバリアント

この例では、Arduino Unoボードには _standard_バリアントが必要なので、build.variantプロパティは"standard"に設定されています:

[.....]
uno.build.core=arduino
uno.build.variant=standard
[.....]

一方、Arduino Leonardoボードには leonardo バリアントが必要です。

[.....]
leonardo.build.core=arduino
leonardo.build.variant=leonardo
[.....]

上記の例では、UnoとLeonardoの両方が同じコアを共有しており、異なるバリアントを使用しています。

いずれの場合も、選択したバリアントフォルダのパスがインクルード検索パスに追加され、その内容がスケッチと一緒にコンパイルおよびリンクされます。

パラメータ build.variant.path は自動的に生成されます。

ボードのVID/PID

USBベンダーID(VID)およびプロダクトID(PID)は、USBデバイスをコンピューターに識別するためのものです。ボードが固有のVID/PIDペアを使用する場合、それはboards.txtで定義できます。

uno.vid.0=0x2341
uno.pid.0=0x0043
uno.vid.1=0x2341
uno.pid.1=0x0001

vid および pid プロパティは任意の番号で終わっており、1つのボードに複数のVID/PIDペアを定義できるようにしています。上記のスニペットは、Unoボードで使用される2341:0043および2341:0001のペアを定義しています。

Arduino開発ソフトウェアは、vid および pid プロパティを使用して、コンピューターに接続されたボードを自動的に識別します。この便利な機能は、一意のVID/PIDペアを提供しないボードでは使用できません。

シリアルモニター制御信号構成

コンピューターとの通信にUSBからTTLシリアルアダプタチップを使用するArduinoボードの場合(例：Uno, Nano, Megaなど)、通常、DTR(data terminal ready)またはRTS(request to send)シリアル制御信号を使用して、Arduino開発ソフトウェアがプライマリマイクロコントローラのリセットをトリガーする仕組みとしています。コンピューターによって制御信号がアサートされると、アダプタのDTRおよびRTSピンは"LOW"に設定され、この"LOW"レベルはボード上の「自動リセット」回路によってマイクロコントローラのリセットピンにパルスに変換されます。自動リセットシステムは、アップロードの開始時にブートローダーをアクティブにするために必要です。

このシステムは、Serial Monitorが開始されたときにもマイクロコントローラをリセットするためにも使用されます。このリセットは便利で、プログラムが開始された時点からすべてのシリアル出力を表示できます。シリアルモニタによって引き起こされるリセットが望ましくない場合、シリアルモニタの制御信号アサート動作は、serial.disableDTRおよびserial.disableRTSプロパティを介して設定できます。これらのプロパティをtrueに設定すると、選択したボードの場合、シリアルモニタが制御信号をアサートしないようになります。

例:

[.....]
uno.serial.disableDTR=true
uno.serial.disableRTS=true
[.....]

ボードの隠蔽

ボード定義にhideプロパティを追加すると、Arduino IDEのTools > Boardメニューに表示されなくなります。

例:

uno.hide=

プロパティの値は無視されます。プロパティの存在または不在がボードの表示/非表示を制御します。

programmers.txt

programmers.txtファイルには外部プログラマの定義が含まれています。これらのプログラマは以下で使用されます:

IDEのTools > Burn Bootloader機能およびarduino-cli burn-bootloader
IDEのSketch > Upload Using Programmer機能およびarduino-cli upload --programmer <プログラマID>

programmers.txtはboards.txtと同様に動作します。プログラマは、プログラマIDという短縮名で参照されます。プログラマの設定は、プログラマIDを接頭辞として使用するキーのセットによって定義されます。

例えば、"Arduino as ISP"プログラマのために選択したプログラマIDは"arduinoasisp"です。

programmers.txt内でこのプログラマーの定義は次のようになります:

[......]
arduinoasisp.name=Arduino as ISP
arduinoasisp.protocol=stk500v1
arduinoasisp.program.speed=19200
arduinoasisp.program.tool=avrdude
arduinoasisp.program.extra_params=-P{serial.port} -b{program.speed}
[......]

これらのプロパティは、プログラマを使用するアクション(erase, bootloaderおよびprogram)のレシピ内でのみ使用できます。

arduinoasisp.nameプロパティは、プログラマの人間に分かる名前を定義します。これはIDEのTools > Programmerメニュー、arduino-cli upload --programmer listおよびarduino-cli burn-bootloader --programmer listの出力に表示されます。

Arduino IDE 1.8.12およびそれ以前では、すべてのインストール済みプラットフォームのすべてのプログラマーが使用可能でした。 Arduino IDE 1.8.13以降(および他のArduino開発ツールの該当バージョンすべて)では、現在選択されているボードのボードおよびコアプラットフォームで定義されたプログラマーのみが使用可能です。この問題によって、以前は他のプラットフォームによって提供されると想定されていたプログラマのコピーを定義する必要がありました。

ボードのデフォルトのプログラマを設定する(Arduino CLI >=0.35.0、Arduino IDE >=2.3.0以降)

各ボードのデフォルトのプログラマは、ボード定義内のprogrammer.defaultディレクティブで指定できます。

BOARD_ID.programmer.default=PROGRAMMER_ID

デフォルトのプログラマは、ユーザーが別のプログラマを指定または選択しない場合に自動的に選択されます。これは、オンボードのプログラマ/デバッガを持つボードに便利です。

たとえば、Arduino UNOのデフォルトのプログラマーとしてAtmel ICEを設定したい場合、次の行をboards.txtファイルに追加します：

uno.programmer.default=atmel-ice

ツール

Arduino開発ソフトウェアは、コンパイルされたスケッチをボードにアップロードしたり、外部プログラマを使用してブートローダーを書き込んだりするために、外部コマンドラインツールを使用します。たとえば、AVRベースのボードには_avrdude_が使用され、SAMベースのボードには_bossac_が使用されますが、制限はありません。任意のコマンドライン実行可能ファイルを使用できます。コマンドラインパラメータは、プラットフォームビルドプロセスと同じ方法でレシピを使用して指定されます。

ツールはplatform.txtファイル内で構成されています。各ツールは、ツールIDと呼ばれる短い名前で識別されます。ツールはさまざまな目的で使用できます:

ブートローダーがボードにプリインストールされている場合、スケッチをターゲットボードにアップロードします
外部プログラマを使用して、スケッチをターゲットボードにプログラムします
外部プログラマを使用して、ターゲットボードのフラッシュメモリを消去します
外部プログラマを使用して、ターゲットボードにブートローダーを書き込みます

各アクションには独自のレシピがあり、その設定は、ツールIDとアクションで始まるキーを持つプロパティを使用して行います。例えば:

[....]
tools.avrdude.upload.pattern=[......]
[....]
tools.avrdude.program.pattern=[......]
[....]
tools.avrdude.erase.pattern=[......]
[....]
tools.avrdude.bootloader.pattern=[......]
[.....]

これにより、特定のツールとアクションに関連する設定が行われます。

ツールは、すべての四つのアクションを定義する必要はなく、一部のアクションが定義されていないこともあります。例として、avrdudeのuploadアクションがどのように定義されているかを見てみましょう:

tools.avrdude.path={runtime.tools.avrdude.path}
tools.avrdude.cmd.path={path}/bin/avrdude
tools.avrdude.config.path={path}/etc/avrdude.conf

tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" -p{build.mcu} -c{upload.port.protocol} -P{upload.port.address} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"

ツールの設定プロパティは、プレフィックスなしでグローバルに利用できます。例えば、tools.avrdude.cmd.path プロパティは、レシピ内で {cmd.path} として使用でき、avrdudeの他の設定変数についても同様です。

`{runtime.tools.*}`プロパティ経由でツールのパスを取得する方法

{runtime.tools.TOOLNAME.path} および {runtime.tools.TOOLNAME-TOOLVERSION.path} プロパティは、現在のプラットフォームおよびブートマネージャを介してインストールされた他のプラットフォームで提供されるツールに対して生成されます。

ランタイムプロパティがどのように決定されるかの詳細については、{runtime.tools.*.path} ルールを参照してください。

環境変数

すべてのスケッチのコンパイルやアップロードに起動されるツールには、次の環境変数が設定されます:

ARDUINO_USER_AGENT: ユーザーが使用するクライアントの名前とバージョンを含み、HTTPユーザーエージェント形式で表されます。たとえば、"arduino-cli/0.21.0" のようになります。この情報が利用可能な場合、複数のスペース区切りのエントリを含むこともあります。例えば、"arduino-cli/0.21.0 ArduinoIDE/2.0.0-rc1" のようになります。

プラガブルディスカバリ

ディスカバリツールは、サポートされているボードを見つけるために使われる特別な種類のツールです。プラットフォームは、そのplatform.txtにおいて一つ以上のプラガブルディスカバリを宣言する必要があります。ディスカバリは、伝統的なディスカバリを含むbuiltinダミーパッケージを含む他のパッケージから参照されることがあります。

ディスカバリを宣言するためには、二つの異なる構文があります。プラットフォームが一つのディスカバリーのみを使用する場合は:

pluggable_discovery.required=VENDOR_ID:DISCOVERY_NAME

複数のディスカバリが必要な場合は:

pluggable_discovery.required.0=VENDOR_ID:DISCOVERY_0_NAME
pluggable_discovery.required.1=VENDOR_ID:DISCOVERY_1_NAME

シリアルポート経由で接続されるボードのみをサポートするプラットフォームは、カスタムのプラガブルディスカバリーを作成することなく、builtinパッケージのserial-discoveryを簡単に使用することができます:

pluggable_discovery.required=builtin:serial-discovery

ネットワーク経由で接続されるボードもサポートする場合、builtinパッケージのmdns-discoveryを使用できます:

pluggable_discovery.required.0=builtin:serial-discovery
pluggable_discovery.required.1=builtin:mdns-discovery

上記の構文では、プラットフォームのパッケージインデックスのdiscoveryDependenciesフィールドを介してディスカバリーを指定する必要がありますが、手動インストールでは扱いにくい場合があります。そこで、開発やベータテストを容易にするために別の構文を提供します:

pluggable_discovery.DISCOVERY_ID.pattern=DISCOVERY_RECIPE

DISCOVERY_IDは特定のディスカバリーに対するユニークな識別子に置き換える必要があり、DISCOVERY_RECIPEはディスカバリーを起動するコマンドラインに置き換える必要があります。例えば以下のようになります:

## Teensy Ports Discovery
pluggable_discovery.teensy.pattern="{runtime.tools.teensy_ports.path}/hardware/tools/teensy_ports" -J2

この構文は開発目的でのみ使用し、リリースされたプラットフォームでは使用しないことを強く推奨します。

後方互換性のため、あるプラットフォームがどのディスカバリーも宣言していない場合(platform.txt内のpluggable_discovery.*プロパティを使用していない場合)、自動的にbuiltin:serial-discoveryとbuiltin:mdns-discoveryが継承されます(ただし、将来的に追加される可能性のある他のbuiltinディスカバリーは含まれません)。

詳細については、プラガブルディスカバリー仕様を参照してください。

プラガブルモニタ

モニタツールは、ユーザーがサポートされているボードと通信するために使用される特別な種類のツールです。

プラットフォームは、そのplatform.txt内で一つ以上のプラガブルモニタを宣言し、それらを特定のポートプロトコルにバインドする必要があります。モニタは他のパッケージから参照されることがあります。

特定のモニタツールに特定なポートプロトコルをバインドするためには、以下の指令を使用します:

pluggable_monitor.required.PROTOCOL=VENDOR_ID:MONITOR_NAME

ここで、PROTOCOLはポートプロトコル識別子に置き換える必要があり、VENDOR_ID:MONITOR_NAMEはモニタツールの識別子に置き換える必要があります。

プラットフォームは、必要に応じて多くのプロトコルをサポートできます:

pluggable_monitor.required.PROTOCOL1=VENDOR_ID:MONITOR_NAME1
pluggable_monitor.required.PROTOCOL2=VENDOR_ID:MONITOR_NAME2
...

上記の構文では、プラットフォームのパッケージインデックスのmonitorDependenciesフィールドを介してモニターツールを指定する必要があります。手動インストールでの使用が煩雑である場合、開発やベータテストを容易にするために別の構文を提供します:

pluggable_monitor.pattern.PROTOCOL=MONITOR_RECIPE

ここで、MONITOR_RECIPEは特定のPROTOCOLのモニターツールを起動するためのコマンドラインに置き換える必要があります。例えば以下のようになります:

pluggable_monitor.pattern.custom-ble="{runtime.tools.my-ble-monitor.path}/my-ble-monitor" -H

この場合、プラットフォームは新しい仮想のcustom-bleプロトコルモニタツールを提供し、コマンドラインツールmy-ble-monitorは-Hパラメータで起動してモニターツールを開始します。この場合のコマンドラインパターンには、任意の追加パラメータを含めることができます。これは、monitorDependenciesフィールドを介してインストールされたモニターツールがコマンドラインパラメータなしで実行されなければならないのとは異なります。

この構文は開発目的でのみ使用し、リリースされたプラットフォームでは使用しないことを強く推奨します。

内蔵モニター

プラットフォームがシリアルポート経由で接続されるボードのみをサポートしている場合、カスタムのプラグ可能なモニターを作成することなく、builtin:serial-monitorツールを簡単に使用することができます:

pluggable_monitor.required.serial=builtin:serial-monitor

後方互換性

後方互換性のため、プラットフォームがディスカバリまたはモニタツール(それぞれplatform.txt内のpluggable_discovery.*またはpluggable_monitor.*プロパティを使用して)を宣言していない場合、自動的にbuiltin:serial-monitorを継承します(ただし、将来的に追加される可能性のある他のbuiltinモニターツールは含まれません)。これにより、従来の非プラグ可能なプラットフォームは、中断なくプラグ可能なモニターへ移行することができます。

詳細については、プラガブルモニタ仕様を参照してください。

ポートの構成

各プラガブルモニタは独自のデフォルト設定を持っており、次のボードプロパティを使用して上書きすることができます:

BOARD_ID.monitor_port.PROTOCOL.SETTING_NAME=SETTING_VALUE

ここで:

BOARD_IDはボード識別子です
PROTOCOLはポートプロトコルです
SETTING_NAMEとSETTING_VALUEはポート設定と期待される値です

例えば、あるボードがserialポートのbaudrate設定を9600にする必要がある場合、boards.txtファイル内の対応するプロパティは以下のようになります:

myboard.monitor_port.serial.baudrate=9600

特定のプラグ可能なモニターで利用可能な設定は、直接問い合わせることができます。

古い`serial.disableRTS`および`serial.disableDTR`プロパティ

古いArduino IDE（1.8.x以下）では、次のプロパティを使用していました:

BOARD_ID.serial.disableRTS=true
BOARD_ID.serial.disableDTR=true

これは、シリアルモニターを開くときにRTSとDTRを無効にするためです。後方互換性を保つため、上記のプロパティは対応するプラグ可能なモニタープロパティに自動的に変換されます:

BOARD_ID.monitor_port.serial.rts=off
BOARD_ID.monitor_port.serial.dtr=off

詳細パラメータ

ユーザーはIDEの設定パネルやArduino CLIの--verboseフラグから詳細モードを有効にすることができます。この設定は、ACTION.verboseプロパティ(ACTIONは考慮中のアクションです)を使用してコマンドラインに転送されます。

詳細モードが有効になると、tools.TOOL_ID.ACTION.params.verboseプロパティがACTION.verboseにコピーされます。詳細モードが無効になると、tools.TOOL_ID.ACTION.params.quietプロパティがACTION.verboseにコピーされます。混乱していますか？例を挙げると分かりやすいかもしれません:

tools.avrdude.upload.params.verbose=-v -v -v -v
tools.avrdude.upload.params.quiet=-q -q
tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" {upload.verbose} -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"

この例では、ユーザーが詳細モードを有効にした場合、{upload.params.verbose} が {upload.verbose} に使用されます:

tools.avrdude.upload.params.verbose    =>    upload.verbose

ユーザーが詳細モードを有効にしていない場合、{upload.params.quiet} が {upload.verbose} に使用されます:

tools.avrdude.upload.params.quiet      =>    upload.verbose

スケッチアップロード設定

「アップロード」アクションは、ユーザーがIDEツールバーの「アップロード」ボタンをクリックするか、arduino-cli uploadを使用するときにトリガーされます。 Arduinoでは、「アップロード」という用語はArduinoボードへのプログラム転送のプロセスを指すために使用されます。

upload.tool.<protocol_name> プロパティは、アップロードに使用されるツールを決定します。 boards.txt内の各ボードに対して特定の upload.tool.<protocol_name> プロパティが定義される必要があります:

[......]
uno.upload.tool.serial=avrdude
[......]
leonardo.upload.tool.serial=avrdude
leonardo.upload.tool.network=arduino_ota
[......]

各ボードには複数のプロトコルを定義できます。ユーザーがボードがサポートしていないプロトコルを使用してアップロードを試みる場合、defaultが定義されていれば、それにフォールバックします:

[......]
uno.upload.tool.default=avrdude
[......]
leonardo.upload.tool.default=avrdude
leonardo.upload.tool.network=arduino_ota
[......]

defaultは、ユーザーがアップロードアドレスを提供しない場合にも使用されます。これは、ポート検出機能が組み込まれているツール(例えば、openocd)で使用できます。

IDE 1.8.15およびそれ以前のバージョンとの後方互換性のために、以前の構文もまだサポートされています:

uno.upload.tool=avrdude

この以前の構文は以下と同等です:

uno.upload.tool.default=avrdude

ボードに対して他のアップロードパラメータも定義することができます。例えば、Arduino AVR Boardsのboards.txtでは以下のようになっています:

[.....]
uno.name=Arduino Uno
uno.upload.tool.serial=avrdude
uno.upload.protocol=arduino
uno.upload.maximum_size=32256
uno.upload.speed=115200
[.....]
leonardo.name=Arduino Leonardo
leonardo.upload.tool.serial=avrdude
leonardo.upload.protocol=avr109
leonardo.upload.maximum_size=28672
leonardo.upload.speed=57600
leonardo.upload.use_1200bps_touch=true
leonardo.upload.wait_for_upload_port=true
[.....]

ほとんどの {upload.XXXX} 変数は、platform.txtのavrdudeアップロードレシピで後に使用されます:

[.....]
tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" {upload.verbose} -p{build.mcu} -c{upload.port.protocol} -P{upload.port.address} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
[.....]

必要に応じて、同じプロパティは異なるプロトコルで複数回定義されることがあります:

leonardo.upload.serial.speed=57600
leonardo.upload.network.speed=19200

上記の二つのプロパティは {upload.speed} として利用可能になり、値はアップロードに使用されるプロトコルによって異なります。

プラガブルディスカバリからのプロパティ

プラットフォームがプラガブルディスカバリをサポートしている場合、ディスカバリによって返されるポートのプロパティも使用できます。例えば、以下のプラガブルディスカバリーからのポートメタデータ:

   {
      "eventType": "add",
      "port": {
        "address": "/dev/ttyACM0",
        "label": "ttyACM0",
        "protocol": "serial",
        "protocolLabel": "Serial Port (USB)",
        "properties": {
          "pid": "0x804e",
          "vid": "0x2341",
          "serialNumber": "EBEABFD6514D32364E202020FF10181E",
          "name": "ttyACM0"
        }
      }
    }

はレシピで以下の変数として利用可能になります:

{upload.port.address} = /dev/ttyACM0
{upload.port.label} = ttyACM0
{upload.port.protocol} = serial
{upload.port.protocolLabel} = Serial Port (USB)
{upload.port.properties.pid} = 0x8043
{upload.port.properties.vid} = 0x2341
{upload.port.properties.serialNumber} = EBEABFD6514D32364E202020FF10181E
{upload.port.properties.name} = ttyACM0
{serial.port} = /dev/ttyACM0                # 後方互換性のため
{serial.port.file} = ttyACM0                # プロトコルがserialの場合のみ

これは別の例です:

    {
      "eventType": "add",
      "port": {
        "address": "192.168.1.232",
        "label": "SSH on my-board (192.168.1.232)",
        "protocol": "ssh",
        "protocolLabel": "SSH Network port",
        "properties": {
          "macprefix": "AA:BB:CC",
          "macaddress": "AA:BB:CC:DD:EE:FF"
        }
      }
    }

これは以下のように変換されます:

{upload.port.address} = 192.168.1.232
{upload.port.label} = SSH on my-board (192.168.1.232)
{upload.port.protocol} = ssh
{upload.port.protocolLabel} = SSH Network port
{upload.port.properties.macprefix} = AA:BB:CC
{upload.port.properties.macaddress} = AA:BB:CC:DD:EE:FF
{serial.port} = 192.168.1.232                  # 後方互換性のため

この設定とプロトコルの選択により、ハードコードされた network_pattern を削除することができます。これで、古いレシピ(明瞭さのために複数の行に分割されています):

tools.bossac.upload.network_pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
                                -address {serial.port} -port 65280
                                -sketch "{build.path}/{build.project_name}.bin"

を、以下のように置き換えることができます:

tools.arduino_ota.upload.pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA"
                            -address {upload.port.address} -port 65280
                            -sketch "{build.path}/{build.project_name}.bin"

ユーザーが指定したフィールド

ネットワーク経由でのアップロードのように、ユーザーが提供しなければならないカスタムフィールドを要求するアップロードレシピがあります。この場合、レシピは特別なプレースホルダー {upload.field.FIELD_NAME} を使用しなければならず、ここでの FIELD_NAME は以下の形式を使って別途レシピで宣言されなければなりません:

tools.UPLOAD_RECIPE_ID.upload.field.FIELD_NAME=FIELD_LABEL
tools.UPLOAD_RECIPE_ID.upload.field.FIELD_NAME.secret=true

FIELD_LABEL は、フィールドの値を入力するようユーザーに求められるグラフィカルなプロンプトに表示されるラベルです。

オプションの secret プロパティは、フィールドが秘密（パスワードやトークンなど）の場合に true に設定されるべきです。

完全な例を見てみましょう:

tools.arduino_ota.upload.field.username=Username
tools.arduino_ota.upload.field.password=Password
tools.arduino_ota.upload.field.password.secret=true
tools.arduino_ota.upload.pattern="{runtime.tools.arduinoOTA.path}/bin/arduinoOTA" -address {upload.port.address} -port 65280 -username "{upload.field.username} -password "{upload.field.password}" -sketch "{build.path}/{build.project_name}.bin"

FIELD_LABEL が50文字を超える場合、49文字に切り詰められ、それに続けて省略記号（…）が追加されます。たとえばこのフィールド:

tools.arduino_ota.upload.field.some_field=This is a really long label that ideally must never be set by any platform

はユーザーに対して以下のように表示されます:

This is a really long label that ideally must nev…

アップロード検証

アップロード検証は、Arduino IDEの File > Preferences > Verify code after upload オプションまたは arduino-cli upload --verify コマンドを通じて有効にすることができます。これは、詳細パラメータと同様のシステムを使用します。

tools.TOOL_ID.ACTION.params.verify は、検証が有効な場合の ACTION.verify プロパティの値を定義し、tools.TOOL_ID.ACTION.params.noverify は検証が無効な場合の値を定義します。

{ACTION.verify} プロパティは、upload.tool の upload および program アクションにのみ定義されます。

Arduino IDE 1.6.9以前では、tools.TOOL_ID.ACTION.params.verify/noverify はサポートされておらず、{upload.verify} は検証設定に従って true/false に設定され、{program.verify} は未定義のままでした。このため、古いIDEバージョンとの後方互換性を保つためには、platform.txtに upload.verify および program.verify プロパティの定義を追加する必要があります:

[.....]
tools.avrdude.upload.verify=
[.....]
tools.avrdude.program.verify=
[.....]

これらの定義は、最新バージョンのArduino開発ソフトウェアが使用されている場合に、tools.TOOL_ID.ACTION.params.verify/noverify によって定義された値で上書きされます。

1200 bps ブートローダーリセット

一部のArduinoボードでは、シリアルポートが開かれたときにメインMCU(ブートローダーを起動)の再起動を担う専用のUSBシリアルチップが使用されています。しかし、LeonardoやZeroのようにネイティブUSB接続を持つボードは、ブートローダーにリブートする際にUSBから切断する必要があります(その後ブートローダーがUSBに再接続し、アップロードのための新しいシリアルポートを提供します)。アップロードが完了すると、ブートローダーは再びUSBから切断し、スケッチを起動します。これがUSBに再接続します。これらの再接続のため、標準的なシリアルオープン時の再起動は機能しません。なぜなら、それによってシリアルポートが消失し、再び閉じられてしまうからです。代わりに、これらのボードで実行されているスケッチは、1200 bpsのビットレートをブートローダーを起動するための信号として解釈します。

Arduino開発ソフトウェアでこれらのステップを実行するには、2つのボードプロパティをtrueに設定します:

use_1200bps_touchは、アップロード開始前に選択されたシリアルポートを短時間1200 bps(8N1)で開くことを指示します
wait_for_upload_portは、アップロードの前後でシリアルポートが(再)表示されるのをアップロード手順が待つことを指示します。これは、use_1200bps_touchが設定されている場合にのみ使用されます。設定されている場合、1200 bpsタッチを行った後、開発ソフトウェアは新しいシリアルポートが表示されるのを待ち、そのポートをアップロード用のポートとして使用します。または、元のポートが数秒以内に消失しない場合は、元のポートでアップロードを続行します(これは、ボードが既に手動でブートローダーに入れられていた場合や、切断および再接続が見逃された場合に該当することがあります)。さらに、アップロードが完了した後、IDEは再び新しいポートが表示されるのを待つか（または最初に選択されたポートが存在するか）を確認します

この1200 bpsタッチのIDE実装にはいくつかの特異性があり、新しいarduino-cli実装も異なるようです(リセット後にポートを待たないため、これはおそらくIDEで間違ったポートをシリアルモニターで開くのを防ぐためにのみ必要であり、ポートが決して消失しない場合のタイムアウトが短い)。

プログラマを使用したデフォルトのアップロード

ボードに対して upload.protocol プロパティが定義されていない場合、Arduino IDEの「アップロード」プロセスは、外部プログラマを使用したアップロードと同じ振る舞いをします。これは、プログラマを介してのみアップロードをサポートするボードにとって便利です。

シリアルポート

IDEまたはarduino-cli uploadの--portオプションを介して選択されたポートの完全なパス(たとえば/dev/ttyACM0)は、設定プロパティ {upload.port.address} として利用可能です。

ポートのパスのファイルコンポーネント(たとえばttyACM0)は、設定プロパティ {upload.port.label} として利用可能です。

IDE 1.8.15およびそれ以前との後方互換性のため、古いプロパティ serial.port はまだ利用可能であり、{upload.port.address} と同一です。代わりに serial.port.file は {upload.port.label} と同一であり、使用中のプロトコルが serial の場合のみ利用可能です。

外部プログラマを使用したアップロード

program アクションは、IDEの Sketch > Upload Using Programmer 機能または arduino-cli upload --programmer <programmer ID> を通じてトリガーされます。このアクションは、外部プログラマを使用してコンパイルされたスケッチをボードに転送するために使用されます。

program.tool プロパティは、このアクションに使用されるツールを決定します。このプロパティは通常、programmers.txt内の各プログラマーに対して定義され、アップロードアクションと同じ構文を使用します:

[......]
usbasp.program.tool.serial=avrdude
[......]
arduinoasisp.program.tool.serial=avrdude
[......]
arduinoisp.program.tool.default=avrdude
[......]

IDE 1.8.15およびそれ以前との後方互換性のために、以前の構文もまだサポートされています:

[......]
usbasp.program.tool=avrdude
[......]
arduinoasisp.program.tool=avrdude
[......]

このアクションは、uploadアクションと同様に、アップロード検証の優先設定システムをprogram.verifyプロパティを介して使用することができます。

Arduino IDEを使用する場合、選択されたプログラマーがボードと異なるプラットフォームからのものである場合、プログラマーのプラットフォームで定義されたprogramレシピは、ボードプラットフォームのplatform.txtで定義されたプロパティからのオーバーライドなしで使用されます。 Arduino IDE以外のArduino開発ソフトウェアを使用する場合、プロパティの処理は標準的なアップロードを行う場合と同じです。

ブートローダーの書き込み

eraseおよびbootloaderアクションは、Arduino IDEのTools > Burn Bootloader機能またはarduino-cli burn-bootloaderを通じてトリガーされます。このアクションは、ボードへのブートローダーのフラッシュに使用されます。

「ブートローダーの書き込み」は、2つのアクションを使用し、それらが順序立てて実行される点で独特です:

eraseは通常、マイクロコントローラのフラッシュメモリを消去し、ボード定義で定義されたプロパティに従って設定ヒューズを設定するために使用されます
bootloaderはボードにブートローダーをフラッシュするために使用されます

bootloader.tool プロパティは、eraseおよびbootloaderの両アクションに使用されるツールを決定します。このプロパティは通常、boards.txt内の各ボードに対して定義され、アップロードアクションと同じ構文を使用します:

[......]
uno.bootloader.tool.serial=avrdude
[......]
leonardo.bootloader.tool.serial=avrdude
leonardo.bootloader.tool.network=arduino_ota
[......]
duemilanove.bootloader.tool.default=avrdude
[......]

IDE 1.8.15およびそれ以前との後方互換性のため、以前の構文もまだサポートされています:

[......]
uno.bootloader.tool=avrdude
[......]
leonardo.bootloader.tool=avrdude
[......]

Arduino IDEを使用する場合、ボードがコア参照を使用している場合、eraseおよびbootloaderアクションのレシピを定義する際に、コアプラットフォームのplatform.txtは一切使用されません。Arduino IDE以外のArduino開発ソフトウェアを使用する場合、コアプラットフォームのplatform.txtからのプロパティの処理は通常どおり行われます。

スケッチのデバッグ構成

Arduino CLI 0.9.0 / Arduino IDE 2.xから、プラットフォームに対するスケッチデバッグサポートが利用可能になりました。

デバッグアクションは、ユーザーがArduino IDEでデバッグボタンをクリックするか、arduino-cli debug コマンドを実行したときにトリガーされます。

デバッグセッションを開始するには多数のツールの調整が必要なため、CLI/IDEがその任務を担います。アップロードアクションとは異なり、プラットフォームがデバッグレシピを提供する必要はありません。唯一の要件は、いくつかのデバッグ設定指令を提供することです。

デバッガー設定指令

すべてのデバッグ指令はdebug.*の下にグループ化されています。サポートされている指令の完全なリストは以下の通りです:

debug.executable: スケッチのコンパイル済みバイナリへの絶対パスです
debug.toolchain: 必要なツールチェーンのユニークな識別子で、現在はgcc（および互換性のあるもの）のみをサポートしています
debug.toolchain.path: ツールチェーンディレクトリへの絶対パスです
debug.toolchain.prefix: ツールチェーンのプレフィックス(たとえばarm-none-eabi-)です
debug.server: 必要なデバッグサーバーのユニークな識別子で、現在はopenocdのみをサポートしています
debug.svd_file: SVD記述子への絶対パスです

debug.executableプロパティが存在しないか空の場合、デバッグは許可されません。

OpenOCDサーバー固有の設定:

debug.server.openocd.path: OpenOCDディレクトリへの絶対パスです
debug.server.openocd.scripts_dir: OpenOCDスクリプトディレクトリへの絶対パスです
debug.server.openocd.scripts.N: 実行するOpenOCDスクリプトファイルのリストで、Nは数値です(連続しない数値のシーケンスが許可されます)
debug.server.openocd.script: 実行するOpenOCDスクリプトが1つだけの場合、この指令はdebug.server.openocd.scripts.Nの代わりに使用できます(この指令は、debug.server.openocd.scripts.Nが存在する場合は無視されます)

Arduino IDE用Cortex-debugプラグインのカスタム設定

Arduino IDEは、デバッグセッションを開始するためにcortex-debugプラグインを使用します。 IDEは、cortex-debugプラグインを介してデバッグを開始するために必要なlaunch.jsonファイルを作成します。プラットフォーム開発者により多くの柔軟性を提供するため、IDEによって生成されたlaunch.jsonに任意の追加セットアップを渡すことが許可されています。これを可能にするために、グループdebug.cortex-debug.custom.*の下の指令はJSONに変換され、生成されたlaunch.jsonにそのまま追加されます。さらに、指令が数値のサフィックスを持つキーを持つ場合、それはJSON配列に変換されます。

たとえば、以下の指令があります:

debug.cortex-debug.custom.postAttachCommands.0=set remote hardware-watchpoint-limit 2
debug.cortex-debug.custom.postAttachCommands.1=monitor reset halt
debug.cortex-debug.custom.postAttachCommands.2=monitor gdb_sync
debug.cortex-debug.custom.postAttachCommands.3=thb setup
debug.cortex-debug.custom.postAttachCommands.4=c
debug.cortex-debug.custom.overrideRestartCommands.0=monitor reset halt
debug.cortex-debug.custom.overrideRestartCommands.1=monitor gdb_sync
debug.cortex-debug.custom.overrideRestartCommands.2=thb setup
debug.cortex-debug.custom.overrideRestartCommands.3=c

以下はArduino IDEで生成されて launch.json にマージされるJSONです:

{
  "overrideRestartCommands": ["monitor reset halt", "monitor gdb_sync", "thb setup", "c"],
  "postAttachCommands": [
    "set remote hardware-watchpoint-limit 2",
    "monitor reset halt",
    "monitor gdb_sync",
    "thb setup",
    "c"
  ]
}

すべての値は、デフォルトでJSON内で文字列に変換されます。他のタイプが必要な場合、値は [boolean]、[number]、[string]、または [object] のタグで始めて、JSON内で特定のタイプを強制することができます。さらに、プロパティの階層はJSONオブジェクトを構築するために使用できます。例えば:

debug.cortex-debug.custom.aBoolean=[boolean]true
debug.cortex-debug.custom.aNumber=[number]10
debug.cortex-debug.custom.anotherNumber=[number]10.20
debug.cortex-debug.custom.anObject=[object]{"key":"value", "boolean":true}
debug.cortex-debug.custom.anotherObject.key=value
debug.cortex-debug.custom.anotherObject.boolean=[boolean]true

これにより、次のようなJSONが生成されます:

{
  "aBoolean": true,
  "aNumber": 10,
  "anotherNumber": 10.2,
  "anObject": {
    "boolean": true,
    "key": "value"
  },
  "anotherObject": {
    "boolean": true,
    "key": "value"
  }
}

ディレクティブによる追加のデバッガー構成の選択

debug.additional_configディレクティブを使用して、デバッガー設定をオーバーライドするためのプラットフォーム設定の任意のサブツリーを使用することができます。このルールは、現在の debug.* 設定をオーバーライドするために CONFIG_PREFIX.* の構成を使用します。

この変更により、デバッガーに適用する設定をより便利に合理化および選択できます。例えば、プラットフォームの platform.txt ファイルで設定の共通部分を要因化できます:

# CONFIG 1
debug-overrides.esp32.cortex-debug.custom.name=Arduino on ESP32
debug-overrides.esp32.cortex-debug.custom.request=attach
debug-overrides.esp32.cortex-debug.custom.postAttachCommands.0=set remote hardware-watchpoint-limit 2
debug-overrides.esp32.cortex-debug.custom.postAttachCommands.1=monitor reset halt
debug-overrides.esp32.cortex-debug.custom.postAttachCommands.2=monitor gdb_sync
debug-overrides.esp32.cortex-debug.custom.postAttachCommands.3=thb setup
debug-overrides.esp32.cortex-debug.custom.postAttachCommands.4=c
debug-overrides.esp32.cortex-debug.custom.overrideRestartCommands.0=monitor reset halt
debug-overrides.esp32.cortex-debug.custom.overrideRestartCommands.1=monitor gdb_sync
debug-overrides.esp32.cortex-debug.custom.overrideRestartCommands.2=thb setup
debug-overrides.esp32.cortex-debug.custom.overrideRestartCommands.3=c

# CONFIG 2
debug-overrides.esp32s2.cortex-debug.custom.name=Arduino on ESP32-S2
debug-overrides.esp32s2.cortex-debug.custom.request=attach
debug-overrides.esp32s2.cortex-debug.custom.postAttachCommands.0=set remote hardware-watchpoint-limit 2
debug-overrides.esp32s2.cortex-debug.custom.postAttachCommands.1=monitor reset halt
debug-overrides.esp32s2.cortex-debug.custom.postAttachCommands.2=monitor gdb_sync
debug-overrides.esp32s2.cortex-debug.custom.postAttachCommands.3=thb setup
debug-overrides.esp32s2.cortex-debug.custom.postAttachCommands.4=c
debug-overrides.esp32s2.cortex-debug.custom.overrideRestartCommands.0=monitor reset halt
debug-overrides.esp32s2.cortex-debug.custom.overrideRestartCommands.1=monitor gdb_sync
debug-overrides.esp32s2.cortex-debug.custom.overrideRestartCommands.2=thb setup
debug-overrides.esp32s2.cortex-debug.custom.overrideRestartCommands.3=c

そして、boards.txt ファイル内でボードに応じて使用する構成を選択することができます。

myboard.name=esp32を搭載したボード
myboard.debug.additional_config=debug-overrides.esp32

anotherboard.name=esp32s2を搭載したボード
anotherboard.debug.additional_config=debug-overrides.esp32s2
...

もう一つの可能性は、ボード構成内で他の変数を使用して構成を作成することです。たとえば、platform.txt に次のように追加する場合:

debug.additional_config=debug-overrides.{build.mcu}

build.mcu の値を使用して、ボード固有のデバッグ構成をグローバルなデバッグ構成にオーバーラップさせる「セレクタ」として使用できます。

myboard.name=esp32を搭載したボード
myboard.build.mcu=esp32
...

anotherboard.name=esp32s2を搭載したボード
anotherboard.build.mcu=esp32s2
...

デバッグ用の最適化レベル

デバッグ中に通常の使用に適したコンパイラの最適化レベルは、良いエクスペリエンスを提供しないことがあります。そのため、デバッガと共にスケッチをコンパイルする際に異なるコンパイラフラグを使用することが役立つことがあります。デバッグ用にコンパイルする際のフラグは、compiler.optimization_flags.debug プロパティを介して定義でき、通常の使用のためのフラグは compiler.optimization_flags.release プロパティを介して定義できます。 compiler.optimization_flags プロパティは、Arduino Pro IDE の Sketch > Optimize for Debugging 設定または arduino-cli compile の --optimize-for-debug オプションに応じて、どちらか一方に定義されます。

カスタムボードオプション

特定のボードに対してユーザーが選択可能な設定オプションを提供すると便利なことがあります。たとえば、ボードは異なるマイクロコントローラを搭載した2つ以上のバリアントで提供されるか、ボードモデルに応じてクリスタル速度が異なる場合などが考えられます。

Arduino CLIを使用する場合、オプションはFQBNを介して選択するか、--board-options フラグを使用して選択できます。

Arduino IDEを使用する場合、これらのオプションは「ツール」メニューの下に追加のメニューアイテムを追加します。

Arduino Web Editorを使用する場合、オプションは「Flavours」メニューに表示されます。

カスタムオプションがどのように実装されるかの例を見てみましょう。この例で使用するボードはArduino Duemilanoveです。このボードはATmega168マイクロコントローラを搭載したモデルと、ATmega328Pを搭載したモデルの2つのモデルで製造されました。したがって、この例では"cpu"MENU_IDを使用して、ユーザーが2つの異なるマイクロコントローラの間から選択できるカスタムオプションを定義します。

まず、menu.MENU_ID=Text プロパティのセットを定義する必要があります。 Text は、作成するカスタムメニューごとにGUIに表示されるテキストで、boards.txt ファイルの先頭で宣言する必要があります。

menu.cpu=Processor
[.....]

この場合、メニューの名前は「Processor」です。

次に、boards.txt ファイル内で、Duemilanoveボードのデフォルト設定(すべてのプロセッサに共通)を追加しましょう。

menu.cpu=Processor
[.....]
duemilanove.name=Arduino Duemilanove
duemilanove.upload.tool=avrdude
duemilanove.upload.protocol=arduino
duemilanove.build.f_cpu=16000000L
duemilanove.build.board=AVR_DUEMILANOVE
duemilanove.build.core=arduino
duemilanove.build.variant=standard
[.....]

次に、“cpu” オプションの可能な値を定義しましょう。

[.....]
duemilanove.menu.cpu.atmega328=ATmega328P
[.....]
duemilanove.menu.cpu.atmega168=ATmega168
[.....]

2つの値、"atmega328"と"atmega168"を定義しました。

プロパティのキーは、BOARD_ID.menu.MENU_ID.OPTION_ID=Text の形式に従う必要があります。ここで、Text はIDEのGUIの"Processor"メニューに表示される内容です。

最後に、各オプション値に対する具体的な設定を行います。

[.....]
## Arduino Duemilanove w/ ATmega328P
duemilanove.menu.cpu.atmega328=ATmega328P
duemilanove.menu.cpu.atmega328.upload.maximum_size=30720
duemilanove.menu.cpu.atmega328.upload.speed=57600
duemilanove.menu.cpu.atmega328.build.mcu=atmega328p

## Arduino Duemilanove w/ ATmega168
duemilanove.menu.cpu.atmega168=ATmega168
duemilanove.menu.cpu.atmega168.upload.maximum_size=14336
duemilanove.menu.cpu.atmega168.upload.speed=19200
duemilanove.menu.cpu.atmega168.build.mcu=atmega168
[.....]

ユーザーがオプション値を選択すると、その値の"サブプロパティ"がグローバル設定にコピーされることに注意してください。たとえば、ユーザーが"Processor"メニューから"ATmega168"を選択した場合、またはArduino CLIを使用してFQBN arduino:avr:duemilanove:cpu=atmega168 を使用した場合、atmega168の設定がグローバルで利用可能になります。

duemilanove.menu.cpu.atmega168.upload.maximum_size     =>   upload.maximum_size
duemilanove.menu.cpu.atmega168.upload.speed            =>   upload.speed
duemilanove.menu.cpu.atmega168.build.mcu               =>   build.mcu

定義できるカスタムメニューの数に制限はありません。

他のコア、バリアント、またはツールの参照

Arduinoプラットフォームの参照システムを使用すると、それらのコンポーネントを複製する必要がある場合に、他のプラットフォームのコンポーネントを使用できます。この機能により、新しい “ハードウェア” を定義するために必要なファイルの最小セットを、boards.txt ファイルのみに削減できます。

コアの参照

boards.txt内で、他のベンダー/メンテナーが提供するコアを使用するボードを、VENDOR_ID:CORE_ID の構文を使用して定義できます。たとえば、“arduino” ベンダーから “arduino” コアを使用するボードを定義したい場合、次のように記述する必要があります:

[....]
myboard.name=My Wonderful Arduino Compatible board
myboard.build.core=arduino:arduino
[....]

なお、“myboard” のアーキテクチャと同じアーキテクチャが使用されているため、“arduino:avr:arduino” の代わりに “arduino:arduino” と記述する必要はありません。

platform.txtの設定は、参照されたコアプラットフォームから継承されるため、特定のプロパティをオーバーライドする必要がない限り、platform.txtを提供する必要はありません。

参照されたプラットフォームのバンドルライブラリが使用されるため、参照プラットフォームはこれらのライブラリをバンドルする必要はありません。ライブラリが提供される場合、利用可能なライブラリのリストは2つのライブラリの合計であり、参照プラットフォームが優先されます。

参照プラットフォームによってプログラマが提供されるため、これらのプログラマを定義する必要はありません。参照プラットフォームが独自のプログラマ定義を提供する場合、利用可能なプログラマのリストは2つのプラットフォームのプログラマの合計となります。 Arduino IDE 1.8.12以前では、インストールされたすべてのプラットフォームのプログラマが利用可能でした。

バリアントの参照

同様に、構文 VENDOR_ID:VARIANT_ID を使用して、他のプラットフォームで定義されたバリアントを使用できます：

[....]
myboard.build.variant=arduino:standard
[....]

ただし、コアの参照とは異なり、他のリソース（platform.txt、バンドルされたライブラリ、プログラマ）は参照されたプラットフォームから_継承されないことに注意してください。

ツールの参照

他のプラットフォームのplatform.txtで定義されたツールレシピも、構文 VENDOR_ID:TOOL_ID を使用して参照できます:

[....]
myboard.upload.tool=arduino:avrdude
myboard.bootloader.tool=arduino:avrdude
[....]

Arduino CLIまたはArduino IDE 2.xを使用する場合(ただし、Arduino IDE 1.xではない)、参照されたツールレシピで使用されるプロパティは、参照プラットフォームのplatform.txtでオーバーライドできます。

コアの参照とは異なり、ツールレシピを参照することによって、参照プラットフォームから他のリソースが継承されないことに注意してください。

プラットフォームの用語

ボードが異なるプラットフォームでコア、バリアント、ツールを参照できるため、1つのビルドまたはアップロードで最大4つの異なるプラットフォームからデータを使用できます。これを明確にするために、以下の用語が使用されます。

"ボードプラットフォーム"は、現在選択されているボードを定義するプラットフォームです(たとえば、ボードが定義されているboard.txtを含むプラットフォーム)
"コアプラットフォーム"は、使用するコアを含むプラットフォームです
"バリアントプラットフォーム"は、使用するバリアントを含むプラットフォームです
"ツールプラットフォーム"は、現在の操作で使用されるツールを含むプラットフォームです

最も一般的なケースでは、参照なしのボードプラットフォームでは、これらすべてが同じプラットフォームを指します。

上記の用語は一般的には広く使用されていませんが、このドキュメント内で明確にするために作成されたものです。実際のArduino CLIコードでは、"ボードプラットフォーム"はtargetPlatformと呼ばれ、"コアプラットフォーム"はactualPlatformと呼ばれ、他のものはほとんど名前がありません。

boards.local.txt

Arduino IDE 1.6.6で導入されました。このファイルは、boards.txtで定義されたプロパティを上書きしたり、boards.txtを変更せずに新しいプロパティを定義したりするために使用できます。このファイルは、それを補完するboards.txtと同じフォルダに配置する必要があります。

プラットフォームにバンドルされたライブラリ

プラットフォームのlibrariesサブフォルダに配置されたArduinoライブラリは、プラットフォームのボードが選択された場合、またはプラットフォームのコアを参照するプラットフォームのボードが選択された場合にアクセス可能です。他のボードが選択されている場合、プラットフォームにバンドルされているライブラリはアクセスできません。

これらは、多くの場合、アーキテクチャ固有のライブラリ(たとえばSPI, Wire)であり、各アーキテクチャごとに異なる方法で実装する必要があります。

プラットフォームのバンドルライブラリは、ビルトインライブラリを上書きするために依存関係解決システムを使用する専門バージョンのライブラリを提供するために使用できます。

詳細については、Arduinoライブラリ仕様を参照してください。

keywords.txt

Arduino IDE 1.6.6以降、プラットフォームのアーキテクチャフォルダにkeywords.txtファイルを追加することで、プラットフォームごとのキーワードを定義できます。これらのキーワードは、そのプラットフォームのボードのいずれかが選択されている場合にのみ、Arduino IDEでハイライト表示されます。このファイルは、ライブラリで使用されるkeywords.txtと同じフォーマットに従います。

インストール後のスクリプト

Boards Managerがプラットフォームのインストールを完了すると、次のスクリプトの存在をチェックします:

post_install.bat - Windowsで実行中の場合
post_install.sh - Windows以外のオペレーティングシステムで実行中の場合

これらのスクリプトが存在する場合、実行されます。

このスクリプトは、ドライバのインストールなどプラットフォームのためにユーザーのシステムを設定するために使用できます。

post-installスクリプトが実行される条件は、使用しているArduino開発ソフトウェアによって異なります：

Arduino IDE 1.x: インストールされたプラットフォームがArduinoの秘密鍵で署名されている場合にスクリプトが実行されます
Arduino IDE 2.x: インストールされたプラットフォームに対してスクリプトが実行されます
Arduino CLI: (0.12.0以降)Arduino CLIが「対話モード」で実行されている場合、インストールされたプラットフォームに対してスクリプトが実行されます。この動作は設定可能です

アンインストール前スクリプト

Boards Managerがプラットフォームのアンインストールを開始する前に、次のスクリプトの存在をチェックします:

pre_uninstall.bat - Windowsで実行中の場合
pre_uninstall.sh - Windows以外のオペレーティングシステムで実行中の場合

これらのスクリプトが存在する場合に実行されます。

このスクリプトは、ドライバの削除、バックグラウンドプログラムの停止、およびプラットフォームのファイルが削除される前に実行する必要があるアクションなど、ユーザーのシステムを設定するために使用できます。

pre-uninstallスクリプトが実行される条件は、使用しているArduino開発ソフトウェアによって異なります:

Arduino CLI: Arduino CLIが「対話モード」で実行されている場合、インストールされたプラットフォームに対してスクリプトが実行されます。この動作は設定可能です