ACAP Developer Guide - Version 3.1.0 - 3.5

AXIS Camera Application Platform (ACAP) is Axis own open application platform. It provides a development platform for software-based solutions and systems built around Axis devices. It’s available on various types of Axis products, and not only on our cameras.

ACAP makes it possible to develop applications for a wide range of applications:

• Security applications that improve surveillance systems and facilitate investigation.

• Business intelligence applications that improve business efficiency.

• Product feature plug-ins that add value beyond the Axis product's core functionality.

AXIS Camera Application Platform SDK (ACAP SDK) provides:

• Full access to most common product features, including video, audio, the event system, I/O ports, PTZ control, and more.

• Enables hardware acceleration on specific functions such as image analysis computations, overlay graphics and more.

• Support for multiple architectures to build applications for all ACAP-enabled Axis products.

• Example applications for all APIs to kickstart your development.

The ACAP SDK consists of:

ACAP SDK –

This Docker container image contains all tools for building and packaging an ACAP 3 application as well as API components (header and library files) needed for accessing different parts of the camera firmware. The toolchain and API images are also available as separate images, described below. This guide assumes that you are working with the combined image.

ACAP Toolchain –

This Docker container image contains the tools, compilers and scripts required to build applications.

ACAP API –

This Docker container image contains header files, libraries and other API components that you need when building an ACAP application.

From version 3.1, the SDK format relies on the Docker toolchain, something we see many developers use to manage their software. An important advantage of using Docker is that the SDK can be decoupled from the underlying host operating system. This enables us to support development across all Docker capable platforms, including not only Linux, but also Windows 10 and MacOS X. Docker also offers a rich set of tools to build and ship software.

If you're new to Docker and its many features, check out their Getting Started guide.

Follow the instructions in Get started to start developing your ACAP using Docker and our containerized SDK.

Compatibility means that if an ACAP can be installed and run on a specific device, then the ACAP is compatible with the device. Compatibility depends on both hardware and software (firmware).

ACAP is supported on a large portion of all Axis devices. For an ACAP to be hardware compatible with a specific device, the ACAP must be compiled using the SDK corresponding to the chip architecture in the device.

ACAP version 3 SDK is available for two different architectures, armv7hf (32 bit) and aarch64 (64 bit).

An ACAP is software compatible with an AXIS OS firmware if the APIs and other ACAP runtime features are available in the specific firmware release. The available APIs in a firmware depends on both the firmware version and the device itself since some APIs are only relevant for certain devices. For example, the Video capture API is only available on devices with an image sensor.

Find the right SDK for the hardware architecture of the specific device or devices that you want to develop for.

See detailed instruction in Find out which SDK to use.

Choose the appropriate SDK version based on what firmware version you want supporting your ACAP.

The ACAP is forward compatible for the firmware related to a specific SDK version. This means that the ACAP is compatible for the listed firmware version and future firmware versions until the next firmware LTS (Long Term Support). After an LTS, there may be breaking changes that breaks compatibility, for example when a deprecated API is removed. Breaking changes are always announced in advance.

An ACAP built with an SDK that is based on an older firmware version should always work on a newer firmware version within the same LTS window.

To get new features, always use the latest ACAP SDK release. A new feature could be, for example, a new version of an API.

New SDK versions between LTS releases always add functionality in a way that an ACAP, built using a previous version, will still compile with the new version of the SDK.

Read more about AXIS OS release tracks and related information here.

If you want an ACAP to be compatible with older firmware, you need to choose an SDK for an older firmware.

To get started using ACAP:

1. Set up your developer environment. See ACAP development requirements.

2. Find out which SDK to use.

3. Set up and verify the SDK.

To develop ACAPs, you need the following:

• A computer with Linux, Windows, or MacOS.

• Docker. Get Docker.

• • For Windows and MacOS, use the automatically upgradable Docker desktop stable.

  • For Linux, use Docker community edition version 18.09 or later.

• GIT scm. GIT downloads.

• We also recommend using Microsoft Visual Studio Code. But you are free to choose your favorite editor.

Different products have different architectures depending on the chip used in the product. Consequently different SDKs are required to ensure that the ACAP is compatible with the product. Currently, there are two different SDKs - one for products with armv7hf architecture, and one for products with aarch64 architecture.

Choosing which SDK to use depends on the starting point of your development:

I already have a specific product that I want to develop an ACAP for –

Which SDK to use depends on the architecture of the specific product. To find out which architecture your product has, see Check device properties.

I want to develop an ACAP for a specific product that I don't have access to yet –

Find out which chip a specific product has in Product interface guide (requires login to Developer Community).

I don't have a specific product, or I'm not sure which architecture to use. –

If you’re not sure, use armv7hf, which supports most products.

To prepare a device for development:

• Find the device on the network to configure IP address and user credentials.

• Setup the device on the network to make sure it’s ready to be connected to the network.

• Check device compatibility to make sure that you use a device that supports ACAP.

• Check device properties and update to the latest firmware if needed, see How to upgrade.

• Check device properties and identify the device architecture to be able to choose the correct toolchain.

To find Axis devices on the network and assign them IP addresses in Windows®, use AXIS IP Utility or AXIS Device Manager. Both applications are free and can be downloaded from axis.com/support.

For more information about how to find and assign IP addresses, go to How to assign an IP address and access your device.

1. Open a browser and enter the IP address or host name of the Axis device.

   If you do not know the IP address, use AXIS IP Utility or AXIS Device Manager to find the device on the network.

2. Enter the username and password. If you access the device for the first time, you must set the root password. See Set a new password for the root account.

3. The live view page opens in your browser.

You can enable SSH on an Axis device either through the device’s web interface or by calling a VAPIX API from command-line.

In the old web interface

1. Depending on you AXIS OS version, go to

2. • 10.5 and earlier: http://192.168.0.90/#settings/system/tools/plainconfig

   • 10.6 and later: http://192.168.0.90/aca/index.html#settings/system/tools/plainconfig

