= ユーザマニュアル（アプリケーション開発者向け） =
{{{
#!html
}}}
EV3RT上でアプリケーションを開発する際に必要となる情報をまとめたマニュアルです。
== 1. Application Programming Interface ==
=== 1.1 利用できるAPI ===
本プラットフォームでは、下記のAPIを使ってアプリケーションを開発することができます。
* TOPPERS／HRP2カーネルAPI
* リアルタイムOSの機能を提供します
* 詳細は、「[http://www.toppers.jp/documents.html#ngki_spec TOPPERS新世代カーネル統合仕様書 Release 1.7.1]」の第4章カーネルAPI仕様を参照してください
* EV3RTで変更された仕様、制限事項があります。[wiki:DiffConstraints こちら]のページを参考にしてください。
* 標準Cライブラリ（Newlib）
* アプリケーションをC言語で開発する際に、文字列操作や入出力等で必要となる基本的な機能を提供します
* 詳細は「[https://sourceware.org/newlib/docs.html Newlib Documentations]」を参照してください
* EV3用C言語API
* モータ、センサ等EV3独自の機能をサポートするC言語のAPIです
* 詳細は「[http://www.toppers.jp/ev3pf/EV3RT_C_API_Reference/index.html EV3RT C言語APIリファレンス]」を参照してください
* その他の機能
* Bluetooth 通信機能
* SDカードのファイル管理機能
=== 1.2 Bluetooth 通信機能 ===
本プラットフォームはBluetoothのSerial Port Profile（SPP）をサポートします。Bluetooth接続を仮想のシリアルポートとして通信することができます。
TOPPERS／HRP2カーネルのシリアルインターフェスドライバを利用する場合、SIO_PORT_BTというID番号で下記の例のようにBluetooth通信を行うことができます。
{{{
// Bluetooth仮想シリアルポートからbufが指すバッファへ最大lenバイトを読み込む
serial_rea_dat(SIO_PORT_BT, buf, len);
// bufが指すバッファからBluetooth仮想シリアルポートへ最大lenバイトを書き込む
serial_wri_dat(SIO_PORT_BT, buf, len);
}}}
また、SIO_BT_FILENOというファイルディスクリプタを使って標準Cライブラリのファイル操作関数でも下記の例のようにBluetooth通信を実現できます。
{{{
// Bluetooth仮想シリアルポートのファイルをオープンする
FILE *bt = ev3_serial_open_file(EV3_SERIAL_BT);
// 書式化した文字列をBluetooth仮想シリアルポートへ書き込む
fprintf(bt, "Bluetooth SPP ID: %d\n", EV3_SERIAL_BT);
// Bluetooth仮想シリアルポートから1文字を読み取る
int c = fgetc(bt);
}}}
これらの受送信機能を使って、Bluetoothでの情報出力やリモートコントロール等が実現できます。
=== 1.3. SDカード内のファイル操作 ===
本プラットフォームはSDカード内のファイル操作をサポートします。ファイル操作は標準Cライブラリのファイル操作関数とEV3用C言語APIのファイルシステムに関する関数で実現できます。これらの関数を操作する時、ファイル（又はディレクトリ）のパスが必要する場合があります。その場合、ルートフォルダ「/」はSDカードのルートフォルダを意味します。例えば、「/test.wav」はSDカードのルートフォルダ内にある「test.wav」を指します。
== ==
== 2.アプリケーションのビルド管理 ==
=== 2.1. アプリケーションのフォルダ構成 ===
アプリケーションのフォルダの典型的な構成は以下のようです。
{{{
.
├── app.c アプリケーションのデフォルトのソースファイル
├── app.cfg アプリケーションのコンフィグレーションファイル
├── app.h アプリケーションのデフォルトのヘッダファイル
├── Makefile.inc 全ての実行形式で共有するメイクファイル
├── Makefile.appmod 動的ローディング形式用のメイクファイル
├── Makefile.app スタンドアローン形式用のメイクファイル
├── … 他のフォルダ（無い場合もある）
│ └── …
└── … 他のファイル（無い場合もある）
}}}
単一ソースファイルしかない小規模のアプリケーションに対して、「app.c/.h」の内容を修正するだけで十分です。但し、比較的に大規模のアプリケーションの場合、複数のソースファイルで開発することが多いです。その時、ソースファイルやヘッダファイルを追加することだけではなく、「Makefile.inc」と「app.cfg」を修正する必要もあります。
=== 2.2. ソースファイルの追加 ===
アプリケーションのソースファイルは以下の手順で追加することができます。
① 追加したいソースファイル（例：newsrc.c）をアプリケーションのフォルダに入れます
② 「Makefile.inc」の「APPL_COBJS」にソースファイルのオブジェクトファイル名を追加します
{{{
例：
Before：
APPL_COBJS += app1.o
After：
APPL_COBJS += app1.o newsrc.o
}}}
③ 「app.cfg」に「ATT_MOD」でソースファイルのオブジェクトファイルのメモリオブジェクトを登録します
{{{
例：
Before：
ATT_MOD("app.o");
After：
ATT_MOD("app.o");
ATT_MOD("newsrc.o");
}}}
④ これで、ソースファイルの追加が完了しました
== 3. ワークスペース機能 ==
=== 3.1. ワークスペースとそのフォルダ構成 ===
ワークスペースはプロジェクトの入れ物です。ワークスペース機能を利用して、複数のアプリケーションのプロジェクトを管理することができます。
ワークスペースのフォルダはプラットフォームのルートフォルダ（hrp2）の下にあります。本プラットフォームで提供するサンプルアプリケーションは全てデフォルトのワークスペース（hrp2/workspace）に入っています。
ワークスペース機能を実現するためのファイルと複数のアプリケーションのフォルダから構成されます。その例として、デフォルトのワークスペースのフォルダ構成は以下のようです。
{{{
.
├── common 共有ファイルのフォルダ
│ └── …
├── gyroboy アプリケーションgyroboy
│ └── …
├── helloev3 アプリケーションhelloev3
│ └── …
├── linetrace アプリケーションlinetrace
│ └── …
└── Makefile ワークスペース用Makefile
}}}
=== 3.2. アプリケーションのビルド ===
ワークスペース機能を利用して、アプリケーションをビルドすることが簡単にできます。
ワークスペースのフォルダに移動して、以下のコマンドでアプリケーションのスタンドアローン形式のブートイメージ（uImage）をビルドできます。ビルドが正常終了したら、ワークスペースのフォルダの下に「uImage」というファイルが生成されます。
{{{
$ make img=アプリケーションのフォルダ名
}}}
ワークスペースのフォルダに移動して、以下のコマンドでアプリケーションの動作ローディング用の実行ファイル（Loadable Moduleと呼ぶ）をビルドできます。ビルドが正常終了したら、ワークスペースのフォルダの下に「app」というファイルが生成されます。
{{{
$ make app=アプリケーションのフォルダ名
}}}
=== 3.3. アプリケーションの新規作成 ===
既にワークスペースにあるアプリケーションをテンプレートとして、以下の手順で新しいアプリケーションを作成できます。
① ワークスペースのフォルダに移動します
② 「cp -r <テンプレートとしたアプリケーションのフォルダ名> <新しいアプリケーションのフォルダ名>」で新しいアプリケーションを作成できます（gyroboyをテンプレートとした例）
{{{
$ cp –r gyroboy newapp1
}}}
③ 以上で「newapp1」というアプリケーションを新規作成しました
=== 3.4. ワークスペースの新規作成 ===
既に存在するワークスペースをテンプレートとして、以下の手順で新しいワークスペースを作成できます。
① プラットフォームのルートフォルダ（hrp2）に移動します
② 「cp -r <テンプレートとしたワークスペースのフォルダ名> <新しいワークスペースのフォルダ名>」で新しいワークスペースを作成できます（デフォルトのワークスペースをテンプレートとした例）
{{{
$ cp –r workspace newworkspace1
}}}
③ 以上で「newworkspace1」というワークスペースを新規作成しました
注意：ワークスペースのフォルダは必ずプラットフォームのルートフォルダ（hrp2）に入れること
== 4. プラットフォームのカスタマイズ ==
=== ![TODO:] ===