Native SDK API

The ACAP Native SDK provides the following APIs:

Compatibility

To find compatibility between ACAP Native SDK and AXIS OS version, refer to Find the right SDK for software compatibility.

Video capture API (VDO)

Go to the ACAP API Documentation for detailed functional descriptions of this API.

The VdoStream API provides:

  • video and image stream
  • video and image capture
  • video and image configuration

Available video compression formats through VDO

The table below shows available subformats for corresponding YUV format.

Sub Formats Corresponding format
nv12 YUV
y800 YUV

An application to start a vdo stream can be found at vdostream, where the first argument is a string describing the video compression format. It takes h264 (default), h265, jpeg, nv12, and y800 as inputs. Both nv12 and y800 correspond to YUV format of VDO.

Compatibility

The API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6
  • Ambarella CV25
  • Ambarella S5L
  • Ambarella S5

Compatibility limitations

  • Global rotation - All platforms except ARTPEC-6 support global image source rotation, this feature is designed to utilize the hardware more efficiently. When designing applications for multiple platforms this needs to be taken into consideration. The Video capture API on ARTPEC-6 allows specifying the desired rotation per stream in contrast to other chips where this is a global option chosen at camera installation time and any attempt to specify capture rotation will be ignored.

Version history

The Video capture API was introduced in Native SDK 1.0.

AXIS OS version VdoStream API version New functions added
10.7 6.13.0 vdo_frame_take_chunk
10.8 6.24.1 vdo_zipstream_profile_get_type, vdo_frame_set_header_size
10.9 6.34.16 vdo_stream_get_event,vdo_stream_get_event_fd, vdo_map_swap
10.10 7.5.22 vdo_frame_take_chunk, vdo_frame_take_chunk_ex, vdo_stream_play
10.11 7.19.2 -
10.12 8.0.15 vdo_map_get_pair32i, vdo_map_get_pair32u, vdo_map_set_pair32i, vdo_map_set_pair32u
11.0 9.0.4 -
11.1 9.8.16 -
11.2 9.18.0 -
11.3 9.32.0 -
11.4 9.41.16 vdo_channel_get_ex
11.5 9.59.0 -
11.6 9.78.12 vdo_stream_set_gop_length, vdo_error_is_resource_limitation

Known issues

  • A memory leak in VDO was found in firmware versions from 10.10 for Artpec chips, later fixed in 10.11.65. The issue affects function vdo_buffer_get_data.