3. Click Network.

4. Under SSH, select Enabled.

5. Scroll to the bottom of the page and click Save.

In the new web interface

1. Go to http://192.168.0.90/camera/index.html#/system/plainConfig.

2. Select the Network group from the drop-down menu.

3. Under Network/SSH, select Enabled.

4. Scroll to the bottom of the page and click Save.

Using command-line

In this example we’re using curl, and more options may be required depending on your network setup:

curl -u '<username>:<password>' "http://192.168.0.90/axis-cgi/admin/param.cgi?action=update&Network.SSH.Enabled=yes"

To make sure the device is ready to be used and connected to the network:

• Verify that no one has tampered with the firmware.

• Set a new password for the root account. See also Secure passwords.

1. To make sure that the device has its original Axis firmware, or to take full control of the device after a security attack:

2. Reset to factory default settings. See the product’s user manual for information on how to reset to factory default settings.

   After the reset, secure boot guarantees the state of the device.

3. Configure and install the device.

The device password is the primary protection for your data and services. Axis devices do not impose a password policy as they may be used in various types of installations.

To protect your data we strongly recommend that you:

• Use a password with at least 8 characters, preferably created by a password generator.

• Don’t expose the password.

• Change the password at a recurring interval, at least once a year.

1. Type a password. Follow the instructions about secure passwords. See Secure passwords.

2. Retype the password to confirm the spelling.

3. Click Create login. The password has now been configured.

To check if device supports ACAP, use VAPIX CGI http://192.168.0.90/axis-cgi/param.cgi and check if the device supports EmbeddedDevelopment with a VAPIX GET/POST request and action list.

To extract the value of the parameter, use the CGI as device URL in a browser window:

http://192.168.0.90/axis-cgi/param.cgi?action=list&group=Properties.EmbeddedDevelopment.EmbeddedDevelopment

The following response shows a device that supports ACAP:

root.Properties.EmbeddedDevelopment.EmbeddedDevelopment=yes

To get basic device information, such as firmware version and architecture, use VAPIX POST request and method getAllProperties:

http://192.168.0.90/axis-cgi/basicdeviceinfo.cgi

To extract the messages, use the CGI from a terminal, using the credentials set in the network configuration:

curl --anyauth "*" -u [username]:[password] 192.168.0.90/axis-cgi/basicdeviceinfo.cgi --data "{\"apiVersion\":\"1.0\",\"context\":\"Client defined request ID\",\"method\":\"getAllProperties\"}"

The following response contains architecture "Architecture": "armv7hf", and firmware version "Version": "9.50.1":

{
	"apiVersion": "1.0",
	"context": "Client defined request ID",
	"data": {
	"propertyList": {
		"Architecture": "armv7hf",
		"Brand": "AXIS",
		"BuildDate": "Nov 07 2019 11:16",
		"HardwareID": "764",
		"ProdFullName": "AXIS P1448-LE Network Camera",
		"ProdNbr": "P1448-LE",
		"ProdShortName": "AXIS P1448-LE",
		"ProdType": "Network Camera",
		"SerialNumber": "ACCC8ED0C9EC",
		"Soc": "Axis Artpec-6",
		"SocSerialNumber": "00000000-00000000-442C2402-87C00153",
		"Version": "9.50.1",
		"WebURL": "http://www.axis.com"
		}
	}
}

Axis offers product AXIS OS management according to the active track or the long-term support (LTS) tracks. Regardless of the track chosen, it’s recommended to upgrade regularly in order to get the latest security updates. Upgraded can be done by using AXIS Device Manager, AXIS Camera Station, AXIS Companion or HTTP.

1. Go to the Device Manager Tab in Axis Device Manager or Configuration Tab > Devices - Management in AXIS Camera Station.

2. Select all devices that should be upgraded.

3. Right click and select Upgrade Firmware, which will open a dialog with a list of device models and the current firmware version installed in each device.

4. In the Upgrade Firmware dialog there are two options:

5. • Check for Updates which requires internet access.

   • Browse to locate the file e.g. on hard drive or memory stick.

6. Check for updates:

7. • Select Check for Updates to download a list of all versions available for all device models.

8. Browse:

9. • Select browse to locate the files and import them. It is possible to select and import several files at the same time.

10. Each device model will show a dropdown containing all available versions for a model, sorted by “Long Term Support” (LTS) and “Active” software tracks.

11. Select the version to install for each device model.

12. Click OK to start upgrading the devices.

For more information, see the help in AXIS Device Manager/AXIS Camera Station.

Upgrade instructions when using the old web interface

1. Download the upgrade file to a directory that is accessible from your local computer.

2. Open the product's start page (e.g. http://192.168.0.90) in a web browser.

3. Click the Setup link and log in as "root" (or any other user with administrator privileges). You must be logged in as an administrator to upgrade the unit.

4. Click System Options in the menu to the left.

5. Click Maintenance.

6. Click the Browse button in the Upgrade Server section.

7. Select the upgrade file you downloaded (and maybe decompressed) from our site. This file is typically named after the product and AXIS OS version.

8. Click the Open button.

9. Click the Upgrade button in the Upgrade Server section.

10. Wait for the flash load to complete, which may take 1-10 minutes. The upgrade procedure occurs in four steps:

11. • Step 1: Shut down. Running applications are shut down and active connections are terminated.

    • Step 2: Uploading. The old version will be erased and the new will be saved. During this step, the power LED will blink green/amber. After a while the progress of the upgrade will be displayed in the web browser.

    • Step 3: Reboot. The system restarts automatically.

    • Step 4: Reconfiguration. The new versions settings are configured to match the previous settings. The color of the status LED will be amber during this step.

12. After the upgrade has completed, the unit will automatically initiate the system, during which the status LED blinks amber. When initiation is complete and the system is ready for use, the status LED will be green.

Upgrade instructions when using the new web interface

1. Download the upgrade file to a directory that is accessible from your local computer.

