Table of contents

Introduction

AdamApp must be packaged into a defined format and be installed. AdamAppSDK provides the environment to make building and packaging AdamApps with ease.

This chapter shows how to build and package an AdamApp using a sample AdamApp called SkeltonsampleApp.

Also, this tutorial refers to the SDK installation directory as ${SDK_DIR}.

Packaging format of AdamApp

AdamApp needs to be in a package format when it is installed into IP camera. Create a zip file and encrypt it with a directory structure indicated below. *C/C++ is described as an example.

bin/

Directory to store AdamApp execution program

conf/

Directory to store configuration files

data/

Directory to store external data files for AdamApp

external/

Directory to allocate external software files that will be used in AdamApp

setup/

Directory to store set-up scripts

AdamApp execution file, data files and configuration files will be stored in the directories above. Detail of each directory is introduced below.

⚫ bin directory: for AdamApp execution program

bin directory stores execution program of AdamApp. You can name the program as you like. If you built and package AdamApp using AdamAppSDK, the execution program will be automatically stored in this directory and will be named as specified by PROG_NAME macro in Makefile.

⚫ conf directory: for configuration files

This directory stores configuration information which is always a combination of Applicense.bin
file and profile.bin file. These 2 files are created out of a configuration file (placed by the name
of configuration.txt as a sample of AdamAppSDK) by using a tool called adamapp_configurator.
Please refer to here for how to write a configuration.txt.

Note that you will have to place the files in this directory once your built and packaged AdamApp by using AdamAppSDK to automatically generate applicense.bin as well as profile.bin out of configuration.txt.

⚫ data directory: for external data files of AdamApp

Data directory is the only place where you can store external data files for AdamApp. Files which were placed in this directory will be copied when AdamApp is installed. This directory should be empty if you do not have data files you need to copy.

⚫ external directory: for external software files used in AdamApp

Place library files (.a .so etc) and header files (.h .hpp .hxx etc) included in the external software under external directory.

⚫ setup directory: for set-up shell script

setup directory is to store shell scripts which will be executed when installing, updating, or uninstalling AdamApp. The format is based on Bourne Shell ( Bourne Shell compatible ash should be used).

Shell script will be executed after the environment variables listed below are passed on. Thus, you can review these environment variables within the shell script.

ADAM_INSTALLID

Install ID of AdamApp.

ADAM_APP_DATA_DIR

Directory path for AdamApp external data files.(= Data directory path)

ADAM_APP_TMP_DIR

Directory path for AdamApp temporary files.

The name of each shell script should be specified by the configuration file. Your preference of using or not using shell script can be set up for each script. Do not write a file name of the shell script for the configuration file if you are not using a shell script. (In this case, keep setup directory empty in order to save some file space)

➢ Install Script (optional)

This script is executed just after AdamApp is installed. Format is based on Bourne Shell ( Bourne Shell compatible ash should be used).

➢ Update Script (optional)

This script is executed after an AdamApp has been updated. Format is based on Bourne Shell ( Bourne Shell compatible ash should be used).

➢ Uninstall Script (optional)

This script is executed right before AdamApp is uninstalled. Format is based on Bourne Shell ( Bourne Shell compatible ash should be used).

For Python it is as follows. A detailed explanation is omitted because it is similar to C/C++.

bin/

Directory to store AdamApp execution program

conf/

Directory to store configuration files

data/

Directory to store external data files for AdamApp

python/

Directory to place Python scripts

setup/

Directory to store set-up scripts

Target Dependent Macro

This section explains target dependent macros, which represent differences of models, OSs, and so on. They are defined as macro variables and are available within source files, header files and Makefiles. You can use these macros to change implementation of AdamApp on a specific model or OS that you are using.

Macros for source file and header file

Target dependent macros for source file and header file are as follows:

Macros for Makefile

Target dependent macros for Makefile are as follows:

Procedure for generation of AdamApp package

The procedure to generate an AdamApp package using a sample application (SkeltonSampleApp) is discussed in this section. There are three phases to generate a package.

1.Generate source files and Makefile

Generate AdamApp source file.

2.Generate and place files

Generate files to build and run AdamApp and place them in the appropriate directories.

3.Build and generate package

Build (compile and link) AdamApp and generate a package.

Each specific method will be explained below.

Generate source file and Makefile

(1) Generate and place source files

Source files of the AdamApp must be placed in the following directory.
<AdamAppSDK installation directory>/src/adamapp

Thus, source codes of the sample program (SkeltonSampleApp) should be placed in the following
directory.
<AdamAppSDK installation directory>/src/adamapp/skeleton_sample_app

When you generate new AdamApp, also generate the following directory and place the source files,
header files and Makefile in there.
<AdamAppSDK installation directory>/src/adamapp/<directory name of the new AdamApp>
It’s recommended that you copy and modify skeleton_sample_app directory to generate new
application for ease.

(2) Place libraries files and header files of external software. (if you use an external software)

