Use Eclipse uProtocol for sending vehicle status updates

The FMS Forwarder has been changed to use uProtocol Publish messages for
sending vehicle status updates to the back end (FMS Consumer).
The direct connection to the InfluxDB has been removed in favor
of the Zenoh based uProtocol transport. As an alternative, custom
uProtocol transports for Hono's MQTT adapter and the Kafka messaging
infrastructure have been added.

Author: sophokles73

.github/scripts/check-3rd-party-licenses.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+deps_file=${DEPS_FILE:-"DEPS.txt"}
+dash_jar=${DASH_JAR:-"/tmp/dash.jar"}
+dash_summary=${DASH_SUMMARY:-"DASH_SUMMARY.txt"}
+project=${PROJECT:-"automotive.uprotocol"}
+token=$1
+
+echo "creating 3rd party dependency list..."
+cargo tree --manifest-path components/Cargo.toml -e no-build,no-dev --prefix none --no-dedupe --locked \
+  | sed -n '2~1p' \
+  | sort -u \
+  | grep -v '^[[:space:]]*$' \
+  | grep -v fms- \
+  | grep -v influx-client \
+  | grep -v up-transport-hono \
+  | sed -E 's|([^ ]+) v([^ ]+).*|crate/cratesio/-/\1/\2|' \
+  > "$deps_file"
+
+if [[ ! -r "$dash_jar" ]]; then
+  echo "Eclipse Dash JAR file [${dash_jar}] not found, downloading latest version from GitHub..."
+  wget_bin=$(which wget)
+  if [[ -z "$wget_bin" ]]; then
+    echo "wget command not available on path"
+    exit 127
+  else
+    wget --quiet -O "$dash_jar" "https://repo.eclipse.org/service/local/artifact/maven/redirect?r=dash-licenses&g=org.eclipse.dash&a=org.eclipse.dash.licenses&v=LATEST"
+  echo "successfully downloaded Eclipse Dash JAR to ${dash_jar}"
+  fi
+fi
+
+args=(-jar "$dash_jar" -timeout 60 -batch 90 -summary "$dash_summary")
+if [[ -n "$token" ]]; then
+  args=("${args[@]}" -review -token "$token" -project "$project")
+fi
+args=("${args[@]}" "$deps_file")
+
+echo "checking 3rd party licenses..."
+java "${args[@]}"

.github/workflows/check-dependencies.yaml

@@ -30,30 +30,14 @@ jobs:
   deps:
     name: "Check 3rd party Rust dependencies' licenses"
     runs-on: ubuntu-latest
+    env:
+      DASH_SUMMARY: "DEPENDENCIES.txt"
     steps:
     - uses: actions/checkout@v4
-    - name: Determine list of 3rd party Rust dependencies
-      working-directory: ${{github.workspace}}
-      run: |
-        cargo tree --manifest-path components/Cargo.toml -e no-build,no-dev --prefix none --no-dedupe --locked \
-          | sort -u \
-          | grep -v '^[[:space:]]*$' \
-          | grep -v fms- \
-          | grep -v influx-client \
-          | grep -v zenoh \
-          | sed -E 's|([^ ]+) v([^ ]+).*|crate/cratesio/-/\1/\2|' \
-          > DEPS.txt
-    - name: Set up JDK
-      uses: actions/setup-java@v4
-      with:
-        distribution: "temurin"
-        java-version: "17"
-    - name: "Run latest Eclipse Dash jar file"
+    - name: "Check 3rd party license compatibility"
       id: "run-checks"
-      working-directory: ${{github.workspace}}
       run: |
-        wget --quiet -O dash.jar "https://repo.eclipse.org/service/local/artifact/maven/redirect?r=dash-licenses&g=org.eclipse.dash&a=org.eclipse.dash.licenses&v=LATEST"
-        if java -Dorg.eclipse.dash.timeout=60 -jar dash.jar -batch 90 -summary DEPENDENCIES.txt DEPS.txt
+        if .github/scripts/check-3rd-party-licenses.sh
         then
           echo "checks-failed=0" >> $GITHUB_OUTPUT
           echo "License information of 3rd party dependencies has been vetted successfully." >> $GITHUB_STEP_SUMMARY
@@ -67,7 +51,7 @@ jobs:
       uses: actions/upload-artifact@v4
       with:
         name: 3rd-party-dependencies
