Merge remote-tracking branch 'origin/master'

.github/workflows/build_webclient.yml

@@ -9,10 +9,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # alias v3
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
         with:
           ref: ${{ github.event.pull_request.head.ref }}
-      - uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # alias v3
+      - uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
         with:
           node-version: '14'
       - run: npm install

.github/workflows/ci-build.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
     - name: Set up JDK 17
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 # v4.0.0
       with:
         java-version: '17'
         distribution: 'temurin'
@@ -25,6 +25,6 @@ jobs:
     # Optional: Uploads the full dependency graph to GitHub to improve the quality of Dependabot alerts this repository can receive
     - name: Update dependency graph
       continue-on-error: true
-      uses: advanced-security/[email protected].2
+      uses: advanced-security/maven-dependency-submission-action@fcd7eab6b6d22946badc98d1e62665cdee93e0ae # v3.0.3
       with:
         directory: '/'

.github/workflows/eclipse_ip.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-    - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
     - name: Set up JDK 17
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 # v4.0.0
       with:
         java-version: '17'
         distribution: 'temurin'

.github/workflows/format.yml

@@ -13,11 +13,11 @@ jobs:
     runs-on: 'ubuntu-latest'
     steps:
     - name: Checkout PR head branch
-      uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       with:
         fetch-depth: 0
     - name: Editor Config Validation against PR base commit
-      uses: github/super-linter/slim@v5
+      uses: github/super-linter/slim@962a6409c1b303d0e53a9d34ada577a0362f4fae # v5.2.1
       env:
         VALIDATE_ALL_CODEBASE: false
         VALIDATE_EDITORCONFIG: true

.github/workflows/license.yml

@@ -14,8 +14,8 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Check License Header
-        uses: apache/skywalking-eyes@main      # always prefer to use a revision instead of `main`.
+        uses: apache/skywalking-eyes@6b2529214f6b1ccee3ec92bb0adfeabf6f66f538 # v0.5.0
         env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # needed only when you want License-Eye to comment on the pull request.https://github.com/eclipse/org.eclipse.sensinact.gateway/tree/future/prototype/prototype

.licenserc.yaml

@@ -49,6 +49,7 @@ header:
     - '.github/**'
     - '.gitignore'
     - '.licenserc.yaml'
+    - '.readthedocs.yaml'
     - '**/.project'
     - '**/*.prefs'
     - 'license.templates'

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+formats:
+  - pdf
+  - htmlzip
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

distribution/features/jakarta-rest-whiteboard-feature/pom.xml

@@ -27,7 +27,7 @@
     <hk2.osgi.version>1.0.3</hk2.osgi.version>
     <jackson.version>2.13.4</jackson.version>
     <jersey.version>3.0.8</jersey.version>
-    <asm.version>9.3</asm.version>
+    <asm.version>9.6</asm.version>
     <javassist.version>3.29.2-GA</javassist.version>
   </properties>
 

distribution/features/jakarta-rest-whiteboard-feature/src/main/resources/jakarta-rest-whiteboard-feature.json

@@ -25,7 +25,7 @@
     { "id": "org.glassfish.hk2:osgi-resource-locator:1.0.3" },
     { "id": "org.glassfish.hk2:hk2-utils:3.0.3" },
     { "id": "org.javassist:javassist:3.29.2-GA" },
