Skip to content

Commit ecb3daf

Browse files
VieshothVieshoth NavaratnamStiv-work
authored and
johan-hultberg-work
committed
Datahub
Co-authored-by: Vieshoth Navaratnam <vieshotn@axis.com> Co-authored-by: Stiv Abdullwahed <stiva@axis.com>
1 parent d99fcb2 commit ecb3daf

29 files changed

Lines changed: 2375 additions & 0 deletions

File tree

‎.github/workflows/device-data-hub.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Build device-data-hub applications
2+
on:
3+
workflow_dispatch:
4+
push:
5+
paths:
6+
- 'device-data-hub/**'
7+
- '!device-data-hub/README.md'
8+
- '.github/workflows/device-data-hub.yml'
9+
jobs:
10+
test-app:
11+
name: Test app
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
axis-os: ["12.10.68"]
17+
arch: ["armv7hf", "aarch64"]
18+
env:
19+
EXREPO: acap-native-examples
20+
EXNAME: device-data-hub
21+
steps:
22+
- uses: actions/checkout@v6
23+
- uses: docker/setup-buildx-action@v3
24+
25+
- name: Build ${{ env.example }} application
26+
env:
27+
example: object-detector
28+
imagetag: ${{ env.EXREPO }}_object-detector:${{ matrix.arch }}
29+
run: |
30+
docker image rm -f $imagetag
31+
cd $EXNAME/acap-communication/$example
32+
docker build --no-cache --tag $imagetag --build-arg ARCH=${{ matrix.arch }} .
33+
docker cp $(docker create $imagetag):/opt/app ./build
34+
cd ../../..
35+
docker image rm -f $imagetag
36+
37+
- name: Build ${{ env.example }} application
38+
env:
39+
example: object-consumer
40+
imagetag: ${{ env.EXREPO }}_object-consumer:${{ matrix.arch }}
41+
run: |
42+
docker image rm -f $imagetag
43+
cd $EXNAME/acap-communication/$example
44+
docker build --no-cache --tag $imagetag --build-arg ARCH=${{ matrix.arch }} .
45+
docker cp $(docker create $imagetag):/opt/app ./build
46+
cd ../../..
47+
docker image rm -f $imagetag
48+
49+
- name: Build ${{ env.example }} application
50+
env:
51+
example: consume-scene-metadata
52+
imagetag: ${{ env.EXREPO }}_consume-scene-metadata:${{ matrix.arch }}
53+
run: |
54+
docker image rm -f $imagetag
55+
cd $EXNAME/$example
56+
docker build --no-cache --tag $imagetag --build-arg ARCH=${{ matrix.arch }} .
57+
docker cp $(docker create $imagetag):/opt/app ./build
58+
cd ../..
59+
docker image rm -f $imagetag
60+
61+
- name: Build ${{ env.example }} application
62+
env:
63+
example: memory-cpu-utilization
64+
imagetag: ${{ env.EXREPO }}_memory-cpu-utilization:${{ matrix.arch }}
65+
run: |
66+
docker image rm -f $imagetag
67+
cd $EXNAME/$example
68+
docker build --no-cache --tag $imagetag --build-arg ARCH=${{ matrix.arch }} .
69+
docker cp $(docker create $imagetag):/opt/app ./build
70+
cd ../..
71+
docker image rm -f $imagetag

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,8 @@ The examples are organized into logical groups to help you find the most relevan
124124
- An example in C that illustrates how to check the licensekey status.
125125
- [message-broker](./message-broker/)
126126
- Examples that showcase how to use the Message Broker API.
127+
- [device-data-hub](./device-data-hub/)
128+
- Examples that showcase how to use the Device Data Hub API (https://developer.axis.com/acap/api/#device-data-hub-api).
127129
- [reproducible-package](./reproducible-package/)
128130
- An example of how to create a reproducible application package.
129131
- [shell-script-example](./shell-script-example)

‎device-data-hub/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Axis Communications AB
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎device-data-hub/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
*Copyright (C) 2026, Axis Communications AB, Lund, Sweden. All Rights Reserved.*
2+
3+
# ACAP applications using the Device Data Hub API
4+
5+
This directory contains ACAP application examples that interact with the [Device Data Hub API] (https://developer.axis.com/acap/api/#device-data-hub-api).
6+
7+
## About the Device Data Hub API
8+
9+
Device Data Hub is a publish/subscribe system in AXIS OS. It uses a model which focuses on the data as
10+
the primary element of interaction. This model enables asynchronous communication and decoupling
11+
of producers and consumers. Device Data Hub is not intended to be used for streaming binary data.
12+
13+
An example of a real-world scenario where Device Data Hub would be used is when clients are interested in
14+
information on objects detected by the camera. Information such as object type, position, shape
15+
and color can be published on Device Data Hub, and clients interested in this type of information can
16+
subscribe on Device Data Hub to get this information.
17+
18+
## Example applications
19+
20+
Each example has a README file in its directory which gives an introduction to the
21+
example, shows the directory structure and gives step-by-step instructions on how
22+
to run the application on an Axis device.
23+
24+
- [ACAP Communication](./acap-communication/README.md)
25+
- This example consists of two applications that communicate with each other.
26+
- [Consume Scene Metadata](./consume-scene-metadata/README.md)
27+
- This example subscribes to an object track topic and prints the scene metadata.
28+
- [Memory and CPU Utilization](./memory-cpu-utilization/README.md)
29+
- This example subscribes to two topics and prints the memory and CPU utilization.
30+
31+
## Device Data Hub API documentation
32+
33+
[Device Data Hub API](https://developer.axis.com/acap/api/#device-data-hub-api)
34+
35+
## License
36+
37+
**[MIT License](./LICENSE)**

‎device-data-hub/acap-communication/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
*Copyright (C) 2026, Axis Communications AB, Lund, Sweden. All Rights Reserved.*
2+
3+
# Asynchronous communication between two applications
4+
5+
This is an example that shows the communication between two applications written using the [Device Data Hub API](https://developer.axis.com/acap/api/#device-data-hub-api), one that
6+
writes data to a topic and another that receives the data written to the topic. The two
7+
applications in this example are *object_detector* and *object_consumer*.
8+
9+
## Introduction
10+
11+
The purpose of this example is to show the communication between two applications that
12+
use the Device Data Hub API. The application *object_detector* will create a topic and then
13+
write data to the topic if there are any consumers. The application *object_consumer*
14+
will subscribe to the topic and print the received data to the system log.
15+
16+
[Link to *object_detector*](./object-detector/README.md)
17+
18+
[Link to *object_consumer*](./object-consumer/README.md)
19+
20+
## How to run this example
21+
22+
1. First, read and build [object_detector](./object-detector/README.md) - this creates the topic and publishes data.
23+
2. Then, read and build [object_consumer](./object-consumer/README.md) - this subscribes and receives data.
24+
3. Install both applications on the same Axis device.
25+
4. Start the applications.
26+
27+
## Directory structure
28+
29+
The files for building the example are organized in the following structure.
30+
31+
```sh
32+
acap-communication
33+
├── object-consumer
34+
│ ├── app
35+
│ │ ├── LICENSE
36+
│ │ ├── Makefile
37+
│ │ ├── manifest.json
38+
│ │ └── object_consumer.c
39+
│ ├── Dockerfile
40+
│ └── README.md
41+
├── object-detector
42+
│ ├── app
43+
│ │ ├── LICENSE
44+
│ │ ├── Makefile
45+
│ │ ├── manifest.json
46+
│ │ └── object_detector.c
47+
│ ├── Dockerfile
48+
│ └── README.md
49+
└── README.md
50+
```
51+
52+
- **object-consumer/app/LICENSE** - Open source licensed source code distributed with the specified application.
53+
- **object-consumer/app/Makefile** - Build and link instructions for the specified application.
54+
- **object-consumer/app/manifest.json** - Definition of the *object_consumer* application and its configuration.
55+
- **object-consumer/app/object_consumer.c** - Source code for the *object_consumer* application.
56+
- **object-consumer/Dockerfile** - Dockerfile with the specified Axis toolchain and API container to build the application specified.
57+
- **object-consumer/README.md** - Step by step instructions on how to run the *object_consumer* application.
58+
- **object-detector/app/LICENSE** - Open source licensed source code distributed with the specified application.
59+
- **object-detector/app/Makefile** - Build and link instructions for the specified application.
60+
- **object-detector/app/manifest.json** - Definition of the *object_detector* application and its configuration.
61+
- **object-detector/app/object_detector.c** - Source code for the *object_detector* application.
62+
- **object-detector/Dockerfile** - Dockerfile with the specified Axis toolchain and API container to build the application specified.
63+
- **object-detector/README.md** - Step by step instructions on how to run the *object_detector* application.
64+
- **README.md** - Information about the *acap-communication example*.
65+
66+
## License
67+
68+
**[MIT License](../LICENSE)**

‎device-data-hub/acap-communication/object-consumer/Dockerfile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
ARG ARCH=armv7hf
2+
ARG VERSION=12.10.0
3+
ARG UBUNTU_VERSION=24.04
4+
ARG REPO=axisecp
5+
ARG SDK=acap-native-sdk
6+
7+
FROM ${REPO}/${SDK}:${VERSION}-${ARCH}-ubuntu${UBUNTU_VERSION}
8+
9+
# Build the ACAP application
10+
COPY ./app /opt/app/
11+
WORKDIR /opt/app
12+
RUN . /opt/axis/acapsdk/environment-setup* && acap-build .

‎device-data-hub/acap-communication/object-consumer/README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
*Copyright (C) 2026, Axis Communications AB, Lund, Sweden. All Rights Reserved.*
2+
3+
# ACAP application that subscribes to Device Data Hub
4+
5+
This application subscribes to a topic using the [Device Data Hub API](https://developer.axis.com/acap/api/#device-data-hub-api) created by another application and logs the received data.
6+
It is part of the acap-communication example. For context, start by reading the README for the object_detector application.
7+
8+
## Project structure
9+
10+
The files for building the application are organized in the following structure.
11+
12+
```sh
13+
object-consumer
14+
├── app
15+
│ ├── LICENSE
16+
│ ├── Makefile
17+
│ ├── manifest.json
18+
│ └── object_consumer.c
19+
├── Dockerfile
20+
└── README.md
21+
```
22+
23+
- **app/LICENSE** - Open source licensed source code distributed with the specified application.
24+
- **app/Makefile** - Build and link instructions for the specified application.
25+
- **app/manifest.json** - Definition of the *object_consumer* application and its configuration.
26+
- **app/object_consumer.c** - Source code for the *object_consumer* application.
27+
- **Dockerfile** - Dockerfile with the specified Axis toolchain and API container to build the application specified.
28+
- **README.md** - Step by step instructions on how to run the *object_consumer* application.
29+
30+
## Program structure and behavior
31+
32+
### Connecting to Device Data Hub
33+
34+
The application creates a Device Data Hub client and connects to the service. The `dh_client_connect` function uses the current Linux user as the username, which in this case is *acap-object_consumer*.
35+
36+
### Subscribing to a topic
37+
38+
The application creates a `DHSubscriber` to subscribe to *acap.object_detector*.
39+
The functions of `DHSubscriberListener` listener struct handles incoming data by logging it.
40+
41+
> [!NOTE]
42+
> You can subscribe to topics that don't exist yet. Data will arrive once the topic is created and
43+
> published to.
44+
45+
## Access rights
46+
47+
By default, an ACAP application can only access its own topics (prefixed with `acap.<appname>`) and
48+
public topics. Since *acap.object_detector* belongs to another application, this application needs
49+
permission to read from it.
50+
51+
The *object_detector* application grants this permission in its manifest,
52+
giving *acap-object_consumer* read access to *acap.object_detector* and all sub-topics.
53+
54+
## The manifest
55+
56+
To be able to connect to Device Data Hub, enable Device Data Hub in the manifest:
57+
58+
```json
59+
"resources": {
60+
"deviceDataHub_beta2": {
61+
"enabled": true
62+
}
63+
}
64+
```
65+
66+
The application will get access rights to create, delete, write to and subscribe to the topic
67+
*acap.object_consumer* and all topics that have this topic as a prefix. However, this
68+
application never creates any such topic. Instead, the application subscribes to the topic
69+
*acap.object_detector*. The access rights to read data from that topic is given to this
70+
application by the *object_detector* application.
71+
72+
## Build the application
73+
74+
> [!NOTE]
75+
>
76+
> For detailed information on how to build, install, and run ACAP applications, refer to the official ACAP documentation: [Build, install, and run](https://developer.axis.com/acap/develop/build-install-run/).
77+
>
78+
> Depending on the network your local build machine is connected to, you may need to add proxy
79+
> settings for Docker. See
80+
> [Proxy in build time](https://developer.axis.com/acap/develop/proxy/#proxy-in-build-time).
81+
82+
Standing in your working directory, run the following commands:
83+
84+
```sh
85+
docker build --platform=linux/amd64 --build-arg ARCH=<ARCH> --tag <APP_IMAGE> .
86+
```
87+
88+
- `<ARCH>` is the SDK architecture, `armv7hf` or `aarch64`.
89+
- `<APP_IMAGE>` is the name to tag the image with, e.g., `consumer:1.0`
90+
91+
Copy the result from the container image to a local directory `build`:
92+
93+
```sh
94+
docker cp $(docker create --platform=linux/amd64 <APP_IMAGE>):/opt/app ./build
95+
```
96+
97+
The `build` directory contains the build artifacts, where the ACAP application
98+
is found with the suffix `.eap`. Depending on which SDK architecture that was
99+
chosen, one of the following files should be found:
100+
101+
- `object_consumer_1_0_0_aarch64.eap`
102+
- `object_consumer_1_0_0_armv7hf.eap`
103+
104+
## Install and start the application
105+
106+
Browse to the application page of the Axis device:
107+
108+
```sh
109+
http://<AXIS_DEVICE_IP>/index.html#apps
110+
```
111+
112+
- Click on the tab `Apps` in the device GUI
113+
- Enable `Allow unsigned apps` toggle
114+
- Click `(+ Add app)` button to upload the application file
115+
- Browse to the newly built ACAP application, and select it
116+
- Click `Install`
117+
- Run the application by enabling the `Start` switch
118+
119+
## Expected output
120+
121+
To find the application log, browse to the *Apps* page, click on the
122+
three dots to the right of the application and select `App log`.
123+
124+
If the *object_detector* application has also started, you will see
125+
messages about the received data in the log. Each message contains an object
126+
(human, bird or dog) and a distance.
127+
128+
The log output may look like this:
129+
130+
```text
131+
[log prefix] object_consumer[429721]: Application started
132+
[log prefix] Received Object Detection data: {"distance":99,"object":"human"}
133+
[log prefix] Received Object Detection data: {"distance":105,"object":"bird"}
134+
[log prefix] Received Object Detection data: {"distance":102,"object":"dog"}
135+
[log prefix] Received Object Detection data: {"distance":98,"object":"human"}
136+
[log prefix] Received Object Detection data: {"distance":110,"object":"bird"}
137+
[log prefix] Received Object Detection data: {"distance":104,"object":"dog"}
138+
[log prefix] object_consumer[429721]: Application terminated
139+
```
140+
141+
## License
142+
143+
**[MIT License](./app/LICENSE)**

‎device-data-hub/acap-communication/object-consumer/app/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Axis Communications AB
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)