SDK同梱ドキュメント：AdamAppDevelopmentManualForIpro_Vx_xx.pdf

目次

...

...

はじめに

...

AdamApp は、定められた形式（AdamApp パッケージ形式）にパッケージングをして、インス トールする必要があります。このため、AdamAppSDK では、AdamApp のビルドと AdamApp パッケージ 作成を、容易に行える環境を提供します。

...

また、このチュートリアルでは、SDKのインストールディレクトリを${SDK_DIR}として記載します。

...

開発環境のディレクトリ構成

...

AdamAppSDK のディレクトリ構成は、以下のようになります。

${SDK_DIR}/ 追加アプリ作成トップディレクトリ

bin/ Adam 実行プログラムのディレクトリ

build_config/ make 用ルールファイルのディレクトリ

conf/ 設定情報用ディレクトリ

external/ AdamApp で利用する Open Source ライブラリファイルのディレクトリ

include/ AdamApp 用ヘッダファイルディレクトリ

lib/ AdamApp 用ライブラリファイルディレクトリ

src/ AdamApp のソースコードを格納するディレクトリ

tool/ ツール類のディレクトリ

www/ Adam の操作用 HTML ページを格納するディレクトリ(未使用)

sdk_version.txt AdamSDK のバージョンを書いたファイル

setup_env.sh make 環境設定用ファイル

 これ以降の節で、各ディレクトリ/ファイルの詳細な説明を行います。

include: AdamApp のヘッダーファイルのディレクトリ

include ディレクトリは、AdamApp（追加アプリ）を作成する際に必要なヘッダファイルを置いています。提供するヘッダファイルは以下の通りです。

AdamType.h Adam の型定義がされているヘッダファイルです。

AdamApi.h 追加アプリ用 API ヘッダです。

lib: AdamApp のライブラリのディレクトリ

lib ディレクトリは、AdamApp（追加アプリ）を作成する際に必要なライブラリファイルを置いています。提供するライブラリファイルは、以下の通りです。

libadam_common.so / libadam_common.a

Adam 共通ライブラリ: Adam 関連プロセスの共通ライブラリです。

libadam.so / libadam.a
追加アプリ用 API ライブラリ: 追加アプリ向けの API を提供するライブラリです。

なお、ライブラリファイルは、実行環境毎に異なるものを使う必要があります。このため、実行環境毎のディレクトリを作り、その下に、それぞれの実行環境用のライブラリファイルを用意しています。

${SDK_DIR}/lib/aarch64-linux-gnu/

i-pro ambaCV2X model 用ライブラリ

src: AdamApp のソースファイルのディレクトリ

src ディレクトリは、AdamApp（追加アプリ）のソースファイルを格納するディレクトリです。この srcディレクトリの直下に、AdamApp 毎のディレクトリをさらに作成して、そこにソースファイルを置くことを想定しています。
AdamApp のソースファイルの配置方法を理解しやすくするため、AdamApp のサンプルとして、srcディレクトリ直下に、skelton_sample_appディレクトリを配置しています。ユーザは、このskelton_sample_app ディレクトリをコピーして、そのコピーしたディレクトリ内でソースファイルを作成することで、ビルド環境の構築が容易になります。なお、skelton_sample_app ディレクトリ以下には、実際にビルド＆可能な簡単なサンプルアプリケーションを格納していますので、AdamApp の API の使用方法の参考にすることができます。srcディレクトリ、及び、skelton_sample_app ディレクトリは、以下の構成になっています。

${SDK_DIR}/src/adamapp/

adamapp_setting.mk Make 用共通設定ファイル

adam_make_package.mk Make用共通ルールファイル

${SDK_DIR}/src/adamapp/skeleton_sample_app/

bin/ AdamApp 実行プログラムを格納するディレクトリ

conf/ コンフィギュレーション情報を格納するディレクトリ

data/ AdamApp 用外部データファイルを格納するディレクトリ

external/ AdamApp で使う外部ソフトウェアを配置するディレクトリ

setup/ セットアップスクリプトファイルを格納するディレクトリ

Makefile メイクファイル

configuration.txt コンフィギュレーションファイル

skeletonSampleApp.cpp サンプルアプリソースプログラム

bin: Adam 実行プログラムのディレクトリ

作成した AdamApp（追加アプリ）を実行させるために必要となる、Adam の実行プログラムを置いています。提供している実行プログラムは、下記のものになります。

adamCore : Adam の主制御を行うプログラムです。
adam.cgi : Adam の CGI プログラムです。HTTP サーバから呼び出されます。
sdkCam : sdkCAM のプログラムです。

なお、実行プログラムは、実行環境毎に異なるものを使う必要があります。このため、実行環境毎のディレクトリを作り、その下に、それぞれの実行環境用の実行プログラムを用意しています。

${SDK_DIR}/bin/