2. Open the product's start page (e.g. http://192.168.0.90) in a web browser.

3. Log in as "root" (or any other user with administrator privileges).

4. Click Settings to the right.

5. Click System-tab.

6. Click Maintenance.

7. Select the upgrade file you downloaded (and maybe decompressed) from our site. This file is typically named after the product and AXIS OS version.

8. Click the Open button.

9. Click the Upgrade button in the Upgrade Server section.

10. Wait for the flash load to complete, which may take 1-10 minutes. The upgrade procedure occurs in four steps:

11. • Step 1: Shut down. Running applications are shut down and active connections are terminated.

    • Step 2: Uploading. The old version will be erased and the new will be saved. During this step, the power LED will blink green/amber. After a while the progress of the upgrade will be displayed in the web browser.

    • Step 3: Reboot. The system restarts automatically.

    • Step 4: Reconfiguration. The new versions settings are configured to match the previous settings. The color of the status LED will be amber during this step.

12. After the upgrade has completed, the unit will automatically initiate the system, during which the status LED blinks amber. When initiation is complete and the system is ready for use, the status LED will be green.

1. You must be at the command prompt and in the directory that contains the upgrade file.

   Example: C:\Axis\Product\Firmware

2. From the command prompt, open an FTP connection to the unit you wish to upgrade.
   (Do not use a Windows based FTP program to do this, use command line FTP programs only.)

3. Log in as “root”. You must be logged in as the root user to upgrade the unit.

4. Change to binary transfer mode by typing "bin" and press enter.

5. Type "hash" and press enter. This will allow you to see how the upgrade progresses.

6. Type the command "put XXX.bin flash" where XXX.bin is the name of the upgrade file you downloaded (and maybe decompressed) from our site. This file is typically named after the product and AXIS OS version.

7. Wait for the flash load to complete, which may take 1-10 minutes. The upgrade procedure occurs in four steps:

8. • Step 1: Shut down. Running applications are shut down and active connections are terminated.

   • Step 2: Uploading. The old version will be erased and the new will be saved. During this step, the power LED will blink green/amber. After a while, the progress of the upgrade will be displayed in the command prompt.

   • Step 3: Reboot. The FTP session terminates and the system starts automatically.

   • Step 4: Reconfiguration. The new versions settings are configured to match the previous settings. The color of the status LED will be amber during this step.

9. After the upgrade has completed, the unit will automatically initiate the system, during which the status LED blinks amber. When initiation is complete and the system is ready for use, the color of the status LED will be green.

The ACAP SDK image, available on Docker Hub, is based on Ubuntu and contains the environment needed for building an AXIS Camera Application Platform (ACAP) application. It includes all tools for building and packaging an ACAP 3 application as well as API components (header and library files) needed for accessing different parts of the camera firmware.

The SDK image can be used as a basis for custom built images to run your application, or as a developer environment inside the container.

To set up and verify the SDK, build, install and run a Hello World application example below.

1. Create a Hello World application

2. Build the Hello World application

3. Install and run the Hello World application

If you want to Build and install the Hello World application inside container, see Build and install the Hello World application inside container.

After completing the Hello World application example, you are set to start with more complex examples, see Code examples and tutorials for more information.

Check out the sections Application project structure and Build, install, and run the application for further details about building, running and installing applications.

Create the following folder and file structure in a working directory:

hello-world
├── app
│   ├── hello_world.c
│   ├── LICENSE
│   ├── Makefile
│   └── manifest.json
├── Dockerfile
└── README.md

The files comprising the following:

hello_world.c

Hello World application which writes to system-log.

#include <syslog.h>
int main(int argc, char **argv)

{
  /* Open the syslog to report messages for "hello_world" */
  openlog("hello_world", LOG_PID | LOG_CONS, LOG_USER);

  /* Choose between { LOG_INFO, LOG_CRIT, LOG_WARN, LOG_ERR }*/
  syslog(LOG_INFO, "Hello World!");

  /* Close application logging to syslog */
  closelog();

  return 0;
}

LICENSE

Text file that lists all open source licensed source code distributed with the application.

Makefile

Makefile containing the build and link instructions for building the ACAP application.

PROG1	= hello_world
OBJS1	= $(PROG1).c

PROGS	= $(PROG1)

CFLAGS-y  = -W -Wformat=2 -Wpointer-arith -Wbad-function-cast -Wstrict-prototypes -Wmissing-prototypes -Winline -Wdisabled-optimization -Wfloat-equal -Wall -Werror

all:	$(PROGS)

$(PROG1): $(OBJS1)
	$(CC) $^ $(CFLAGS) $(LIBS) -o $@
	$(STRIP) $@

clean:
	rm -f $(PROGS) *.o core *.eap

manifest.json

Defines the application and its configuration.

{
    "schemaVersion": "1.1",
    "acapPackageConf": {
        "setup": {
            "appName": "hello_world",
            "vendor": "Axis Communications",
            "embeddedSdkVersion": "3.0",
            "user": {
                "username": "sdk",
                "group": "sdk"
            },
            "runMode": "never",
            "version": "1.0.0"
        }
    }
}

Dockerfile

Docker file with the specified Axis toolchain and API container to build the example specified.

ARG ARCH=armv7hf
ARG VERSION=3.3
ARG UBUNTU_VERSION=20.04
ARG REPO=axisecp
ARG SDK=acap-sdk

FROM ${REPO}/${SDK}:${VERSION}-${ARCH}-ubuntu${UBUNTU_VERSION}


# Building the ACAP application
COPY ./app /opt/app/
WORKDIR /opt/app
RUN . /opt/axis/acapsdk/environment-setup* && acap-build ./

Standing in your working directory run the following commands:

docker build --tag <APP_IMAGE> .

<APP_IMAGE> is the name to tag the image with, e.g., hello_world:1.0

Default architecture is armv7hf. To build for aarch64 it's possible to update the ARCH variable in the Dockerfile or to set it in the docker build command via build argument:

