SDK同梱ドキュメント：AdamAppDevelopmentManualForIpro_Vx_xx.pdf
目次
| Table of Contents | ||||
|---|---|---|---|---|
|
1.はじめに
AdamApp は、定められた形式（AdamApp パッケージ形式）にパッケージングをして、インス トールする必要があります。このため、AdamAppSDK では、AdamApp のビルドと AdamApp パッケージ 作成を、容易に行える環境を提供します。
本章では、AdamApp のビルド、及び、AdamApp パッケージ形式の作成に必要な情報と手順について、 AdamAppSDK で提供するサンプルプログラム(SkeletonSampleApp)を用いて説明します。
また、このチュートリアルでは、SDKのインストールディレクトリを${SDK_DIR}として記載します。
1.1.AdamApp のパッケージ形式
AdamApp パッケージ形式とは、カメラにインストールする際のパッケージ形式です。 具体的には、下記に示すディレクトリ構成で、かつ、これらを zip 化 ＋ 暗号化したものです。
bin/
AdamApp 実行プログラムを格納するディレクトリ
config/
コンフィギュレーション情報を格納するディレクトリ
data/
AdamApp 用外部データファイルを格納するディレクトリ
external/
AdamApp で使う外部ソフトウェアを配置するディレクトリ
setup/
セットアップスクリプトファイルを格納するディレクトリ
上記のディレクトリに、AdamApp の実行プログラムや、コンフィギュレーション情報などの関連ファイ ルを配置します。それぞれのディレクトリの詳しい説明は、下記の通りです。
⚫ bin ディレクトリ： AdamApp 実行プログラムを格納するディレクトリ
bin ディレクトリは、AdamApp の実行プログラムを格納するディレクトリです。実行プログラ ム名は、任意の名前で構いません。 なお、AdamAppSDKを用いて、AdamAppをビルド、パッケージ化した場合には、このディレ クトリに、実行プログラムが自動的に配置されます。その際、実行プログラム名は、Makefile の PROG_NAME マクロで指定した名前となります。
⚫ config ディレクトリ： コンフィギュレーション情報を格納するディレクトリ
config ディレクトリは、AdamApp 用のコンフィギュレーション情報を格納するディレクトリで す。コンフィギュレーション情報は、applicense.bin と profile.binの 2つのファイルが必須です。 applicense.bin と profile.bin の 2 つのファイルは、adamapp_configurator というツールを用い て、コンフィギュレーションファイル（AdamAppSDK のサンプルでは、configuration.txt とい う名前で配置しています）から生成します。コンフィギュレーションファイルの記載方法につい ては、★1.4 を参照してください。 なお、 AdamAppSDK を用いて、 AdamApp をビルド、パッケージ化した場合には、 configuration.txt から applicense.bin と profile.bin を自動的に生成して、このディレクトリに配 置します。
⚫ data ディレクトリ： AdamApp 用外部データファイルを格納するディレクトリ
data ディレクトリは、AdamApp 用外部データファイルを配置できる唯一のディレクトリで す。 AdamApp 用外部データファイルを、インストール時に同時にコピーしたい場合には、そのフ ァイルをこの下に配置します。インストール時に、コピーしたい AdamApp 用外部データファイ ルがない場合は、このディレクトリは空にしておきます。
⚫ external ディレクトリ： AdamApp で使う外部ソフトウェアを配置するディレクトリ
AdamApp で利用する外部ソフトウェアのライブラリファイル(.a や.so ファイル)とヘッダファイル (.h .hpp .hxx ファイルなど)を、external ディレクトリ以下に配置してください。
⚫ setup ディレクトリ： セットアップスクリプトファイルを格納するディレクトリ
setup ディレクトリは、AdamApp のインストール時、アップデート時、アンインストール時に 実行させたいシェルスクリプトを格納します。記述できるシェルスクリプトは、Bourne Shell （実際には、Bourne Shell 互換シェルである ash を利用)スクリプトのみです。 シェルスクリプトは、下記の環境変数が渡されて実行されますので、シェルスクリプト内から これら環境変数を参照することができます。
ADAM_INSTALLID
AdamApp のインストール ID
ADAM_APP_DATA_DIR
AdamApp 用外部データファイルを格納するディレクトリのパス (= data ディレクトリのパス)
ADAM_APP_TMP_DIR
AdamApp の一時的なファイルを格納するディレクトリのパス
それぞれのシェルスクリプト名は、コンフィギュレーションファイルで指定します。 なお、シェルスクリプトを使うかどうかを、スクリプト毎に任意に設定可能です。使わない場 合は、コンフィギュレーションファイルに、シェルスクリプトのファイル名を記載しないでくだ さい。（その際、setup ディレクトリに、スクリプトファイルを配置しても問題は発生しません が、FlashROM の容量を無駄に消費することになりますので、配置しない方がよいです。）
➢ インストールスクリプト（任意）
AdamApp をインストールする際に実行されるシェルスクリプトです。AdamApp がインス トールされた直後に実行されます。
➢ アップデートスクリプト（任意）
AdamApp をアップデートする際に実行されるシェルスクリプトです。AdamApp がアップ デートされた直後に実行されます。
➢ アンインストールスクリプト（任意）
AdamApp をアンインストールする際に実行されるシェルスクリプトです。AdamApp がア ンインストールされる直前に実行されます。
1.2.ターゲット依存マクロ
この節では、ターゲット依存マクロについて説明します。ターゲット依存マクロは、機種や OS などの違 いを示すもので、マクロ変数として定義され、ソースコード、ヘッダファイル、Makefileから利用すること ができます。開発者は、機種や OS などによって AdamApp の実装を変える必要がある場合、このマクロを 利用することで、作り分けることができます。
1.2.1 では、ソースコード、及び、ヘッダファイルに対するマクロの説明を行います。
1.2.2 では、Makefile に対するマクロの説明を行います。
1.2.1.ソースファイルとヘッダーファイルのマクロ
★記載準備中
1.2.2.Makefileのマクロ
★記載準備中
1.3.AdamApp パッケージの生成手順
この節では、AdamApp パッケージの具体的な作成手順について、AdamAppSDK のサンプルプログラム (SkeletonSampleApp)を用いて、説明します。 パッケージ作成手順は、大きく分けて、下記の 3 つのフェーズで構成されています。
1.ソースファイルの作成、Makefile の作成
AdamApp のソースファイルを作成します。
2.関連ファイルの作成と配置
AdamApp のビルド・動作に必要なファイルを作成し、適切なディレクトリに配置します。
3.ビルド & パッケージ作成
AdamApp のビルド（コンパイル、リンク）と、パッケージ作成を行います。
それぞれの具体的な方法について、これ以降で説明していきます。
1.3.1.ソースファイルと Makefile を生成する
(1) ソースファイルの作成と配置
AdamAppSDK では、AdamApp のソースコードは、
<AdamAppSDK の イ ン ス ト ー ル デ ィ レ ク ト リ >/src/adamapp
以下に置くことを前提としています。
その前提に従って、AdamAppSDK 付属のサンプルプログラム(SkeletonSampleApp)のソースコードは、
<AdamAppSDK の イ ン ス ト ー ル デ ィ レ ク ト リ >/src/adamapp/skeleton_sample_app
に配置されています。
このため、新規に AdamApp を作りたい場合は、
<AdamAppSDK のインストールディレクトリ>/src/adamapp/<新規 AdamApp のディレクトリ名>
のディレクトリを作成し、その下にソースコード、及び、ヘッダファイル、Makefile を作成・配置する
ようにしてください。
なお、skeleton_sample_app ディレクトリをコピーして新規ディレクトリを作成することで、新規
AdamApp 作成に必要なファイル一式もコピーされますので、新規 AdamApp を作る場合は、
skeleton_sample_app ディレクトリをコピーして利用することをお薦めします。
(2) 外部ソフトウェアのライブラリとヘッダファイルの配置（必要であれば）
AdamApp で利用する外部ソフトウェアのライブラリファイル(.a や.so ファイル)とヘッダファイル
(.h .hpp .hxx ファイルなど)を、external ディレクトリ以下に配置してください。
(3) Makefile の編集
ソースファイル、ヘッダファイルの作成後、Makefile の編集を行います。Makefileは雛形が用意されて
いますので、その雛形に必要な情報を追記して完成させます。Makefile の雛形は、変数が並んでいて、
それらの変数に値を追記する形で構成されています。
下記は、サンプルプログラム(SkeletonSampleApp)のMakefile の雛形の中から、代表的な変数を抜き出し、説明したものになります。この説明を参考にして、Makefile の編集を行って下さい。
PROG_NAME= SkeletonSampleApp
PROG_NAME は、作成されるプログラム名を指定する変数です。 プログラム名には、英数字、ハイフン、アンダースコア、ピリオドを用いることが できます。また、プログラム名の長さは 32 文字までです。
SRC_FILES= skeletonSampleApp.cpp
SRC_FILES は、ビルド対象のソースファイルを指定する変数です。 ビルド対象のすべてのソースファイルを、この変数に指定してください。 なお、この変数は、C のソースファイル（.c の拡張子のファイル）、C++のソースフ ァイル（.cpp の拡張子のファイル）を混在して指定可能です。
ADD_LIB_PATH=$(ADAM_ADD_LIB_PATH)
ADD_LIB_PATH+=
ADD_LIB_PATH は、ライプラリパスを指定する変数です。 指定時には、パス名のみを記載してください。 Adam のライブラリ以外をリンクする場合に、追記して下さい。 なお、ADD_LIB_PATH に設定済みの値[$(ADAM_ADD_LIB_PATH)]は、消さない でください。
ADD_LIBS=$(ADAM_ADD_LIBS)
ADD_LIBS+=
ADD_LIBS は、リンクするライプラリ名を指定する変数です。 Adam のライブラリ以外をリンクする場合は、この変数に追記してください。 なお、ADD_LIBS に設定済みの値[$(ADAM_ADD_LIBS)]は、消さないでください。
ADD_INCLUDE_PATH=$(ADAM_ADD_INCLUDE_PATH)
ADD_INCLUDE_PATH+=
ADD_INCLUDE_PATH は、include パスを指定する変数です。 Adam の include ファイル以外を include する場合に、そのパスを追記して下さ い。 なお、ADD_INCLUDE_PATH に設定済みの値[$(ADAM_ADD_INCLUDE_PATH)]は、 消さないでください。
PROG_CPPFLAGS= $(ADAM_DFLAGS)
PROG_CPPFLAGS+=
PROG_CPPFLAGS は、プリプロセッサオプションを指定する変数です。 AdamApp 独自のプリプロセッサオプションがある場合は、この変数に追記して下さ い。 なお、PROG_CPPFLAGSに設定済みの値[$(ADAM_DFLAGS)]は、消さないでくださ い。
PROG_CFLAGS= $(ADAM_CFLAGS)
PROG_CFLAGS+=
PROG_CFLAGS は、C のコンパイルオプションを指定する変数です。 AdamApp 独自の C コンパイルオプションがある場合は、この変数に追記して下さ い。 なお、PROG_CFLAS に設定済みの値[$(ADAM_CFLAGS)]は、消さないでくださ い。
PROG_CXXFLAGS= $(ADAM_CXXFLAGS)
PROG_CXXFLAGS+= -fno-rtti
PROG_CXXFLAGS+=
PROG_CXXFLAGS は、C++のコンパイルオプションを指定する変数です。 AdamApp 独自の C++コンパイルオプションがある場合は、この変数に追記して下さ い。 なお、PROG_CXXFLAGS に設定済みの値[$(ADAM_CXXFLAGS)]は、消さないでく ださい。
1.3.2.ファイルの生成と配置
(1) AdamApp 用外部データファイルの作成と配置
AdamApp から Read/Write したいファイルがある場合は、skeleton_sample_app/data ディレクトリ
以下に、作成・配置してください。なお、data ディレクトリ以下に配置されたファイルは、AdamApp
パッケージ作成時に、AdamApp パッケージの中に一緒に含められます。このため、AdamApp が実行
時には、AdamApp から data ディレクトリに配置されたファイルにアクセスすることができます。
(2) スクリプトファイルの作成と配置
AdamApp は、インストール時（直後）、アップデート時（直後）、アンインストール時（直前） に、指定されたスクリプトを実行する機能を持っています。それぞれの時に、実行したいスクリプトが あれば、skeleton_sample_app/setup ディレクトリに配置してください。もし、実行したいスクリプト がなければ、配置する必要はありません。
(3) コンフィギュレーションファイルの作成
1.4 章★に示す記載方法に従って、コンフィギュレーションファイルを作成し、configuration.txt という ファイル名で、skeleton_sample_app/ディレクトリ直下に配置してください。
(4) 設定値ファイルの作成
AdamApp で、設定値管理機能を用いる場合は、「App Preference Function Guide」★に従って、設定 値管理ファイルを作成し、appPrefs.json というファイル名で、skeleton_sample_app/ディレクトリ直 下に配置してください。
1.3.3.AdamApp のビルドとパッケージの生成
AdamApp に必要なファイルの作成と配置が完了したら、AdamApp のビルドとパッケージ作成を行いま
す。具体的には、(1)AdamApp の実行環境に対応する設定ファイルを読み込み、(2)make の実行、を実施し
ます。
詳しい手順について、これ以降で説明します。
(1) ビルド用環境設定ファイルの読み込み
ビルド用環境設定ファイルとして、setup_env.sh が用意されています。これを source コマンドを用い て読み込むことで、環境設定が完了します。その際、AdamApp を動作させる実行環境に応じて、引数 を指定する必要があります。
指定できる引数は下記の通りです。
i-pro ambaCV2X 用の AdamApp を作成する場合：
ipro-ambaCV2X
下記に、それぞれの場合の詳細な手順を示します。
| Code Block |
|---|
$ cd ${SDK_DIR}
$ source setup_env.sh ipro-ambaCV2X |
| Info |
|---|
下記のようなメッセージが表示されれば、ビルド用環境設定ファイルの読み込みは成功です。 ***** /usr/local/linaro-aarch64-2018.08-gcc8.2/bin/aarch64-linux-gnu-gcc found. ***** |
(2) make の実行（AdamApp のビルド&パッケージの作成）
続いて、AdamApp（追加アプリ）のビルドとパッケージ作成を行うために、make を実行します。
make を実行すると、ビルドとパッケージの作成を一気に行います。make が成功した場合には、
skeleton_sample_app ディレクトリ直下に、
SkeletonSampleApp ：
SkeletonSampleApp の実行プログラム
SkeletonSampleApp.zip ：
SkeletonSampleApp のパッケージ
SkeletonSampleApp.ext ：
SkeletonSampleApp.zip を Base64 化したもの
の 3 つのファイルが生成されます。
| Code Block |
|---|
$ cd src/adamapp/skeleton_sample_app $ ls –CF Makefile configuration.txt skeletonSampleApp.cpp bin/ data/ setup/ $ make (略) $ ls –CF Makefile bin/ setup/ SkeletonSampleApp* configuration.txt skeletonSampleApp.cpp SkeletonSampleApp.ext conf/ skeltonSampleApp.d SkeletonSampleApp.zip data/ skeltonSampleApp.o |
make の実行によって、生成される 3 つのファイルの詳細な説明は、下記の通りです。
SkeletonSampleApp ：
デバッグ情報付きの実行プログラムです。gdbserver などを使って、AdamApp のデバッグする時に は、このファイルを用いて、デバッグ情報の読み込みを行います。なお、bin/SkeletonSampleApp は、デバッグ情報を取り除かれた実行プログラムです。
SkeletonSampleApp.zip ：
必要な情報を格納した bin, data, config, setup の各ディレクトリを zip 化したパッケージファイルで す。AdamApp をインストールする際には、このファイルを用います。また暗号化する際は、この ファイルを i-PRO 株式会社へ送付します。
SkeletonSampleApp.ext ：
SkeletonSampleApp.zip を Base64 化したパッケージファイルです。AdamApp のインストールす る際に、zip ファイルではなく、Base64 ファイルを指定する必要がある場合に、このファイルを用 います。（監視カメラの商品 UI を用いてのインストールなど）
1.4.コンフィギュレーションファイルのフォーマット
コンフィギュレーションファイルとは、AdamApp の動作に必要な情報を記述したファイルです。Adam
実行環境は、このファイルの内容を参照して、AdamApp の制御（インストール/開始など）を行います。このため、このファイルの内容が誤っている場合は、AdamApp のインストールや開始に失敗することがありますので、正確に記述してください。
なお、このファイルは、AdamApp パッケージの作成時に参照されますので、AdamApp 作成のための
make 実行前までに作成しておく必要があります。
1.4.1 では、コンフィギュレーションファイルの記述すべき項目についての説明を行います。
具体的な記述例については、任意のサンプルアプリのconfiguration.txt を参照してください。
${SDK_DIR}/src/adamapp/[任意のサンプルアプリ]/configuration.txt
1.4.1.configuration.txt の各用語
コンフィギュレーションファイルの各項目は、タグと値で構成されており、下記のフォーマットで記述し ます。
# 行頭の「#」はコメントアウトを表わす
# head of line ‘#’ means comment out
TagName Value
TagName と Value の間の空白は、１文字以上のスペースか、タブで構成してください。行頭の「#」は、
コメントアウトを表わします。なお、行の途中に「#」が来ても、コメントアウトとは認識されませんの
で、ご注意ください。
具体的なタグの種類は、Table1.4.1-1 に示しています。また、Value に使える文字は、タグの種類によって異なりますので、こちらについても Table1.4.1-1 を参照してください。
記述の具体例を下記に示します。
# AdamApp 実行ファイル名の設定
# set of the name of execution file of AdamApp
APPLICATION SkeletonSampleApp
# AdamApp のバージョンの設定
# set of version of AdamApp
APPVERSION V0.01
また、項目によっては、複数設定することも可能です。複数設定する場合は、下記のように項目を複数の 項目を並べて記述してください。
# APPNAME(AdamApp の正式名称)の設定
# set of the official name of AdamApp
APPNAME0 Sample Application
APPNAME1 サンプルアプリケーション
APPNAME5 esempio di applicazione
コンフィギュレーションファイルに記載できるタグ名の種類は、下記の通りです。
なお、選択性に、「M（Mandatory）」と書かれている項目は、記述必須の項目です（何も書かれていてい
ない項目は、省略可能です）。
Table 1.4.1-1 コンフィギュレーションファイルに記載するタグの説明
タグ名 | 説明 | 複数指定 | 選択性 | |||
|---|---|---|---|---|---|---|
ア プ リ ケ ー シ ョ ン 名 関 連 情 報 | APPLICATION | AdamApp の実行ファイル名。 Makefile の PROG_NAME 変数と同じ名前を記載します。 使える文字は、英数字、ハイフン、アンダースコア、ピリオド で、256 文字以内です。 | M | |||
APPVERSION | AdamApp のバージョン。 使える文字は、英数字、ピリオドで、7 文字以内です。 | M | ||||
APPNAME | AdamApp の正式名称。 各言語に対応するタグ名は下記の通りです。
なお、APPNAME0(英語)は、必ず指定してください。その他の | O | M | |||
リ ソ ー ス 関 連 情 報 | ROMSIZE (*1) | AdamApp が利用する ROM 使用量 (KB)。 | M | |||
RAMSIZE (*2) | AdamApp が利用する RAM 使用量（KB）。 | M | ||||
CPURATE (*2) | AdamApp が利用する CPU 使用率（％）。 | M | ||||
AIACCRATE (*2) | AdamApp が利用する AI アクセラレータ使用率(%) | |||||
AIMEMSIZE (*3) | AdamApp が利用する AI メモリ使用量(KB) | |||||
ス ク リ プ ト フ ァ イ ル 情 報 | INSTALLER | インストール実行直後に実行されるシェルスクリプト名。 | ||||
UPDATER | アップデート実行直後に実行されるシェルスクリプト名。 | |||||
UNINSTALLER | アンインストール実行直前に実行されるシェルスクリプト名。 | |||||
ラ イ セ ン ス 関 連 情 報 | FUNCID | 機能 ID。機能 ID は、AdamApp 毎に一意に割当てられる値で、通常、i-PRO 株式会社によって定められます。
| M | |||
*1: ROMSIZE
以下の合計：
実行可能なファイルと共有ライブラリ（Linux サイズコマンドで取得した”text”と”data”のフィールドの合計値）。
Data ディレクトリの容量
Conf ディレクトリの容量
*2: RAMSIZE, CPURATE, AIACCRATE,
初めにサンプルアプリケーションと同じ値を設定してください。最後に、i-PRO カメラ上でアプリケーションを実行した際の値を設定してください。これらのパラメータについては Section8★ を参照ください。
また、利用可能な ROM/RAM のリソースについては Section10★ を参照ください。
*3: AIMEMSIZE
サンプルアプリケーションと同じ値を設定してください。
1.5.AIアクセラレーターの活用事例
| Note |
|---|
・AI アクセラレータは i-pro ambaCV2X モデル向けの AdamApp でのみ、利用可能です。 ・ツール(cvtool)は AdamAppSDK には含まれていません。必要な場合には、i-PRO 株式会社にお問合せください。 |
i-pro ambaCV2X モデルのカメラには、AI の推論処理用アクセラレータ(CVFlow)を内蔵しています。
AdamApp からは、専用の API 経由でこのアクセラレータを使用することが可能です。API の入力として、アクセラレータ用のバイナリファイルが必要になります。以下の手順でバイナリの作成、およびAdamApp への組み込みを行ってください。
[手順]
学習済みの AI モデルを、アクセラレータ用のバイナリファイルに変換します。
1.3.AdamApp パッケージの生成手順の記載手順にしたがって、AdamApp パッケージを作成します。この際に、手順 1.で作成したバイナリを data/cnn ディレクトリの下に置いてください。
Adam では、上記の手順 1.を行うためのツール(cvtool)を用意しています。cvtool の使用方法については、 別冊のドキュメント AdamApp_CVtool_UserManual ★を参照してください。
1.6.Appendix
Appendix A: 製品のセキュリティについて
製品セキュリティを確保するため以下の事に注意して開発してください。
・静的解析を実施してください。
・脆弱性の検証を行ってください。
・OSS 使用時には、最新の OSS を使用する、或いは、既知の脆弱性を確認してからご使用ください。
Appendix B: AdamApp で利用可能な CPU と RAM
AdamApp で利用可能な CPU 使用率及び RAM 使用量は、i-PRO カメラの機種によって異なります。
CPU 使用率が上限に達すると、カメラはそれ以上 AdamApp が CPU を使用しないように制限します。
メモリ使用量が上限に達すると、AdamApp は強制終了されます。
機種ごとの利用可能なリソース情報は下記 URL を参照下さい。