-        path: DEPENDENCIES.txt
+        path: ${{ env.DASH_SUMMARY }}
     - name: "Determine exit code"
       env:
         EXIT_CODE: ${{ steps.run-checks.outputs.checks-failed }}

.gitignore

@@ -21,5 +21,5 @@
 *.drawio.bkp
 **/target
 
-config/
+config/hono/
 *.env

.sdv-blueprint.json

@@ -3,9 +3,23 @@
   "version": "0.1.0",
   "description": "A close to real-life showcase for truck fleet management where trucks run an SDV software stack so that logistics fleet operators can manage apps, data and services for a diverse set of vehicles.",
   "participatingProjects": [
-    { "id": "automotive.kuksa" },
-    { "id": "automotive.leda" },
-    { "id": "iot.hono" },
-    { "id": "iot.paho" }
+    {
+      "id": "automotive.kuksa"
+    },
+    {
+      "id": "automotive.leda"
+    },
+    {
+      "id": "automotive.uprotocol"
+    },
+    {
+      "id": "iot.hono"
+    },
+    {
+      "id": "iot.paho"
+    },
+    {
+      "id": "iot.zenoh"
+    }
   ]
-}
+}

DEPENDENCIES

@@ -29,27 +29,32 @@ for truck fleet management where trucks run an SDV software stack so that logist
 manage apps, data and services for a diverse set of vehicles.
 
 The use case illustrates how the standard VSS model can be customized and used to report data from a vehicle
