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}.

Directory structure of development environment

Directory structure of AdamAppSDK is as follows.

${SDK_DIR}/ Top directory

bin/ Directory for Adam execution program

build_config/ Directory for rule files for make

conf/ Directory for configuration information

external/ Directory for open source library files for AdamApp

include/ Directory for header files for AdamApp

lib/ Directory for library files for AdamApp

src/ Directory for source files for AdamApp

tool/ Directory for tools

www/ Directory for HTML files for operation of Adam (Not used)

sdk_version.txt Text file described version of AdamSDK

setup_env.sh Script file for configuration of make

Details of each directory/file are discussed in the next section.

include: Directory of header files of AdamApp

The following header files which are required for generation of AdamApp are placed in include directory.

AdamType.h Types of Adam are defined

AdamApi.h API for AdamApp is defined

lib: Directory of libraries for AdamApp

The following library files which are required for generation of AdamApp are placed in lib directory.

libadam_common.so / libadam_common.a

Adam common library: common library for Adam processes

libadam.so / libadam.a
AdamApp API library: described API for AdamApp

Note that separate library file must be used in accordance with the execution environment. Directories for each execution environment and library files for them are provided.

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

Library for i-pro ambaCV2X model.

src: Directory of source files of AdamApp

Source files of AdamApp are placed in src directory. You could generate sub-directories and place source
files in them.skelton_sample_app directory is located in src directory as a sample for you to understand
how to place source files with ease. It is easier if you copy this sample directory and create a source file
within the copied directory to create a building environment.
In addition, sample applications are stored under skelton_sample_app directory which can be used for
actual building of an environment with ease. Use this samples as references for how to use AdamApp
API. Directory structure of src and skeleton_sample_app is as follows.

${SDK_DIR}/src/adamapp/

adamapp_setting.mk common configuration file for make

adam_make_package.mk common rule file for make

${SDK_DIR}/src/adamapp/skeleton_sample_app/

bin/ for execution program of AdamApp

conf/ for configuration information

data/ for data files of AdamApp

external/ for external software files using in AdamApp

setup/ for setup script files

Makefile Makefile

configuration.txt configuration file

skeletonSampleApp.cpp sample source file

bin: Directory of Adam execution program

Bin files which are required for execution of AdamApp are placed in bin directory. Execution programs provided are listed below.

adamCore : Adam Core program
adam.cgi : Adam CGI program, which is called by HTTP server
sdkCam : sdkCAM program

Note that separate library file must be used in accordance with the execution environment. Directories for each execution environment and library files for them are provided.

${SDK_DIR}/bin/

i686-linux-gnu/ Binary for execution on PC (32 bit version)

X86_64-linux-gnu/ Binary for execution on PC (64 bit version)

build_config: Directory of basic setting file for build

Make rule file which is required for AdamApp building is placed in build_config directory. You normally
don’t need to edit the files in this directory unless you want to change the existing make rule.

tool: Directory for tools

The tools for creating or executing Adam related files, such as a tool to generate Adam configuration data or a script file to launch Adam, are placed in tool directory.

adamapp_configurator A script that generates configuration data out of the configuration file.
httpdctl.sh A script to start and stop httpd
startAdam.sh Start Adam script
stopAdam.sh Stop Adam script

external: Directory of Open Source library used for AdamApp

Open Source library files which are required AdamApp building are placed in external directory. Please
refer to adamappsdk/external/license for the available Open Source.
Note that separate library file must be used in accordance with the execution environment. Directories
for each execution environment and library files for them are provided.

${SDK_DIR}/external/license/
Location of Open Source license files in external directory

${SDK_DIR}/external/lib/aarch64-linux-gnu/
Library for i-pro ambaCV2X model.

sdk_version.txt: version file of SDK

Version information of iPRO_CAMERA_SDK in sdk_version.txt.

setup_env.sh: setting file

setup_env.sh is provided as an environment setup file for building.

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/data_CV2X/data_CV5X

Directory to store external data files for AdamApp
*data_CV2X/data_CV5X only for SDK1.80 or later

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/data_CV2X/data_CV5X 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.
The data_CV2X directory is a directory where you can place external data files for AdamApp for ambaCV2X. The data_CV5X directory is a directory where you can place external data files for AdamApp for ambaCV5X. If you want to share it between ambaCV2X and ambaCV5X, store the external data file for AdamApp in the data directory and it will be shared. If you want to differentiate external data files for AdamApp between ambaCV2X and ambaCV5X, place them under the data_CV2X and data_CV5X directories.

⚫ 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 here 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
For detailed instructions, please see here if you are using SDK v1.71 or earlier.
If you are using SDK v1.80 or later, please refer here.

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.