Skip to content

Commit 165a61a

Browse files
alexadereykoalexadereyko
committed
<TBBAS-2538> Add README for project and GitHub Actions
- Project README: overview, build/test instructions, openDAQ integration notes - framework-latest-release: inputs, outputs, usage - framework-download: inputs, usage - framework-install: inputs, usage, OS-specific install details
1 parent e4c5bb2 commit 165a61a

File tree

7 files changed

+332
-8
lines changed

7 files changed

+332
-8
lines changed

‎.github/actions/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# GitHub Reusable Actions for openDAQ Framework
2+
3+
This directory contains **reusable GitHub Actions** used to work with the **openDAQ framework**.
4+
The actions support determining the latest or specific release, downloading it from S3, and installing it on Linux or Windows runners.
5+
6+
---
7+
8+
## Actions Overview
9+
10+
| Action | Description | Inputs | Outputs |
11+
|--------|-------------|--------|---------|
12+
| [framework-latest-release](./framework-latest-release/README.md) | Determines which openDAQ framework package to use (latest release or specific version). | `opendaq-framework-release-version`, `win32-force` | `version`, `platform`, `packaging`, `artefact`, `uri`, `scheme`, `authority`, `path` |
13+
| [framework-download](./framework-download/README.md) | Downloads the resolved openDAQ framework package from AWS S3. | `src-opendaq-framework-dev`, `dst-opendaq-framework-dev`, `aws_access_key_id`, `aws_secret_access_key`, `aws_region` | None |
14+
| [framework-install](./framework-install/README.md) | Installs the downloaded openDAQ framework package on the runner. | `opendaq-framework-package-filename`, `opendaq-framework-package-path` | None |
15+
16+
---
17+
18+
## Recommended Usage
19+
20+
A typical workflow combining all three actions:
21+
22+
```yaml
23+
jobs:
24+
build:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout repo
28+
uses: actions/checkout@v4
29+
30+
- name: Resolve openDAQ framework version
31+
id: framework
32+
uses: ./.github/actions/framework-latest-release
33+
with:
34+
opendaq-framework-release-version: latest
35+
36+
- name: Download openDAQ framework
37+
uses: ./.github/actions/framework-download
38+
with:
39+
src-opendaq-framework-dev: ${{ steps.framework.outputs.uri }}
40+
aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
41+
aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
42+
aws_region: ${{ secrets.AWS_REGION }}
43+
44+
- name: Install openDAQ framework
45+
uses: ./.github/actions/framework-install
46+
with:
47+
opendaq-framework-package-filename: ${{ steps.framework.outputs.artefact }}
48+
```
49+
50+
## Notes
51+
52+
- Linux and Windows runners are supported.
53+
- framework-latest-release requires GitHub CLI (gh) and jq.
54+
- framework-download requires AWS CLI.
55+
- framework-install installs differently depending on OS.

‎.github/actions/framework-download/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# framework-download
2+
3+
This composite action downloads an **openDAQ framework package** from **AWS S3** to the runner.
4+
It supports both Linux/macOS and Windows runners.
5+
6+
---
7+
8+
## Inputs
9+
10+
| Name | Required | Default | Description |
11+
|-----------------------------|----------|---------------------|-------------|
12+
| `src-opendaq-framework-dev` | yes | — | Full S3 URI to the package (e.g. `s3://bucket/releases/v3.20.4/SDK/opendaq-3.20.4-win64.exe`). |
13+
| `dst-opendaq-framework-dev` | no | `${{ runner.temp }}`| Destination path for the downloaded package on the runner. |
14+
| `aws_access_key_id` | yes | — | AWS Access Key ID used for authentication. |
15+
| `aws_secret_access_key` | yes | — | AWS Secret Access Key used for authentication. |
16+
| `aws_region` | yes | — | AWS Region where the bucket is located. |
17+
18+
---
19+
20+
## Example usage
21+
22+
```yaml
23+
jobs:
24+
download:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
30+
- name: Download openDAQ framework
31+
uses: ./.github/actions/framework-download
32+
with:
33+
src-opendaq-framework-dev: "s3://bb-blueberry-sdk-releases/releases/v3.20.4/SDK/opendaq-3.20.4-ubuntu22.04-x86_64.deb"
34+
dst-opendaq-framework-dev: "/tmp/opendaq-3.20.4-ubuntu22.04-x86_64.deb"
35+
aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
36+
aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
37+
aws_region: ${{ secrets.AWS_REGION }}
38+
```
39+
40+
## Notes
41+
- Uses aws-actions/configure-aws-credentials to set up credentials.
42+
- Downloads via aws s3 cp, which must be available in the runner environment.
43+
- On GitHub-hosted runners, the AWS CLI is pre-installed.
44+
- Supports Linux/macOS (bash) and Windows (pwsh) runners.
45+
- Destination path must be writable by the runner.