docker build --build-arg ARCH=aarch64 --tag <APP_IMAGE> .

Copy the result from the build to a local directory build.

docker cp $(docker create <APP_IMAGE>):/opt/app ./build

The working directory now contains a build folder with the following files:

hello-world
├── app
│   ├── hello_world.c
│   ├── LICENSE
│   ├── Makefile
│   └── manifest.json
├── build
│   ├── hello_world*
│   ├── hello_world_1_0_0_armv7hf.eap
│   ├── hello_world_1_0_0_LICENSE.txt
│   ├── hello_world.c
│   ├── LICENSE
│   ├── Makefile
│   ├── manifest.json
│   ├── package.conf
│   ├── package.conf.orig
│   └── param.conf
├── Dockerfile
└── README.md

build/hello_world* –

Application executable binary file.

build/hello_world_1_0_0_armv7hf.eap –

Application package .eap file

build/hello_world_1_0_0_LICENSE.txt –

Copy of LICENSE file.

build/manifest.json –

Defines the application and its configuration.

build/package.conf –

Defines the application and its configuration.

build/package.conf.orig –

Defines the application and its configuration, original file.

build/param.conf –

File containing application parameters.

To install your application on an Axis video product:

1. Browse to the following page (replace <axis_device_ip> with the IP number of your Axis video product).

   http://<axis_device_ip>/#settings/apps

2. Click Add, the + icon, and browse to the newly built hello_world_1_0_0_armv7hf.eap.

3. Click Install.

hello_world is now available as an application on the device.

To run the application:

1. Browse to the following page (replace <axis_device_ip> with the IP number of your Axis video product).

   http://<axis_device_ip>/#settings/apps

2. Click the application icon.

3. Start the application.

You can find the application log at:

http://<axis_device_ip>/axis-cgi/admin/systemlog.cgi?appname=hello_world

or by clicking the App log link in the device GUI.

You can also extract the logs using the following commands in the terminal:

tail -f /var/log/info.log | grep hello_world

----- Contents of SYSTEM_LOG for 'hello_world' -----

14:13:07.412 [ INFO ] hello_world[6425]: Hello World!

Standing in your working directory, run the following command to bind mount the application directory in to the acap-sdk container:

docker run --rm -v $PWD/app:/opt/app -it hello_world:1.0

Or if you want to use the original image:

docker run --rm -v $PWD/app:/opt/app -it axisecp/acap-sdk:3.3-armv7hf-ubuntu20.04

Now inside the container, to build the application, run:

acap-build ./

The app directory now contains the following files:

├── Dockerfile
└── app
    ├── LICENSE
    ├── Makefile
    ├── hello_world*
    ├── hello_world.c
    ├── hello_world.o
    ├── hello_world_1_0_0_LICENSE.txt
    ├── hello_world_1_0_0_armv7hf.eap
    ├── manifest.json
    ├── package.conf
    ├── package.conf.orig
    └── param.conf

To install the application to a camera use command:

eap-install.sh --help

An application project contains several files and directories for an application. The mandatory files are:

Other optional files and directories to include:

manifest.json defines the application and its configuration.

An eap package based on manifest.json is similar to one based on a package.conf. The features previously configured using the package.conf and special configuration files are now included in manifest.json.

Use manifest.json for ACAP SDK version 3.3 and later.

For more information see:

• Create a manifest file from scratch

• Create a manifest file from existing package.conf

• Manifest file content

• Manifest file schema

• Discontinued support when using manifest file

Create a manifest.json file based on the manifest.json schema, see Manifest file schema.

To create the manifest file for a simple Hello Glib ACAP application:

1. Create a minimal manifest.json file with basic metadata:

• Friendly name

• Identifier and binary

• Vendor name

• Version

Example

"friendlyName": "Hello Glib",
"appName": "hello_glib",
"vendor": "Axis Communications",
"version": "2.0.0"

2. Define how you want the applications to be executed:

• Running mode - the application keeps running at a reboot.

• User and group for execution and file ownership, typically the sdk:sdk.

• If needed, you could also define special start options for the execution of the binary.

Example

"runMode": "never",
"user": {
	"group": "sdk",
	"username": "sdk"
}

3. Add the required embedded development version on the target device.

Example

"embeddedSdkVersion": "2.0"

4. Add any supported cgi endpoints.

Example

"configuration": {
	"httpConfig": [
		{
			"access": "viewer",
			"name": "example.cgi",
			"type": "transferCgi"
		}
	]
}

{
	"schemaVersion": "1.0",
	"acapPackageConf": {
		"setup": {
			"friendlyName": "Hello Glib",
			"appName": "hello_glib",
			"vendor": "Axis Communications",
			"version": "2.0.0",
			"embeddedSdkVersion": "2.0",
			"runMode": "never",
			"user": {
				"group": "sdk",
				"username": "sdk"
			},
		},
		"configuration": {
			"httpConfig": [
				{
					"access": "viewer",
					"name": "example.cgi",
					"type": "transferCgi"
				}
			]
		}
	}
}

If there is a package.conf file for the ACAP application project, you can use it to generate an initial manifest.json file.

The easiest way to do this is interactively inside the container. To generate the initial manifest.json file:

1. Locate packageconf2manifest.py tool inside the container, under /opt/axis/acapsdk/axis-acap-manifest-tools.

2. Run packageconf2manifest.py inside your ACAP project (that has an existing package.conf file).

This generates a manifest file based on that configuration. The manifest file should include everything that is needed to build the EAP file.

For help on using packageconf2manifest, run packageconf2manifest.py -h.

The table below shows the package configuration with manifest file, in relationship with the package.conf file.

1. We introduces this field in Schema version 1.3. It’s generated at the build step for architecture-dependent applications and should not be added. For architecture-independent applications, for example, a shell script, the architecture can be set to all in the manifest.json file.
2. 2.0 for manifest.json schema version 1.0 and earlier (for firmware version 10.5 and earlier). 3.0 for manifest.json schema version 1.1 and later. The minor version may need to be stepped up for certain APIs. See API for more information.