Place library files (.a .so etc) and header files (.h .hpp .hxx etc) included in external software used for AdamApp in the external directory.

(3) Edit Makefile

Edit Makefile after you create the source files and the header files. Input required information in
the Makefile template provided. Variables are listed in the template so that you can add the required values.
Typical variables from the template are shown below. Please refer to this part to edit your Makefile.

PROG_NAME= SkeletonSampleApp

PROG_NAME is a variable for setting generated program name.
Alpha-numeral, hyphen, underscore, period can be used for the name.
Length of the name is up to 32.

SRC_FILES= skeletonSampleApp.cpp

SRC_FILES is a variable for indicating build-target source file.
Developers need to describe all build-target source files.
By the way, developers can describe both of C source files (extension is .c) and C++ source files (extension is .cpp).

ADD_LIB_PATH=$(ADAM_ADD_LIB_PATH)

ADD_LIB_PATH+=

ADD_LIB_PATH is a variable for setting the path of library.
Developers have to describe the only path name.
If developers need to link any libraries in addition to Adam library, please describe value (the name of library).
By the way, DO NOT delete pre-set value $(ADAM_ADD_LIB_PATH).

ADD_LIBS=$(ADAM_ADD_LIBS)

ADD_LIBS+=

ADD_LIBS is a variable for setting the name of linked library.
If developers need to link any libraries in addition to libraries for Adam, please describe value.
By the way, DO NOT delete pre-set value $(ADAM_ADD_LIBS).

ADD_INCLUDE_PATH=$(ADAM_ADD_INCLUDE_PATH)

ADD_INCLUDE_PATH+=

ADD_INCLUDE_PATH is a variable for setting include path.
If developers need to any include files in addition to include file for Adam, please describe value.
By the way, DO NOT delete pre-set value $(ADAM_ADD_INCLUDE_PATH).

PROG_CPPFLAGS= $(ADAM_DFLAGS)

PROG_CPPFLAGS+=

PROG_CPP_FLAGS is a variable for setting preprocessor option.
If developers need the unique preprocessor option for AdamApp, please describe value.
By the way, DO NOT delete pre-set value $(ADAM_DFLAGS).

PROG_CFLAGS= $(ADAM_CFLAGS)

PROG_CFLAGS+=

PROG_CFLAGS is a variable for setting C compile option.
If developers need the unique C compile option for AdamApp, please describe value.
By the way, DO NOT delete pre-set value $(ADAM_CFLAGS).

PROG_CXXFLAGS= $(ADAM_CXXFLAGS)

PROG_CXXFLAGS+= -fno-rtti

PROG_CXXFLAGS+=

PROG_CXXFLAGS is a variable for setting C++ compiling option.
If developers need the unique C++ compiling option for AdamApp, please describe value.
By the way, DO NOT delete pre-set value $(ADAM_CXXFLAGS).

Generate and place files

(1) Generate and place external data files for AdamApp

Create and place the file under skeleton_sample_app/data directory if you need to read and write on the files (e.g., parameters of threshold). The files placed under the data directory will be included in the AdamApp package. You can access these files when AdamApp is executed.

(2) Generate and place script files

AdamApp has a function to execute specified script right after its installation and update or right
before its uninstallation. Place the script that you want to execute on each occasion under
skeleton_sample_app/setup. skeleton_sample_app/setup directory can be empty if you do not have a
specific script that you want to execute.

(3) Generate configuration file

Follow the procedure indicated in the here to create a configuration file. Place the file under skeleton_sample_app/ directory by the name of configuration.text.

(4) Generate preferences file

Please refer to “App Preference Function Guide”★link(in preparation)★ to create setting value control file when using setting
value control function. Place the file under skeleton_sample_app/ directory by the name of
appPref.json.

Building AdamApp & generate package

Build and create a package of AdamApp after creating and placing the required files for AdamApp.
(1) Read configuration file for the AdamApp execution environment and (2) Execute make

(1) Read configuration file for the building environment settings

setup_env.sh is provided as a setup file for the building environment. You can set up building
environment by reading setup_env.sh using ‘source’ command with parameter depending on execution
environment of AdamApp.
Addressable parameters are as follows:

When creating an AdamApp that runs on i-pro ambaCV2X model:

　ipro-ambaCV2X

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

(2) Execute make (build and generate package of AdamApp)

You will need to execute make to build and generate an AdamApp package. AdamApp package will be build and generated automatically. When it is successful, the following three files are generated within skelton_sample_app directory.

SkeletonSampleApp ：

The execution program of SkeletonSampleApp

SkeletonSampleApp.zip ：

The package of SkeletonSampleApp

SkeletonSampleApp.ext ：

Encoded file by BASE64