-    { "id": "org.ow2.asm:asm:9.3" }
+    { "id": "org.ow2.asm:asm:9.6" }
   ],
   "extensions": {
     "sensinact.feature.depends": {

docs/docker-build.sh

@@ -26,15 +26,25 @@ else
     formats="$@"
 fi
 
-# Run the container and let it sleep
-echo "Starting container..."
-CID=$(docker run --rm -d -it -v "${PWD}:/docs" -w /docs --entrypoint sleep sphinxdoc/sphinx inf)
+CID=sensiNact-docs-build-v1
 
-# Install requirements
-echo "Install requirements..."
-docker exec "$CID" apt update
-docker exec "$CID" apt install -y git
-docker exec "$CID" python -m pip install -r requirements.txt
+echo "Checking for existing $CID container..."
+
+if docker container inspect "$CID" > /dev/null 2>&1;
+then
+    echo "Reusing $CID container..."
+    docker start "$CID"
+else
+    # Run the container and let it sleep
+    echo "Creating $CID container..."
+    docker run --name "$CID" -d -it -v "${PWD}:/docs" -w /docs --entrypoint sleep sphinxdoc/sphinx inf
+
+    # Install requirements
+    echo "Install requirements..."
+    docker exec "$CID" apt update
+    docker exec "$CID" apt install -y git
+    docker exec "$CID" python -m pip install -r requirements.txt
+fi
 
 # Clear output directory
 echo "Clean up..."
@@ -48,4 +58,5 @@ do
 done
 
 # Clean up
-docker rm -f "$CID"
+echo "Stopping $CID container..."
+docker stop --signal SIGKILL "$CID" > /dev/null 2>&1

docs/requirements.txt

@@ -1,32 +1,32 @@
-alabaster==0.7.13
-Babel==2.12.1
-beautifulsoup4==4.12.2
-certifi==2023.7.22
-charset-normalizer==3.2.0
-colorama==0.4.6
-docutils==0.20.1
-idna==3.4
-imagesize==1.4.1
-Jinja2==3.1.2
-markdown-it-py==3.0.0
-MarkupSafe==2.1.3
-mdit-py-plugins==0.4.0
-mdurl==0.1.2
-myst-parser==2.0.0
-packaging==23.1
-piccolo-theme==0.17.0
-Pygments==2.16.1
-PyYAML==6.0.1
-requests==2.31.0
-snowballstemmer==2.2.0
-soupsieve==2.4.1
-Sphinx==7.2.5
-sphinx-basic-ng==1.0.0b2
-sphinxcontrib-applehelp==1.0.7
-sphinxcontrib-devhelp==1.0.5
-sphinxcontrib-htmlhelp==2.0.4
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.6
-sphinxcontrib-serializinghtml==1.1.9
-urllib3==2.0.4
+alabaster>=0.7.13
+Babel>=2.12.1
+beautifulsoup4>=4.12.2
+certifi>=2023.7.22
+charset-normalizer>=3.2.0
+colorama>=0.4.6
+docutils>=0.20.1
+idna>=3.4
+imagesize>=1.4.1
+Jinja2>=3.1.2
+markdown-it-py>=3.0.0
+MarkupSafe>=2.1.3
+mdit-py-plugins>=0.4.0
+mdurl>=0.1.2
+myst-parser>=2.0.0
+packaging>=23.1
+piccolo-theme>=0.17.0
+Pygments>=2.16.1
+PyYAML>=6.0.1
+requests>=2.31.0
+snowballstemmer>=2.2.0
+soupsieve>=2.4.1
+Sphinx>=7.2.5
+sphinx-basic-ng>=1.0.0b2
+sphinxcontrib-applehelp>=1.0.7
+sphinxcontrib-devhelp>=1.0.5
+sphinxcontrib-htmlhelp>=2.0.4
+sphinxcontrib-jsmath>=1.0.1
+sphinxcontrib-qthelp>=1.0.6
+sphinxcontrib-serializinghtml>=1.1.9
+urllib3>=2.0.4
 git+https://github.com/Kristinita/PygmentsCSVLexer.git@e3994efbf2058cd3f141edc869b37b84530eb61c

docs/source/_static/css/style.css

@@ -0,0 +1,29 @@
+/*
+* Copyright (c) 2023 Contributors to the Eclipse Foundation.
+*
+* This program and the accompanying materials are made
+* available under the terms of the Eclipse Public License 2.0
+* which is available at https://www.eclipse.org/legal/epl-2.0/
+* SPDX-License-Identifier: EPL-2.0
+*
+* Contributors:
+*   Kentyou - initial implementation
+*/
+
+/* Custom styles for use in the documentation */
+
+/* Float on the right hand side */
+.float-right {
+    float: right;
+}
+
+/* Push down to clear a right-hand float */
+.clear-right {
+    clear: right;
+}
+
+/* Display as a centred block */
+.block-center {
+    display: block;
+    margin: auto;
+}

docs/source/_templates/layout.html

@@ -0,0 +1,3 @@
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ["_static/css/style.css"] %}

docs/source/core/CoreModel.md

@@ -4,23 +4,23 @@ The sensiNact core model describes the interactions and in-memory representation
 
 The sensiNact core data model is broken down into *Resources*, *Services* and *Providers* which are interacted with using the verbs *GET*, *DESCRIBE*, *SET*, *ACT*, *SUBSCRIBE* and *UNSUBSCRIBE*
 
-# Verbs
+## Verbs
 
 The sensiNact *verbs* are conceptually similar to the verbs in HTTP. They represent a common set of instructions that can be used to query or change the state of a sensiNact gateway.
 
-## Read only verbs
+### Read only verbs
 
 The following verbs are used to interrogate the state of the gateway without changing it
 
-### GET
+#### GET
 
 The simplest verb is *GET* which is a request to read a *Resource's* value, or one of its metadata values, from the sensiNact gateway.
 
-### DESCRIBE
+#### DESCRIBE
 
 The *DESCRIBE* verb is another read request, but rather than providing access to data or metadata values it provides information about the structure of the described part of the data model. For example a *DESCRIBE* operation on a *Provider* will list the *Services* for that *Provider*, whereas a *DESCRIBE* on a *Resource* will list information about the data and metadata values for the *Resource*.
 
-### SUBSCRIBE
+#### SUBSCRIBE
 
 The *SUBSCRIBE* verb allows the caller to watch for changes in the target part of the data model, for example:
 
@@ -29,52 +29,54 @@ The *SUBSCRIBE* verb allows the caller to watch for changes in the target part o
  * Changes in the value of a *Resource*
  * Actions ocurring on a *Resource*
 
-### UNSUBSCRIBE
+#### UNSUBSCRIBE
 
 The *UNSUBSCRIBE* verb allows the caller to remove a subscription from an earlier *SUBSCRIBE* call
 
-## Edit operations
+### Edit operations
 
 The following verbs are used to change the state of the gateway, and potentially the devices connected to it
 
-### SET
+#### SET
 
 The *SET* verb is used to change the value of a *Resource* or to change the metadata associated with a *RESOURCE*
 
-### ACT
+#### ACT
 
 The *ACT* verb is used to trigger an *Action Resource*, potentially passing one or more parameters to a device, and potentially returning a value.
 
-# The core data model
+## The core data model
 
 The sensiNact core data model is composed of *Resources*, *Services* and *Providers*, which are arranged in a tree-structure. The definition of the structure for a provider is referred to as the provider model.
 
+![The sensiNact Data Model](../_static/core/datamodel-white.png){.block-center w=15em}
+
 A `Resource` is the lowest level of the sensiNact data model. A resource represents a single sensor, actuator or state variable within the digital twin. There are two types of *Resources*, data resources and action resources
 
-## Data Resources
+### Data Resources
 
 A data resource has a single `value` associated with it representing the data it provides.
 A resource also has zero or more metadata entries associated with it. For brevity we will use the term `field` to refer to both value and metadata entries.
 
 The `fields` of a resource have associated time stamps representing the times at which they were last updated. They also have an associated property indicating how their value can change.
 
-### Read-only fields
+#### Read-only fields
 
 A read-only field is one cannot be changed by sensiNact. Read-only fields may be `UPDATABLE` and have the potential to change over time (e.g. the data reading from a sensor) or `FIXED` and unchanging (e.g. a hardware identifier reported by a device).
 
 The value of a read-only field can be queried using the `GET` verb, or watched using the `SUBSCRIBE` verb.
 
-### `MODIFIABLE` fields
+#### `MODIFIABLE` fields
 
 A `MODIFIABLE` field is one that can be changed by sensiNact. It may represent a configuration property for a device, or a direct output.
 
 The value of a `MODIFIABLE` field can be queried using the `GET` verb, watched using the `SUBSCRIBE` verb, or changed using the `SET` verb.
 
-## Action resources
+### Action resources
 
 Action resources are similar to data resources, but do not have a `value` that can be queried. Action resources represent some actuation capability of a device. Action resources can be triggered using the `ACT` verb. Action resource metadata will include information about the parameters that can be passed when triggering the action.
 
-## Services
+### Services
 
 A service is a logical grouping of one or more resources that are related, for example a smart plug might have two services:
 
@@ -85,18 +87,18 @@ A service is a logical grouping of one or more resources that are related, for e
     * `current` - a resource providing the current passing through the plug
     * `power` - a resource providing the power passing through the plug
 
-## Providers
+### Providers
 
 A `Provider` is a logical representation of a device, group of devices, or physical object, that should be available within sensiNact. Each `Provider` will contain one or more `Service` entries. The description of the services and resources associated with a provider is known as the provider model.
 
-### The `admin` Service
+#### The `admin` Service
 
 All `Provider` instances have an implicit service called `admin`. The `admin` service provides information that sensiNact holds about the device. This information may, or may not, correspond to information actually provided by the device.
 
  * `friendlyName` - a human readable name for this device
  * `location` - a GeoJSON string representing the location of this device
  * `icon` - an icon to use when representing this device
 
-## Looking for more detail?
+### Looking for more detail?
 
 More detail about the data model can be defined and interacted with is available [here](data-model/DataModel.md)

docs/source/index.md

@@ -13,12 +13,14 @@ The project is licensed under the terms of the [Eclipse Public License - v 2.0](
 
 Eclipse sensiNact represents its data using the following model:
 
+![The sensiNact Data Model](_static/core/datamodel-white.png){.float-right w=25em}
+
 * **Model**: a static or dynamic representation of a kind of provider. This allows to describe the structure of a provider, *i.e.* its services and the type, default value, description, ... of their resources
-  * **Provider**: a provider of services. It usually represents a physical object, but the granularity depends on the use case. For example, it can be an IoT device with multiple sensors, a car, ...
-    * **Service**: the name of a set of resources. All providers have the reserved `admin` service which holds sensiNact details about them, including their `location` resource.
-      * **Resource**: a resource can either represent a property of the provider (like the temperature read from a sensor) or an action (for example to send a text message).
+* **Provider**: a provider of services. It usually represents a physical object, but the granularity depends on the use case. For example, it can be an IoT device with multiple sensors, a car, ...
+* **Service**: the name of a set of resources. All providers have the reserved `admin` service which holds sensiNact details about them, including their `location` resource.
+* **Resource**: a resource can either represent a property of the provider (like the temperature read from a sensor) or an action (for example to send a text message).
 
-The model is described more in details in the [Data Model](./core/CoreModel.md) section.
+The model is described more in detail in the [Data Model](./core/CoreModel.md){.clear-right} section.
 
 
 ## Getting Started