‎.github/actions/framework-install/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# framework-install
2+
3+
This composite action installs an **openDAQ framework package** on the runner.
4+
It supports **Windows (installer executable)** and **Linux (Debian package)**.
5+
Other operating systems are not supported.
6+
7+
---
8+
9+
## Inputs
10+
11+
| Name | Required | Default | Description |
12+
|-----------------------------------|----------|---------------------|-------------|
13+
| `opendaq-framework-package-filename` | yes | — | Name of the package file (e.g. `opendaq-3.20.4-win64.exe`, `opendaq-3.20.4-ubuntu22.04-x86_64.deb`). |
14+
| `opendaq-framework-package-path` | no | `${{ runner.temp }}`| Directory where the package file is located. |
15+
16+
---
17+
18+
## Example usage
19+
20+
```yaml
21+
jobs:
22+
install:
23+
runs-on: windows-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
28+
- name: Install openDAQ framework
29+
uses: ./.github/actions/framework-install
30+
with:
31+
opendaq-framework-package-filename: "opendaq-3.20.4-win64.exe"
32+
opendaq-framework-package-path: "C:\\actions\\temp"
33+
```
34+
```yml
35+
jobs:
36+
install:
37+
runs-on: ubuntu-latest
38+
steps:
39+
- name: Checkout
40+
uses: actions/checkout@v4
41+
42+
- name: Install openDAQ framework
43+
uses: ./.github/actions/framework-install
44+
with:
45+
opendaq-framework-package-filename: "opendaq-3.20.4-ubuntu22.04-x86_64.deb"
46+
opendaq-framework-package-path: "/tmp"
47+
```
48+
49+
## Notes
50+
- Windows:
51+
- Runs the installer in silent mode (/S).
52+
- After installation, updates the PATH environment variable to include:
53+
```powershell
54+
PATH=C:\Program Files\openDAQ\bin;$PATH
55+
```
56+
- Linux:
57+
- Installs the package via dpkg -i.
58+
- Requires sudo access on the runner.
59+
- Unsupported OS:
60+
- The action exits with an error for macOS or other platforms.

‎.github/actions/framework-latest-release/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# framework-latest-release
2+
3+
This composite action determines the **openDAQ framework package** to use.
4+
It supports resolving either the **latest release** from GitHub or a **specific version** provided as input,
5+
and outputs all required information to download and install the package.
6+
7+
---
8+
9+
## Inputs
10+
11+
| Name | Required | Default | Description |
12+
|-------------------------------------|----------|---------|-------------|
13+
| `opendaq-framework-release-version` | no | `latest`| openDAQ framework version. Use `latest` for the newest release, or provide a specific version (e.g. `3.20.4`). |
14+
| `win32-force` | no | `false` | On Windows runners, forces `win32` instead of `win64` platform. |
15+
16+
---
17+
18+
## Outputs
19+
20+
| Name | Description |
21+
|------------|-------------|
22+
| `version` | Resolved openDAQ release version (e.g. `3.20.4`). |
23+
| `platform` | Detected platform string (`ubuntu22.04-x86_64`, `ubuntu22.04-arm64`, `win32`, `win64`). |
24+
| `packaging`| Package type (`deb` on Linux, `exe` on Windows). |
25+
| `artefact` | Resolved artefact filename (e.g. `opendaq-3.20.4-win64.exe`). |
26+
| `scheme` | URI scheme (currently `s3`). |
27+
| `authority`| Storage authority (S3 bucket name). |
28+
| `path` | Path inside the bucket (e.g. `releases/v3.20.4/SDK`). |
29+
| `uri` | Full URI to the artefact (e.g. `s3://bucket/releases/v3.20.4/SDK/opendaq-3.20.4-win64.exe`). |
30+
31+
---
32+
33+
## Example usage
34+
35+
```yaml
36+
jobs:
37+
build:
38+
runs-on: ubuntu-latest
39+
steps:
40+
- name: Checkout
41+
uses: actions/checkout@v4
42+
43+
- name: Determine openDAQ framework package
44+
id: framework
45+
uses: ./.github/actions/framework-latest-release
46+
with:
47+
opendaq-framework-release-version: latest
48+
49+
- name: Print resolved artefact info
50+
run: |
51+
echo "Version: ${{ steps.framework.outputs.version }}"
52+
echo "Platform: ${{ steps.framework.outputs.platform }}"
53+
echo "Artefact: ${{ steps.framework.outputs.artefact }}"
54+
echo "URI: ${{ steps.framework.outputs.uri }}"
55+
```
56+
57+
## Notes
58+
- The action relies on GitHub CLI (gh) and jq.
59+
- These are pre-installed on GitHub-hosted Ubuntu and Windows runners.
60+
- On Windows, if you explicitly need a 32-bit package, set win32-force: true.
61+
- If the latest release cannot be determined, the action fails.

‎.github/workflows/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
## CI/CD Workflows
2+
3+
- [Build and Test Simple Device Module](ci.md)
4+
Builds and tests against openDAQ framework (latest or specific version).