You can find the schema application-manifest-schema-v1.3.json in the acap-sdk Docker image under /opt/axis/acapsdk/axis-acap-manifest-tools/schema/schemas.

The following is no longer supported for an ACAP application, when using manifest file:

Pre-upgrade script –

Script run before an ACAP application is installed as an upgrade.

Forking main process –

Forking and demonizing of the ACAP application during start.

The package.conf file is included in the application package and contains variables describing the application. Shell script command create-package.sh reads the contents of package.conf when the application package is created.

Below are descriptions of the mandatory parameters in the package.conf file.

1. 2.0 if you are using package.conf only (and not manifest.json). The minor version may need to be stepped up for certain APIs. See API for more information.

Below are descriptions of the optional parameters in the package.conf file.

The LICENSE file is included in the application package. It shall contain all required open source license information for open source code distributed with the application package.

Application data such as configuration data and images should in runtime be saved to the localdata directory of the application project's root directory. The localdata directory is owned by APPUSR and the application has write access to it, once installed on a device. All content in the localdata directory remains after an application upgrade.

To build, install and run an ACAP application, use the image in the axisecp/acap-sdk repository. You can use this image in two ways:

• As a base image to build a custom application builder image, see Build, install and run with custom application image.

• Interactively inside the container, see Build, install and run interactively inside container.

To build an application defined by manifest.json, use the acap-build tool, see Build tool.

To build an application defined by package.conf, use the create-package.sh build script, see Build script.

For applications defined by package.conf, use the build script create-package.sh.

The script does the following:

• Checks that the file package.conf exists and does not contain any errors.

• Asks for missing or invalid parameters and creates package.conf.

• Executes make in the current directory to compile the application source code into an application binary file.

• Creates an eap (embedded application package) package including the application binary, html files (if any) and configuration files.

• Creates a copy of LICENSE file.

The created application package filename has the following format:

<PACKAGENAME>_<APPMAJORVERSION>_<APPMINORVERSION>_<APPMICROVERSION>_<SDK_ARCHITECTURE>.eap

The created copy of LICENSE filename has the following format:

<PACKAGENAME>_<APPMAJORVERSION>_<APPMINORVERSION>_<APPMICROVERSION>_LICENSE.txt

For applications defined by manifest.json, use the build tool acap-build.

The acap-build tool does the following:

• Runs make, performing any required cross-compilation as defined in the available Makefile.

• Validates the manifest file against the manifest schema.

• Generates a package.conf file and related configuration files for backward compatibility.

• Creates an EAP file including:

• • application executable

  • LICENSE file

  • any available html and lib folder

  • other files listed in the acap-build request

  • generated backward compatibility files

For help on using the build tool, run acap-build -h.

With some network requirements, you must run the following script on the Axis device.

#!/bin/sh
# Setup proxy for dockerd
cat >> /etc/systemd/system/sdkrun_dockerd.service <<EOF
[Service]
{{Environment="HTTP_PROXY=http://<myproxy.com>:<port>"
Environment="HTTPS_PROXY=http://<myproxy>:<port>"
Environment="NO_PROXY=localhost,127.0.0.0/8,10.0.0.0/8,192.168.0.0/16,172.16.0.0/12,.<domain>"}}
EOF
systemctl daemon-reload
systemctl restart sdkrun_dockerd
exit

For instructions on how to set up your build, to install, and to run with custom application image, use the Hello World application example shown in Set up and verify the SDK.

Using the custom application image, all the building and packaging is done inside a Docker container. The application is then copied to a custom directory, meaning that the original application project directory is not changed.

The top structure for an ACAP application contains a Dockerfile and a directory called app where the application project files are placed.

To install, start, stop and remove the application, use the device’s web interface.

To be able to work interactively with your application, you can bind mount the application project directory into the container. In this way, you can build and package the application directly in this folder. You may also install, start, stop and remove the application on a device directly from inside the container.

The top structure for an ACAP application contains a directory called, for example app where the application project files are placed.

To run the acap-sdk container interactively and mount the application project, go to the directory that contains app and run:

docker run -v $PWD/app:/opt/app -it hello_world:1.0

where:

• axisecp/acap-sdk is the Docker hub repostitory

• 3.3-armv7hf-ubuntu20.04 is the tag that points out which SDK version and architecture to use

• -v $PWD/app:/opt/app mounts the host directory $PWD/app into the container directory /opt/app

• --rm removes the container after closing it

• -i is to run the container interactively

• -t which repository tag to use

You should end up in a container with a prompt similar to:

root@1e6b4f3d5a2c:/opt/app#

Now you’re ready to build and install the application. See Build the application, and Install the application

Using package.conf (ACAP SDK version 3.2 and earlier)

To build an application stand in the application directory inside the container and run create-package.sh.

Using manifest.json (ACAP SDK version 3.3 and later)

To build an application, stand in the application directory inside the container and run the acap-build tool.

The SDK helps with installing a built application on the device from a terminal. You can also install application packages, using the device's web interface. But this method is less convenient during application development.

To install a built application on a device, run:

eap-install.sh

Run the command without any options to get help.

To install a built application on a device, run the following command (you must enter the IP address and the root password of the device the first time):

eap-install.sh <device-ip> <password> install

eap-install.sh 192.168.0.90 pass install

The command remembers the device-ip and password after the first successful execution. After this you can simply run:

eap-install.sh install

Before you continue, make sure that you have done a first successful execution of shell script command eap-install.sh, see Install the application for more information.

To start, stop and remove an installed application, run:

eap-install.sh [start|stop|remove]

To start an installed application on the device, run:

eap-install.sh start

Now you can see the status of the application using the device's web interface.

To stop a running application, run:

eap-install.sh stop

To remove an installed application, run:

eap-install.sh remove