i686-linux-gnu/ PC(32bit 版)実行用バイナリ

X86_64-linux-gnu/ PC(64bit 版)実行用バイナリ

build_config: ビルド用基本設定ファイルのディレクトリ

build_config ディレクトリは、AdamApp アプリのビルドの際に必要となる make 用ルールファイルを格納しています。通常は、このディレクトリ以下のファイルを編集する必要はありません。もし、ユーザ独自で make ルールを変更したい場合には、このディレクトリ以下のファイルを編集してください。

tool: ツールのディレクトリ

tool ディレクトリは、コンフィギュレーション情報生成ツールなどの Adam 用のツールや、Adam 起動用スクリプトファイルなど、Adam 関連ファイルの作成や実行を行うツール類を格納したディレクトリです。
提供するツールは、下記のものになります。

adamapp_configurator コンフィギュレーションファイルからコンフィギュレーション情報を生成するスクリプト
httpdctl.sh httpd 起動、終了スクリプト (busybox httpd を使います)
startAdam.sh Adam 起動スクリプト
stopAdam.sh Adam 終了スクリプト

external: AdamApp に使用されるオープン ソース ライブラリのディレクトリ

external ディレクトリは、AdamApp のビルドに必要な Open Source のライブラリファイルを置いています。このディレクトリに格納されている Open Source の種類については、adamappsdk/external/license を参照してください。
なお、ライブラリファイルは、実行環境毎に異なるものを使う必要があります。このため、ターゲット毎のディレクトリを作り、その下に、それぞれの実行環境用のライブラリファイルを用意しています。

${SDK_DIR}/external/license/
external ディレクトリに格納されている Open Source のライセンスを置き場です。

${SDK_DIR}/external/lib/aarch64-linux-gnu/
i-pro ambaCV2X model 用ライブラリ

sdk_version.txt: SDK のバージョン ファイル

iPRO_CAMERA_SDK のバージョン情報が記載されています。

setup_env.sh: 設定ファイル

ビルドに必要な環境設定ファイルです。

AdamApp のパッケージ形式

...

AdamApp パッケージ形式とは、カメラにインストールする際のパッケージ形式です。 具体的には、下記に示すディレクトリ構成で、かつ、これらを zip 化 ＋ 暗号化したものです。暗号化したものです。※C/C++を例に記載します。

bin/

AdamApp 実行プログラムを格納するディレクトリ

configconf/

コンフィギュレーション情報を格納するディレクトリ

data/data_CV2X/data_CV5X

AdamApp 用外部データファイルを格納するディレクトリ
※data_CV2X/data_CV5X はSDK1.80以降のみ

external/

AdamApp で使う外部ソフトウェアを配置するディレクトリ

setup/

セットアップスクリプトファイルを格納するディレクトリ

...

bin ディレクトリは、AdamApp の実行プログラムを格納するディレクトリです。実行プログラ ム名は、任意の名前で構いません。 なお、AdamAppSDKを用いて、AdamAppをビルド、パッケージ化した場合には、このディレ クトリに、実行プログラムが自動的に配置されます。その際、実行プログラム名は、Makefile の PROG_NAME マクロで指定した名前となります。

⚫ config conf ディレクトリ： コンフィギュレーション情報を格納するディレクトリ

config conf ディレクトリは、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/data_CV2X/data_CV5X ディレクトリ： AdamApp 用外部データファイルを格納するディレクトリ

data ディレクトリは、AdamApp 用外部データファイルを配置できる唯一のディレクトリで す。 AdamApp 用外部データファイルを、インストール時に同時にコピーしたい場合には、そのフ ァイルをこの下に配置します。インストール時に、コピーしたい AdamApp 用外部データファイ ルがない場合は、このディレクトリは空にしておきます。
data_CV2Xディレクトリは、ambaCV2X用のAdamApp 用外部データファイルを配置できるディレクトリで す。
data_CV5Xディレクトリは、ambaCV5X用のAdamApp 用外部データファイルを配置できるディレクトリで す。
ambaCV2XおよびambaCV5Xで共用する場合はdataディレクトリにAdamApp 用外部データファイルを格納すれば、共用されます。ambaCV2XおよびambaCV5XでAdamApp 用外部データファイルを区別する場合はdata_CV2Xディレクトリおよびdata_CV5Xディレクトリの下に配置します。

AIアクセラレータを使用する場合は、変換したバイナリデータをcnn ディレクトリの下に配置します。

⚫ external ディレクトリ： AdamApp で使う外部ソフトウェアを配置するディレクトリ

...

AdamApp をアンインストールする際に実行されるシェルスクリプトです。AdamApp がア ンインストールされる直前に実行されます。

...

Pythonの場合は下記の通りです。詳細な説明はC/C++と同様のため省略します。

bin/

AdamApp 実行プログラムを格納するディレクトリ