Code Examples

  • vdostream
    • The example code is written in C which 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.
  • vdo-larod
    • The example code is written in C and loads an image classification model to the Machine learning API (Larod) and then uses the Video capture API (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.
  • vdo-opencl-filtering
    • This example illustrates how to capture frames from the vdo service, access the received buffer, and finally perform a GPU accelerated Sobel filtering with OpenCL.

Machine learning API (Larod)

Go to the ACAP API Documentation for detailed functional descriptions of this API.

Larod is a service provides a simple unified C API for running machine learning and image preprocessing efficiently. 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.

Compatibility

The Larod 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.

Version history

The Machine learning API was introduced in Native SDK 1.0. All larod API versions are available.

Code Examples

  • vdo-larod
    • The example code is written in C and loads an image classification model to the Machine learning API (Larod) and then uses the Video capture API (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.
  • object-detection
    • The example code focus on object detection, cropping and saving detected objects into JPEG files.
    • A separate example is available for CV25 cameras.

Overlay API

Go to the ACAP API Documentation for detailed functional descriptions 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.

Compatibility

The API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6

Version history

The Axoverlay API was introduced in Native SDK 1.0.

Code Examples

  • axoverlay
    • The example code is written in C which illustrates how to draw plain boxes and text as overlays in a stream.

Cairo

Open-source rendering library for 2D vector graphics. See Cairo documentation.

Compatibility

The Cairo API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6

Version history

The Cairo API was introduced in Native SDK 1.0.

Code Examples

  • axoverlay
    • The example code is written in C which illustrates how to draw plain boxes and text as overlays in a stream.

OpenCL

Accelerate parallel compute with GPU. See OpenCL documentation.

Compatibility

The OpenCL API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7

Version history

The OpenCL 1.2 was introduced in Native SDK 1.0.

Code Examples

  • vdo-opencl-filtering
    • This example illustrates how to capture frames from the vdo service, access the received buffer, and finally perform a GPU accelerated Sobel filtering with OpenCL.

Parameter API

Go to the ACAP API Documentation for detailed functional descriptions of this API.

The AXParameter C library provides the following functionality:

  • Read and modify application parameters stated in manifest.json.
  • Add and remove application parameters in C code, in addition to the ones already defined in manifest.json.
  • Set up callbacks so the application can act immediately on changes made to the application parameters via the application settings web page or VAPIX.
  • Read system parameters.

Application parameters have the following properties:

  • They are preserved when an application is restarted or upgraded.
  • They are preserved when the device is restarted and when firmware is upgraded.
  • They are displayed and possible to set in the application settings web page.
  • They can be read and modified using VAPIX API param.cgi.

The application parameters are not private to the application, they can be:

  • read via VAPIX by a user with operator privileges.
  • read and modified via VAPIX by a user with admin privileges.
  • read and modified by another application if the application users belongs to the same group.

Application settings web page

The application settings web page can be used to modify application parameters.

In the Axis device web page:

  • Go to Apps tab
  • Open the application options
  • Click Settings to open a dialog where parameters can be set

Note that a reload of the web page is required to display values set from C code or VAPIX.

Compatibility

The Parameter API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6
  • Ambarella CV25
  • Ambarella S5L
  • Ambarella S5
  • i.MX 6SoloX
  • i.MX 6ULL

Version history

The Parameter API was introduced in Native SDK 1.13.

Code Examples

  • axparameter
    • An example in C that demonstrates how to manage application-defined parameters, allowing you to add, remove, set, get, and register callback functions for parameter value updates.

Event API

Go to the ACAP API Documentation for detailed functional descriptions 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

Compatibility

The API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6
  • Ambarella CV25
  • Ambarella S5L
  • Ambarella S5
  • i.MX 6SoloX
  • i.MX 6ULL

Version history

The Axevent API was introduced in Native SDK 1.0.

Code Examples

  • send_event
    • The example code is written in C which sends an ONVIF event periodically.
  • subscribe_to_event
    • The example code is written in C which subscribe to the ONVIF event sent from application “send_event”.
  • subscribe_to_events
    • The example code is written in C which subscribes to different predefined events.

Edge storage API

Go to the ACAP API Documentation for detailed functional descriptions of this API.

The Edge storage 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. An application can both send and receive events.

Compatibility

The API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6
  • Ambarella CV25
  • Ambarella S5L
  • Ambarella S5
  • i.MX 6SoloX
  • i.MX 6ULL

Version history

The Edge storage API was introduced in Native SDK 1.11.

Code Examples

  • axstorage
    • This application demonstrates the usage of axstorage APIs, offering the following functionality:
      • List configured storage devices.
      • Subscribe to events from all storage devices.
      • Set up and utilize all available/mounted storage devices.
      • Continuously write data to two files on all available storage devices.
      • Automatically release any unmounted storage devices.

License Key API

Go to the ACAP API Documentation for detailed functional descriptions of this API.

Use the License Key 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.

Compatibility

The API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6
  • Ambarella CV25
  • Ambarella S5L
  • Ambarella S5
  • i.MX 6SoloX
  • i.MX 6ULL

Version history

This API was introduced in Native SDK 1.0.

Code Examples

  • licensekey
    • The example code is written in C which illustrates how to check the licensekey status.

FastCGI

FastCGI is a protocol for interfacing interactive programs with a web server.

Compatibility

The FastCGI API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • ARTPEC-6
  • Ambarella CV25
  • Ambarella S5L
  • Ambarella S5
  • i.MX 6SoloX
  • i.MX 6ULL

Version history

The FastCGI API was introduced in Native SDK 1.6.

Code Examples

  • web-server-using-fastcgi
    • This example is written in C and explains how to build an ACAP application that can handle HTTP requests sent to the Axis device, using the device’s own web server and FastCGI.

Serial port API

Go to the ACAP API Documentation for detailed functional descriptions of this API.

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

Compatibility

  • The API supports the following standards:
    • RS-232
    • RS-422
    • RS-485
  • The API is product dependent since not all Axis products are equipped with a serial port.
  • The API supports products with the following chips:
    • ARTPEC-8
    • ARTPEC-7

Version history

The Serial port API was introduced in Native SDK 1.11.

Code Examples

  • axserialport
    • This example details the creation of an ACAP application utilizing the axserialport API, showcasing the following actions:
      • Enabling the serial port.
      • Configuring parameters using the API.
      • Establishing communication between two available ports in the Axis product using GLib IOChannel methods.

Metadata Broker API

This API is a Beta version and developers are encouraged to test and leave feedback.

Go to the ACAP API Documentation for detailed functional descriptions of this API.

The Metadata Broker API allows an ACAP application to consume metadata from a producer in AXIS OS by subscribing to a topic.

The API implements the Publish/Subscribe messaging paradigm.

Compatibility

The Metadata Broker API supports products with the following chips:

  • ARTPEC-8
  • ARTPEC-7
  • Ambarella CV25

Version history

The Metadata Broker API was introduced in Native SDK 1.13.

Code Examples

Back to top

© Axis Communications AB. All rights reserved. AXIS COMMUNICATIONS, AXIS, ARTPEC and VAPIX are registered trademarks of Axis AB in various jurisdictions, and you are not granted any license to use them. All other trademarks are the property of their respective owners.