Reproducible builds is a set of practices for compiling software that ensures the resulting binary code can be reproduced.

See An example of how to create a reproducible ACAP application to learn more.

From AXIS OS 11.6, ACAP applications can acquire VAPIX service account credentials in runtime. With these credentials, the ACAP application can call a local virtual host to make VAPIX requests on the device. A username and a password with high complexity are created for every credential acquisition. These credentials are only valid on the local virtual host (127.0.0.12) and aren't stored in any file. It should only be kept in memory by the ACAP application.

The following steps show how to get VAPIX credentials in an ACAP application:

1. Modify the manifest file

2. Acquire credentials

3. Make a VAPIX call

4. Test from command-line

1. Add the required D-Bus method com.axis.HTTPConf1.Auth1.GetVapixServiceAccountCredentials in the manifest file under field resources.dbus.requiredMethods.

2. Use a dynamic user by removing the user section from the manifest. To use this D-Bus service, the ACAP must run as a generated user and it is not available for the general SDK user.

Example manifest

{
    "schemaVersion": "1.3",
    "acapPackageConf": {
        "setup": {
            "appName": "vapix_access",
            "vendor": "Axis Communications",
            "embeddedSdkVersion": "3.0",
            "runMode": "never",
            "version": "1.0.0"
        }
    },
    "resources": {
        "dbus": {
            "requiredMethods": [
                "com.axis.HTTPConf1.Auth1.GetVapixServiceAccountCredentials"
            ]
        }
    }
} 

An ACAP application can acquire VAPIX service account credentials through a D-Bus call. This example uses GDBus, a high-level D-Bus library for working with D-Bus.

1. Establish a D-Bus connection to the system bus:

   This connection allows the application to communicate over the D-Bus system.

GDBusConnection *connection = g_bus_get_sync(G_BUS_TYPE_SYSTEM, NULL, &error);

2. Create a proxy object for your D-Bus interface:

   This proxy allows users to interact with your D-Bus service or interface.

GDBusProxy *proxy = g_dbus_proxy_new_sync(connection,
                                            G_DBUS_PROXY_FLAGS_NONE,
                                            NULL, 
                                            "com.axis.HTTPConf1",
                                            "/com/axis/HttpConf1/Auth",
                                            "com.axis.HTTPConf1.Auth1",
                                            NULL, 
                                            &error);

3. Invoke the D-Bus method using the proxy:

   The user can effectively call the method that returns the credentials by doing this.

GVariant *username = g_variant_new("(s)", "testuser");

GVariant *result = g_dbus_proxy_call_sync(proxy,
                                            "com.axis.HTTPConf1.Auth1.GetVapixServiceAccountCredentials",
                                            username,  
                                            G_DBUS_CALL_FLAGS_NONE,
                                            -1,  
                                            NULL, 
                                            &error);

When the GetVapixServiceAccountCredentials method is invoked, it generates credentials with the specified username and a random password, which is returned to the ACAP as a string.

After obtaining the credentials, it is ready to make the actual VAPIX call. The ACAP application will communicate with a local server, which then checks the given credentials (using basic access authentication) and forwards the VAPIX request.

This example uses the openssl_curl_example as a baseline and the libcurl C API is used to make the VAPIX call.

1. Define a VAPIX endpoint:

   As VAPIX calls are essentially HTTP requests, the URL must be specified.

curl_easy_setopt(curl, CURLOPT_URL, "http://127.0.0.12/axis-cgi/applications/list.cgi");

2. Generate and set credentials:

   The credentials obtained from the D-Bus call are concatenated and then added to the cURL request.

curl_easy_setopt(curl, CURLOPT_USERPWD, credentials);

3. Set the authentication method and make the VAPIX call:

   Here, basic access authentication is used, and then the actual cURL request is made.

curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_to_file);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &file);

SSH into a device and make a D-Bus call using a command-line to get VAPIX service account credentials.

Example call:

gdbus call --system
            --dest com.axis.HTTPConf1
            --object-path /com/axis/HttpConf1/Auth
            --method com.axis.HTTPConf1.Auth1.GetVapixServiceAccountCredentials
            "testuser"

Example response:

('id:a0-testuser, pass:MH757eGZdsyBuAbhAQ3j2ZtRNg9xchEg',)

Make a VAPIX request on local virtual host 127.0.0.12 with the given credentials using cURL.

Example:

curl -s -u '<id:pass>' http://127.0.0.12/axis-cgi/applications/list.cgi

Where id and pass are the credentials obtained from the GDBus call. This cURL command sends an HTTP GET request to the specified VAPIX endpoint with the required authentication.

• A device can hold a maximum of 200 VAPIX service accounts.

• There are no VAPIX service accounts after rebooting a device. Restarting the device removes all the created credentials.

• The credentials should be re-fetched each time the ACAP application starts and should only be kept in memory by the ACAP application, not stored in any file.

• We officially support only the specific D-Bus method calls introduced in this feature. Use of other D-Bus methods outside of this feature is not supported and may result in undefined behavior.

Visual Studio ​​​Code​ provides access to containerized development tools, without the need for you to install them natively on your development computer.

To start developing ACAPs using Visual Studio Code:

1. Install the Remote - Containers extension available in the Extensions Marketplace in Visual Studio Code.

2. Create a subfolder called .devcontainer in the top directory of the source code project you are working on.

3. In .devcontainer, create a Dockerfile and devcontainer.json containing the code below.

4. Save the Dockerfile and devcontainer.json.

5. Press Ctrl+Shift+P and type in Remote-Containers: Reopen in Container.

FROM axisecp/acap-sdk:3.2-armv7hf-ubuntu20.04
CMD /bin/bash

{
	"name": "ACAP SDK ",
	"build": {
		"dockerfile": "Dockerfile"
	}
}

The application restarts and is now attached to a container with the SDK and your code. This way, you can interactively edit your source code just as if the tools had been installed natively, including using all the debugging and support features in Visual Studio Code.