‎.github/workflows/ci.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Build and Test Simple Device Module with openDAQ Framework
2+
3+
This workflow builds and tests the **Simple Device Module** using the **openDAQ framework**.
4+
It supports using either the **latest release** of openDAQ or a **specific version** provided as input.
5+
6+
## Triggers
7+
8+
- **push** to `main`
9+
- **pull_request** targeting `main` or `jira/*`
10+
- **workflow_dispatch** (manual run with parameters)
11+
12+
## Inputs (workflow_dispatch)
13+
14+
| Name | Type | Required | Default | Description |
15+
|-----------------------------|--------|----------|---------|-------------|
16+
| `branch` | string | no | `main` | Branch to checkout |
17+
| `opendaq-framework-version` | string | no | `latest`| openDAQ framework version. Use `latest` for the newest release, or provide a specific version tag (e.g. `3.20.4`). |
18+
19+
## Matrix
20+
21+
The workflow runs on:
22+
23+
- `ubuntu-latest` (CMake + Ninja)
24+
- `windows-latest` (CMake + Visual Studio 17 2022)
25+
26+
## Jobs and Steps
27+
28+
1. **Checkout Simple Device Module repo** — fetches the specified branch.
29+
2. **Determine openDAQ framework package**
30+
- If `opendaq-framework-version` is `latest`, the workflow queries GitHub Releases for the newest version.
31+
- If a version string is provided, that version is used directly.
32+
3. **Download openDAQ framework** — fetches the package (from S3).
33+
4. **Install openDAQ framework package** — installs the framework.
34+
5. **Configure with CMake** — configures the project with the appropriate generator.
35+
6. **Build with CMake** — builds the project.
36+
7. **Run tests** — executes unit tests with CTest.
37+
38+
## Examples
39+
40+
### Automatic runs
41+
- On push to `main`
42+
- On pull request to `main` or `jira/*`
43+
44+
### Manual run
45+
```yaml
46+
workflow_dispatch:
47+
inputs:
48+
branch: "feature/my-branch"
49+
opendaq-framework-version: "3.20.4"
50+
```

‎README.md‎

Lines changed: 57 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,63 @@
1-
# Example device module
1+
# SimpleDeviceModule
22

3-
Simple example that builds an openDAQ module giving access to an example device. Said device contains 2 channels, each with a value and time signal. The value signal outputs a counter signal, increasing at a rate of 1 per second.
3+
**SimpleDeviceModule** is an example module demonstrating how to build and test a simple device module using the **openDAQ framework**.
4+
This repository can serve as a template for building other modules integrated with openDAQ.
45

5-
## Testing the module
6+
---
67

7-
To test the module, enable the `OPENDAQ_DEVICE_EXAMPLE_ENABLE_SERVER_APP` cmake flag. Doing so will add an openDAQ native server module to your build targets, and add an additional "server_application" executable. Running the executable will create a device, add an openDAQ server, and enable discovery.
8+
## Prerequisites
89

9-
To connect to the device, the openDAQ Python GUI application can be used (Latest Python version is recommended):
10+
- **CMake** (>= 3.25)
11+
- **Git**
12+
- **C++ compiler** (Visual Studio on Windows, GCC/Clang on Linux/macOS)
13+
- Optional: **openDAQ framework** installed locally or available via versioned checkout
1014

15+
---
16+
17+
## Building the Project
18+
19+
There are two main ways to provide the openDAQ framework:
20+
21+
1. **Using a local openDAQ installation**
22+
- Install the openDAQ package on your machine.
23+
- Set the environment variable `OPENDAQ_ROOT` to the path containing the binaries.
24+
- Then CMake will automatically detect the binaries during configuration.
25+
26+
```bash
27+
export OPENDAQ_ROOT=/path/to/opendaq
28+
29+
cmake -S . -B build/output \
30+
-G "Ninja" \
31+
-DEXAMPLE_MODULE_ENABLE_TESTS=ON \
32+
-DSIMPLE_DEVICE_MODULE_OPENDAQ_SDK_VER=3.20.4
33+
```
34+
35+
2. **Using a specific openDAQ version via CMake**
36+
- Pass the desired version using the `SIMPLE_DEVICE_MODULE_OPENDAQ_SDK_VER`.
37+
- CMake will perform a checkout of the openDAQ repository at the specified tag and build the minimal set of binaries needed to build the module and run tests.
38+
39+
```bash
40+
cmake -S . -B build/output \
41+
-G "Ninja" \
42+
-DEXAMPLE_MODULE_ENABLE_TESTS=ON \
43+
-DSIMPLE_DEVICE_MODULE_OPENDAQ_SDK_VER=3.20.4
44+
```
45+
46+
---
47+
48+
### Example: Build Module
49+
50+
```bash
51+
cmake --build build/output --config Release
52+
```
53+
54+
#### Note:
55+
- The flag `EXAMPLE_MODULE_ENABLE_TESTS=ON` is required if you want to build the module tests for subsequent execution.
56+
- Building the module without `EXAMPLE_MODULE_ENABLE_TESTS=ON` will skip test compilation.
57+
- Providing either `OPENDAQ_ROOT` or `SIMPLE_DEVICE_MODULE_OPENDAQ_SDK_VER` is mandatory for the module to find the required binaries.
58+
59+
### Running Tests
60+
Once the build is complete:
61+
```bash
62+
ctest --test-dir build/output --output-on-failure -C Release -V
1163
```
12-
py -m pip install openDAQ
13-
py -m openDAQ
14-
```

0 commit comments

Comments
 (0)