https://github.com/axiscommunications/acap-runtime
AXIS Camera Application Platform version 4 - ACAP Runtime: A gRPC service providing APIs for extended ACAP development
https://github.com/axiscommunications/acap-runtime
acap api axis grpc grpc-server runtime
Last synced: 9 months ago
JSON representation
AXIS Camera Application Platform version 4 - ACAP Runtime: A gRPC service providing APIs for extended ACAP development
- Host: GitHub
- URL: https://github.com/axiscommunications/acap-runtime
- Owner: AxisCommunications
- License: apache-2.0
- Created: 2021-10-19T17:05:13.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-11T07:33:18.000Z (over 1 year ago)
- Last Synced: 2024-11-11T08:27:41.677Z (over 1 year ago)
- Topics: acap, api, axis, grpc, grpc-server, runtime
- Language: C++
- Homepage: https://hub.docker.com/r/axisecp/acap-runtime
- Size: 596 KB
- Stars: 5
- Watchers: 2
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
*Copyright (C) 2022, Axis Communications AB, Lund, Sweden. All Rights Reserved.*
# ACAP Runtime
[](https://github.com/AxisCommunications/acap-runtime/actions/workflows/lint.yml)
[](https://github.com/AxisCommunications/acap-runtime/actions/workflows/ci-cd.yml)
[](https://github.com/AxisCommunications/acap-runtime/actions/workflows/build-proto-image.yml)
ACAP Runtime is a network protocol based service, using [gRPC][gRPC].
This makes the service available to clients written in different languages on
the same device. ACAP Runtime is also described in the [ACAP documentation][acap-documentation-acap-runtime].
If you are new to the world of ACAPs take a moment to check out
[What is ACAP?][acap-documentation]
## Notable Releases
| Release | AXIS OS min. version | Comment |
| -----------------------: | -------------------: |---------------------------------|
| [2.0.0][latest-release] | 11.10 | Latest release |
| [1.3.1][1.3.1-release] | 10.12 | Legacy release AXIS OS 2022 LTS |
> [!NOTE]
>
> Up until release 1.3.1 ACAP Runtime was distributed both in the form of an ACAP application eap-file and as a Docker image.
> From release 2.0.0 and onwards ACAP Runtime will be distributed as a Docker image only.
## Table of contents
- [Overview](#overview)
- [Requirements](#requirements)
- [APIs](#apis)
- [Usage](#usage)
- [Configuration](#configuration)
- [Examples](#examples)
- [Building ACAP Runtime](#building-acap-runtime)
- [Building protofiles for Python](#building-protofiles-for-python)
- [Test suite](#test-suite)
- [Contributing](#contributing)
- [License](#license)
## Overview
ACAP Runtime provides a network protocol based service, using gRPC to
expose a number of [APIs](#apis). Once started, ACAP Runtime runs a gRPC server
that can be accessed by a client application, written in any gRPC compatible language.
For further information on the gRPC protocol and how to write gRPC clients see
[https://grpc.io/][gRPC].
ACAP Runtime is available as a docker image and requires that [Docker ACAP][docker-acap] or [Docker Compose ACAP][docker-compose-acap]
is installed and running on the device. Configuration
options are described in the Configuration sub section
in the [Usage](#usage) section.
A client for the ACAP Runtime gRPC server could be developed either using the
[ACAP Native SDK][acap-documentation-native] or the
[ACAP Computer Vision SDK][acap-documentation-cv]. See the [Examples](#examples)
section for examples of how ACAP Runtime is used together with ACAP Computer Vision SDK.
> [!NOTE]
>
> The ACAP Runtime service can run with TLS authentication or without.
> Be aware that running without TLS authentication is extremely insecure and we
strongly recommend against this.
> See [TLS](#tls) for information on how to generate certificates for TLS
authentication when using ACAP Runtime.
### Requirements
The following requirements need to be met.
- Axis device:
- [Docker ACAP][docker-acap] or [Docker Compose ACAP][docker-compose-acap] version 2.0.0 or higher, installed and running.
- AXIS OS version 11.10 or higher.
- Certificate files if [TLS](#tls) is used.
- Computer:
- Either [Docker Desktop][dockerDesktop] version 4.11.1 or higher, or
[Docker Engine][dockerEngine] version 20.10.17 or higher.
- To build ACAP Runtime locally it is required to have [Buildx][buildx] installed.
### APIs
The ACAP Runtime service provides the following APIs:
- Machine learning API - An implementation of [TensorFlow Serving][tensorflow]. A usage example for the Machine learning API written in Python can be found in [minimal-ml-inference][minimal-ml-inference].
- Parameter API - Provides gRPC read access to the parameters of an Axis device.
A usage example for the Parameter API written in Python can be found in [parameter-api-python][parameter-api-python].
- Video capture API - Enables capture of images from a camera.
A usage example for the Video capture API written in Python can be found in [object-detector-python][object-detector-python].
## Usage
To use ACAP Runtime on an AXIS device first install [Docker ACAP][docker-acap] or [Docker Compose ACAP][docker-compose-acap] on the device. Please refer to the documentation in the repo of either of those applications to make sure the device is compatible.
Pre-built versions of the ACAP Runtime Docker image are available on
[axisecp/acap-runtime][docker-hub-acap-runtime] with tags on the form
`--containerized`. The documentation of the Docker ACAP/Docker Compose ACAP describes how to upload a docker image to the device as well as how to run it.
To include the containerized ACAP Runtime server in a project, add the image in
the projects `docker-compose.yml` file. The following is an illustrative
example of how the service can be set up with docker-compose. Here we use the
image for `aarch64` architecture. For a complete description
see one of the working project [examples](#examples).
```yml
services:
acap-runtime-server:
image: axisecp/acap-runtime:2.0.0-aarch64-containerized
entrypoint: ["/opt/app/acap_runtime/acapruntime", "-j", "12"]
volumes:
- /run/dbus/system_bus_socket:/run/dbus/system_bus_socket
- /run/parhand/parhandsocket:/run/parhand/parhandsocket
- /usr/lib:/usr/lib
- /usr/bin:/usr/bin
- shared_volume:/tmp
acap-runtime-client:
image:
environment:
- INFERENCE_HOST=unix:///tmp/acap-runtime.sock
- INFERENCE_PORT=0
volumes:
- shared_volume:/tmp
volumes:
shared_volume: {}
```
### Configuration
When starting the ACAP Runtime service from command line, as is done with the
containerized version, it accepts the following settings:
```text
-v Verbose, enable extended logging,
-a IP address of gRPC server, default 0.0.0.0. See note1,
-p IP port of gRPC server, default 0. See note1,
-t Runtime in seconds (used for test),
-c Certificate file for TLS authentication. See note2,
-k Private key file for TLS authentication. See note2,
-j Chip id used by Machine learning API service. See note3,
-m Inference model file used by Machine learning API service,
-o Override settings from device parameters. This is a legacy flag that should not be used.
```
Notes.
**(1)** The gRPC server can be set up with either a unix-socket (default) or a
network socket. To set up as network socket the IP port should be set to a non-zero
value. The IP address is only used when set up as a network socket.
See [gRPC](#grpc-socket) for more information.
**(2)** To use TLS a certificate file and a corresponding private key file must
be supplied. If either is omitted TLS is not used.
See [TLS](#tls) for more information.
**(3)** When using the Machine learning API the chip Id corresponding to the device must
be given. See [Chip id](#chip-id) for more information.
#### Chip id
The Machine learning API uses the [Machine learning API][acap-documentation-native-ml] for image processing
and to set it up the correct chip id for the device needs to be selected.
Note that there is no direct correlation between chip id and architecture.
For convenience the pre-built images for the ACAP Runtime native application sets
the default value for ChipId to 4 for `armv7hf` and 12 for `aarch64`, since those
are currently the most common ids for the respective architectures.
See the table below for a full list of supported values.
If the value is set to 0 (LAROD_CHIP_INVALID) the Machine learning API inference service will not
be started.
| Chip id | Name | Description |
|---------|-------------------------------|--------------------------------------------|
| 0 | LAROD_CHIP_INVALID | Invalid chip |
| 1 | LAROD_CHIP_DEBUG | Dummy chip for debugging |
| 4 | LAROD_CHIP_TPU | Google TPU |
| 6 | LAROD_CHIP_CVFLOW_NN | Ambarella CVFlow (NN) |
| 8 | LAROD_CHIP_TFLITE_GLGPU | GPU with TensorFlow Lite. WARNING: This is an experimental chip which is subject to change. |
| 9 | LAROD_CHIP_CVFLOW_PROC | Ambarella CVFlow (proc) |
| 10 | LAROD_CHIP_ACE | Axis Compute Engine |
| 11 | LAROD_CHIP_LIBYUV | CPU with libyuv. |
| 12 | LAROD_CHIP_TFLITE_ARTPEC8DLPU | ARTPEC-8 DLPU with TensorFlow Lite. |
| 13 | LAROD_CHIP_OPENCL | Image processing using OpenCL |
#### TLS
The ACAP Runtime service can be run either in TLS authenticated or unsecured mode.
TLS authenticated mode provides additional security and encryption on the gRPC
channel and is the recommended (and default) mode. The service requires a certificate
file and a key file to run in TLS authenticated mode.
One way to generate the certificates is to use the [`openssl req`][openssl-req]
command, e.g.:
```sh
# generate the files
openssl req -x509 \
-batch \
-subj '/CN=localhost' \
-days \
-newkey rsa:4096 \
-nodes \
-out server.pem \
-keyout server.key
```
Where `` is the number of days you wish the certificate to be valid.
To use the certificates make sure they are available to the ACAP Runtime service, e.g. by placing them in a location that will be mounted to the container when running. Then use the `-c` and `-k` settings to point them out:
```sh
docker run -v :/opt/app/certificates \
--entrypoint="/opt/app/acap_runtime/acapruntime \
-k /opt/app/certificates/server.key \
-c /opt/app/certificates/server.pem" \
axisecp/acap-runtime:--containerized
```
where `` is the path on the host system where the certificates are stored.
#### gRPC socket
With the default settings the ACAP Runtime service will set at a Unix Domain Socket
(UDS) with the address:
```sh
unix:///tmp/acap-runtime.sock
```
This is suitable for projects that are contained on a device. If a network socket
is needed instead, this can be done by using the `-a` and `-p` settings.
### Examples
The following example use the Parameter API with ACAP Runtime as a native
ACAP application:
- [parameter-api-python][parameter-api-python]
The following example use the ACAP Runtime containerized version to use the
Machine learning API service:
- [minimal-ml-inference][minimal-ml-inference]
## Building ACAP Runtime
Docker is used to build ACAP Runtime by using the provided Dockerfile. Note that Buildx is used. To build the image run:
```sh
# Build ACAP Runtime containerized version
docker buildx build --file Dockerfile --build-arg ARCH= --tag acap-runtime:-containerized .
```
where `` is either `armv7hf` or `aarch64`.
## Building protofiles for Python
The repository includes a Dockerfile (`Dockerfile.proto`) for building the APIs protofiles for Python. The Dockerfile generates the necessary Python files from the protobuf definitions, allowing gRPC communication with the ACAP Runtime service. This means that applications can copy these prebuilt files from `axisecp/acap-runtime:-protofiles` image instead of having to build the protofiles themselves.
To build the protofiles:
```sh
docker build -f Dockerfile.proto -t acap-runtime-proto:latest .
```
## Test suite
The repo contains a test suite project to verify that ACAP Runtime works as expected
on a supported device. It builds and is executed as a standalone ACAP application
called `Acapruntimetest`.
Build and install it by running:
```sh
# Build ACAP Runtime test suite image
docker buildx build --file Dockerfile --build-arg ARCH= --build-arg TEST=yes --tag acap-runtime:-test --target runtime-base .
docker run --rm acap-runtime:-test install
```
where `` is either `armv7hf` or `aarch64` and `` and ``
are the IP and root password of the device in use.
The application can be started, stopped and eventually uninstalled in the **Apps**
tab in the device GUI or by running:
```sh
docker run --rm acap-runtime:-test start|stop|remove
```
To see the test run output, check the application log either by clicking on the
**App log** link in the device GUI, or directly at:
```sh
http:///axis-cgi/admin/systemlog.cgi?appname=acapruntimetest
```
If the tests pass the log should end with \[ PASSED ]. If any test fails, it
will be listed.
## Contributing
Take a look at the [CONTRIBUTING.md](CONTRIBUTING.md) file.
## License
[Apache 2.0](LICENSE)
[1.3.1-release]: https://github.com/AxisCommunications/acap-runtime/releases/tag/1.3.1
[acap-documentation]: https://axiscommunications.github.io/acap-documentation/docs/introduction/what-is-acap.html
[acap-documentation-native]: https://axiscommunications.github.io/acap-documentation/docs/introduction/acap-sdk-overview.html#acap-native-sdk
[acap-documentation-native-ml]: https://axiscommunications.github.io/acap-documentation/docs/api/native-sdk-api.html#machine-learning-api
[acap-documentation-cv]: https://axiscommunications.github.io/acap-documentation/docs/introduction/acap-sdk-overview.html#acap-computer-vision-sdk
[acap-documentation-acap-runtime]: https://axiscommunications.github.io/acap-documentation/docs/api/computer-vision-sdk-apis.html#beta---acap-runtime
[buildx]: https://docs.docker.com/build/install-buildx/
[docker-acap]: https://github.com/AxisCommunications/docker-acap
[docker-compose-acap]: https://github.com/AxisCommunications/docker-compose-acap
[docker-hub-acap-runtime]: https://hub.docker.com/r/axisecp/acap-runtime
[dockerDesktop]: https://docs.docker.com/desktop/
[dockerEngine]: https://docs.docker.com/engine/
[gRPC]: https://grpc.io/
[latest-release]: https://github.com/AxisCommunications/acap-runtime/releases/latest
[minimal-ml-inference]: https://github.com/AxisCommunications/acap-computer-vision-sdk-examples/tree/main/minimal-ml-inference
[openssl-req]: https://www.openssl.org/docs/man3.0/man1/openssl-req.html
[object-detector-python]: https://github.com/AxisCommunications/acap-computer-vision-sdk-examples/tree/main/object-detector-python
[parameter-api-python]: https://github.com/AxisCommunications/acap-computer-vision-sdk-examples/tree/main/parameter-api-python
[tensorflow]: https://github.com/tensorflow/serving