You can install different versions of the SDK in separate containers. When you open your source code folder, Visual Studio Code identifies the SDK version defined in the Dockerfile.

The ACAP SDK-container includes all the SDK tools, Git and some other useful things. But you can add more tools to the Dockerfile and the devcontainer.json configuration. See Microsofts tutorials on how to use Development Containers​ for more information on what this way of working can offer.

The ACAP SDK is capable of building applications in various languages.

Shell script

The build process requires a Makefile, even if nothing is being compiled. An empty Makefile is necessary to build shell script programs.

C

Most of the examples are built using C and can be found on GitHub. The SDK uses gcc to compile C programs.

C++

For an example of a C++ application, go to using-opencv. The SDK uses g++ to compile C++ programs.

Several ACAP code examples and tutorials are open-sourced and available on Github.

Each example has a well-defined README file with the example structure on GitHub which will help you execute the examples on an Axis camera. The README file structure is comprised of:

• example description

• repository structure

• limitation

• how to build and run the code

• expected output

The tutorials have the same structure as the examples but are more extensive in content and scope.

We are continuously adding new examples and tutorials for both existing as well as for new functionality. Keep checking GitHub to stay updated with the latest changes.

Axis Developer Community is an Axis hosted website for developers that want to work with Axis devices. Membership is required but it’s open to anyone.

On the community pages you'll find

• a wide array of documentation and tools that are useful when developing ACAP applications.

• documentation on, for example, how to integrate with Axis devices and other SDKs.

• a reference guide for all Axis devices supporting ACAP with information about chipset and memory resources.

• a Developer loan tool for running tests and trying out Axis products online.

The Product interface guide gives you information about architecture and chipset memory resources (RAM and flash) for all supported Axis devices. This information is helpful for finding out which SDK to use.

The sign package service is available in the ACAP Service Portal, and requires Technology Integration Partner Program access.

By signing an ACAP package you make sure that the content of the package is not tampered with between the release and installation on the Axis device.

During the signing process, a signature is added at the end of the application package. The signature is verified by the device when installing the ACAP application. Signing an application requires some fields to be set in the manifest, for example, vendor and architecture (from manifest schema 1.3 first released in ACAP Native SDK 1.1). You can find a full list of requirements and other information in the Axis ACAP Service Portal.

Support for verifying signed ACAPs was introduced in firmware 9.20. The format as such is fully backward compatible. A signed ACAP can be installed on devices with a firmware earlier than 9.20, in which case it’s not verified by the device.

A VAPIX API to toggle allowance of unsigned ACAP applications has been added in AXIS OS 11.2, see the API specifications in the VAPIX documentation.

Use the ACAP Service Portal for administrators to register new applications compatible with Axis products, and to manage all related information such as:

• Name and description for applications.

• Enable and setup the licensing service, such as trial or free licenses to users.

• Manage all aspects around licenses such as generating codes, and track and modify license keys.

• Configure compatibility between your application and Axis products.

• Sign ACAP packages to ensure authenticity, and to prevent tampering.

1. Go to axis.com and sign into your personal axis account.

2. Go to My Axis > Partner Pages.

3. Go to Software Development > ACAP > Axis ACAP Service Portal.

You can use a toggle to configure an Axis device to accept signed packages only.

The signature verification is performed during the ACAP application installation.

The SDK provides the following APIs:

Video and audio APIs

• Audio API: Axaudio

• Video capture API: VdoStream

• Machine learning API: Larod

• Overlay API: Axoverlay

• Open standard APIs

Application support APIs

• Parameter API: AxParameter

• HTTP API: AxHTTP

• Event API: Axevent

• License API: LicenseKey

Camera feature APIs

• Edge storage API: AxStorage

• Serial port API: AxSerialPort

• Pan tilt zoom API: AxPTZ

Go to the ACAP API documentation for detailed functional descriptions and examples of the APIs.

The table below shows API and firmware version compatibility.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The Axaudio API allows the application to:

• retrieve compressed or uncompressed audio in different formats,​ from the camera.

• send uncompressed audio to cameras with audio output.

• configure sample rates and bitrates for some compressed formats

The API supports several get methods that returns supported formats for a camera or other audio product.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

• Ambarella S2L

• i.MX 6SoloX

• i.MX 6ULL

This API was introduced in API version earlier than 3.0.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The VdoStream API provides:

• video and image stream

• video and image capture

• video and image configuration

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

Global rotation –

All platforms except ARTPEC-6 support global image source rotation. This feature is designed to utilize the hardware more efficiently. You need to take this into consideration when designing applications for multiple platforms. The Video capture API on ARTPEC-6 allows specifying the desired rotation per stream. For other chips this is a global option set when the camera is installed, and any attempt to specify capture rotation is ignored.

The VdoStream API was introduced in API version 3.0.

VdoStream has a memory leak in products with an ARTPEC chip using firmware version 10.10 or later. The issue was fixed in firmware version 10.11.65. The issue affects the vdo_buffer_get_data function.

This code example on GitHub starts a vdo stream and then illustrates how to continuously capture frames from the vdo service, access the received buffer contents as well as the frame metadata.

This code example on GitHub loads an image classification model to larod and then uses vdo to fetch frames of size WIDTH x HEIGHT in yuv format which are converted to interleaved rgb format and then sent to larod for inference on MODEL.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The API supports products with the following chips:

• ARTPEC-7

• ARTPEC-6

• Ambarella S5L

• Ambarella S5

• Ambarella S3L

• Ambarella S2L

Media Capture API was deprecated and removed in version 3.5.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

Larod provides a simple unified C API for efficiently running machine learning and image preprocessing. The purpose of Larod is to provide a unified API for all hardware platforms with very little overhead and to arbitrate between different processes (apps) requesting access to the same hardware.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• Ambarella CV25

• Ambarella S5L

For products with a DLPU (Deep Learning Processing Unit), inference runs on the DLPU otherwise it runs on the CPU.