$ cd src/adamapp/skeleton_sample_app
$ ls –CF
Makefile configuration.txt skeletonSampleApp.cpp
bin/ data/ setup/
$ make
(Omitted)
$ ls –CF
Makefile bin/ setup/
SkeletonSampleApp* configuration.txt skeletonSampleApp.cpp
SkeletonSampleApp.ext conf/ skeltonSampleApp.d
SkeletonSampleApp.zip data/ skeltonSampleApp.o

The descriptions of the three files mentioned above are as follows.

SkeletonSampleApp ：

This is the execution program with the information for debug. The information required for debugging will be derived from this file when AdamApp is debugged using gdbserver (or other), On the other hand, bin/SkeltonSampleApp are the execution programs without information for debug.

SkeletonSampleApp.zip ：

This is a package file including bin, data, config and setup directories and is encoded by zip. This file is used for installation of AdamApp to camera. Please send this file to i-PRO Co., Ltd. when encrypting.

SkeletonSampleApp.ext ：

This file is an encoded file of SkeltonSampleApp.zip by BASE64. Use this file if you need to specify Base64 instead of zip file when installing AdamApp to the camera. (e.g., installation using UI of commercial surveillance camera).

Format of configuration file

Configuration file contains essential information to run AdamApp. AdamApp is controlled within Adam execution environment in line with the contents of this file (e.g., at the time of installation or starting). Therefore, installation or starting of AdamApp may fail if the content in this file is incorrect. In addition, this file is also used when AdamApp is packaged, which means that you need to create this file before the execution of make to create AdamApp.

See the configuration.txt of any sample app for specific examples.

${SDK_DIR}/src/adamapp/[any sample app]/configuration.txt

Each term in configuration.txt

Each item has a tag and a value as shown below.

# head of line ‘#’ means comment out

TagName Value

Add a space between TagName and Value for one or more characters, or a tab.
‘#’ placed at the beginning of a sentence means ‘comment out’ whereas, a ‘#’ in the middle of sentence
means otherwise.
Details of each tag is shown in Table 1.4.1-1. Please refer to this table to determine what character can be
used for Value for each tag. Examples are shown below.

# set of the name of execution file of AdamApp

APPLICATION SkeletonSampleApp

# set of version of AdamApp

APPVERSION V0.01

More than one item can be selected. Example is as follows.

# set of the official name of AdamApp

APPNAME0 Sample Application

APPNAME1 サンプルアプリケーション

APPNAME5 esempio di applicazione

Following tag names can be used in the configuration file. The optionality field where ‘M (Mandatory)’ is indicated must be filled. The field can be left blank if it is not indicated as mandatory.

Table 1.4.1-1 Tags written in the configuration file

*1: ROMSIZE
Sum of followings.
Size of executable file and shared libraries (sum of “text” and “data” field value obtained with the
Linux size command.)
Size of data directory.
Size of conf directory.

*2: RAMSIZE, CPURATE, AIACCRATE,
At first, set the same value as the sample application.
At last, set the value when running the application on the i-PRO camera.
How to see these parameters described in here.
Available ROM/RAM resources described in here.

*3: AIMEMSIZE

Set the same value as the sample application.

Case of using AI accelerator

Accelerator (CVFlow) for AI inference process is embedded in i-pro ambaCV2X model IP camera. AdamApp can use the accelerator through a dedicated Adam API. A binary file for accelerator is needed as an input for API. Create a binary file and built it into AdamApp by the following sequence.

1. Convert a pre-trained AI model into a binary file for accelerator.

2. Create AdamApp package in accord to here in this document. Place the binary file generated in step 1 under data/cnn directory.

A tool (cvtool) to be used to process the step1 above is provided by Adam. Please see here for how to use cvtool.

Appendix

Appendix A: Regarding product security

Please be aware of the following matters to ensure product security throughout the course of your development.

- Perform static analysis

- Verify vulnerability of the app.

- When using OSS, use the latest OSS or check for known vulnerabilities before using.

Appendix B: CPU and RAM available in AdamApp

The CPU usage and RAM usage available in AdamApp varies depending on i-PRO camera model. The camera will restrain AdamApp not to use CPU when CPU usage limit has been reached. AdamApp will be forced to terminate as the memory usage reaches the limit. Please access the URL for usage information for each model.

https://dev-partner.i-pro.com/space/TPFAQ/694780048

Appendix C: About development in Python

Python environment of i-PRO camera

The Python environment pre-installed to the i-PRO camera is shown below.

Interpreter : Python 3.7.9

External library : python adam module for ADAM API

Structure of the Python version AdamApp

The Python version AdamApp runs 2 threads, Main thread and Python thread as shown below.

Python scripts are usually executed on Python thread. On the other hand, callback functions such as stopCallback, httpCallback and appPrefCallback are executed on Main thread.

Main thread is created as soon as the Python version AdamApp commences. Then Python thread is created after Main thread completes initializing AdamApp. Python thread then launches Python interpreter, loads pymain.py, and executes Python scripts. Python thread will be automatically terminated once the Python script ends. This is followed by the termination of the Main thread and then AdamApp.