{"id":28995111,"url":"https://github.com/axiscommunications/acap-runtime","last_synced_at":"2025-06-25T04:06:35.720Z","repository":{"id":77758049,"uuid":"419018210","full_name":"AxisCommunications/acap-runtime","owner":"AxisCommunications","description":"AXIS Camera Application Platform version 4 - ACAP Runtime: A gRPC service providing APIs for extended ACAP development","archived":false,"fork":false,"pushed_at":"2024-11-11T07:33:18.000Z","size":610,"stargazers_count":5,"open_issues_count":6,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-11T08:27:41.677Z","etag":null,"topics":["acap","api","axis","grpc","grpc-server","runtime"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/axisecp/acap-runtime","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AxisCommunications.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-19T17:05:13.000Z","updated_at":"2024-09-20T07:15:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"9238bef3-b3d9-4dd2-a0a5-13e929fdd657","html_url":"https://github.com/AxisCommunications/acap-runtime","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/AxisCommunications/acap-runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxisCommunications%2Facap-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxisCommunications%2Facap-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxisCommunications%2Facap-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxisCommunications%2Facap-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AxisCommunications","download_url":"https://codeload.github.com/AxisCommunications/acap-runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AxisCommunications%2Facap-runtime/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261801988,"owners_count":23211664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acap","api","axis","grpc","grpc-server","runtime"],"created_at":"2025-06-25T04:06:33.980Z","updated_at":"2025-06-25T04:06:35.679Z","avatar_url":"https://github.com/AxisCommunications.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"*Copyright (C) 2022, Axis Communications AB, Lund, Sweden. All Rights Reserved.*\n\n\u003c!-- omit in toc --\u003e\n# ACAP Runtime\n\n[![Lint codebase](https://github.com/AxisCommunications/acap-runtime/actions/workflows/lint.yml/badge.svg)](https://github.com/AxisCommunications/acap-runtime/actions/workflows/lint.yml)\n[![CI/CD](https://github.com/AxisCommunications/acap-runtime/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/AxisCommunications/acap-runtime/actions/workflows/ci-cd.yml)\n[![Proto build](https://github.com/AxisCommunications/acap-runtime/actions/workflows/build-proto-image.yml/badge.svg)](https://github.com/AxisCommunications/acap-runtime/actions/workflows/build-proto-image.yml)\n\nACAP Runtime is a network protocol based service, using [gRPC][gRPC].\nThis makes the service available to clients written in different languages on\nthe same device. ACAP Runtime is also described in the [ACAP documentation][acap-documentation-acap-runtime].\n\nIf you are new to the world of ACAPs take a moment to check out\n[What is ACAP?][acap-documentation]\n\n\u003c!-- omit in toc --\u003e\n## Notable Releases\n\u003c!-- markdownlint-disable MD013 --\u003e\n| Release                  | AXIS OS min. version | Comment                         |\n| -----------------------: | -------------------: |---------------------------------|\n| [2.0.0][latest-release]  | 11.10                | Latest release                  |\n| [1.3.1][1.3.1-release]   | 10.12                | Legacy release AXIS OS 2022 LTS |\n\n\u003e [!NOTE]\n\u003e\n\u003e 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.\n\u003e From release 2.0.0 and onwards ACAP Runtime will be distributed as a Docker image only.\n\n\u003c!-- omit in toc --\u003e\n## Table of contents\n\n- [Overview](#overview)\n  - [Requirements](#requirements)\n  - [APIs](#apis)\n- [Usage](#usage)\n  - [Configuration](#configuration)\n  - [Examples](#examples)\n- [Building ACAP Runtime](#building-acap-runtime)\n- [Building protofiles for Python](#building-protofiles-for-python)\n- [Test suite](#test-suite)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nACAP Runtime provides a network protocol based service, using gRPC to\nexpose a number of [APIs](#apis). Once started, ACAP Runtime runs a gRPC server\nthat can be accessed by a client application, written in any gRPC compatible language.\nFor further information on the gRPC protocol and how to write gRPC clients see\n[https://grpc.io/][gRPC].\n\n![ACAP Runtime Service with gRPC client](assets/gRPC.png)\n\nACAP Runtime is available as a docker image and requires that [Docker ACAP][docker-acap] or [Docker Compose ACAP][docker-compose-acap]\nis installed and running on the device. Configuration\noptions are described in the Configuration sub section\nin the [Usage](#usage) section.\n\nA client for the ACAP Runtime gRPC server could be developed either using the\n[ACAP Native SDK][acap-documentation-native] or the\n[ACAP Computer Vision SDK][acap-documentation-cv]. See the [Examples](#examples)\nsection for examples of how ACAP Runtime is used together with ACAP Computer Vision SDK.\n\n\u003e [!NOTE]\n\u003e\n\u003e The ACAP Runtime service can run with TLS authentication or without.\n\u003e Be aware that running without TLS authentication is extremely insecure and we\nstrongly recommend against this.\n\u003e See [TLS](#tls) for information on how to generate certificates for TLS\nauthentication when using ACAP Runtime.\n\n### Requirements\n\nThe following requirements need to be met.\n\n- Axis device:\n  - [Docker ACAP][docker-acap] or [Docker Compose ACAP][docker-compose-acap] version 2.0.0 or higher, installed and running.\n  - AXIS OS version 11.10 or higher.\n  - Certificate files if [TLS](#tls) is used.\n\n- Computer:\n  - Either [Docker Desktop][dockerDesktop] version 4.11.1 or higher, or\n  [Docker Engine][dockerEngine] version 20.10.17 or higher.\n  - To build ACAP Runtime locally it is required to have [Buildx][buildx] installed.\n\n### APIs\n\nThe ACAP Runtime service provides the following APIs:\n\n- 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].\n- Parameter API - Provides gRPC read access to the parameters of an Axis device.\n  A usage example for the Parameter API written in Python can be found in [parameter-api-python][parameter-api-python].\n- Video capture API - Enables capture of images from a camera.\n  A usage example for the Video capture API written in Python can be found in [object-detector-python][object-detector-python].\n\n## Usage\n\nTo 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.\n\nPre-built versions of the ACAP Runtime Docker image are available on\n[axisecp/acap-runtime][docker-hub-acap-runtime] with tags on the form\n`\u003cversion\u003e-\u003cARCH\u003e-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.\n\nTo include the containerized ACAP Runtime server in a project, add the image in\nthe projects `docker-compose.yml` file. The following is an illustrative\nexample of how the service can be set up with docker-compose. Here we use the\nimage for `aarch64` architecture. For a complete description\nsee one of the working project [examples](#examples).\n\n```yml\nservices:\n    acap-runtime-server:\n      image: axisecp/acap-runtime:2.0.0-aarch64-containerized\n      entrypoint: [\"/opt/app/acap_runtime/acapruntime\", \"-j\", \"12\"]\n      volumes:\n        - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket\n        - /run/parhand/parhandsocket:/run/parhand/parhandsocket\n        - /usr/lib:/usr/lib\n        - /usr/bin:/usr/bin\n        - shared_volume:/tmp\n\n    acap-runtime-client:\n        image: \u003cclient app image\u003e\n        environment:\n            - INFERENCE_HOST=unix:///tmp/acap-runtime.sock\n            - INFERENCE_PORT=0\n        volumes:\n          - shared_volume:/tmp\n\n    \u003cany other apps\u003e\n\n    volumes:\n      shared_volume: {}\n```\n\n### Configuration\n\nWhen starting the ACAP Runtime service from command line, as is done with the\ncontainerized version, it accepts the following settings:\n\n```text\n-v                Verbose, enable extended logging,\n-a \u003cIP address\u003e   IP address of gRPC server, default 0.0.0.0. See note1,\n-p \u003cIP port\u003e      IP port of gRPC server, default 0. See note1,\n-t \u003cseconds\u003e      Runtime in seconds (used for test),\n-c \u003cfile name\u003e    Certificate file for TLS authentication. See note2,\n-k \u003cfile name\u003e    Private key file for TLS authentication. See note2,\n-j \u003cchip id\u003e      Chip id used by Machine learning API service. See note3,\n-m \u003cfile name\u003e    Inference model file used by Machine learning API service,\n-o                Override settings from device parameters. This is a legacy flag that should not be used.\n```\n\nNotes.\n\n**(1)** The gRPC server can be set up with either a unix-socket (default) or a\nnetwork socket. To set up as network socket the IP port should be set to a non-zero\nvalue. The IP address is only used when set up as a network socket.\nSee [gRPC](#grpc-socket) for more information.\n\n**(2)** To use TLS a certificate file and a corresponding private key file must\nbe supplied. If either is omitted TLS is not used.\nSee [TLS](#tls) for more information.\n\n**(3)** When using the Machine learning API the chip Id corresponding to the device must\nbe given. See [Chip id](#chip-id) for more information.\n\n#### Chip id\n\nThe Machine learning API uses the [Machine learning API][acap-documentation-native-ml] for image processing\nand to set it up the correct chip id for the device needs to be selected.\nNote that there is no direct correlation between chip id and architecture.\nFor convenience the pre-built images for the ACAP Runtime native application sets\nthe default value for ChipId to 4 for `armv7hf` and 12 for `aarch64`, since those\nare currently the most common ids for the respective architectures.\nSee the table below for a full list of supported values.\n\nIf the value is set to 0 (LAROD_CHIP_INVALID) the Machine learning API inference service will not\nbe started.\n\n| Chip id | Name                          | Description                                |\n|---------|-------------------------------|--------------------------------------------|\n| 0       | LAROD_CHIP_INVALID            | Invalid chip      |\n| 1       | LAROD_CHIP_DEBUG              | Dummy chip for debugging |\n| 4       | LAROD_CHIP_TPU                | Google TPU |\n| 6       | LAROD_CHIP_CVFLOW_NN          | Ambarella CVFlow (NN) |\n| 8       | LAROD_CHIP_TFLITE_GLGPU       | GPU with TensorFlow Lite. WARNING: This is an experimental chip which is subject to change. |\n| 9       | LAROD_CHIP_CVFLOW_PROC        | Ambarella CVFlow (proc) |\n| 10      | LAROD_CHIP_ACE                | Axis Compute Engine |\n| 11      | LAROD_CHIP_LIBYUV             | CPU with libyuv. |\n| 12      | LAROD_CHIP_TFLITE_ARTPEC8DLPU | ARTPEC-8 DLPU with TensorFlow Lite. |\n| 13      | LAROD_CHIP_OPENCL | Image processing using OpenCL |\n\n#### TLS\n\nThe ACAP Runtime service can be run either in TLS authenticated or unsecured mode.\nTLS authenticated mode provides additional security and encryption on the gRPC\nchannel and is the recommended (and default) mode. The service requires a certificate\nfile and a key file to run in TLS authenticated mode.\n\nOne way to generate the certificates is to use the [`openssl req`][openssl-req]\ncommand, e.g.:\n\n```sh\n# generate the files\nopenssl req -x509 \\\n            -batch \\\n            -subj '/CN=localhost' \\\n            -days \u003cdays valid\u003e \\\n            -newkey rsa:4096 \\\n            -nodes \\\n            -out server.pem \\\n            -keyout server.key\n```\n\nWhere `\u003cdays valid\u003e` is the number of days you wish the certificate to be valid.\n\nTo 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:\n\n```sh\ndocker run  -v \u003cHOST_PATH\u003e:/opt/app/certificates \\\n            --entrypoint=\"/opt/app/acap_runtime/acapruntime \\\n                          -k /opt/app/certificates/server.key \\\n                          -c /opt/app/certificates/server.pem\" \\\n            axisecp/acap-runtime:\u003cversion\u003e-\u003cARCH\u003e-containerized\n```\n\nwhere `\u003cHOST_PATH\u003e` is the path on the host system where the certificates are stored.\n\n#### gRPC socket\n\nWith the default settings the ACAP Runtime service will set at a Unix Domain Socket\n(UDS) with the address:\n\n```sh\nunix:///tmp/acap-runtime.sock\n```\n\nThis is suitable for projects that are contained on a device. If a network socket\nis needed instead, this can be done by using the `-a` and `-p` settings.\n\n### Examples\n\nThe following example use the Parameter API with ACAP Runtime as a native\nACAP application:\n\n- [parameter-api-python][parameter-api-python]\n\nThe following example use the ACAP Runtime containerized version to use the\nMachine learning API service:\n\n- [minimal-ml-inference][minimal-ml-inference]\n\n## Building ACAP Runtime\n\nDocker is used to build ACAP Runtime by using the provided Dockerfile. Note that Buildx is used. To build the image run:\n\n```sh\n# Build ACAP Runtime containerized version\ndocker buildx build --file Dockerfile --build-arg ARCH=\u003cARCH\u003e --tag acap-runtime:\u003cARCH\u003e-containerized .\n```\n\nwhere `\u003cARCH\u003e` is either `armv7hf` or `aarch64`.\n\n## Building protofiles for Python\n\nThe 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:\u003cRelease version\u003e-protofiles` image instead of having to build the protofiles themselves.\n\nTo build the protofiles:\n\n```sh\ndocker build -f Dockerfile.proto -t acap-runtime-proto:latest .\n```\n\n## Test suite\n\nThe repo contains a test suite project to verify that ACAP Runtime works as expected\non a supported device. It builds and is executed as a standalone ACAP application\ncalled `Acapruntimetest`.\n\nBuild and install it by running:\n\n```sh\n# Build ACAP Runtime test suite image\ndocker buildx build --file Dockerfile --build-arg ARCH=\u003cARCH\u003e --build-arg TEST=yes --tag acap-runtime:\u003cARCH\u003e-test  --target runtime-base .\n\ndocker run --rm acap-runtime:\u003cARCH\u003e-test \u003cdevice IP\u003e \u003cdevice password\u003e install\n```\n\nwhere `\u003cARCH\u003e` is either `armv7hf` or `aarch64` and `\u003cdevice IP\u003e` and `\u003cdevice password\u003e`\nare the IP and root password of the device in use.\n\nThe application can be started, stopped and eventually uninstalled in the **Apps**\ntab in the device GUI or by running:\n\n```sh\ndocker run --rm acap-runtime:\u003cARCH\u003e-test \u003cdevice IP\u003e \u003cdevice password\u003e start|stop|remove\n```\n\nTo see the test run output, check the application log either by clicking on the\n**App log** link in the device GUI, or directly at:\n\n```sh\nhttp://\u003cdevice IP\u003e/axis-cgi/admin/systemlog.cgi?appname=acapruntimetest\n```\n\nIf the tests pass the log should end with \\[  PASSED  ]. If any test fails, it\nwill be listed.\n\n## Contributing\n\nTake a look at the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n## License\n\n[Apache 2.0](LICENSE)\n\n\u003c!-- Links to external references --\u003e\n\u003c!-- markdownlint-disable MD034 --\u003e\n[1.3.1-release]: https://github.com/AxisCommunications/acap-runtime/releases/tag/1.3.1\n[acap-documentation]: https://axiscommunications.github.io/acap-documentation/docs/introduction/what-is-acap.html\n[acap-documentation-native]: https://axiscommunications.github.io/acap-documentation/docs/introduction/acap-sdk-overview.html#acap-native-sdk\n[acap-documentation-native-ml]: https://axiscommunications.github.io/acap-documentation/docs/api/native-sdk-api.html#machine-learning-api\n[acap-documentation-cv]: https://axiscommunications.github.io/acap-documentation/docs/introduction/acap-sdk-overview.html#acap-computer-vision-sdk\n[acap-documentation-acap-runtime]: https://axiscommunications.github.io/acap-documentation/docs/api/computer-vision-sdk-apis.html#beta---acap-runtime\n[buildx]: https://docs.docker.com/build/install-buildx/\n[docker-acap]: https://github.com/AxisCommunications/docker-acap\n[docker-compose-acap]: https://github.com/AxisCommunications/docker-compose-acap\n[docker-hub-acap-runtime]: https://hub.docker.com/r/axisecp/acap-runtime\n[dockerDesktop]: https://docs.docker.com/desktop/\n[dockerEngine]: https://docs.docker.com/engine/\n[gRPC]: https://grpc.io/\n[latest-release]: https://github.com/AxisCommunications/acap-runtime/releases/latest\n[minimal-ml-inference]: https://github.com/AxisCommunications/acap-computer-vision-sdk-examples/tree/main/minimal-ml-inference\n[openssl-req]: https://www.openssl.org/docs/man3.0/man1/openssl-req.html\n[object-detector-python]: https://github.com/AxisCommunications/acap-computer-vision-sdk-examples/tree/main/object-detector-python\n[parameter-api-python]: https://github.com/AxisCommunications/acap-computer-vision-sdk-examples/tree/main/parameter-api-python\n[tensorflow]: https://github.com/tensorflow/serving\n\n\u003c!-- markdownlint-enable MD034 --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxiscommunications%2Facap-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxiscommunications%2Facap-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxiscommunications%2Facap-runtime/lists"}