conf/

コンフィギュレーション情報を格納するディレクトリ

data/

AdamApp 用外部データファイルを格納するディレクトリ

python/

Python スクリプトファイルを格納するディレクトリ

setup/

セットアップスクリプトファイルを格納するディレクトリ

ターゲット依存マクロ

...

この節では、ターゲット依存マクロについて説明します。ターゲット依存マクロは、機種や OS などの違 いを示すもので、マクロ変数として定義され、ソースコード、ヘッダファイル、Makefileから利用すること ができます。開発者は、機種や OS などによって AdamApp の実装を変える必要がある場合、このマクロを 利用することで、作り分けることができます。

1.2.1 では、ソースコード、及び、ヘッダファイルに対するマクロの説明を行います。

1.2.2 では、Makefile に対するマクロの説明を行います。

1.2.1.ソースファイルとヘッダーファイルのマクロ

★記載準備中

1.2.2.Makefileのマクロ

★記載準備中

...

ソースファイルとヘッダーファイルのマクロ

ソースファイル、及び、ヘッダファイル用のターゲット依存マクロは、下記のマクロが定義されます。

Makefileのマクロ

Makefile 用のターゲット依存マクロは、下記のマクロが定義されます。

AdamApp パッケージの生成手順

...

この節では、AdamApp パッケージの具体的な作成手順について、AdamAppSDK のサンプルプログラム (SkeletonSampleApp)を用いて、説明します。 パッケージ作成手順は、大きく分けて、下記の 3 つのフェーズで構成されています。

...

それぞれの具体的な方法について、これ以降で説明していきます。

...

ソースファイルと 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) 外部ソフトウェアのライブラリとヘッダファイルの配置（必要であれば）

...

PROG_CXXFLAGS= $(ADAM_CXXFLAGS)

PROG_CXXFLAGS+= -fno-rtti

PROG_CXXFLAGS+=

PROG_CXXFLAGS は、C++のコンパイルオプションを指定する変数です。 AdamApp 独自の C++コンパイルオプションがある場合は、この変数に追記して下さ い。 なお、PROG_CXXFLAGS に設定済みの値[$(ADAM_CXXFLAGS)]は、消さないでく ださい。

...

ファイルの生成と配置

(1) AdamApp 用外部データファイルの作成と配置

...

AdamApp は、インストール時（直後）、アップデート時（直後）、アンインストール時（直前） に、指定されたスクリプトを実行する機能を持っています。それぞれの時に、実行したいスクリプトが あれば、skeletonに、指定されたスクリプトを実行する機能を持っています。それぞれの時に、実行したいスクリプトがあれば、skeleton_sample_app/setup ディレクトリに配置してください。もし、実行したいスクリプト がなければ、配置する必要はありません。ディレクトリに配置してください。もし、実行したいスクリプトがなければ、配置する必要はありません。

(3) コンフィギュレーションファイルの作成

1コンフィギュレーションファイルのフォーマットに示す記載方法に従って、コンフィギュレーションファイルを作成し、configuration.4 章★に示す記載方法に従って、コンフィギュレーションファイルを作成し、configuration.txt という ファイル名で、skeleton_sample_app/ディレクトリ直下に配置してください。

(4) 設定値ファイルの作成

AdamApp で、設定値管理機能を用いる場合は、「App Preference Function Guide」★に従って、設定 値管理ファイルを作成し、appPrefsで、設定値管理機能を用いる場合は、こちらに従って、設定値管理ファイルを作成し、appPrefs.json というファイル名で、skeleton_sample_app/ディレクトリ直 下に配置してください。

...

ディレクトリ直下に配置してください。

AdamApp のビルドとパッケージの生成

AdamApp に必要なファイルの作成と配置が完了したら、AdamApp のビルドとパッケージ作成を行いま
す。具体的には、(1)AdamApp の実行環境に対応する設定ファイルを読み込み、(2)make の実行、を実施し
ます。
詳しい手順について、これ以降で説明します。

(1) ビルド用環境設定ファイルの読み込み

ビルド用環境設定ファイルとして、setup_env.sh が用意されています。これを source コマンドを用い て読み込むことで、環境設定が完了します。その際、AdamApp を動作させる実行環境に応じて、引数 を指定する必要があります。

指定できる引数は下記の通りです。

i-pro ambaCV2X 用の AdamApp を作成する場合：

　ipro-ambaCV2X

下記に、それぞれの場合の詳細な手順を示します。

$ cd ${SDK_DIR}
$ source setup_env.sh ipro-ambaCV2X

(2) make の実行（AdamApp のビルド&パッケージの作成）

続いて、AdamApp（追加アプリ）のビルドとパッケージ作成を行うために、make を実行します。
make を実行すると、ビルドとパッケージの作成を一気に行います。make が成功した場合には、
skeleton_sample_app ディレクトリ直下に、