This code example on GitHub connects to larod and loads a model, runs inference on it and then finally deletes the loaded model from larod.

This code example on GitHub loads an image classification model to larod and then uses vdo to fetch frames of size WIDTH x HEIGHT in yuv format which are converted to interleaved rgb format and then sent to larod for inference on MODEL.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The Axoverlay API is a helper library that enables an ACAP to draw overlays in selected video streams. It has built-in support for Cairo as rendering API, as well as an open backend for any other custom rendering.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

The Axoverlay API was introduced in API version 3.0.

This code example on GitHub shows how to draw plain boxes and text as overlays in a stream with the Axoverlay API.

The open standard APIs were introduced in API version 3.0.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The AxParameter API allows the application to save data and application settings so that they are not lost during a restart or firmware upgrade of the Axis product.

AxParameter makes it possible to define callback functions that perform specific actions if a parameter is updated, for example if the user updates a parameter using the Axis product's web pages.

Parameters specific to the application can be pre-configured when the application is created or be added in runtime.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

• Ambarella S3L

• Ambarella S2L

• i.MX 6SoloX

• i.MX 6ULL

This API was introduced in API version earlier than 3.0.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The AxHTTP API allows the application to act as a CGI. This is done through a socket transfer to the ACAP application. This is a useful way to provide a configuration API, or updated information from the ACAP application. The information or configuration can then be accessed in ACA through a page provided by the ACAP application.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

• Ambarella S3L

• Ambarella S2L

• i.MX 6SoloX

• i.MX 6ULL

This API was introduced in API version earlier than 3.0.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The Axevent API provides:

• an interface to the event system found in Axis products.

• applications with a mechanism for sending and receiving events.

An application can both send and receive events.

Event types

Stateless (Pulse) –

An event that indicates that something has occurred. Typically used to trigger some action rule.

Stateful (State) –

An event with an active and inactive state. Typically used in action rules like “record while active”.

Data (Application Data) –

An event that includes data that needs to be processed by the consuming application such as transaction data, license plate or other dynamic data. A data event is normally not used to trigger generic action rules.

Supported Namespaces

When declaring events it is required to set a namespace. Following are the supported namespaces:

tnsaxis –

Axis namespace to use with Axis events

tns1 –

ONVIF namespace to use with ONVIF events

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

• Ambarella S3L

• Ambarella S2L

• i.MX 6SoloX

• i.MX 6ULL

This code example on GitHub illustrates both how to subscribe to different events and how to send an event.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The AxStorage API allows the application to save and retrieve data on mounted storage devices such as SD cards and NAS (Network Attached Storage) units. An application can only modify its own files on the storage device.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

• Ambarella S3L

• Ambarella S2L

• i.MX 6SoloX

• i.MX 6ULL

This API was introduced in API version earlier than 3.0.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

Use the LicenseKey API to validate an application license key.

A license key is a signed file, generated for a specific device ID and application ID. The ACAP Service Portal maintains both license keys and application IDs.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S5

• Ambarella S3L

• Ambarella S2L

• i.MX 6SoloX

• i.MX 6ULL

This API was introduced in API version earlier than 3.0.

This code example on GitHub shows how to check the status of a license key.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The AxSerialPort API allows the application to configure and control the external serial port on selected Axis products.

The API is product dependent since not all Axis products are equipped with a serial port.

The API supports the RS-232, RS-422 and RS-485 standard.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

This API was introduced in API version earlier than 3.0.

Go to the ACAP API documentation for detailed functional descriptions and examples of this API.

The AxPTZ API allows the application to control the camera's pan, tilt and zoom movements, to interact with the PTZ control queue and to create and delete preset positions.

The API supports products with the following chips:

• ARTPEC-8

• ARTPEC-7

• ARTPEC-6

• Ambarella CV25

• Ambarella S5L

• Ambarella S3L

• Ambarella S2L

This API was introduced in API version earlier than 3.0.

New features

• ARTPEC-8 support

• Manifest schema 1.3 and architecture

Library or tool updates

• glibc updated to version 2.33

Deprecated APIs

• Media Capture (libcapture.so) is removed from this SDK version.

Library or tool updates

• Changed the GCC directory search option format from -L dir to -Ldir in the SDK compiler variables in ACAP build tools. See GCC documentation for more information.

• Added a symbolic link that points python to python3. In ACAP SDK 3.4 and earlier, python3 is installed but some programs and scripts rely on the python command.

New features

• All application defines and configurations fully supported in tools for conversion to manifest based ACAP application.

• Build command updated to support reproducible builds. See Reproducible builds for more information.

Library or tool updates

• glibc 2.32

New APIs

• larod 2.0 - Handles TFLite when using firmware version 10.6 and later.

New features

• Support for manifest.json - used for application defines and configurations such as app name and version. manifest.json is a JSON based manifest file enabling schema validation for error handling. The SDK includes a tool for converting package.conf to a manifest file. We recommend using the manifest now to future proof your application. See Manifest file for more information.

New APIs

• larod 2.0 - New version of machine learning API with support for hardware accelerated image pre-processing operations crop, scale and color-space conversion.

New features

• A toggle that controls loading of signed ACAPs, see Accept or deny unsigned ACAPs.

Library or tool updates

• gcc updated to version 9.3.

Other changes

• From this release on, the ACAP SDK is available on DockerHub only.

Deprecated APIs

• Capture is removed from SDK and firmware after the next firmware LTS. Use Video capture API instead.

Library or tool updates

• gcc updated to version 9.2.

Other changes

• From this release, the ACAP toolchain and ACAP API are available as container images on DockerHub.

New APIs

• Machine learning API

Library or tool updates

• gcc updated to version 8.3.

Other changes

• ACAP SDK not available for the mips architecture from this version.

New APIs

• Overlay API

• Open standard APIs

• Video capture API

You can find the ACAP SDK open source licenses and copyleft source code here.

By downloading AXIS Embedded Development SDK, you agree to the terms in the license agreement.