-to a back end. The following diagram provides an overview of the current architecture:
+to a back end. It also shows how [Eclipse uProtocol™](https://eclipse-uprotocol.github.io) can be used to connect in-vehicle components to an off-vehicle service in the back end. uProtocol provides a generic API for using the well known pub/sub and RPC message exchange patterns over arbitrary transport protocols like MQTT, Eclipse Zenoh etc.
 
-<img src="img/architecture.drawio.svg">
+The following component diagram provides a high level overview of the building blocks and how they are related to each other.
+
+<img src="img/architecture-uprotocol.drawio.svg">
 
 The overall idea is to enable back end applications to consume data coming from a vehicle using the rFMS API.
 
 Data originates from the vehicle's sensors which are represented by a CSV file that is being played back by the
-kuksa.val CSV feeder. The CSV feeder publishes the data to the kuksa.val Databroker. From there, the FMS Forwarder
-consumes the data and writes it to an InfluxDB in the back end. The measurements in the InfluxDB can then be
-visualized in a web browser by means of a Grafana dashboard. Alternatively, the measurements can be retrieved by
-a Fleet Management application via the FMS Server's (HTTP based) rFMS API.
+[Eclipse Kuksa&trade; CSV Provider](https://github.com/eclipse-kuksa/kuksa-csv-provider). The *CSV Provider* publishes
+the data to the [Kuksa Databroker](https://github.com/eclipse-kuksa/kuksa-databroker).
+The *FMS Forwarder* reads the signal values from the Databroker and sends them to the *FMS Consumer* in the back end. The FMS Consumer then writes the measurements to an *InfluxDB* from where it
+can be visualized in a web browser by means of a *Grafana* dashboard. Alternatively, the measurements can be
+retrieved by a Fleet Management application via the *FMS Server's* (HTTP based) rFMS API.
+
+Both the FMS Forwarder and Consumer are implemened as uProtocol entities (_uEntity_). This allows the FMS Forwarder to send its data to the Consumer by means of a uProtocol _Notification_. The concrete transport protocol being used to transmit the message on the wire is a matter of configuration and has no impact on the implementation of the business logic itself.
 
 # Quick Start
 
 The easiest way to set up and start the services is by means of using the Docker Compose file in the top level folder:
 
 ```sh
-docker compose -f ./fms-blueprint-compose.yaml up --detach
+docker compose -f ./fms-blueprint-compose.yaml -f ./fms-blueprint-compose-zenoh.yaml up --detach
 ```
 
-This will pull or build (if necessary) the container images and create and start all components.
+This will pull (or build if necessary) the container images and create and start all components.
 
 Once all services have been started, the current vehicle status can be viewed on a [Grafana dashboard](http://127.0.0.1:3000),
 using *admin*/*admin* as username and password for logging in.
@@ -61,16 +66,18 @@ The rFMS API can be used to retrieve the data, e.g.
 curl -v -s http://127.0.0.1:8081/rfms/vehicleposition?latestOnly=true | jq
 ```
 
-# Using Eclipse Hono to send Vehicle Data to Back End
+# Eclipse Zenoh&trade; Transport
 
-By default, the Docker Compose file starts the FMS Forwarder configured to write vehicle data directly to the
-Influx DB running in the back end.
+The command line from the quick start section will start up containers for the _FMS Forwarder_ and _FMS Consumer_ that are configured to use a [Zenoh](https://zenoh.io) based uProtocol transport as shown in the deployment diagram below:
 
-However, in a real world scenario, this tight coupling between the vehicle and the Influx DB is not desirable.
-As an alternative, the blueprint supports configuring the FMS Forwarder to send vehicle data to the MQTT adapter
-of an Eclipse Hono instance as shown in the diagram below.
+<img src="img/architecture-zenoh.drawio.svg">
 
-<img src="img/architecture-hono.drawio.svg">
+# Eclipse Hono&trade; based Transport
+
+The blueprint can also be configured to use a Hono based uProtocol transport that employs Hono's MQTT adapter
+and Apache Kafka&trade; based messaging infrastructure for sending vehicle data to the Consumer.
+
+In order to run the blueprint with the Hono transport, perform the following steps:
 
 1. Register the vehicle as a device in Hono using the [create-config-hono.sh shell script](./create-config-hono.sh):
 
@@ -80,7 +87,7 @@ of an Eclipse Hono instance as shown in the diagram below.
 
    Make sure to replace `MY_TENANT_ID`, `MY_DEVICE_ID` and `MY_PWD` with your own values.
 
-   The script registers the tenant and device in Hono's Sandbox installation at `hono.eclipseprojects.io` unless the
+   The script registers the tenant and device in [Hono's Sandbox installation](https://eclipse.dev/hono/sandbox/) at `hono.eclipseprojects.io` unless the
    `--host` and/or `--kafka-brokers` command line arguments are used. Use the `--help` switch to print usage information.
 
    The script also creates configuration files in the `OUT_DIR/config/hono` folder. The OUT_DIR can be specified using
@@ -95,25 +102,9 @@ of an Eclipse Hono instance as shown in the diagram below.
 
    The path set via the `--env-file` option needs to be adapted to the output folder specified in the previous step.
 
-   The second compose file specified on the command line will also start the [FMS Consumer](./components/fms-consumer)
-   back end component which receives vehicle data via Hono's north bound Kafka based Telemetry API and writes it to the
-   Influx DB.
-   
-# Using Eclipse Zenoh to geographically distribute the vehicle data
-
-The blueprint supports configuring the FMS Forwarder to send vehicle data to the Eclipse Zenoh router of an [Eclipse Zenoh](https://zenoh.io/) instance as shown in the diagram below.
-Zenoh router provides a plugin mechanism to other protocols to enable the Vehicle to anything communication.
-
-<img src="img/architecture-zenoh.drawio.svg">
+This will result in a deployment as shown below:
 
-Start up the vehicle and back end services using Docker Compose:
-
-```sh
-docker compose -f ./fms-blueprint-compose.yaml -f ./fms-blueprint-compose-zenoh.yaml up --detach
-```
-
-Once all services have been started, the current vehicle status can be viewed on a [Grafana dashboard](http://127.0.0.1:3000),
-using *admin*/*admin* as username and password for logging in.
+<img src="img/architecture-hono.drawio.svg">
 
 # Manual configuration
 
@@ -125,5 +116,6 @@ Additional information can be found in the components' corresponding subfolders.
 
 # Contributing
 
-We are looking forward to your ideas and PRs. Each PRs triggers a GitHub action which checks the formating, performs linting and runs the test. You can performe similar check in your development environment. For more details check the respective [action](.github/workflows/lint_source_code.yaml) where the checks are listed in the bottom of the file.
-
+We are looking forward to your ideas and PRs. Each PRs triggers a GitHub action which checks the formating, performs
+linting and runs the test. You can performe similar check in your development environment. For more details check the
+respective [action](.github/workflows/lint_source_code.yaml) where the checks are listed in the bottom of the file.