SkeletonSampleApp ：

SkeletonSampleApp の実行プログラム

SkeletonSampleApp.zip ：

SkeletonSampleApp のパッケージ

SkeletonSampleApp.ext ：

SkeletonSampleApp.zip を Base64 化したもの

の 3 つのファイルが生成されます。

$ 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 を用いてのインストールなど）

...

詳しい手順について、SDK v1.71以前を利用される場合はこちらを参照ください。
SDK v1.80以降を利用される場合はこちらを参照ください。

ambaCV2XおよびambaCV5Xの拡張アプリを1ファイルにまとめてビルドする

ambaCV2XおよびambaCV5Xのアプリを1ファイルにまとめる方法を説明します。1ファイルにまとめる必要が無い場合は実施しなくても問題ありません。
事前にambaCV2XおよびambaCV5Xのアプリをビルドしておきます。例としてPythonのsqlite_appをビルドした場合は、下記のファイルが生成されることになります。

SQLiteSampleAppPy_V0_1_ambaCV2X.ext
SQLiteSampleAppPy_V0_1_ambaCV2X.zip
SQLiteSampleAppPy_V0_1_ambaCV5X.ext
SQLiteSampleAppPy_V0_1_ambaCV5X.zip

このまま、下記の通り対象のディレクトリに移動しmake packを実行します。

cd ${SDK_DIR}/src/adamapp-py/sqlite_app/
make pack

成功すると、ambaCV2XおよびambaCV5Xのアプリが1ファイルにまとめられます。

SQLiteSampleAppPy_V0_1_ambaCV2X5X.ext
SQLiteSampleAppPy_V0_1_ambaCV2X5X.zip

上記ファイルはambaCV2XカメラおよびambaCV5Xカメラに利用可能です。

コンフィギュレーションファイルのフォーマット

...

コンフィギュレーションファイルとは、AdamApp の動作に必要な情報を記述したファイルです。Adam
実行環境は、このファイルの内容を参照して、AdamApp の制御（インストール/開始など）を行います。このため、このファイルの内容が誤っている場合は、AdamApp のインストールや開始に失敗することがありますので、正確に記述してください。
なお、このファイルは、AdamApp パッケージの作成時に参照されますので、AdamApp 作成のための
make 実行前までに作成しておく必要があります。1.4.1 では、コンフィギュレーションファイルの記述すべき項目についての説明を行います。

具体的な記述例については、任意のサンプルアプリのconfiguration.txt を参照してください。

${SDK_DIR}/src/adamapp/[任意のサンプルアプリ]/configuration.txt

...

configuration.txt の各用語

コンフィギュレーションファイルの各項目は、タグと値で構成されており、下記のフォーマットで記述し ます。

...

Table 1.4.1-1 コンフィギュレーションファイルに記載するタグの説明

*1: ROMSIZE
以下の合計：
実行可能なファイルと共有ライブラリ（Linux サイズコマンドで取得した”text”と”data”のフィールドの合計値）。
Data ディレクトリの容量
Conf ディレクトリの容量

*2: RAMSIZE, CPURATE, AIACCRATE,
初めにサンプルアプリケーションと同じ値を設定してください。最後に、i-PRO カメラ上でアプリケーションを実行した際の値を設定してください。これらのパラメータについては Section8★ を参照ください。
また、利用可能な ROM/RAM のリソースについては Section10★ Resource Monitorを参照ください。
*3: AIACCRATE,AIMEMSIZE

サンプルアプリケーションと同じ値を設定してください。

1.5.AIアクセラレーターの活用事例

i-pro ambaCV2X モデルのカメラには、AI の推論処理用アクセラレータ(CVFlow)を内蔵しています。
AdamApp からは、専用の API 経由でこのアクセラレータを使用することが可能です。API の入力として、アクセラレータ用のバイナリファイルが必要になります。以下の手順でバイナリの作成、およびAdamApp への組み込みを行ってください。

[手順]

1. 学習済みの AI モデルを、アクセラレータ用のバイナリファイルに変換します。

2. 1.3.AdamApp パッケージの生成手順の記載手順にしたがって、AdamApp パッケージを作成します。この際に、手順 1.で作成したバイナリを data/cnn ディレクトリの下に置いてください。

...

Adam では、上記の手順 1.を行うためのツール(cvtool)を用意しています。cvtool の使用方法については、 別冊のドキュメント AdamApp_CVtool_UserManual ★を参照してください。サンプルアプリケーションと同じ値を設定してください。内部処理で使用されることはありません。

Appendix

...

Appendix A: 製品のセキュリティについて

製品セキュリティを確保するため以下の事に注意して開発してください。
・静的解析を実施してください。
・脆弱性の検証を行ってください。
・OSS 使用時には、最新の OSS を使用する、或いは、既知の脆弱性を確認してからご使用ください。