Arduino公式文書の翻訳

2024年1月16日
 
2024年2月9日

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

スケッチ仕様書

これはArduinoスケッチの仕様です。

Arduinoボード上で動作するプログラムは「スケッチ」と呼ばれます。 この用語は 、Arduino IDE とコア API の基礎となったProcessingから継承されました。

フォルダーとファイルをスケッチする

スケッチ ルート フォルダ名とコード ファイル名は、基本文字 (A-Z または a-z、数字(0-9)1、またはアンダースコア ( _) 2で始まり、その後に基本文字、数字、アンダースコア、ドット (.)、およびダッシュ (-) が続く必要があります-。最大長は 63 文字です。スケッチ名をドット (.) で終わらせたり、予約名にすることはできません 。

1 Arduino IDE 1.8.4 からサポートされています。
2 Arduino IDE 2.0.4/Arduino CLI 0.30.0 - 0.30.1を除くすべてのバージョンでサポートされています。

スケッチルートフォルダー

多くの Arduino スケッチには 1 つの .ino ファイルしか含まれていないため、そのファイルがスケッチであると考えるのは簡単です。 ただし、スケッチとなるのはフォルダーです。 その理由は、スケッチは複数のコードファイルで構成されている可能性があり、フォルダーはそれらのファイルを1つのプログラムにグループ化するためです。

プライマリスケッチファイル

すべてのスケッチには、スケッチのルートフォルダー名と一致するファイル名の.inoファイルが含まれている必要があります。

.pde もサポートされていますが、非推奨であり、将来削除される予定です。.ino 拡張機能を使用することを強くお勧めします。

追加のコード ファイル

スケッチは複数のコード ファイルで構成されている場合があります。

次の拡張子がサポートされています。

  • .ino - Arduino言語 ファイル。
  • .pde - Arduino 言語ファイルの代替拡張子。このファイル拡張子は、スケッチの処理でも使用されます。混乱を避けるために、.ino を使用することをお勧めします。.pde 拡張子は非推奨であり、将来削除される予定です。
  • .cpp - C++ ファイル。
  • .c - C ファイル。
  • .S - アセンブリ言語ファイル。
  • .h、.hpp、.hh 1 - ヘッダー ファイル。
  • .tpp、.ipp 2 - ヘッダー ファイル。

1 .hpp および .hh は Arduino IDE 1.8.0/arduino-builder 1.3.22 からサポートされています。
2 Arduino CLI 0.19.0 からサポートされています。

これらの各ファイルとスケッチの他の部分がコンパイル中にどのように使用されるかについては、「Sketchビルドプロセスのドキュメントを参照してください。

src サブフォルダー

src サブフォルダーの内容は再帰的にコンパイルされます。スケッチルートフォルダー内のコードファイルとは異なり、これらはファイルは IDE ではタブとして表示されません。

これは、IDEのインターフェイスを介してスケッチ ユーザーに公開したくないファイルの場合に便利です。これを使用してライブラリをスケッチにバンドルし、自己完結型プロジェクトにすることができます。

src フォルダー内はArduino言語ファイルのサポートがされていません。

  • Arduino IDE 1.6.5-r5 以前では、再帰的コンパイルは行われませんでした。
  • Arduino IDE 1.6.6 ～ 1.6.9 では、スケッチフォルダーのすべてのサブフォルダーに対して再帰コンパイルが行われました。
  • Arduino IDE 1.6.10 以降では、再帰的コンパイルはスケッチフォルダーの src サブフォルダーに限定されます。

data サブフォルダー

dataフォルダーは、コンパイルされない追加ファイルをスケッチに追加するために使用されます。

Arduino IDE の Sketch > Add File… を介してスケッチに追加されたファイルは、data フォルダーに配置されます。

Arduino IDE の [File] > [Save As…] は、スケッチ ルートフォルダー内のコードファイルとその完全な内容のみをコピーします。 したがって、dataフォルダーの外にある非コード ファイルはすべて削除されます。

メタデータ

sketch.json

Arduino Web エディターは、スケッチのルートフォルダーにある sketch.json という名前のファイルを使用して、スケッチのメタデータを保存します。 このファイルは Arduino CLI または Arduino IDE では使用されません。Arduino Web Editor ユーザーでない場合は、このファイルを無視しても問題ありません。

cpuキーにはボード構成情報が含まれています。これはスケッチが開いているときに Arduino Web エディタでボードを選択することで設定できます。

include_libsキーは、Arduino Web エディターがスケッチのコンパイル時に使用するライブラリのバージョンを定義します。 これは Arduino Web エディタに固有のものです。 これは、すべてのライブラリマネージャーライブラリのすべてのバージョンが Arduino Web エディタにプリインストールされているのに対し、他のArduino開発ソフトウェアを使用する場合は、各ライブラリの1つのバージョンのみがインストールされる可能性があるためです。

スケッチプロジェクトファイル

これはsketch.yamlという名前のオプションファイルで、スケッチのルートフォルダーにあります。

スケッチプロジェクトファイル内で、ユーザーは1つ以上の「プロファイル」を定義できます。 各プロファイルは、スケッチの構築に必要なすべてのリソース(特定のバージョンに固定されたプラットフォームとライブラリ)の説明です。

スケッチ プロジェクト ファイルは、現在選択されているボードとポートを保存するために arduino-cli board attachコマンドでも使用されます。

詳細については、スケッチプロジェクトファイルのドキュメントを参照してください。

シークレット

Arduino Webエディターには、 機密データ (パスワードやトークンなど) を誤って公開することなくスケッチを簡単に共有できる「シークレットタブ機能](https://create.arduino.cc/projecthub/Arduino_Genuino/store-your-sensitive-data-safely-when-sharing-a-sketch-e7d0f0)」があります。 Arduino Webエディターは、スケッチ内の、SECRET_とすべて大文字を含む識別子に対してマクロを自動的に生成します。

Arduino Web エディターから Secret タブを含むスケッチをダウンロードすると、#defineシークレットの空のディレクティブが arduino_secrets.h という名前のファイル内にあり、#includeそのファイルへのディレクティブがプライマリスケッチファイルの先頭にあります。これは、Arduino Webエディターでスケッチを表示すると非表示になります。

ドキュメンテーション

スケッチのルートフォルダーに存在する一般的な形式の画像ファイルとテキストファイルは、Arduino Web エディターのタブに表示されます。

スケッチファイル構造の例

Foo
|_ arduino_secrets.h
|_ Abc.ino
|_ Def.cpp
|_ Def.h
|_ Foo.ino
|_ Ghi.c
|_ Ghi.h
|_ Jkl.h
|_ Jkl.S
|_ sketch.yaml
|_ data
|  |_ Schematic.pdf
|_ src
   |_ SomeLib
      |_ library.properties
      |_ src
         |_ SomeLib.h
         |_ SomeLib.cpp

スケッチブック

Arduino IDE は、「スケッチブック」フォルダー (Arduino CLI の「ユーザー ディレクトリ」に似ています) を提供します。 スケッチブックは、ユーザーライブラリと手動でインストールされたプラットフォームがインストールされる場所であることに加えて、スケッチを保存するのにも便利な場所です。 スケッチブックフォルダー内のスケッチは、Arduino IDEのFile > Sketchbookメニューに表示されます。ただし、スケッチをスケッチブックフォルダーに保存する必要はありません。

ライブラリ/ボードマネージャーのリンク

(Arduino IDE >=1.6.9 <2.x || >=2.0.1で利用可能)

コメント内の URI は次の形式になります。

http://librarymanager[/TYPE_FILTER[/TOPIC_FILTER]][#SEARCH_KEYWORDS]

Arduino IDE でクリックすると、ライブラリマネージャーで検索が開きます 。

これらのリンクを使用すると、スケッチの依存関係をインストールする簡単な方法をユーザーに提供できます。

Arduino 内でクリックすると、Boards Manager で検索が開きます。

これらのリンクを使用すると、スケッチの依存関係をインストールする簡単な方法をユーザーに提供できます。

検索フィールドには、SEARCH_KEYWORDSURIのフラグメントコンポーネントが入力されます。A - Z、a - z、0 - 9、および : 以外の文字は検索アルゴリズムによってスペースとして扱われるため、URI を介して複数のキーワードを指定できます。

(Arduino IDE >=2.0.1で利用可能)

"Type"フィルターは、 URI のオプションのTYPE_FILTERパスコンポーネントに設定されます。

ライブラリマネージャーの"Topic"フィルターは、URI のオプションの TOPIC_FILTER パスコンポーネントに設定されます。

SEARCH_KEYWORDS フラグメントとは異なり、これらのコンポーネント内のスペースと予約文字は、 パーセントエンコード (例: Signal%20Input%2FOutput)でなければなりません。

フィルター設定は以前の IDE バージョンではサポートされていませんが、これらのパス コンポーネントを含む URI は他のすべての点で引き続き機能します。

この機能は Arduino IDE を使用している場合にのみ利用できるため、他の開発ソフトウェアのユーザーがスケッチの依存関係をインストールするのに役立つ補足ドキュメントを必ず提供してください。

例

// install the Arduino SAMD Boards platform to add support for your MKR WiFi 1010 board
// if using the Arduino IDE, click here: http://boardsmanager/Arduino#SAMD

// install the WiFiNINA library via Library Manager
// if using the Arduino IDE, click here: http://librarymanager/Arduino/Communication#WiFiNINA
#include <WiFiNINA.h>

こちらも参照