From 383f29a4d4b5cf87e794b07485ab36b9b0f8cb1b Mon Sep 17 00:00:00 2001 From: dennismeister93 Date: Tue, 27 Feb 2024 05:44:07 +0100 Subject: [PATCH 01/10] Version fixes and removal of strange header of rendered page (#117) Signed-off-by: Dennis Meister --- .devcontainer/Dockerfile | 4 ++-- .devcontainer/devcontainer.json | 3 +-- .devcontainer/scripts/postCreateCommand.sh | 2 +- .github/workflows/ci.yml | 2 +- .github/workflows/manual.yml | 2 +- content/en/_index.html | 6 ------ package-lock.json | 16 ++++------------ 7 files changed, 10 insertions(+), 25 deletions(-) diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 7630d29b1..070239903 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -14,7 +14,7 @@ # Update the NODE_VERSION arg in docker-compose.yml to pick a Node version: 18, 16, 14 ARG NODE_VERSION=18 -FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${NODE_VERSION} +FROM mcr.microsoft.com/devcontainers/javascript-node:${NODE_VERSION} # VARIANT can be either 'hugo' for the standard version or 'hugo_extended' for the extended version. ARG VARIANT=hugo @@ -22,7 +22,7 @@ ARG VARIANT=hugo ARG VERSION=latest # Download Hugo -RUN apt-get update && apt-get install -y ca-certificates openssl git curl golang python pip && \ +RUN apt-get update && apt-get install -y ca-certificates openssl git curl golang python-is-python3 && \ rm -rf /var/lib/apt/lists/* && \ case ${VERSION} in \ latest) \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index c4e2928d0..86837cc66 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -37,10 +37,9 @@ "forwardPorts": [ 1313 ], - // Use 'postCreateCommand' to run commands after the container is created. - // "postCreateCommand": "uname -a", // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root. "remoteUser": "node", + // Use 'postCreateCommand' to run commands after the container is created. "postCreateCommand": ".devcontainer/scripts/postCreateCommand.sh", "postStartCommand": "hugo server -b http://localhost/velocitas -w" } diff --git a/.devcontainer/scripts/postCreateCommand.sh b/.devcontainer/scripts/postCreateCommand.sh index 26c85c44f..a7163efb3 100755 --- a/.devcontainer/scripts/postCreateCommand.sh +++ b/.devcontainer/scripts/postCreateCommand.sh @@ -23,7 +23,7 @@ npm install hugo mod get -u github.com/google/docsy@v0.6.0 # install pre-commit -pip install pre-commit==3.5.0 +pip install pre-commit==3.6.0 --break-system-packages # add repo to git safe.directory & fix hugo issue with server start REPO=$(pwd) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1268538df..d0cf78183 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,7 +31,7 @@ jobs: - name: Setup Hugo uses: peaceiris/actions-hugo@v2.6.0 with: - hugo-version: "0.110.0" + hugo-version: "0.123.3" extended: true - name: Build diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml index 04db45b44..d282b3c6c 100644 --- a/.github/workflows/manual.yml +++ b/.github/workflows/manual.yml @@ -28,7 +28,7 @@ jobs: - name: Setup Hugo uses: peaceiris/actions-hugo@v2.6.0 with: - hugo-version: "0.110.0" + hugo-version: "0.123.3" extended: true - name: Build diff --git a/content/en/_index.html b/content/en/_index.html index 8cca36509..d8a5de848 100644 --- a/content/en/_index.html +++ b/content/en/_index.html @@ -14,12 +14,6 @@ ~ SPDX-License-Identifier: Apache-2.0 --> -+++ -title = "Velocitas™" -linkTitle = "Velocitas" -description = "Toolchain for fast and easy development of vehicle applications for OEMs and suppliers" -+++ - {{< blocks/cover title="Eclipse Velocitas™" image_anchor="top" height="full" color="dark">}}

Toolchain for creating containerized in-vehicle applications

diff --git a/package-lock.json b/package-lock.json index 051bc7e5b..b24184de6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,7 +1,7 @@ { "name": "velocitas-docs", "version": "1.0.0", - "lockfileVersion": 2, + "lockfileVersion": 3, "requires": true, "packages": { "": { @@ -12,9 +12,9 @@ } }, "node_modules/prettier": { - "version": "2.6.2", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.6.2.tgz", - "integrity": "sha512-PkUpF+qoXTqhOeWL9fu7As8LXsIUZ1WYaJiY/a7McAQzxjk82OF0tibkFXVCDImZtWxbvojFjerkiLb0/q8mew==", + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", "dev": true, "bin": { "prettier": "bin-prettier.js" @@ -26,13 +26,5 @@ "url": "https://github.com/prettier/prettier?sponsor=1" } } - }, - "dependencies": { - "prettier": { - "version": "2.6.2", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.6.2.tgz", - "integrity": "sha512-PkUpF+qoXTqhOeWL9fu7As8LXsIUZ1WYaJiY/a7McAQzxjk82OF0tibkFXVCDImZtWxbvojFjerkiLb0/q8mew==", - "dev": true - } } } From 741097f72b3e4e55c669ceece2ec64e11dc68a6e Mon Sep 17 00:00:00 2001 From: Markus Petke Date: Thu, 4 Apr 2024 12:56:18 +0200 Subject: [PATCH 02/10] Remove dapr and k3d (#119) * remove from text * fix diagrams * fix linter * fix review findings * fix more * another fix --- .vscode/settings.json | 2 - .../docs/concepts/deployment_model/_index.md | 3 +- .../vehicle_app_releases/_index.md | 3 - .../docs/concepts/development_model/_index.md | 7 +- .../vehicle_app_manifest/_index.md | 2 +- .../vehicle_app_sdk/_index.md | 24 +- .../lifecycle_management/packages/usage.md | 2 +- .../docs/tutorials/quickstart/quickstart.md | 32 +- .../vehicle_app_deployment/_index.md | 2 + .../vehicle_app_deployment/helm_deployment.md | 164 ----- .../podspecs_deployment.md | 101 --- .../cpp_development.md | 56 +- .../integration_tests.md | 30 +- .../python_development.md | 87 +-- .../tutorials/vehicle_app_runtime/_index.md | 2 +- .../vehicle_app_runtime/kanto_runtime.md | 3 +- .../vehicle_app_runtime/kubernetes_runtime.md | 58 -- .../vehicle_app_runtime/local_runtime.md | 4 +- static/assets/diagrams.drawio | 13 +- static/assets/sdk_overview.drawio.svg | 665 +----------------- static/assets/seat_adjuster_dataflow.svg | 4 +- static/assets/seat_adjuster_dataflow_1.svg | 4 +- static/assets/seat_adjuster_dataflow_2.svg | 4 +- 23 files changed, 64 insertions(+), 1208 deletions(-) delete mode 100644 content/en/docs/tutorials/vehicle_app_deployment/helm_deployment.md delete mode 100644 content/en/docs/tutorials/vehicle_app_deployment/podspecs_deployment.md delete mode 100644 content/en/docs/tutorials/vehicle_app_runtime/kubernetes_runtime.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 7316f82e2..56ef7aac6 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -13,7 +13,6 @@ "controlplane", "COVESA", "cppdbg", - "Dapr", "Databroker", "datapoint", "datapoints", @@ -31,7 +30,6 @@ "gohugoio", "grpcio", "hediet", - "helmignore", "hitkodev", "hotfixes", "hvac", diff --git a/content/en/docs/concepts/deployment_model/_index.md b/content/en/docs/concepts/deployment_model/_index.md index b1166b87a..132abae2b 100644 --- a/content/en/docs/concepts/deployment_model/_index.md +++ b/content/en/docs/concepts/deployment_model/_index.md @@ -13,8 +13,7 @@ The Velocitas project uses a common deployment model. It uses [OCI-compliant](ht The deployment model is guided by the following principles - Applications are provided as OCI-compliant container images. -- The container runtime offers a Kubernetes-compatible control plane and API to manage the container lifecycle. -- Helm charts are used as deployment descriptor specification. +- The container runtime offers a control plane and API to manage the container lifecycle. The template projects provided come with a pre-configured developer toolchain that accelerates the development process. The developer toolchain ensures an easy creation through a high-degree of automation of all required artifacts needed to follow the _Velocitas_ principles. diff --git a/content/en/docs/concepts/deployment_model/vehicle_app_releases/_index.md b/content/en/docs/concepts/deployment_model/vehicle_app_releases/_index.md index e6e5582d2..50cff5d25 100644 --- a/content/en/docs/concepts/deployment_model/vehicle_app_releases/_index.md +++ b/content/en/docs/concepts/deployment_model/vehicle_app_releases/_index.md @@ -43,7 +43,6 @@ The `Build multi-arch image workflow` is triggered on every commit to the main b - **Building a multi-arch container for the app** - actions create a containerized version of the _Vehicle App_ for multiple architectures (currently AMD64 and ARM64). - **Scanning for vulnerabilities** - actions scan your code and container for vulnerabilities and in case of findings the workflow will be marked as "failed". - **Storing container images to GitHub action artifacts** - at the end of the workflow, the container image created is stored in a Github Action Artifacts so that it can be referenced by the Release Workflow later. -- **Generate Deployment Files** - actions generate a PodSpec-file and HelmCharts to ease the deployment of the _Vehicle App_ and the runtime services. ## Release Workflow ([release.yml](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.github/workflows/release.yml)) @@ -85,5 +84,3 @@ The release process would be the same as described in the overview, except that ## Further information - Tutorial: [How to write integration tests](/docs/tutorials/vehicle_app_development/integration_tests) -- Tutorial: [Deploy a _Vehicle App_ with Helm](/docs/tutorials/vehicle_app_deployment/helm_deployment.md) -- Tutorial: [Deploy a _Vehicle App_ with PodSpecs](/docs/tutorials/vehicle_app_deployment/podspecs_deployment.md) diff --git a/content/en/docs/concepts/development_model/_index.md b/content/en/docs/concepts/development_model/_index.md index 563002b23..0062d6a9a 100644 --- a/content/en/docs/concepts/development_model/_index.md +++ b/content/en/docs/concepts/development_model/_index.md @@ -56,12 +56,13 @@ Asynchronous communication between [_Vehicle Apps_](#vehicle-apps) and other veh ### Middleware Abstraction -Velocitas provides middleware abstraction interfaces for Service Discovery, PubSub Messaging Protocol and other cross-cutting functionality. -By default, Velocitas leverages [Dapr](https://dapr.io) for gRPC service discovery, Open Telemetry tracing and the [publish/subscribe building block](https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview/). +Velocitas basically provides middleware abstraction interfaces for service discovery, pubsub messaging, and other cross-cutting functionalites. +At the moment, Velocitas just offers a (what we call) "native middleware" implementation, which does not provide (gRPC) service discovery. Instead, addresses and port number of services need to be provided via environment variables to an app; e.g. SDV_VEHICLEDATABROKER_ADDRESS=grpc://localhost:55555. +The support of Dapr as middleware has recently been removed. ### Vehicle Edge Operating System -[_Vehicle Apps_](#vehicle-apps) are expected to run on a [Linux](https://www.linux.org/)-based operating system. An OCI-compliant container runtime is required to host the _Vehicle App_ containers and the Dapr middleware mandates a Kubernetes control plane. For publish/subscribe messaging a MQTT broker must be available (e.g., [Eclipse Mosquitto](https://mosquitto.org/)). +[_Vehicle Apps_](#vehicle-apps) are expected to run on a [Linux](https://www.linux.org/)-based operating system. An OCI-compliant container runtime is required to host the _Vehicle App_ containers. For publish/subscribe messaging a MQTT broker must be available (e.g., [Eclipse Mosquitto](https://mosquitto.org/)). ## _Vehicle App_ Characteristics diff --git a/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md b/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md index 64ce4d215..48208b08f 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md +++ b/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md @@ -48,7 +48,7 @@ To fully understand the _AppManifest_, let's have a look at **who** interacts wi * Description of your applications **functional interfaces**(VehicleModel, services, APIs, ...) * Enable **loose coupling** of functional interface descriptions and the Velocitas toolchain. Some parts of the toolchain are responsible for reading the file and acting upon it, depending on the type of functional interface * Providing an **extendable** syntax to enable custom functional interface types which may not provided by the Velocitas toolchain itself, but by a third party -* Providing a **single source of truth** for generation of deployment specifications (i.e. Helm-Charts, Kanto spec, etc...) +* Providing a **single source of truth** for generation of deployment specifications (i.e. Kanto spec, etc...) ## Example diff --git a/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md b/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md index af17c919e..981c05ae5 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md +++ b/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md @@ -17,7 +17,7 @@ The _Vehicle App_ SDK consists of the following building blocks: - **[Vehicle Model Ontology](#vehicle-model-ontology):** The SDK provides a set of model base classes for the creation of vehicle models. -- **[Middleware integration](#middleware-integration):** Vehicle Models can contain gRPC stubs to communicate with _Vehicle Services_. gRPC communication is integrated with the [Dapr](https://dapr.io) middleware for service discovery and [OpenTelemetry](https://opentelemetry.io) logging and tracing. +- **[Middleware integration](#middleware-integration):** Vehicle Models can contain gRPC stubs to communicate with _Vehicle Services_. gRPC communication is integrated natively. - **[Fluent query & rule construction](#fluent-query--rule-construction):** Based on a concrete Vehicle Model, the SDK is able to generate queries and rules against the KUKSA Data Broker to access the real values of the data points that are defined in the vehicle model. @@ -303,10 +303,6 @@ private: {{< /tab >}} {{< /tabpane >}} -### Service discovery - -The underlying gRPC channel is provided and managed by the `Service` base class of the SDK. It is also responsible for routing the method invocation to the service through the Dapr middleware. As a result, a `dapr-app-id` has to be assigned to every `Service`, so that Dapr can discover the corresponding _Vehicle Services_. This `dapr-app-id` has to be specified as an environment variable named `_DAPR_APP_ID`. - ## Fluent query & rule construction A set of query methods like `get()`, `where()`, `join()` etc. are provided through the `Model` and `DataPoint` base classes. These functions make it possible to construct SQL-like queries and subscriptions in a fluent language, which are then transmitted through the gRPC interface to the KUKSA Data Broker. @@ -434,7 +430,7 @@ void onSeatPositionChanged(const DataPointMap_t datapoints) { ## Publish & subscribe messaging -The SDK supports publishing messages to a MQTT broker and subscribing to topics of a MQTT broker. By leveraging the Dapr pub/sub building block for this purpose, the low-level MQTT communication is abstracted away from the _Vehicle App_ developer. Especially the physical address and port of the MQTT broker is no longer configured in the _Vehicle App_ itself, but rather is part of the Dapr configuration, which is outside of the _Vehicle App_. +The SDK supports publishing messages to a MQTT broker and subscribing to topics of a MQTT broker. Using the Velocitas SDK, the low-level MQTT communication is abstracted away from the _Vehicle App_ developer. Especially the physical address and port of the MQTT broker is no longer configured in the _Vehicle App_ itself, but rather is set as an environment variable, which is outside of the _Vehicle App_. ### Publish MQTT Messages @@ -474,22 +470,6 @@ subscribeToTopic("seatadjuster/setPosition/request")->onItem([this](auto&& item) {{< /tab >}} {{< /tabpane >}} -Under the hood, the _Vehicle App_ creates a gRPC endpoint on port `50008`, which is exposed to the Dapr middleware. The Dapr middleware will then subscribe to the MQTT broker and forward the messages to the _Vehicle App_. - -To change the app port, set it in the `main()` method of the app: - -{{< tabpane langEqualsHeader=true >}} -{{< tab "Python" >}} -from sdv import conf - -async def main(): - conf.DAPR_APP_PORT = -{{< /tab >}} -{{< tab "C++" >}} -// C++ does not use Dapr for Pub/Sub messaging at this point -{{< /tab >}} -{{< /tabpane >}} - ## Vehicle App abstraction _Vehicle Apps_ are inherited from the `VehicleApp` base class. This enables the _Vehicle App_ to use the Publish & Subscribe messaging and to connect to the KUKSA Data Broker. diff --git a/content/en/docs/concepts/lifecycle_management/packages/usage.md b/content/en/docs/concepts/lifecycle_management/packages/usage.md index 7fddd8b42..998cfe9c0 100644 --- a/content/en/docs/concepts/lifecycle_management/packages/usage.md +++ b/content/en/docs/concepts/lifecycle_management/packages/usage.md @@ -17,7 +17,7 @@ Currently, the packages provided by the _Velocitas_ team are the following: {{}} | name | description | |:--------|:---------------| -|[devenv-runtimes](https://github.com/eclipse-velocitas/devenv-runtimes)| Containing scripts and configuration for [Local](/docs/tutorials/vehicle_app_runtime/local_runtime/) and [Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime/) Runtime Services | +|[devenv-runtimes](https://github.com/eclipse-velocitas/devenv-runtimes)| Containing scripts and configuration for [Local](/docs/tutorials/vehicle_app_runtime/local_runtime/) and [Kanto](/docs/tutorials/vehicle_app_runtime/kanto_runtime/) Runtime Services | |[devenv-devcontainer-setup](https://github.com/eclipse-velocitas/devenv-devcontainer-setup)| Basic configuration for the devcontainer, like proxy configuration, post create scripts, entry points for the lifecycle management. | |[devenv-github-workflows](https://github.com/eclipse-velocitas/devenv-github-workflows)| Containing github workflow files used by velocitas repositories | |[devenv-github-templates](https://github.com/eclipse-velocitas/devenv-github-templates)| Containing github templates used by velocitas repositories | diff --git a/content/en/docs/tutorials/quickstart/quickstart.md b/content/en/docs/tutorials/quickstart/quickstart.md index af02b2e09..1480f83b6 100644 --- a/content/en/docs/tutorials/quickstart/quickstart.md +++ b/content/en/docs/tutorials/quickstart/quickstart.md @@ -125,7 +125,7 @@ You can find more information about the _Vehicle App_ development in the [respec The runtime services (like _KUKSA Data Broker_ or _Vehicle Services_) are required to develop _Vehicle Apps_ and run integration tests. -Currently, the supported options to run these services is either [locally](/docs/tutorials/vehicle_app_runtime/local_runtime), in a [Kubernetes (K3D) cluster](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) or via the [Kanto runtime](/docs/tutorials/vehicle_app_runtime/kanto_runtime). +Currently, the supported options to run these services is either [locally](/docs/tutorials/vehicle_app_runtime/local_runtime) or via the [Kanto runtime](/docs/tutorials/vehicle_app_runtime/kanto_runtime). {{< tabpane text=true >}} {{% tab header="Local Runtime" %}} @@ -154,36 +154,8 @@ To stop the runtime simply press `Ctrl + C`. {{% /pageinfo %}} {{% /tab %}} -{{% tab header="K3D Runtime" %}} -A VS Code task called `K3D Runtime - Up` is available to start all necessary services in the correct order. - -1. Press F1 -2. Select command `Tasks: Run Task` -3. Select `K3D Runtime - Up` - -You should see the task `K3D Runtime - Up` being executed on a separate VS Code terminal with the following content: - -```bash -$ velocitas exec runtime-k3d up - -Hint: Log files can be found in your workspace's logs directory -> Checking K3D registry... created. -> Creating cluster with proxy configuration. -> Checking K3D cluster... created. -> Checking zipkin deployment... deployed. -> Checking dapr... initialized. -✅ Configuring controlplane for k3d... -> Deploying runtime... installed. -✅ Starting k3d runtime... -``` - -{{% pageinfo color="primary" %}} - You need to perform the task `K3D Runtime - Down` to properly stop all runtime activities. -{{% /pageinfo %}} - -{{% /tab %}} - {{% tab header="Kanto Runtime" %}} +{{% tab header="Kanto Runtime" %}} A VS Code task called `Kanto Runtime - Up` is available to start all necessary services in the correct order. diff --git a/content/en/docs/tutorials/vehicle_app_deployment/_index.md b/content/en/docs/tutorials/vehicle_app_deployment/_index.md index 743d4f7e9..e52c8ede0 100644 --- a/content/en/docs/tutorials/vehicle_app_deployment/_index.md +++ b/content/en/docs/tutorials/vehicle_app_deployment/_index.md @@ -5,3 +5,5 @@ weight: 60 description: > Learn how to deploy the _Vehicle App_ to currently supported infrastructure targets. --- + +See the [Kanto container configuration](https://eclipse.dev/kanto/docs/references/containers/container-config/) for details how to write Kanto deployment files. diff --git a/content/en/docs/tutorials/vehicle_app_deployment/helm_deployment.md b/content/en/docs/tutorials/vehicle_app_deployment/helm_deployment.md deleted file mode 100644 index eaa3f9c3c..000000000 --- a/content/en/docs/tutorials/vehicle_app_deployment/helm_deployment.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: "Helm Deployment" -date: 2022-05-09T13:43:25+05:30 -weight: 80 -description: > - Learn how to prepare a Helm chart for the deployment of a _Vehicle App_ in a Kubernetes cluster. -aliases: - - /docs/tutorials/vehicle_app_deployment/helm_deployment.md ---- - -This tutorial will show you how to: - -- Prepare a Helm chart. -- Deploy your _Vehicle App_ to a local K3D cluster. - -## Prerequisites - -- `Devcontainer` is up and running. -- Complete the tutorial [How to create a _Vehicle App_](/docs/tutorials/vehicle_app_development). - -## Use the sample Helm chart - -If the _Vehicle App_ has been created from one of our template repositories, a sample Helm chart is already available inside our maintained `runtime-k3d` of the [`devenv-runtimes`](https://github.com/eclipse-velocitas/devenv-runtimes) package at [`./runtime-k3d/src/app_deployment/config/helm/`](https://github.com/eclipse-velocitas/devenv-runtimes/blob/main/runtime-k3d/src/app_deployment/config/helm/) and can be used as it is without any modification. -This sample chart is using the values from [`./runtime-k3d/src/app_deployment/config/helm/values.yaml`](https://github.com/eclipse-velocitas/devenv-runtimes/blob/main/runtime-k3d/src/app_deployment/config/helm/values.yaml) file. - -{{% alert title="Note" %}} -The same app name as defined in `./app/AppManifest.json` will be used for the deployment -
-The app port is configurable as `vehicleAppPort` inside your `.velocitas.json` variables section. If not set there, the default value is [50008 - as defined in manifest.json](https://github.com/eclipse-velocitas/devenv-runtimes/blob/main/manifest.json#L204) of the devenv-runtimes package. -{{% /alert %}} - -## Prepare a new Helm chart - -If you would like to write a new helm chart, this section will guide you to adapt and deploy a new _Vehicle App_, which is called `my_vehicle_app` for this walkthrough. - -1. Start Visual Studio Code and open the previously created _Vehicle App_ repository. -1. Create a new folder `my_vehicle_app` under `deploy` -1. Copy all files from the [devenv-runtimes/runtime-k3d/src/app_deployment/config/helm](https://github.com/eclipse-velocitas/devenv-runtimes/tree/main/runtime-k3d/src/app_deployment/config/helm) folder to the new folder `deploy/my_vehicle_app`. -1. Rename the file `deploy/my_vehicle_app/helm/templates/vehicleapp.yaml` to `deploy/my_vehicle_app/helm/templates/my_vehicle_app.yaml` -1. Open `deploy/my_vehicle_app/helm/Chart.yaml` and change the name of the chart to `my_vehicle_app` and provide a meaningful description. - - ```yaml - apiVersion: v2 - name: my-vehicle-app - description: Short description for my-vehicle-app - - # A chart can be either an 'application' or a 'library' chart. - # - # Application charts are a collection of templates that can be packaged into versioned archives - # to be deployed. - # - # Library charts provide useful utilities or functions for the chart developer. They're included as - # a dependency of application charts to inject those utilities and functions into the rendering - # pipeline. Library charts do not define any templates and cannot be deployed as a result. - type: application - - # This is the chart version. This version number should be incremented each time you make changes - # to the chart and its templates, including the app version. - # Versions are expected to follow Semantic Versioning (https://semver.org/) - version: 0.1.0 - - # This is the version number of the application being deployed. This version number should be - # incremented each time you make changes to the application. Versions are not expected to - # follow Semantic Versioning. They should reflect the version the application is using. - appVersion: 1.16.0 - ``` - -1. Open `deploy/my_vehicle_app/helm/values.yaml` and change `name`, `repository` and `daprAppid` to `my-vehicle-app`. Rename the root node from `imageVehicleApp` to `imageMyVehicleApp`. - - ```yaml - imageMyVehicleApp: - name: my-vehicle-app - repository: k3d-registry.localhost:12345/my-vehicle-app - pullPolicy: Always - # Overrides the image tag whose default is the chart appVersion. - tag: "#SuccessfulExecutionOfReleaseWorkflowUpdatesThisValueToReleaseVersionWithoutV#" - daprAppid: my-vehicle-app - daprPort: 50008 - - nameOverride: "" - fullnameOverride: "" - ``` - -1. Open `deploy/my_vehicle_app/helm/templates/my_vehicle_app.yaml` and replace `imageVehicleApp` with `imageMyVehicleApp`: - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: {{.Values.imageMyVehicleApp.name}} - labels: - app: {{.Values.imageMyVehicleApp.name}} - spec: - selector: - matchLabels: - app: {{.Values.imageMyVehicleApp.name}} - template: - metadata: - annotations: - dapr.io/enabled: "true" - dapr.io/app-id: "{{.Values.imageMyVehicleApp.daprAppid}}" - dapr.io/app-port: "{{.Values.imageMyVehicleApp.daprPort}}" - dapr.io/log-level: "debug" - dapr.io/config: "config" - dapr.io/app-protocol: "grpc" - labels: - app: {{.Values.imageMyVehicleApp.name}} - {{- include "helm.selectorLabels" . | nindent 8 }} - spec: - containers: - - name: {{.Values.imageMyVehicleApp.name}} - image: "{{ .Values.imageMyVehicleApp.repository }}:{{ .Values.imageMyVehicleApp.tag | default .Chart.AppVersion }}" - imagePullPolicy: {{ .Values.imageMyVehicleApp.pullPolicy }} - - ``` - -At this point, the Helm chart is prepared for the next step and the folder structure under `deploy/my_vehicle_app` should look like this: - -``` bash -deploy -├── my_vehicle_app -│ └── helm -│ └── templates -│ └── _helpers.tpl -│ └── my_vehicle_app.yaml -│────────── .helmignore -│────────── Chart.yaml -└────────── values.yaml -``` - -## Deploy your _Vehicle App_ to the local K3D cluster - -### Prerequisites - -- A local K3D installation must be available. For how to setup K3D, check out this [tutorial](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime). - -After the Helm chart has been prepared, you can deploy it to the local K3D cluster by following the steps: - -1. Building and pushing the Docker image for your _Vehicle App_ - -```bash -DOCKER_BUILDKIT=1 docker build -f ./app/Dockerfile --progress=plain -t localhost:12345/my-vehicle-app:local . --no-cache - -docker push localhost:12345/my-vehicle-app:local -``` - -2. Installing the Helm Chart - -``` bash -helm install my-vapp-chart ./deploy/my_vehicle_app --values ./deploy/my_vehicle_app/values.yaml --wait --timeout 60s -``` - -These steps are building the local source code of the application into a container, pushing it to the local cluster registry and deploying the app via a helm chart to the K3D cluster. Rerun the steps after you have changed the source code of your application to re-deploy with the latest changes. - -If you have issues installing the helm chart again try uninstalling the chart upfront: - -```bash -helm uninstall my-vapp-chart -``` - -## Next steps - -- Tutorial: [Start runtime services in Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) -- Concept: [Build and release process](/docs/concepts/deployment_model/vehicle_app_releases) diff --git a/content/en/docs/tutorials/vehicle_app_deployment/podspecs_deployment.md b/content/en/docs/tutorials/vehicle_app_deployment/podspecs_deployment.md deleted file mode 100644 index 258312169..000000000 --- a/content/en/docs/tutorials/vehicle_app_deployment/podspecs_deployment.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "PodSpecs Deployment" -date: 2022-05-09T13:43:25+05:30 -weight: 70 -description: > - Learn how to prepare PodSpecs for the deployment of a _Vehicle App_ in a Kubernetes cluster. -aliases: - - /docs/tutorials/vehicle_app_deployment/podspecs_deployment.md ---- - -This tutorial will show you how to: - -- Prepare PodSpecs. -- Deploy your _Vehicle App_ to a local K3D cluster. - -## Prerequisites - -- Complete the tutorial [How to create a _Vehicle App_](/docs/tutorials/vehicle_app_development). - -## Use the sample PodSpecs - -If the _Vehicle App_ has been created from one of our template repositories, a sample PodSpec is already available inside our maintained `runtime-k3d` of the [`devenv-runtimes`](https://github.com/eclipse-velocitas/devenv-runtimes) package at [`./runtime-k3d/src/app_deployment/config/podspec/`](https://github.com/eclipse-velocitas/devenv-runtimes/blob/main/runtime-k3d/src/app_deployment/config/podspec/vehicleapp.yaml) and can be used as it is without any modification. Another example can also be found in the [documentation of Leda](https://eclipse-leda.github.io/leda/docs/app-deployment/velocitas/). - -### Content - -Looking at the content of the sample PodSpec, it is starting with some general information about the app and the Dapr configuration. You can define e.g. the app-port and the log-level. You could also add more labels to your app, which might help to identify the app for later usages. - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: sampleapp - annotations: - dapr.io/enabled: "true" - dapr.io/app-id: sampleapp - dapr.io/app-port: "50008" - dapr.io/app-protocol: grpc - dapr.io/log-level: info - labels: - app: sampleapp -``` - -Afterwards the configuration of the container is specified. Please be aware that `containerPort` should match the `app-port` from the Dapr configuration above. In the example the app-id of the Vehicle Data Broker is also specified, since the app wants to connect to it. Last but not least the image is defined which should be used for the deployment. In this example the local registry is used, which is created during the configuration of the controlplane (see [here](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) for details). - -```yaml -spec: - containers: - - name: sampleapp - imagePullPolicy: IfNotPresent - ports: - - containerPort: 50008 - env: - - name: VEHICLEDATABROKER_DAPR_APP_ID - value: "vehicledatabroker" - image: k3d-registry.localhost:12345/sampleapp:local -``` - -{{% alert title="Note" %}} -Please make sure that you have already pushed your image to the local registry before trying to deploy it. If you used the provided task (see [here](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) for details) to build your app, you can use this command: - -```bash -docker push localhost:12345/sampleapp:local -``` - -{{% /alert %}} - -### Local registry or remote registry - -In the example above we used the local registry, but you can also define a remote registry in the image tag, e.g. - -```yaml -image: ghcr.io/eclipse-velocitas/vehicle-app-python-template/sampleapp:0.1.0 -``` - -If the used registry requires an authentication, you can add the needed secrets to your Kubernets configuration, see the [official documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials) for details. Afterwards you have to add the secrets also to the PodSpec: - -```yaml - imagePullSecrets: - - name: regcred -``` - -## Deploy your _Vehicle App_ to local K3D - -### Prerequisites - -- A local K3D installation must be available. For how to setup K3D, check out this [tutorial](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime). - -{{% alert color="warning" %}} -Make sure that there is no running _Vehicle App_ with the same name and configuration deployed on your K3D environment. -{{% /alert %}} - -Deploying your app with PodSpecs can be done with one simple command: - -`kubectl apply -f ` - -In parallel you can check with K9S if the deployment is working correctly. - -## Next steps - -- Tutorial: [Start runtime services in Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) -- Concept: [Build and release process](/docs/concepts/deployment_model/vehicle_app_releases) diff --git a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md index c5a002cec..f24e0acbc 100644 --- a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md @@ -66,7 +66,7 @@ In your constructor, you have to choose which implementations to use for the Veh ```Cpp MyVehicleApp() - : VehicleApp(IVehicleDataBrokerClient::createInstance("vehicledatabroker"), // this is the dapr-app-id of the KUKSA Databroker in the VAL. + : VehicleApp(IVehicleDataBrokerClient::createInstance("vehicledatabroker"), // this is the app-id of the KUKSA Databroker in the VAL. IPubSubClient::createInstance("MyVehicleApp")) // the clientId identifies the client at the pub/sub broker {} {} @@ -221,7 +221,7 @@ If this is your first time building, you might have to run `install_dependencies In order to run the app make sure the `devenv-runtimes` package is part of your [`.velocitas.json`](https://github.com/eclipse-velocitas/vehicle-app-cpp-template/blob/main/.velocitas.json) (which should be the default) and the runtime is up and running. Read more about it in the [run runtime services](/docs/tutorials/vehicle_app_runtime/local_runtime) section. -Now chose one of the options to start the VehicleApp under development (including Dapr sidecar): +Now chose one of the options to start the VehicleApp under development: 1. Press F5 @@ -241,7 +241,7 @@ The debug session launch settings are already prepared for the `VehicleApp`. { "configurations": [ { - "name": "VehicleApp - Debug (dapr run)", + "name": "VehicleApp - Debug (Native)", "type": "cppdbg", "request": "launch", "program": "${workspaceFolder}/build/bin/app", @@ -250,60 +250,27 @@ The debug session launch settings are already prepared for the `VehicleApp`. "cwd": "${workspaceFolder}", "environment": [ { - "name": "DAPR_HTTP_PORT", - "value": "3500" + "name": "SDV_MIDDLEWARE_TYPE", + "value": "native" }, { - "name": "DAPR_GRPC_PORT", - "value": "50001" + "name": "SDV_VEHICLEDATABROKER_ADDRESS", + "value": "127.0.0.1:55555" }, { - "name": "VEHICLEDATABROKER_DAPR_APP_ID", - "value": "vehicledatabroker" + "name": "SDV_MQTT_ADDRESS", + "value": "127.0.0.1:1883" } ], "externalConsole": false, "MIMode": "gdb", "setupCommands": [ ], - "preLaunchTask": "dapr-sidecar-start", - "postDebugTask": "dapr-sidecar-stop", } ] } ``` -We specify which binary to run using the `program` key. In the `environment` you can specify all needed environment variables. With the `preLaunchTask` and `postDebugTask` keys, you can also specify tasks to run before or after debugging. In this example, DAPR is set up to start the app before and stop it again after debugging. Below you can see the 2 tasks. - -```JSON -{ - "label": "dapr-sidecar-start", - "detail": "Start Dapr sidecar (with dapr run) to be present for debugging the VehicleApp (used by launch config).", - "type": "shell", - "command": "velocitas exec runtime-local run-dapr-sidecar vehicleapp --dapr-grpc-port 50001 --dapr-http-port 3500", - "group": "none", - "isBackground": true, - "presentation": { - "close": true, - "reveal": "never" - } -} -``` - -```JSON -{ - "label": "dapr-sidecar-stop", - "detail": "Stop Dapr sidecar after finish debugging the VehicleApp (used by launch config).", - "type": "shell", - "command": [ - "dapr stop --app-id vehicleapp" - ], - "presentation": { - "close": true, - "reveal": "never" - } -} -``` - +We specify which binary to run using the `program` key. In the `environment` you can specify all needed environment variables. You can adapt the JSON to your needs (e.g., change the ports, add new tasks) or even add a completely new configuration for another _Vehicle App_. Once you are done, you have to switch to the debugging tab (sidebar on the left) and select your configuration using the dropdown on the top. You can now start the debug session by clicking the play button or F5. Debugging is now as simple as in every other IDE, just place your breakpoints and follow the flow of your _Vehicle App_. @@ -312,8 +279,7 @@ Once you are done, you have to switch to the debugging tab (sidebar on the left) - Concept: [SDK Overview](/docs/concepts/development_model/vehicle_app_sdk) - Concept: [Deployment Model](/docs/concepts/deployment_model) -- Tutorial: [Deploy runtime services in Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) +- Tutorial: [Deploy runtime services in Kanto](/docs/tutorials/vehicle_app_runtime/kanto_runtime) - Tutorial: [Start runtime services locally](/docs/tutorials/vehicle_app_runtime/local_runtime) - Tutorial: [Creating a Vehicle Model](/docs/tutorials/vehicle_model_creation) - Tutorial: [Develop and run integration tests for a Vehicle App](/docs/tutorials/vehicle_app_development/integration_tests) -- Tutorial: [Deploy a _Vehicle App_ with Helm](/docs/tutorials/vehicle_app_deployment/helm_deployment.md) diff --git a/content/en/docs/tutorials/vehicle_app_development/integration_tests.md b/content/en/docs/tutorials/vehicle_app_development/integration_tests.md index b5fbb8306..6320e91c6 100644 --- a/content/en/docs/tutorials/vehicle_app_development/integration_tests.md +++ b/content/en/docs/tutorials/vehicle_app_development/integration_tests.md @@ -47,21 +47,17 @@ To write an integration test, you should check the sample that comes with the te This class can be initialized with a given port. If no port is specified, the environment variable `VDB_PORT` will be checked. If this is not possible either, the default value of `55555` will be used. **It's recommended to specify no port when initializing that class as it will locally use the default port `55555` and in CI the port is set by the environment variable `VDB_PORT`. This will prevent a check-in in the wrong port during local development.** -> **Please make sure that you don't check in the test classes with using local ports because then the execution in the CI workflow will fail (as the CI workflow uses Kubernetes execution for running integration tests).** - ## Runtime components To be able to test the _Vehicle App_ in an integrated way, the following components should be running: -- Dapr - Mosquitto - Data Broker -- Vehicle Services +- Vehicle Mock Service We distinguish between two environments for executing the _Vehicle App_ and the runtime components: - [**Local execution:**](/docs/tutorials/vehicle_app_runtime/local_runtime/) components are running locally in the development environment -- [**Kubernetes execution:**](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime/) components (and application) are deployed and running in a Kubernetes control plane (e.g. K3D) - [**Kanto execution:**](/docs/tutorials/vehicle_app_runtime/kanto_runtime/) components (and application) are deployed and running in a Kanto control plane ### Local execution @@ -92,20 +88,11 @@ When the runtime services and the application are running, integration tests can or using the testing tab in the sidebar to the left. -### Kubernetes execution (K3D) - -If you want to execute the integration tests in Kubernetes mode, make sure that K3D is up and running according to the [documentation](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime). Local ports for _Mosquitto_ and _KUKSA Data Broker_ are `1883` and `55555`. In Kubernetes mode, these ports are exposed as nodeports `31883` and `30555` respectively (see [here](https://k3d.io/v5.0.1/usage/exposing_services/#2-via-nodeport) for details). To ensure that the tests connect to correct ports of the containers, please execute the following commands in a new bash terminal: - -```bash - export MQTT_PORT=31883 && export VDB_PORT=30555 - pytest ./app/tests/integration -``` - ## Integration Tests in CI pipeline -The tests will be discovered and executed automatically in the provided [CI pipeline](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.github/workflows/ci.yml). The job `Run Integration Tests` contains all steps to set up and execute all integration tests in Kubernetes mode. Basically it is doing the same steps as you saw above: +The tests will be discovered and executed automatically in the provided [CI pipeline](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.github/workflows/ci.yml). The job `Run Integration Tests` contains all steps to set up and execute all integration tests in the Kanto runtime. Basically it is doing the same steps as you saw above: -1. start the K3D runtime +1. start the Kanto runtime 1. deploy the _Vehicle App_ container 1. set the correct MQTT and Databroker ports 1. execute the integration tests @@ -114,24 +101,19 @@ Finally the test results are collected and published as artifacts of the workflo ## Troubleshooting -### Check if the services are registered correctly in Dapr - -- Dapr extension is available as VS Code extension and gives overview of all running Dapr services. - ### Troubleshoot IntTestHelper - Make sure that the _KUKSA Data Broker_ is up and running by checking the task log. -- Make sure that you are using the right ports for local/Kubernetes execution. +- Make sure that you are using the right ports. - Make sure that you installed the correct version of the SDK (_SDV_-package). ### Troubleshoot Mosquitto (MQTT Broker) - Make sure that _Mosquitto_ is up and running by checking the task log. -- Make sure that you are using the right ports for local/Kubernetes execution. -- Use VsMqtt extension to connect to MQTT broker locally (`localhost:1883`) or in a Kubernetes cluster (`localhost:31883`) to monitor topics in MQTT broker by subscribing to all topics using `#`. +- Make sure that you are using the right ports. +- Use VsMqtt extension to connect to MQTT broker locally (`localhost:1883`) to monitor topics in MQTT broker by subscribing to all topics using `#`. ## Next steps - Concept: [Deployment Model](/docs/concepts/deployment_model/) - Concept: [Build and release process](/docs/concepts/deployment_model/vehicle_app_releases/) -- Tutorial: [Deploy a Python _Vehicle App_ with Helm](/docs/tutorials/vehicle_app_deployment/helm_deployment.md) diff --git a/content/en/docs/tutorials/vehicle_app_development/python_development.md b/content/en/docs/tutorials/vehicle_app_development/python_development.md index 117bb0d67..5e85ddb36 100644 --- a/content/en/docs/tutorials/vehicle_app_development/python_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/python_development.md @@ -281,7 +281,7 @@ Once the implementation is done, it is time to run and debug the app. In order to run the app make sure the `devenv-runtimes` package is part of your [`.velocitas.json`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.velocitas.json) (which should be the default) and the runtime is up and running. Read more about it in the [run runtime services](/docs/tutorials/vehicle_app_runtime/local_runtime) section. -Now chose one of the options to start the VehicleApp under development (including Dapr sidecar if middleware type is Dapr): +Now chose one of the options to start the VehicleApp under development: 1. Press F5 @@ -298,74 +298,26 @@ In the [introduction about debugging](/docs/tutorials/quickstart/quickstart/#how The debug session launch settings are already prepared for the `VehicleApp` in `/.vscode/launch.json`. ```JSON -"configurations": [ - { - "type": "python", - "justMyCode": false, - "request": "launch", - "name": "VehicleApp", - "program": "${workspaceFolder}/app/src/main.py", - "console": "integratedTerminal", - "preLaunchTask": "dapr-sidecar-start", - "postDebugTask": "dapr-sidecar-stop", - "env": { - "APP_PORT": "50008", - "DAPR_HTTP_PORT": "3500", - "DAPR_GRPC_PORT": "50001", - "VEHICLEDATABROKER_DAPR_APP_ID": "vehicledatabroker" +{ + "configurations": [ + { + "type": "python", + "justMyCode": false, + "request": "launch", + "name": "VehicleApp", + "program": "${workspaceFolder}/app/src/main.py", + "console": "integratedTerminal", + "env": { + "SDV_MIDDLEWARE_TYPE": "native", + "SDV_VEHICLEDATABROKER_ADDRESS": "grpc://127.0.0.1:55555", + "SDV_MQTT_ADDRESS": "mqtt://127.0.0.1:1883" + } } - } -] -``` - -We specify which python-script to run using the `program` key. With the `preLaunchTask` and `postDebugTask` keys, you can also specify tasks to run before or after debugging. In this example, DAPR is set up to start the app before and stop it again after debugging. Below you can see the 2 tasks to find in `/.vscode/tasks.json`. - -```JSON - { - "label": "dapr-sidecar-start", - "detail": "Start Dapr sidecar (with dapr run) to be present for debugging the VehicleApp (used by launch config).", - "type": "shell", - "command": "velocitas exec runtime-local run-dapr-sidecar vehicleapp --app-port 50008 --dapr-grpc-port 50001 --dapr-http-port 3500", - "group": "none", - "isBackground": true, - "presentation": { - "close": true, - "reveal": "never" - }, - "problemMatcher": { - "pattern": [ - { - "regexp": ".", - "file": 1, - "location": 2, - "message": 3 - } - ], - "background": { - "activeOnStart": true, - "beginsPattern": "^You're up and running! Dapr logs will appear here.", - "endsPattern": "." - } - }, - "hide": true - } + ] +} ``` -```JSON -{ - "label": "dapr-sidecar-stop", - "detail": "Stop Dapr sidecar after finish debugging the VehicleApp (used by launch config).", - "type": "shell", - "command": [ - "dapr stop --app-id vehicleapp" - ], - "presentation": { - "close": true, - "reveal": "never" - }, - "hide": true -}, -``` +We specify which python-script to run using the `program` key. You can adapt the configuration in `/.vscode/launch.json` and in `/.vscode/tasks.json` to your needs (e.g., change the ports, add new tasks) or even add a completely new configuration for another _Vehicle App_. @@ -374,9 +326,8 @@ Once you are done, you have to switch to the debugging tab (sidebar on the left) ## Next steps - Concept: [SDK Overview](/docs/concepts/development_model/vehicle_app_sdk) -- Tutorial: [Deploy runtime services in Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) +- Tutorial: [Deploy runtime services in Kanto](/docs/tutorials/vehicle_app_runtime/kanto_runtime) - Tutorial: [Start runtime services locally](/docs/tutorials/vehicle_app_runtime/local_runtime) - Tutorial: [Creating a Python Vehicle Model](/docs/tutorials/vehicle_model_creation) - Tutorial: [Develop and run integration tests for a _Vehicle App_](/docs/tutorials/vehicle_app_development/integration_tests) - Concept: [Deployment Model](/docs/concepts/deployment_model/) -- Tutorial: [Deploy a Python _Vehicle App_ with Helm](/docs/tutorials/vehicle_app_deployment/helm_deployment.md) diff --git a/content/en/docs/tutorials/vehicle_app_runtime/_index.md b/content/en/docs/tutorials/vehicle_app_runtime/_index.md index 95c905b77..0fd3d48d3 100644 --- a/content/en/docs/tutorials/vehicle_app_runtime/_index.md +++ b/content/en/docs/tutorials/vehicle_app_runtime/_index.md @@ -3,5 +3,5 @@ title: "Vehicle App Runtime" date: 2022-05-09T13:43:25+05:30 weight: 50 description: > - Learn how to run the _Vehicle App_ Runtime Services locally or in Kubernetes. + Learn how to run the _Vehicle App_ Runtime Services locally or in Kanto. --- diff --git a/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md b/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md index c9f469ce6..b0696da81 100644 --- a/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md +++ b/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md @@ -7,7 +7,7 @@ aliases: - /docs/tutorials/vehicle_app_runtime/kanto_runtime --- -Besides starting the vehicle runtime components [locally](/docs/tutorials/vehicle_app_runtime/local_runtime) and in [Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime), another way is to deploy them as containers using [Kanto](https://eclipse.dev/kanto/) as a container runtime. To start the runtime, we provide VS Code _Tasks_, a feature of Visual Studio Code. Additional information on tasks can be found [here](https://code.visualstudio.com/docs/editor/tasks). +Besides starting the vehicle runtime components [locally](/docs/tutorials/vehicle_app_runtime/local_runtime), another way is to deploy them as containers using [Kanto](https://eclipse.dev/kanto/). To start the runtime, we provide VS Code _Tasks_, a feature of Visual Studio Code. Additional information on tasks can be found [here](https://code.visualstudio.com/docs/editor/tasks). **Quick Start:** Each step has a task that is defined in `/.vscode/tasks.json`: @@ -57,5 +57,4 @@ More information about FeederCan can be found [here](https://github.com/eclipse/ * Concept: [Deployment Model](/docs/concepts/deployment_model) * Concept: [Build and release process](/docs/concepts/deployment_model/vehicle_app_releases) * Tutorial: [Start runtime services locally](/docs/tutorials/vehicle_app_runtime/local_runtime) -* Tutorial: [Start runtime services in Kubernetes](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) * Tutorial: [Quickstart](/docs/tutorials/quickstart.md) diff --git a/content/en/docs/tutorials/vehicle_app_runtime/kubernetes_runtime.md b/content/en/docs/tutorials/vehicle_app_runtime/kubernetes_runtime.md deleted file mode 100644 index be7efa2d3..000000000 --- a/content/en/docs/tutorials/vehicle_app_runtime/kubernetes_runtime.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Kubernetes Runtime" -date: 2022-05-09T13:43:25+05:30 -description: > - Learn how to run the _Vehicle App_ Runtime Services in Kubernetes. -aliases: - - /docs/tutorials/vehicle_app_runtime/kubernetes_runtime ---- - -Besides [local execution](/docs/tutorials/vehicle_app_runtime/local_runtime) of the vehicle runtime components, another way is to deploy them as containers in a Kubernetes control plane (like K3D). To create a K3D instance, we provide Visual Studio Code _Tasks_, a feature of Visual Studio Code. Additional information on tasks can be found [here](https://code.visualstudio.com/docs/editor/tasks). - -**Quick Start:** Each step has a task that is defined in `/.vscode/tasks.json`: - -* Core tasks (dependent on each other in the given order): - * ```K3D - Runtime Up```: Starts up the K3D runtime (Including configuring control plane and initializing Dapr). - * ```K3D - Build VehicleApp```: Builds the VehicleApp. - * ```K3D - Deploy VehicleApp```: Deploys the VehicleApp via Helm to the K3D cluster. - -Each task has the required dependencies defined. If you want to run the runtime in K3D, the task ```K3D - Deploy VehicleApp``` will create and configure everything. So it's enough to run that task. - -* Optional helper tasks: - * ```K3D - Deploy VehicleApp (without rebuild)```: Deploys the VehicleApp via Helm to the K3D cluster (without rebuilding it). That requires, that the task ```K3D - Build VehicleApp``` has been executed once before. - * ```K3D - Runtime Down```: Uninstalls and removes K3D runtime configuration. - -K3D is configured so that _Mosquitto_ and the _KUKSA Data Broker_ can be reached from outside the container over the ports ```31883``` (Mosquitto) and ```30555```(KUKSA Data Broker). The test runner, that is running outside of the cluster, can interact with these services over those ports. - -To check the status of your K3D instance (running pods, containers, logs, ...) you can either use the ```kubectl``` utility or start _K9s_ in a terminal window to have a terminal UI for interacting with the cluster. - -**Run as Bundle:** To orchestrate these tasks, you can use the task `K3D - Deploy VehicleApp`. This task runs the other tasks in the correct order. You can run this task by clicking `F1` and choose `Tasks: Run task`, then select `K3D - Deploy VehicleApp`. - -**Tasks Management:** Visual Studio Code offers various other commands concerning tasks like Start/Terminate/Restart/... You can access them by pressing F1 and typing `task`. A list with available task commands will appear. - -**Logging:** Running tasks appear in the Terminals View of Visual Studio Code. From there, you can see the logs of each running task. More detailed logs can be found inside your workspace's logs directory `./logs/*` - -## Uploading files to persistentVolume - -Some applications (e.g. FeederCAN) might make it necessary to load custom files from mounted volume. For that reason, persistentVolume is created in k3d cluster. -All the files that are located in `[./config/feedercan](https://github.com/eclipse-velocitas/devenv-runtimes/tree/main/config/feedercan)` will be uploaded to the k3d cluster dynamically. In order to mount files to the directory that is accessible by the application, please refer to the deployment configuration file: [`runtime-k3d/src/runtime/deployment/config/helm/templates/persistentVolume.yaml`](https://github.com/eclipse-velocitas/devenv-runtimes/blob/main/runtime-k3d/src/runtime/deployment/config/helm/templates/persistentVolume.yaml). - -Changes in `./config/feedercan` are automatically reflected in PersistentVolume. - -### Uploading custom candump file to FeederCAN - -FeederCAN requires a candump file. A pre-defined candump file is already part of our delivery, however, if necessary, there is an option to upload a custom file by: - -1. Creating/updating candump file with the name `candumpDefault.log` in `./config/feedercan` -1. Recreating the feedercan pod: `kubectl delete pods -l app=feedercan` - -More information about FeederCan can be found [here](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) - -## Next steps - -* Concept: [Deployment Model](/docs/concepts/deployment_model) -* Concept: [Build and release process](/docs/concepts/deployment_model/vehicle_app_releases) -* Tutorial: [Start runtime services locally](/docs/tutorials/vehicle_app_runtime/local_runtime) -* Tutorial: [Deploy a _Vehicle App_ with Kanto](/docs/tutorials/vehicle_app_runtime/kanto_runtime) -* Tutorial: [Quickstart](/docs/tutorials/quickstart.md) -* Tutorial: [Deploy a Python _Vehicle App_ with Helm](/docs/tutorials/vehicle_app_deployment/helm_deployment.md) diff --git a/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md b/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md index f28ca0143..8be4f9253 100644 --- a/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md +++ b/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md @@ -63,12 +63,10 @@ A new service can be easily started by calling it from bash script, however rest ### Codespaces -If you are using Codespaces, remember that you are working on a remote agent. That's why it could happen that the tasks are already running in the background. If that's the case a new start of the tasks will fail, since the ports are already in use. In the Dapr-tab of the sidebar you can check if there are already tasks running. Another possibility to check if the processes are already running, is to check which ports are already open. Check the Ports-tab to view all open ports (if not already open, hit `F1` and enter `View: Toggle Ports`). +If you are using Codespaces, remember that you are working on a remote agent. That's why it could happen that the tasks are already running in the background. If that's the case a new start of the tasks will fail, since the ports are already in use. Another possibility to check if the processes are already running, is to check which ports are already open. Check the Ports-tab to view all open ports (if not already open, hit `F1` and enter `View: Toggle Ports`). ## Next steps -- Tutorial: [Deploy runtime services in local Kubernetes cluster](/docs/tutorials/vehicle_app_runtime/kubernetes_runtime) - Tutorial: [Quickstart](/docs/tutorials/quickstart) - Concept: [Deployment Model](/docs/concepts/deployment_model/) - Concept: [Build and release process](/docs/concepts/deployment_model/vehicle_app_releases/) -- Tutorial: [Deploy a Python _Vehicle App_ with Helm](/docs/tutorials/vehicle_app_deployment/helm_deployment.md) diff --git a/static/assets/diagrams.drawio b/static/assets/diagrams.drawio index 706d77558..37fe2453a 100644 --- a/static/assets/diagrams.drawio +++ b/static/assets/diagrams.drawio @@ -1,6 +1,6 @@ - + - + @@ -281,9 +281,6 @@ - - - @@ -495,9 +492,6 @@ - - - @@ -663,9 +657,6 @@ - - - diff --git a/static/assets/sdk_overview.drawio.svg b/static/assets/sdk_overview.drawio.svg index 1efc43caa..1dcd4b6bc 100644 --- a/static/assets/sdk_overview.drawio.svg +++ b/static/assets/sdk_overview.drawio.svg @@ -1,661 +1,4 @@ - - - - - - - - -
-
-
- Vehicle App SDK -
-
-
- - - Vehicle App SDK - - - - - - - -
-
-
- Vehicle Model -
-
-
- - - Vehicle Model - - - - - - - - -
-
-
- based on -
-
-
- - - based on - - - - - - - -
-
-
- Semantic Model (e.g. DTDL, VSC, VSS) -
-
-
- - - Semantic Model (e.g.... - - - - - - - -
-
-
- KUKSA Data Broker -
-
-
- - - KUKSA Data Broker - - - - - - - -
-
-
- - Root Model - -
-
-
- - - Root Model - - - - - - - -
-
-
- Vehicle Services -
-
-
- - - Vehicle Services - - - - - - - -
-
-
- Vehicle Model Ontology -
-
- - - Model -
- - DataPoint -
- - DataPointInt32 -
- - DataPointString -
- -DataPointArray -
- ... -
- -
-
-
- - - Vehicle Model Ontolo... - - - - - - - -
-
-
- - Fluent query & rule construction - -
-
- Example: -
- vehicle.Cabin.Seat.Base -
- .subscribe() -
-
-
- - - Fluent query & rule construction... - - - - - - - -
-
-
- dapr Middleware -
-
-
- - - dapr Middle... - - - - - - - - -
-
-
- gRPC -
-
-
- - - gRPC - - - - - - - -
-
-
- Publish & subscribe messaging -
-
-
- - - Publish & subscribe... - - - - - - - -
-
-
- MQTT Broker -
-
-
- - - MQTT Broker - - - - - - - - - -
-
-
- MQTT -
-
-
- - - MQTT - - - - - - - - - -
-
-
- gRPC -
-
-
- - - gRPC - - - - - - - -
-
-
- Vehicle App -
- abstraction -
-
-
- - - Vehicle App... - - - - - - - - - - - -
-
-
- Cabin: Model -
-
-
- - - Cabin: Model - - - - - - - - - -
-
-
- Seat: Model -
-
-
- - - Seat: Model - - - - - - - - -
-
-
- Base: DataPointInt32 -
-
-
- - - Base: DataPointInt32 - - - - - - - - - -
-
-
- Back: DataPointInt32 -
-
-
- - - Back: DataPointInt32 - - - - - - - - - -
-
-
- SeatService: Service -
-
-
- - - SeatService: Service - - - - - - - - - -
-
-
- CurrentLocation: Model -
-
-
- - - CurrentLocation: Model - - - - - - - -
-
-
- Vehicle: Model -
-
-
- - - Vehicle: Model - - - - - - - - - - -
-
-
- Latitude: DataPointDouble -
-
-
- - - Latitude: DataPointDouble - - - - - - - -
-
-
- Longitude: DataPointDouble -
-
-
- - - Longitude: DataPointDouble - - - - - - - - -
-
-
- Data Points -
-
-
- - - Data Points - - - - - - - -
-
-
- Methods -
-
-
- - - Methods - - - - - - - - -
-
-
- Models -
-
-
- - - Models - - - - - - - - -
-
-
- Services -
-
-
- - - Services - - - - - - - - -
-
-
- gRPC -
- (subscribe(rule = 'SELECT Vehicle.Cabin.Seat.Base') -
-
-
- - - gRPC... - - - - - - - - - -
-
-
- gRPC -
- (dapr proxying) -
-
-
- - - gRPC... - - - - - - - - - -
-
-
- gRPC -
- (dapr proxying) -
-
-
- - - gRPC... - - - - - - - -
-
-
- - Example - - : -
-
-
- - - Example: - - - - - - - - -
-
-
- Base classes -
-
-
- - - Base clas... - - - - - - - - - Viewer does not support full SVG 1.1 - - - - + + + +
Vehicle App SDK
Vehicle App SDK
Vehicle Model
Vehicle Model
based on
based on
Semantic Model (e.g. DTDL, VSC, VSS)
Semantic Model (e.g....
KUKSA Data Broker
KUKSA Data Broker
Root Model
Root Model
Vehicle Services
Vehicle Services
Vehicle Model Ontology

- Model
- DataPoint
- DataPointInt32
- DataPointString
-DataPointArray
...
Vehicle Model Ontolo...
Fluent query & rule construction

Example: 
vehicle.Cabin.Seat.Base
.subscribe()
Fluent query & rule construction...
gRPC
gRPC
Publish & subscribe messaging
Publish & subscribe...
MQTT Broker
MQTT Broker
MQTT
MQTT
Vehicle App
abstraction
Vehicle App...
Cabin: Model
Cabin: Model
Seat: Model
Seat: Model
Base: DataPointInt32
Base: DataPointInt32
Back: DataPointInt32
Back: DataPointInt32
SeatService: Service
SeatService: Service
CurrentLocation: Model
CurrentLocation: Model
Vehicle: Model
Vehicle: Model
Latitude: DataPointDouble
Latitude: DataPointDouble
Longitude: DataPointDouble
Longitude: DataPointDouble
Data Points
Data Points
Methods
Methods
Models
Models
Services
Services
gRPC 
(subscribe(rule = 'SELECT Vehicle.Cabin.Seat.Base')
gRPC...
Example:
Example:
Base classes
Base clas...Text is not SVG - cannot display diff --git a/static/assets/seat_adjuster_dataflow.svg b/static/assets/seat_adjuster_dataflow.svg index 43175ffe9..871765ab3 100644 --- a/static/assets/seat_adjuster_dataflow.svg +++ b/static/assets/seat_adjuster_dataflow.svg @@ -1,4 +1,4 @@ - + -
Seat Adjuster
Vehicle App
Seat Adjuster...
Vehicle App SDK
Vehicle App SDK
Seats Service
Seats Service
Customer
Customer
KUKSA Data
Broker
Data Broker
Seat
Seat
MQTT Broker
MQTT Broker
KUKSA DBC
Feeder
CAN Feeder
Vehicle Abstraction Layer
Vehicle Abstraction Layer
Middelware
Middelware
MQTT
MQTT
gRPC
gRPC
CAN
CAN
ECU
ECUText is not SVG - cannot display +
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
Generic CAN
Feeder
Vehicle Abstraction Layer
Middelware
MQTT
gRPC
CAN
ECU
 diff --git a/static/assets/seat_adjuster_dataflow_1.svg b/static/assets/seat_adjuster_dataflow_1.svg index 9e547bf43..faa9eae09 100644 --- a/static/assets/seat_adjuster_dataflow_1.svg +++ b/static/assets/seat_adjuster_dataflow_1.svg @@ -1,4 +1,4 @@ - + -
Seat Adjuster
Vehicle App
Seat Adjuster...
Vehicle App SDK
Vehicle App SDK
Seats Service
Seats Service
Customer
Customer
KUKSA Data
Broker
Data Broker
Seat
Seat
MQTT Broker
MQTT Broker
2a
2a
5
5
7a
7a
6b
6b
KUKSA CAN
Feeder
CAN Feeder
Vehicle Abstraction Layer
Vehicle Abstraction Layer
Middelware
Middelware
4a
4a
4b
4b
6a
6a
3e
3e
3c
3c
3d
3d
8
8
1
1
2b
2b
MQTT
MQTT
gRPC
gRPC
CAN
CAN
7b
7b
ECU
ECU
3a
3a
3b
3bText is not SVG - cannot display +
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
2a
5
7a
6b
Generic
CAN Feeder
Vehicle Abstraction Layer
Middelware
4a
4b
6a
3e
3c
3d
8
1
2b
MQTT
gRPC
CAN
7b
ECU
3a
3b
 diff --git a/static/assets/seat_adjuster_dataflow_2.svg b/static/assets/seat_adjuster_dataflow_2.svg index c16326fb1..ead154066 100644 --- a/static/assets/seat_adjuster_dataflow_2.svg +++ b/static/assets/seat_adjuster_dataflow_2.svg @@ -1,4 +1,4 @@ - + -
Seat Adjuster
Vehicle App
Seat Adjuster...
Vehicle App SDK
Vehicle App SDK
Seats Service
Seats Service
Customer
Customer
KUKSA Data
Broker
Data Broker
Seat
Seat
MQTT Broker
MQTT Broker
9
9
12a
12a
Vehicle Abstraction Layer
Vehicle Abstraction Layer
Middelware
Middelware
10a
10a
11b
11b
11a
11a
10b
10b
MQTT
MQTT
gRPC
gRPC
CAN
CAN
13
13
12b
12bText is not SVG - cannot display +
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
9
12a
Vehicle Abstraction Layer
Middelware
10a
11b
11a
10b
MQTT
gRPC
CAN
13
12b
 From d2a1b104603f155e949486b5b03d5aca8df39141 Mon Sep 17 00:00:00 2001 From: Markus Petke Date: Wed, 10 Apr 2024 10:31:18 +0200 Subject: [PATCH 03/10] adapt to new kuksa repos (#120) * adapt to new kuksa repos * fix KUKSA and Databroker spelling * revert cpp changes * more fixes * fix fix fix --- .../docs/about/repository-overview/_index.md | 4 +- .../project-overview.drawio.svg | 2 +- .../about/use_cases/seat_adjuster/_index.md | 8 ++-- .../docs/about/use_cases/use_case.drawio.svg | 2 +- .../docs/concepts/development_model/_index.md | 12 ++--- .../concepts/development_model/val/_index.md | 44 +++++++++---------- .../val/val_overview.drawio.svg | 2 +- .../vehicle_app_manifest/_index.md | 2 +- .../interfaces/grpc_interface.md | 4 +- .../interfaces/vehicle_signal_interface.md | 2 +- .../vehicle_app_sdk/_index.md | 8 ++-- .../prototyping/service_integration.md | 12 ++--- .../docs/tutorials/quickstart/quickstart.md | 2 +- .../cpp_development.md | 2 +- .../integration_tests.md | 14 +++--- .../python_development.md | 2 +- .../vehicle_app_runtime/kanto_runtime.md | 2 +- .../vehicle_app_runtime/local_runtime.md | 6 +-- .../vehicle_model_creation/_index.md | 2 +- .../manual_creation_python.md | 4 +- static/assets/diagrams.drawio | 6 +-- .../assets/direct_service_invocation.drawio | 2 +- static/assets/programming_model.drawio.svg | 2 +- static/assets/project-overview.svg | 2 +- static/assets/sdk_overview.drawio.svg | 2 +- static/assets/seat_adjuster_dataflow.svg | 2 +- static/assets/seat_adjuster_dataflow_1.svg | 2 +- static/assets/seat_adjuster_dataflow_2.svg | 2 +- 28 files changed, 78 insertions(+), 78 deletions(-) diff --git a/content/en/docs/about/repository-overview/_index.md b/content/en/docs/about/repository-overview/_index.md index a2d73ab61..705d280be 100644 --- a/content/en/docs/about/repository-overview/_index.md +++ b/content/en/docs/about/repository-overview/_index.md @@ -19,8 +19,8 @@ description: > | [vehicle-app-cpp-template](https://github.com/eclipse-velocitas/vehicle-app-cpp-template) | GitHub Template repository contains an exemplary _Vehicle App_ that uses an exemplary SDK to provide access to vehicle data points and methods. The sample SDK extends the _sdv-vehicle-app-cpp-sdk_. In addition the template repository contains the development environment for Visual Studio Code for a _Vehicle App_ as well as the CI/CD workflows that can be used as blueprint for your own _Vehicle App_ written in C++. | | [vehicle-app-cpp-sdk](https://github.com/eclipse-velocitas/vehicle-app-cpp-sdk) | Provides basic functionality to write a SDK to allow access to vehicle data points and method. This includes publishing & subscribe messaging, _VehicleApp_ API, vehicle data model ontology and function-based query & rule support. | | [vehicle-model-cpp](https://github.com/eclipse-velocitas/vehicle-model-cpp) | Basic vehicle model for C++ is generated from [VSS](https://github.com/COVESA/vehicle_signal_specification/tree/master/spec) with addition of some specialized vehicle services. | -| [kuksa.val](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) | Is a part of the _Vehicle Abstraction Layer (VAL)_ of the [Eclipse KUKSA project](https://www.eclipse.org/kuksa/) and provides the KUKSA Data Broker (aka Vehicle Data Broker). The KUKSA Data Broker offers data points available in the vehicle to the _Vehicle Apps_ semantically aligned to a data model like the [Vehicle Signal Specification (VSS)](https://covesa.github.io/vehicle_signal_specification/). | -| [kuksa.val.feeders](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) | The KUKSA DBC Feeder is a generic data feeder that reads data from the vehicle's [CAN bus](https://en.wikipedia.org/wiki/CAN_bus) defined by a DBC file, maps them to a set of data points (e.g. according to the VSS) and feeds it into the Data Broker. | +| [kuksa-databroker](https://github.com/eclipse-kuksa/kuksa-databroker) | Is a part of the _Vehicle Abstraction Layer (VAL)_ of the [Eclipse KUKSA project](https://github.com/eclipse-kuksa) and provides the KUKSA Databroker. The KUKSA Databroker offers data points available in the vehicle to the _Vehicle Apps_ semantically aligned to a data model like the [Vehicle Signal Specification (VSS)](https://covesa.github.io/vehicle_signal_specification/). | +| [kuksa-can-provider](https://github.com/eclipse-kuksa/kuksa-can-provider) | The KUKSA CAN Provider is a generic data feeder that reads data from the vehicle's [CAN bus](https://en.wikipedia.org/wiki/CAN_bus) defined by a DBC file, maps them to a set of data points (e.g. according to the VSS) and feeds it into the Databroker. | | [kuksa.val.services](https://github.com/eclipse/kuksa.val.services) | Provides exemplary vehicle services and respective implementations that illustrates how to interact with in-vehicle components and services via an unified access that is semantically described e.g. in the [Vehicle Service Catalog (VSC)](https://github.com/COVESA/vehicle_service_catalog). | | [release-documentation-action](https://github.com/eclipse-velocitas/release-documentation-action) | GitHub Action to generate a release documentation from the CI workflow output by rendering it to markdown files so that this can be easily published with GitHub Pages. | | [license-check](https://github.com/eclipse-velocitas/license-check) | GitHub Action to collect the licenses of the used components and can be configured to fail with an error message on invalid licenses. | diff --git a/content/en/docs/about/repository-overview/project-overview.drawio.svg b/content/en/docs/about/repository-overview/project-overview.drawio.svg index 4ef515d84..e1d6afdbb 100644 --- a/content/en/docs/about/repository-overview/project-overview.drawio.svg +++ b/content/en/docs/about/repository-overview/project-overview.drawio.svg @@ -1 +1 @@ -
devenv-runtimes
(e.g. local runtime)
[Repository]
devenv-runtimes...
extends
extends
VehicleApp SDK
VehicleApp SDK
Seat Adjuster VehicleApp
Seat Adjuster Vehicl...
uses
uses
uses
uses
feeds
feeds
Seats Service
Seats Service
test
test
test
test
GH Workflows
GH Workflows
Kuksa.VAL
Kuksa.VAL
vehicle-app-*-template
[Repository]
vehicle-app-*-template...
vehicle-app-*-sdk
[Repository]
vehicle-app-*-sdk...
Unit tests
Unit tests
Integration tests
Integration tests
SDV package
SDV package
Unit tests
Unit tests
Integration tests
Integration tests
Vehicle Data Broker
Vehicle Data Broker
Developer Manual
Developer Manual
Data Feeder
Data Feeder
.velocitas.json
.velocitas.json
devenv-*
[Repository]
devenv-*...
uses content
uses content
DevContainer
DevContainer
manages sync
manages sync
installs
installs
references
references
test
test
Velocitas CLI
[Repository]
Velocitas CLI...
test
test
Velocitas CLI
[tool]
Velocitas CLI...
creates
creates
reads
reads
runs with
devcontainer-base-image
[Repository]
runs with...
Render Action
Render Action
devenv-github-workflows
[Repository]
devenv-github-workflows[Repository]
GH Workflows
GH Workflows
sync
sync
release-documentation-action
[Repository]
release-documentation-action...
Render Action
Render Action
Package Action
Package Acti...
uses
usesText is not SVG - cannot display +
devenv-runtimes
(e.g. local runtime)
[Repository]
devenv-runtimes...
extends
extends
VehicleApp SDK
VehicleApp SDK
Seat Adjuster VehicleApp
Seat Adjuster Vehicl...
uses
uses
uses
uses
feeds
feeds
Seats Service
Seats Service
test
test
test
test
GH Workflows
GH Workflows
KUKSA.VAL
KUKSA.VAL
vehicle-app-*-template
[Repository]
vehicle-app-*-template...
vehicle-app-*-sdk
[Repository]
vehicle-app-*-sdk...
Unit tests
Unit tests
Integration tests
Integration tests
SDV package
SDV package
Unit tests
Unit tests
Integration tests
Integration tests
KUKSA Databroker
KUKSA Databroker
Developer Manual
Developer Manual
Data Feeder
Data Feeder
.velocitas.json
.velocitas.json
devenv-*
[Repository]
devenv-*...
uses content
uses content
DevContainer
DevContainer
manages sync
manages sync
installs
installs
references
references
test
test
Velocitas CLI
[Repository]
Velocitas CLI...
test
test
Velocitas CLI
[tool]
Velocitas CLI...
creates
creates
reads
reads
runs with
devcontainer-base-image
[Repository]
runs with...
Render Action
Render Action
devenv-github-workflows
[Repository]
devenv-github-workflows[Repository]
GH Workflows
GH Workflows
sync
sync
release-documentation-action
[Repository]
release-documentation-action...
Render Action
Render Action
Package Action
Package Acti...
uses
usesText is not SVG - cannot display diff --git a/content/en/docs/about/use_cases/seat_adjuster/_index.md b/content/en/docs/about/use_cases/seat_adjuster/_index.md index 25d70a304..f4368556c 100644 --- a/content/en/docs/about/use_cases/seat_adjuster/_index.md +++ b/content/en/docs/about/use_cases/seat_adjuster/_index.md @@ -13,7 +13,7 @@ description: > In the scenario of a car sharing company, the goal is to provide the functionality of automatically adjusting the driver's seat position based on their preferred settings stored in their profile. When the driver unlocks the car, a request is sent to the vehicle to retrieve the preferred seat position. This is where your implementation begins. -The _Seat Adjuster Vehicle App_ receives a MQTT message containing the seat position, which then triggers a seat adjustment command through the _Seat Service_ to change the seat position. Additionally, to ensure convenience for future trips, the car sharing company saves the driver's preferred seat position and utilizes it accordingly. _The Seat Adjuster Vehicle App_ subscribes to the seat position, receiving updates from the _Data Broker_, which streams data from the _Seat Service_. +The _Seat Adjuster Vehicle App_ receives a MQTT message containing the seat position, which then triggers a seat adjustment command through the _Seat Service_ to change the seat position. Additionally, to ensure convenience for future trips, the car sharing company saves the driver's preferred seat position and utilizes it accordingly. _The Seat Adjuster Vehicle App_ subscribes to the seat position, receiving updates from the _Databroker_, which streams data from the _Seat Service_. ## Requesting new seat position @@ -26,7 +26,7 @@ The _Seat Adjuster Vehicle App_ receives a MQTT message containing the seat posi ``` 2. The **Seat Adjuster _Vehicle App_** that has subscribed to this topic, receives the request to change the seat position as a MQTT message. -3. The **Seat Adjuster _Vehicle App_** gets the current vehicle speed from the data broker, which is fed by the **CAN Feeder (KUKSA DBC Feeder)**. +3. The **Seat Adjuster _Vehicle App_** gets the current vehicle speed from the Databroker, which is fed by the **CAN Provider (KUKSA CAN Provider)**. 4. With the support of the **_Vehicle App_ SDK**, the **Seat Adjuster _Vehicle App_** triggers a seat adjustment command of the **Seat Service** via gRPC in the event that the speed is equal to zero. Hint: This is a helpful convenience check but not a safety check. 5. The **Seat Service** moves the seat to the new position via CAN messages. 6. The **Seat Service** returns OK or an error code as gRPC status to the **Seat Adjuster _Vehicle App_**. @@ -49,8 +49,8 @@ The _Seat Adjuster Vehicle App_ receives a MQTT message containing the seat posi ![seat_adjuster_dataflow_2](./seat_adjuster_dataflow_2.png) 1. If the seat position will be changed by the driver, the new seat position will be sent to the **Seat Service** via CAN. -2. The **Seat Service** streams the seat position via gRPC to the **KUKSA Data Broker** since it was registered beforehand. -3. The **Seat Adjuster _Vehicle App_** that subscribed to the seat position receives the new seat position from the **KUKSA Data Broker** as a result. +2. The **Seat Service** streams the seat position via gRPC to the **KUKSA Databroker** since it was registered beforehand. +3. The **Seat Adjuster _Vehicle App_** that subscribed to the seat position receives the new seat position from the **KUKSA Databroker** as a result. 4. The **Seat Adjuster _Vehicle App_** publishes this on topic `seatadjuster/currentPosition` with the payload: ```json diff --git a/content/en/docs/about/use_cases/use_case.drawio.svg b/content/en/docs/about/use_cases/use_case.drawio.svg index 47ae8187e..0a304316b 100755 --- a/content/en/docs/about/use_cases/use_case.drawio.svg +++ b/content/en/docs/about/use_cases/use_case.drawio.svg @@ -1,4 +1,4 @@ -
Vehicle
Model
and SDK
Vehicle...
Seat
Seat
Cloud Connectivity
Cloud Connecti...
ECU
ECU
Business
logic
Business...
Vehicle App
Vehicle App
Vehicle App Development Toolchain
Vehicle App Development Toolchain
Vehicle Data Broker
Vehicle Data...

Data Providers
Data Provide...

Vehicle Services
(e.g. Seat Service)
Vehicle Serv...
Vehicle Abstraction Layer
Vehicle Abstraction LayerVehicle AppDeveloperViewer does not support full SVG 1.1 +
Vehicle
Model
and SDK
Vehicle...
Seat
Seat
Cloud Connectivity
Cloud Connecti...
ECU
ECU
Business
logic
Business...
Vehicle App
Vehicle App
Vehicle App Development Toolchain
Vehicle App Development Toolchain
KUKSA Databroker
Vehicle Data...

Data Providers
Data Provide...

Vehicle Services
(e.g. Seat Service)
Vehicle Serv...
Vehicle Abstraction Layer
Vehicle Abstraction LayerVehicle AppDeveloperViewer does not support full SVG 1.1 diff --git a/content/en/docs/concepts/development_model/_index.md b/content/en/docs/concepts/development_model/_index.md index 0062d6a9a..cbb0e76c1 100644 --- a/content/en/docs/concepts/development_model/_index.md +++ b/content/en/docs/concepts/development_model/_index.md @@ -25,7 +25,7 @@ The Vehicle Applications (_Vehicle Apps_) contain the business logic that needs ### Vehicle Models -A Vehicle Model makes it possible to easily get vehicle data from the [Data Broker](#data-broker) and to execute remote procedure calls over gRPC against [Vehicle Services](#vehicle-services) and other [_Vehicle Apps_](#vehicle-apps). It is generated from the underlying [semantic models](#semantic-models) for a concrete programming language as a graph-based, strongly-typed, intellisense-enabled library. The elements of the vehicle models are defined by the [SDKs](#sdks). +A Vehicle Model makes it possible to easily get vehicle data from the [Databroker](#kuksa-databroker) and to execute remote procedure calls over gRPC against [Vehicle Services](#vehicle-services) and other [_Vehicle Apps_](#vehicle-apps). It is generated from the underlying [semantic models](#semantic-models) for a concrete programming language as a graph-based, strongly-typed, intellisense-enabled library. The elements of the vehicle models are defined by the [SDKs](#sdks). ### SDKs @@ -34,15 +34,15 @@ SDKs are available for Python and C++, currently. Further SDKs for Rust and C ar ### Vehicle Services -Vehicle Services provide service interfaces to control actuators or to trigger (complex) actions. E.g. they communicate with the vehicle internal networks like CAN or Ethernet, which are connected to actuators, electronic control units (ECUs) and other vehicle computers (VCs). They may provide a simulation mode to run without a network interface. Vehicle services may feed data to the [Data Broker](#data-broker) and may expose gRPC endpoints, which can be invoked by [_Vehicle Apps_](#vehicle-apps) over a [Vehicle Model](#vehicle-models). +Vehicle Services provide service interfaces to control actuators or to trigger (complex) actions. E.g. they communicate with the vehicle internal networks like CAN or Ethernet, which are connected to actuators, electronic control units (ECUs) and other vehicle computers (VCs). They may provide a simulation mode to run without a network interface. Vehicle services may feed data to the [Databroker](#kuksa-databroker) and may expose gRPC endpoints, which can be invoked by [_Vehicle Apps_](#vehicle-apps) over a [Vehicle Model](#vehicle-models). -### KUKSA Data Broker (aka Vehicle Data Broker) {#data-broker} +### KUKSA Databroker -Vehicle data is stored in the KUKSA Data Broker conforming to an underlying [Semantic Model](#semantic-models) like [VSS](https://covesa.github.io/vehicle_signal_specification/). [_Vehicle Apps_](#vehicle-apps) can either pull this data or subscribe for updates. In addition, it supports rule-based access to reduce the number of updates sent to the _Vehicle App_. +Vehicle data is stored in the KUKSA Databroker conforming to an underlying [Semantic Model](#semantic-models) like [VSS](https://covesa.github.io/vehicle_signal_specification/). [_Vehicle Apps_](#vehicle-apps) can either pull this data or subscribe for updates. In addition, it supports rule-based access to reduce the number of updates sent to the _Vehicle App_. ### Semantic models -The Vehicle Signal Specification ([VSS](https://covesa.github.io/vehicle_signal_specification/)) provides a domain taxonomy for vehicle signals and defines the vehicle data semantically, which is exchanged between _Vehicle Apps_ and the Data Broker. +The Vehicle Signal Specification ([VSS](https://covesa.github.io/vehicle_signal_specification/)) provides a domain taxonomy for vehicle signals and defines the vehicle data semantically, which is exchanged between _Vehicle Apps_ and the Databroker. The Vehicle Service Catalog ([VSC](https://github.com/COVESA/vehicle_service_catalog#vehicle-service-catalog)) extends VSS with functional remote procedure call definitions and semantically defines the gRPC interfaces of Vehicle Services and _Vehicle Apps_. @@ -52,7 +52,7 @@ The Velocitas SDK is using [VSS](https://covesa.github.io/vehicle_signal_specifi ### Communication Protocols -Asynchronous communication between [_Vehicle Apps_](#vehicle-apps) and other vehicle components, as well as cloud connectivity, is facilitated through [MQTT](https://mqtt.org/) messaging. Direct, synchronous communication between [_Vehicle Apps_](#vehicle-apps), [Vehicle Services](#vehicle-services) and the [Data Broker](#data-broker) is based on the [gRPC](https://grpc.io/) protocol. +Asynchronous communication between [_Vehicle Apps_](#vehicle-apps) and other vehicle components, as well as cloud connectivity, is facilitated through [MQTT](https://mqtt.org/) messaging. Direct, synchronous communication between [_Vehicle Apps_](#vehicle-apps), [Vehicle Services](#vehicle-services) and the [Databroker](#kuksa-databroker) is based on the [gRPC](https://grpc.io/) protocol. ### Middleware Abstraction diff --git a/content/en/docs/concepts/development_model/val/_index.md b/content/en/docs/concepts/development_model/val/_index.md index 0568f63a0..9e124c9f0 100644 --- a/content/en/docs/concepts/development_model/val/_index.md +++ b/content/en/docs/concepts/development_model/val/_index.md @@ -8,7 +8,7 @@ resources: - src: "**val_architecture*.png" - src: "**val_overview*.drawio.svg" description: > - Learn about the main concepts and components of the vehicle abstraction and how it relates to the [Eclipse KUKSA project](https://www.eclipse.org/kuksa/). + Learn about the main concepts and components of the vehicle abstraction and how it relates to the [Eclipse KUKSA project](https://github.com/eclipse-kuksa). --- ## Introduction @@ -16,11 +16,11 @@ description: > The Vehicle Abstraction Layer (VAL) enables access to the systems and functions of a vehicle via a unified - or even better - a standardized _Vehicle API_ abstracting from the details of the end-to-end architecture of the vehicle. The unified API enables _Vehicle Apps_ to run on different vehicle architectures of a single OEM. _Vehicle Apps_ can be even implemented OEM-agnostic, if using an API based on a standard like the [COVESA Vehicle Signal Specification (VSS)](https://covesa.github.io/vehicle_signal_specification/). The _Vehicle API_ eliminates the need to know the source, destination, and format of signals for the vehicle system. -The Eclipse Velocitas project is using the VAL of the [_Eclipse KUKSA project_](https://www.eclipse.org/kuksa/), also called _KUKSA.VAL_. +The Eclipse Velocitas project is using the VAL of the [_Eclipse KUKSA project_](https://github.com/eclipse-kuksa), also called _KUKSA.VAL_. KUKSA.VAL does not provide a concrete VAL. That's up to you as an OEM (vehicle manufacturer) or as a supplier. But KUKSA.VAL provides the components and tools that helps you to implement a VAL for your chosen end-to-end architecture. Also, it can support you to simulate the vehicle hardware during the development phase of an _Vehicle App_ or Service. -KUKSA.VAL provides you with ready-to-use generic components for the signal-based access to the vehicle, like the _KUKSA Data Broker_ and the generic _Data Providers_ (aka _Data Feeders_). +KUKSA.VAL provides you with ready-to-use generic components for the signal-based access to the vehicle, like the _KUKSA Databroker_ and the generic _Data Providers_ (aka _Data Feeders_). It also provides you reference implementations of certain _Vehicle Services_, like the _Seat Service_ and the _HVAC Service_. ## Architecture @@ -29,39 +29,39 @@ The image below shows the main components of the VAL and its relation to the [Ve ![Overview of the VAL architecture](./val_overview.drawio.svg) -### KUKSA Data Broker (aka Vehicle Data Broker) +### KUKSA Databroker -The [KUKSA Data Broker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) is a gRPC service acting as a broker of vehicle data / signals also called _data points_ in the following. +The [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker) is a gRPC service acting as a broker of vehicle data / signals also called _data points_ in the following. It provides central access to vehicle data points arranged in a - preferably standardized - vehicle data model like the COVESA VSS or others. But this is not a must, it is also possible to use your own (proprietary) vehicle model or to extend the COVESA VSS with your specific extensions via [VSS _overlays_](https://covesa.github.io/vehicle_signal_specification/rule_set/overlay/). Data points represent certain states of a vehicle, like the current vehicle speed or the currently applied gear. Data points can represent sensor values like the vehicle speed or engine temperature, actuators like the wiper mode, and immutable attributes of the vehicle like the needed fuel type(s) of the vehicle, engine displacement, maximum power, etc. Data points factually belonging together are typically arranged in branches and sub-branches of a tree structure (like [this example](https://covesa.github.io/vehicle_signal_specification/introduction/overview/#example) on the COVESA VSS site). -The KUKSA Data Broker is implemented in Rust, can run in a container and provides services to get data points, update data points and for subscribing to automatic notifications on data point changes. +The KUKSA Databroker is implemented in Rust, can run in a container and provides services to get data points, update data points and for subscribing to automatic notifications on data point changes. Filter- and rule-based subscriptions of data points can be used to reduce the number of updates sent to the subscriber. ### Data Providers / Data Feeders -Conceptually, a data provider is the responsible to take care for a certain set of data points: It provides updates of sensor data from the vehicle to the data broker and forwards updates of actuator values to the vehicle. The set of data points a data provider maintains may depend on the network interface (e.g. CAN bus) via that those data is accessible or it can depend on a certain use case the provider is responsible for (like seat control). +Conceptually, a data provider is the responsible to take care for a certain set of data points: It provides updates of sensor data from the vehicle to the Databroker and forwards updates of actuator values to the vehicle. The set of data points a data provider maintains may depend on the network interface (e.g. CAN bus) via that those data is accessible or it can depend on a certain use case the provider is responsible for (like seat control). -Eclipse KUKSA provides several _generic_ [_Data Providers_](https://github.com/eclipse/kuksa.val.feeders) for different datasources. -As of today, Eclipse Velocitas only utilizes the generic [CAN feeder (KUKSA DBC Feeder)](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) implemented in Python, which reads data from a CAN bus based on mappings specified in e.g. a CAN network description (dbc) file. -The feeder uses a mapping file and data point metadata to convert the source data to data points and injects them into the data broker using its `Collector` gRPC interface. -The feeder automatically reconnects to the data broker in the event that the connection is lost. +Eclipse KUKSA provides several _generic_ [_Data Providers_](https://github.com/eclipse-kuksa#providers-exchanging-data-with-databrokerserver) for different datasources. +As of today, Eclipse Velocitas only utilizes the generic [CAN Provider (KUKSA CAN Provider)](https://github.com/eclipse-kuksa/kuksa-can-provider) implemented in Python, which reads data from a CAN bus based on mappings specified in e.g. a CAN network description (dbc) file. +The feeder uses a mapping file and data point metadata to convert the source data to data points and injects them into the Databroker using its `Collector` gRPC interface. +The feeder automatically reconnects to the Databroker in the event that the connection is lost. ### Vehicle Services A vehicle service offers a _Vehicle App_ to interact with the vehicle systems on a RPC-like basis. It can provide service interfaces to control actuators or to trigger (complex) actions, or provide interfaces to get data. -It communicates with the Hardware Abstraction to execute the underlying services, but may also interact with the data broker. +It communicates with the Hardware Abstraction to execute the underlying services, but may also interact with the Databroker. The [KUKSA.VAL Services repository](https://github.com/eclipse/kuksa.val.services/) contains examples illustrating how such kind of vehicle services can be built. ### Hardware Abstraction Data feeders rely on hardware abstraction. Hardware abstraction is project/platform specific. -The reference implementation relies on **SocketCAN** and **vxcan**, see [kuksa.val.feeders](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val). +The reference implementation relies on **SocketCAN** and **vxcan**, see [KUKSA CAN Provider](https://github.com/eclipse-kuksa/kuksa-can-provider). The hardware abstraction may offer replaying (e.g., CAN) data from a file (can dump file) when the respective data source (e.g., CAN) is not available. {{< imgproc val_architecture Resize "800x" >}} @@ -72,14 +72,14 @@ The hardware abstraction may offer replaying (e.g., CAN) data from a file (can d The VAL offers an information flow between vehicle networks and vehicle services. The data that can flow is ultimately limited to the data available through the Hardware Abstraction, which is platform/project-specific. -The KUKSA Data Broker offers read/subscribe access to data points based on a gRPC service. The data points which are actually available are defined by the set of feeders providing the data into the broker. -Services (like the [seat service](https://github.com/eclipse/kuksa.val.services/tree/main/seat_service)) define which CAN signals they listen to and which CAN signals they send themselves, see [documentation](https://github.com/eclipse/kuksa.val.services/blob/main/seat_service/src/lib/seat_adjuster/seat_controller/README.md). -Service implementations may also interact as feeders with the data broker. +The KUKSA Databroker offers read/subscribe access to data points based on a gRPC service. The data points which are actually available are defined by the set of feeders providing the data into the broker. +Services (like the [seat service](https://github.com/eclipse-kuksa/kuksa-incubation/tree/main/seat_service)) define which CAN signals they listen to and which CAN signals they send themselves, see [documentation](https://github.com/eclipse-kuksa/kuksa-incubation/blob/main/seat_service/src/lib/seat_adjuster/seat_controller/README.md). +Service implementations may also interact as feeders with the Databroker. -### Data flow when a _Vehicle App_ uses the KUKSA Data Broker +### Data flow when a _Vehicle App_ uses the KUKSA Databroker {{< imgproc dataflow_broker Resize "800x" >}} - Architectural representation of the KUKSA data broker data flow + Architectural representation of the KUKSA Databroker data flow {{< /imgproc >}} ### Data flow when a _Vehicle App_ uses a Vehicle Service @@ -90,11 +90,11 @@ Service implementations may also interact as feeders with the data broker. ## Source Code -Source code and build instructions are available in the respective KUKSA.VAL repositories: +Source code and build instructions are available in the respective KUKSA repositories: -* [KUKSA Data Broker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) -* [KUKSA DBC Feeder](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) -* [KUKSA example services](https://github.com/eclipse/kuksa.val.services/) +* [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker) +* [KUKSA CAN Provider](https://github.com/eclipse-kuksa/kuksa-can-provider) +* [KUKSA example providers](https://github.com/eclipse-kuksa#providers-exchanging-data-with-databrokerserver) ## Guidelines diff --git a/content/en/docs/concepts/development_model/val/val_overview.drawio.svg b/content/en/docs/concepts/development_model/val/val_overview.drawio.svg index cf5dd1afe..3063ddcf7 100755 --- a/content/en/docs/concepts/development_model/val/val_overview.drawio.svg +++ b/content/en/docs/concepts/development_model/val/val_overview.drawio.svg @@ -1,4 +1,4 @@ -
Vehicle
busses / service "rails"
Vehicle...
Unified/
standardized Vehicle API
Unified/...
KUKSA
Data Broker:
VSS-based signal API
KUKSA...
«VehicleService»
e.g. Seat Service
Provider
«VehicleService»...
«VehicleService»
e.g. HVAC Service
Provider
«VehicleService»...
«VehicleService»
... Service
Provider
«VehicleService»...
«VehicleApp»
e.g. SeatAdjuster
«VehicleApp»...
«VehicleApp»
e.g. DogMode
«VehicleApp»...
«gRPC»
Broker If
«gRPC»...
«gRPC»
Seat Service If
«gRPC»...
«gRPC»
HVAC Service If
«gRPC»...
«gRPC»
... Service If
«gRPC»...
«DataProvider»
DBC Feeder
«DataProvider»...
«DataProvider»
SOME/IP Feeder
«DataProvider»...
«DataProvider»
... Feeder
«DataProvider»...
«gRPC»
Collector If
«gRPC»...
«VehicleApp»
...
«VehicleApp»...
Vehicle Abstraction Layer
Vehicle A...
Vehicle App Layer
Vehicle A...
Seat
ECU
Seat...
HVAC
ECU
HVAC...
Vehicle
Computer
Vehicle...SOME/IP...CAN
Vehicle Hardware
Vehicle H...UnifiedOEM/vehiclespecificViewer does not support full SVG 1.1 +
Vehicle
busses / service "rails"
Vehicle...
Unified/
standardized Vehicle API
Unified/...
KUKSA
Databroker:
VSS-based signal API
KUKSA...
«VehicleService»
e.g. Seat Service
Provider
«VehicleService»...
«VehicleService»
e.g. HVAC Service
Provider
«VehicleService»...
«VehicleService»
... Service
Provider
«VehicleService»...
«VehicleApp»
e.g. SeatAdjuster
«VehicleApp»...
«VehicleApp»
e.g. DogMode
«VehicleApp»...
«gRPC»
Broker If
«gRPC»...
«gRPC»
Seat Service If
«gRPC»...
«gRPC»
HVAC Service If
«gRPC»...
«gRPC»
... Service If
«gRPC»...
«DataProvider»
DBC Feeder
«DataProvider»...
«DataProvider»
SOME/IP Feeder
«DataProvider»...
«DataProvider»
... Feeder
«DataProvider»...
«gRPC»
Collector If
«gRPC»...
«VehicleApp»
...
«VehicleApp»...
Vehicle Abstraction Layer
Vehicle A...
Vehicle App Layer
Vehicle A...
Seat
ECU
Seat...
HVAC
ECU
HVAC...
Vehicle
Computer
Vehicle...SOME/IP...CAN
Vehicle Hardware
Vehicle H...UnifiedOEM/vehiclespecificViewer does not support full SVG 1.1 diff --git a/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md b/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md index 48208b08f..88c1c9f8e 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md +++ b/content/en/docs/concepts/development_model/vehicle_app_manifest/_index.md @@ -81,7 +81,7 @@ To fully understand the _AppManifest_, let's have a look at **who** interacts wi { "type": "grpc-interface", "config": { - "src": "https://raw.githubusercontent.com/eclipse/kuksa.val.services/main/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto", + "src": "https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto", "required": { "methods": [ "Move", "MoveComponent" ] }, diff --git a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/grpc_interface.md b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/grpc_interface.md index 5481f6a05..9d090752c 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/grpc_interface.md +++ b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/grpc_interface.md @@ -26,7 +26,7 @@ If a _Vehicle App_ provides a `grpc-interface` - a server stub embedded into the {{
}} | Attribute | Type | Example value | Description | |-|-|-|-| -| `src` | string | `"https://raw.githubusercontent.com/eclipse/kuksa.val.services/v0.2.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto"` | URI of the used protobuf specification of the service. URI may point to a local file or to a file provided by a server. It is generally recommended that a **stable** proto file is used. I.e. one that is already released under a proper tag rather than an in-development proto file. | +| `src` | string | `"https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto"` | URI of the used protobuf specification of the service. URI may point to a local file or to a file provided by a server. It is generally recommended that a **stable** proto file is used. I.e. one that is already released under a proper tag rather than an in-development proto file. | | `required.methods` | array | Array of service's methods that are accessed by the application. In addition to access control the methods attribute may be used to determine backward or forward compatibility i.e. if semantics of a service's interface did not change but methods were added or removed in a future version. | | `required.methods.[].name` | string | `"Move"`, `"MoveComponent"` | Name of the method that the application would like to access | | `provided` | object | `{}` | Reserved object indicating that the interface is provided. Might be filled with further configuration values. @@ -38,7 +38,7 @@ If a _Vehicle App_ provides a `grpc-interface` - a server stub embedded into the { "type": "grpc-interface", "config": { - "src": "https://raw.githubusercontent.com/eclipse/kuksa.val.services/v0.2.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto", + "src": "https://raw.githubusercontent.com/eclipse-kuksa/kuksa-incubation/0.4.0/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto", "required": { "methods": [ "Move", "MoveComponent" diff --git a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md index e9c2999eb..de6f7061b 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md +++ b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md @@ -17,7 +17,7 @@ The _Vehicle Signal Interface_ formerly known as [_Vehicle Model_](/docs/concept If a _Vehicle App_ requires a `vehicle-signal-interface`, it will act as a consumer of datapoints already available in the system. If, on the other hand, a _Vehicle App_ provides a `vehicle-signal-interface`, it will act as a provider (formerly feeder in KUKSA terms) of the declared datapoints. -Furthermore, in the source code generated by this functional interface, a connection to [Kuksa Databroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) will be established via the configured Velocitas middleware. It uses the `broker.proto` if provided by the Kuksa Databroker to connect via gRPC. A seperate declaration of a `grpc-interface` for the databroker is **NOT** required. +Furthermore, in the source code generated by this functional interface, a connection to [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker) will be established via the configured Velocitas middleware. It uses the `broker.proto` if provided by the KUKSA Databroker to connect via gRPC. A seperate declaration of a `grpc-interface` for the databroker is **NOT** required. More information: [Vehicle Model Creation](/docs/tutorials/vehicle_model_creation/) diff --git a/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md b/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md index 981c05ae5..acea4a93e 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md +++ b/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md @@ -19,7 +19,7 @@ The _Vehicle App_ SDK consists of the following building blocks: - **[Middleware integration](#middleware-integration):** Vehicle Models can contain gRPC stubs to communicate with _Vehicle Services_. gRPC communication is integrated natively. -- **[Fluent query & rule construction](#fluent-query--rule-construction):** Based on a concrete Vehicle Model, the SDK is able to generate queries and rules against the KUKSA Data Broker to access the real values of the data points that are defined in the vehicle model. +- **[Fluent query & rule construction](#fluent-query--rule-construction):** Based on a concrete Vehicle Model, the SDK is able to generate queries and rules against the KUKSA Databroker to access the real values of the data points that are defined in the vehicle model. - **[Publish & subscribe messaging](#publish--subscribe-messaging):** The SDK supports publishing messages to a MQTT broker and subscribing to topics of a MQTT broker. @@ -305,7 +305,7 @@ private: ## Fluent query & rule construction -A set of query methods like `get()`, `where()`, `join()` etc. are provided through the `Model` and `DataPoint` base classes. These functions make it possible to construct SQL-like queries and subscriptions in a fluent language, which are then transmitted through the gRPC interface to the KUKSA Data Broker. +A set of query methods like `get()`, `where()`, `join()` etc. are provided through the `Model` and `DataPoint` base classes. These functions make it possible to construct SQL-like queries and subscriptions in a fluent language, which are then transmitted through the gRPC interface to the KUKSA Databroker. ### Query examples @@ -472,11 +472,11 @@ subscribeToTopic("seatadjuster/setPosition/request")->onItem([this](auto&& item) ## Vehicle App abstraction -_Vehicle Apps_ are inherited from the `VehicleApp` base class. This enables the _Vehicle App_ to use the Publish & Subscribe messaging and to connect to the KUKSA Data Broker. +_Vehicle Apps_ are inherited from the `VehicleApp` base class. This enables the _Vehicle App_ to use the Publish & Subscribe messaging and to connect to the KUKSA Databroker. The `Vehicle Model` instance is passed to the constructor of the `VehicleApp` class and should be stored in a member variable (e.g. `self.vehicle` for Python, `std::shared_ptr m_vehicle;` for C++), to be used by all methods within the application. -Finally, the `run()` method of the `VehicleApp` class is called to start the _Vehicle App_ and register all MQTT topic and Data Broker subscriptions. +Finally, the `run()` method of the `VehicleApp` class is called to start the _Vehicle App_ and register all MQTT topic and Databroker subscriptions. {{% alert title="Implementation detail" color="warning" %}} In Python, the subscriptions are based on `asyncio`, which makes it necessary to call the `run()` method with an active `asyncio event_loop`. diff --git a/content/en/docs/tutorials/prototyping/service_integration.md b/content/en/docs/tutorials/prototyping/service_integration.md index 692887b42..9b46d9568 100644 --- a/content/en/docs/tutorials/prototyping/service_integration.md +++ b/content/en/docs/tutorials/prototyping/service_integration.md @@ -8,7 +8,7 @@ description: > Services can make sure, that when you write a VSS data point, something is actually happening. Eclipse Velocitas has an example seat or hvac service. If your _Vehicle App_ makes use of e.g. `Vehicle.Cabin.Seat.Row1.Pos1.Position` or other seat/hvac specific data points you are in for some real action. To learn more, visit [_Vehicle Services_](/docs/concepts/development_model/val/#vehicle-services). -Our maintained [`devenv-runtimes`](https://github.com/eclipse-velocitas/devenv-runtimes) package ([Velocitas Lifecycle Management](/docs/concepts/lifecycle_management)) comes with the support of adding further _Vehicle Services_ to the `runtime.json` of a package. More information [here](/docs/concepts/lifecycle_management/packages/development/#configuration-of-runtime-packages). (A general vehicle _mock service_ is also coming soon!) +Our maintained [`devenv-runtimes`](https://github.com/eclipse-velocitas/devenv-runtimes) package ([Velocitas Lifecycle Management](/docs/concepts/lifecycle_management)) comes with the support of adding further _Vehicle Services_ to the `runtime.json` of a package. More information [here](/docs/concepts/lifecycle_management/packages/development/#configuration-of-runtime-packages). ### Modify existing services @@ -16,11 +16,11 @@ For more advanced usage you can also try to modify existing services. Check out ### Create your own services -If you want to create your own service the [KUKSA.VAL Services repository](https://github.com/eclipse/kuksa.val.services/) contains examples illustrating how such kind of vehicle services can be built. You need to write an application that talks to _KUKSA.VAL_ listening to changes of a _target value_ of some VSS data point and then do whatever you want. You can achieve this by using the _KUKSA.VAL_ [gRPC API](https://github.com/eclipse/kuksa.val/tree/master/proto/kuksa/val/v1) with any programming language of your choice (learn more about [gRPC](https://grpc.io)). +If you want to create your own service the [KUKSA.VAL Services repository](https://github.com/eclipse/kuksa.val.services/) contains examples illustrating how such kind of vehicle services can be built. You need to write an application that talks to _KUKSA.VAL_ listening to changes of a _target value_ of some VSS data point and then do whatever you want. You can achieve this by using the _KUKSA.VAL_ [gRPC API](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/kuksa/val/v1) with any programming language of your choice (learn more about [gRPC](https://grpc.io)). -### Mock Service and Mock Service Integration +### Mock Provider and Mock Provider Integration -[The Vehicle Mock Service](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service) is a dummy service allowing to control all specified actuator- and sensor-signals via a configuration file. These configuration files are expressed in a Python-based domain-specific language (DSL). -The default behavior is predefined in [mock.py](https://github.com/eclipse/kuksa.val.services/blob/main/mock_service/mock.py) +[The Vehicle Mock Provider](https://github.com/eclipse-kuksa/kuksa-mock-provider) is a dummy service allowing to control all specified actuator- and sensor-signals via a configuration file. These configuration files are expressed in a Python-based domain-specific language (DSL). +The default behavior is predefined in [mock.py](https://github.com/eclipse-kuksa/kuksa-mock-provider/blob/main/mock/mock.py) -The Mock Service is already integrated in all our [Vehicle Runtimes](/docs/tutorials/vehicle_app_runtime). To be able to configure it, you need to add a custom `mock.py` in the root of your Vehicle App Project. The Mock Service Container will pick it up automatically. +The Mock Provider is already integrated in all our [Vehicle Runtimes](/docs/tutorials/vehicle_app_runtime). To be able to configure it, you need to add a custom `mock.py` in the root of your Vehicle App Project. The Mock Provider Container will pick it up automatically. diff --git a/content/en/docs/tutorials/quickstart/quickstart.md b/content/en/docs/tutorials/quickstart/quickstart.md index 1480f83b6..b79048d39 100644 --- a/content/en/docs/tutorials/quickstart/quickstart.md +++ b/content/en/docs/tutorials/quickstart/quickstart.md @@ -123,7 +123,7 @@ You can find more information about the _Vehicle App_ development in the [respec ## How to start the runtime services? -The runtime services (like _KUKSA Data Broker_ or _Vehicle Services_) are required to develop _Vehicle Apps_ and run integration tests. +The runtime services (like _KUKSA Databroker_ or _Vehicle Services_) are required to develop _Vehicle Apps_ and run integration tests. Currently, the supported options to run these services is either [locally](/docs/tutorials/vehicle_app_runtime/local_runtime) or via the [Kanto runtime](/docs/tutorials/vehicle_app_runtime/kanto_runtime). diff --git a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md index f24e0acbc..01357d519 100644 --- a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md @@ -141,7 +141,7 @@ void onSeatPositionChanged(const DataPointsResult& result) { ``` -The `VehicleApp` class provides the `subscribeDataPoints()` method which allows to listen for changes on one or many data points. Once a change in any of the data points is registered, the callback registered via `AsyncSubscription::onItem()` is called. Conversely, the callback registered via `AsyncSubscription::onError()` is called once there is any error during communication with the KUKSA data broker. +The `VehicleApp` class provides the `subscribeDataPoints()` method which allows to listen for changes on one or many data points. Once a change in any of the data points is registered, the callback registered via `AsyncSubscription::onItem()` is called. Conversely, the callback registered via `AsyncSubscription::onError()` is called once there is any error during communication with the KUKSA Databroker. The result passed to the callback registered via `onItem()` is an object of type `DataPointsResult` which holds all data points that have changed. Individual data points can be accessed directly by their reference: `result.get(Vehicle.Cabin.Seat.Row1.Pos1.Position)`) diff --git a/content/en/docs/tutorials/vehicle_app_development/integration_tests.md b/content/en/docs/tutorials/vehicle_app_development/integration_tests.md index 6320e91c6..2b7fe1627 100644 --- a/content/en/docs/tutorials/vehicle_app_development/integration_tests.md +++ b/content/en/docs/tutorials/vehicle_app_development/integration_tests.md @@ -3,12 +3,12 @@ title: "Vehicle App Integration Testing" date: 2022-05-09T13:46:21+05:30 weight: 60 description: > - Learn how to test that a _Vehicle App_ together with the KUKSA Data Broker and potentially other dependant Vehicle Services or _Vehicle Apps_ runs as expected. + Learn how to test that a _Vehicle App_ together with the KUKSA Databroker and potentially other dependant Vehicle Services or _Vehicle Apps_ runs as expected. aliases: - /docs/tutorials/vehicle_app_development/integration_tests --- -To be sure that a newly created _Vehicle App_ will run together with the _KUKSA Data Broker_ and potentially other dependant _Vehicle Services_ or _Vehicle Apps_, it's essential to write integration tests along with developing the app. +To be sure that a newly created _Vehicle App_ will run together with the _KUKSA Databroker_ and potentially other dependant _Vehicle Services_ or _Vehicle Apps_, it's essential to write integration tests along with developing the app. To execute an integration test, the dependant components need to be running and be accessible from the test runner. This guide will describe how integration tests can be written and integrated in the CI pipeline so that they are executed automatically when building the application. @@ -18,7 +18,7 @@ This guide is currently only available for development of integration tests with ## Writing Test Cases -To write an integration test, you should check the sample that comes with the template ([`/app/tests/integration/integration_test.py`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/app/tests/integration/integration_test.py)). To support interacting with the MQTT broker and the KUKSA Data Broker (to get and set values for data points), there are two classes present in Python SDK that will help: +To write an integration test, you should check the sample that comes with the template ([`/app/tests/integration/integration_test.py`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/app/tests/integration/integration_test.py)). To support interacting with the MQTT broker and the KUKSA Databroker (to get and set values for data points), there are two classes present in Python SDK that will help: - `MqttClient`: this class provides methods for interacting with the MQTT broker. Currently, the following methods are available: @@ -40,7 +40,7 @@ To write an integration test, you should check the sample that comes with the te This class can be initialized with a given port. If no port is specified, the environment variable `MQTT_PORT` will be checked. If this is not possible either, the default value of `1883` will be used. **It's recommended to specify no port when initializing that class as it will locally use the default port `1883` and in CI the port is set by the environment variable `MQTT_PORT`. This will prevent a check-in in the wrong port during local development.** -- `IntTestHelper`: this class provides functionality to interact with the _KUKSA Data Broker_. +- `IntTestHelper`: this class provides functionality to interact with the _KUKSA Databroker_. - `register_datapoint`: registers a new data point with given name and type ([here](/docs/concepts/development_model/vehicle_app_sdk/#typed-datapoint-classes) you can find more information about the available types) - `set_..._datapoint`: set the given value for the data point with the given name (with given type). If the data point does not exist, it will be registered. @@ -52,8 +52,8 @@ To write an integration test, you should check the sample that comes with the te To be able to test the _Vehicle App_ in an integrated way, the following components should be running: - Mosquitto -- Data Broker -- Vehicle Mock Service +- Databroker +- Vehicle Mock Provider We distinguish between two environments for executing the _Vehicle App_ and the runtime components: @@ -103,7 +103,7 @@ Finally the test results are collected and published as artifacts of the workflo ### Troubleshoot IntTestHelper -- Make sure that the _KUKSA Data Broker_ is up and running by checking the task log. +- Make sure that the _KUKSA Databroker_ is up and running by checking the task log. - Make sure that you are using the right ports. - Make sure that you installed the correct version of the SDK (_SDV_-package). diff --git a/content/en/docs/tutorials/vehicle_app_development/python_development.md b/content/en/docs/tutorials/vehicle_app_development/python_development.md index 5e85ddb36..835d1ee3a 100644 --- a/content/en/docs/tutorials/vehicle_app_development/python_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/python_development.md @@ -145,7 +145,7 @@ If you want to get notified about changes of a specific `DataPoint`, you can sub ``` Every `DataPoint` provides a _.subscribe()_ method that allows for providing a callback function which will be invoked on every data point update. Subscribed data is available in the respective _DataPointReply_ object and need to be accessed via the reference to the subscribed data point. The returned object is of type `TypedDataPointResult` which holds the `value` of the data point -and the `timestamp` at which the value was captured by the data broker. +and the `timestamp` at which the value was captured by the Databroker. Therefore the `on_seat_position_changed` callback function needs to be implemented like this: ```Python diff --git a/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md b/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md index b0696da81..88ab53659 100644 --- a/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md +++ b/content/en/docs/tutorials/vehicle_app_runtime/kanto_runtime.md @@ -50,7 +50,7 @@ FeederCAN requires a candump file. A pre-defined candump file is already part of 1. Creating/updating candump file with the name `candumpDefault.log` in `./config/feedercan` 1. Restarting Kanto (execute the tasks ```Kanto - Runtime Down``` and ```Kanto - Runtime Up```) -More information about FeederCan can be found [here](https://github.com/eclipse/kuksa.val.feeders/tree/main/dbc2val) +More information about the CAN Provider can be found [here](https://github.com/eclipse-kuksa/kuksa-can-provider) ## Next steps diff --git a/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md b/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md index 8be4f9253..7c8dd4183 100644 --- a/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md +++ b/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md @@ -10,7 +10,7 @@ aliases: ## Using tasks in Visual Studio Code -**Overview:** If you are developing in Visual Studio Code, the runtime components (like _KUKSA Data Broker_ or _Vehicle Services_) are available for local execution coming from our _devenv-runtimes_ package and are accessible as _Tasks_, a feature of the Visual Studio Code. Additional information on tasks can be found [here](https://code.visualstudio.com/docs/editor/tasks). +**Overview:** If you are developing in Visual Studio Code, the runtime components (like _KUKSA Databroker_ or _Vehicle Services_) are available for local execution coming from our _devenv-runtimes_ package and are accessible as _Tasks_, a feature of the Visual Studio Code. Additional information on tasks can be found [here](https://code.visualstudio.com/docs/editor/tasks). **Start local runtime:** To start local runtime, a task called `Local Runtime - Up` is available. This task runs the runtime services in the correct order. You can run this task by clicking `F1` and choose `Tasks: Run task`, then select `Local Runtime - Up`. @@ -23,9 +23,9 @@ aliases: The configuration for services of our provided local runtime are defined in the [`runtime.json`](https://github.com/eclipse-velocitas/devenv-runtimes/blob/main/runtime.json) at the root of the repository [devenv-runtimes](https://github.com/eclipse-velocitas/devenv-runtimes/tree/main). For a more detailed view on how to change or add runtime service configuration, please visit: [Lifecycle Management Package Development](/docs/concepts/lifecycle_management/packages/development/#configuration-of-runtime-packages) -## Using KUKSA Data Broker CLI +## Using KUKSA Databroker CLI -A CLI tool is provided for interacting with a running instance of the KUKSA Data Broker. It can be started by running the task `Local Runtime - VehicleDataBroker CLI`(by pressing _F1_, type _Run Task_ followed by `Local Runtime - VehicleDataBroker CLI`). The _Runtime Local_ needs to be running for you to be able to use the tool. +A CLI tool is provided for interacting with a running instance of the KUKSA Databroker. It can be started by running the task `Local Runtime - VehicleDataBroker CLI`(by pressing _F1_, type _Run Task_ followed by `Local Runtime - VehicleDataBroker CLI`). The _Runtime Local_ needs to be running for you to be able to use the tool. ## Integrating a new runtime service into Visual Studio Code Task diff --git a/content/en/docs/tutorials/vehicle_model_creation/_index.md b/content/en/docs/tutorials/vehicle_model_creation/_index.md index d23df418b..ee190623f 100644 --- a/content/en/docs/tutorials/vehicle_model_creation/_index.md +++ b/content/en/docs/tutorials/vehicle_model_creation/_index.md @@ -9,7 +9,7 @@ description: > {{% alert title="Info" %}} On Friday, 2023-03-03 we released our new [model lifecycle approach](automated_model_lifecycle/). With the update of the documentation the previous content of this page can be found in the section [Manual Vehicle Model Creation](manual_model_creation/) now. {{% /alert %}} -A _Vehicle Model_ makes it possible to easily get vehicle data from the KUKSA Data Broker and to execute remote procedure calls over gRPC against _Vehicle Services_ and other _Vehicle Apps_. It is generated from the underlying semantic models based e.g. on the [COVESA Vehicle Signal Specification (VSS)](https://covesa.github.io/vehicle_signal_specification/). The model is generated for a concrete programming language as a graph-based, strongly-typed, intellisense-enabled library providing vehicle abstraction "on code level". +A _Vehicle Model_ makes it possible to easily get vehicle data from the KUKSA Databroker and to execute remote procedure calls over gRPC against _Vehicle Services_ and other _Vehicle Apps_. It is generated from the underlying semantic models based e.g. on the [COVESA Vehicle Signal Specification (VSS)](https://covesa.github.io/vehicle_signal_specification/). The model is generated for a concrete programming language as a graph-based, strongly-typed, intellisense-enabled library providing vehicle abstraction "on code level". By default our app templates now generate the vehicle model during the devContainer initialization - managed by the Velocitas life cycle management. The respective VSS-based model source is referenced in the app manifest allowing to freely choose the model being used in your project. You will find more details about this in section [Automated Model Lifecycle](automated_model_lifecycle/). diff --git a/content/en/docs/tutorials/vehicle_model_creation/manual_model_creation/manual_creation_python.md b/content/en/docs/tutorials/vehicle_model_creation/manual_model_creation/manual_creation_python.md index 11627db6a..0901691e7 100644 --- a/content/en/docs/tutorials/vehicle_model_creation/manual_model_creation/manual_creation_python.md +++ b/content/en/docs/tutorials/vehicle_model_creation/manual_model_creation/manual_creation_python.md @@ -184,14 +184,14 @@ description: > ### Add a Vehicle Service -_Vehicle Services_ provide service interfaces to control actuators or to trigger (complex) actions. E.g. they communicate with the vehicle internal networks like CAN or Ethernet, which are connected to actuators, electronic control units (ECUs) and other vehicle computers (VCs). They may provide a simulation mode to run without a network interface. _Vehicle Services_ may feed data to the Data Broker and may expose gRPC endpoints, which can be invoked by _Vehicle Apps_ over a _Vehicle Model_. +_Vehicle Services_ provide service interfaces to control actuators or to trigger (complex) actions. E.g. they communicate with the vehicle internal networks like CAN or Ethernet, which are connected to actuators, electronic control units (ECUs) and other vehicle computers (VCs). They may provide a simulation mode to run without a network interface. _Vehicle Services_ may feed data to the Databroker and may expose gRPC endpoints, which can be invoked by _Vehicle Apps_ over a _Vehicle Model_. In this section, we add a _Vehicle Service_ to the _Vehicle Model_. 1. Create a new folder `proto` under `my_vehicle_model/my_vehicle_model`. 2. Copy your proto file under `my_vehicle_model/my_vehicle_model/proto` - As example you could use the protocol buffers message definition [seats.proto](https://github.com/eclipse/kuksa.val.services/blob/main/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto) provided by the KUKSA.VAL services which describes a [seat control service](https://github.com/eclipse/kuksa.val.services/tree/main/seat_service). + As example you could use the protocol buffers message definition [seats.proto](https://github.com/eclipse-kuksa/kuksa-incubation/blob/main/seat_service/proto/sdv/edge/comfort/seats/v1/seats.proto) provided by the KUKSA.VAL services which describes a [seat control service](https://github.com/eclipse-kuksa/kuksa-incubation/tree/main/seat_service). 3. Install the grpcio tools including mypy types to generate the Python classes out of the proto-file: diff --git a/static/assets/diagrams.drawio b/static/assets/diagrams.drawio index 37fe2453a..d8904dbf2 100644 --- a/static/assets/diagrams.drawio +++ b/static/assets/diagrams.drawio @@ -45,13 +45,13 @@ - + - + @@ -166,7 +166,7 @@ - + diff --git a/static/assets/direct_service_invocation.drawio b/static/assets/direct_service_invocation.drawio index ffe9510bc..bf86abb3d 100644 --- a/static/assets/direct_service_invocation.drawio +++ b/static/assets/direct_service_invocation.drawio @@ -128,7 +128,7 @@ - + diff --git a/static/assets/programming_model.drawio.svg b/static/assets/programming_model.drawio.svg index 360c02744..713239200 100644 --- a/static/assets/programming_model.drawio.svg +++ b/static/assets/programming_model.drawio.svg @@ -1,4 +1,4 @@ -
KUKSA Vehicle Abstraction Layer
KUKSA Vehicle Abstraction Layer
Communication Protocols (gRPC, MQTT)
Communication Protocols (gRPC, MQTT)
SDKs (Python, C++, ...)
SDKs (Python, C++, ...)
KUKSA Data Broker
KUKSA Data Broker
Vehicle Twin
DataStore (*)
Vehicle Twin...
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Services (*)
Vehicle Services (*)
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Apps
Vehicle Apps
Middleware Abstraction
Middleware Abstraction
Vehicle Edge Operating System
Vehicle Edge Operating System
Service Locator
Service Locator
Security
Security
Tracing
Tracing
Pub/Sub
Pub/Sub
Container Runtime
Container Runtime
Kubernetes Control Plane
Kubernetes Control Plane
MQTT Broker (Mosquitto)
MQTT Broker (Mosquitto)
Vehicle Models
Vehicle Models
Vehicle Models (*)
Vehicle Models (*)
Vehicle Model Ontology
Vehicle Model Ont...
KUKSA Data Broker Client
KUKSA Data Broker...
Vehicle App Abstraction
Vehicle App Abstr...(*) based on semantic models (VSS, ...)
Vehicle Networks (CAN, ...)
Vehicle Networks (CAN, ...)Text is not SVG - cannot display +
KUKSA Vehicle Abstraction Layer
KUKSA Vehicle Abstraction Layer
Communication Protocols (gRPC, MQTT)
Communication Protocols (gRPC, MQTT)
SDKs (Python, C++, ...)
SDKs (Python, C++, ...)
KUKSA Databroker
KUKSA Databroker
Vehicle Twin
DataStore (*)
Vehicle Twin...
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Services (*)
Vehicle Services (*)
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Service
Vehicle Apps
Vehicle Apps
Middleware Abstraction
Middleware Abstraction
Vehicle Edge Operating System
Vehicle Edge Operating System
Service Locator
Service Locator
Security
Security
Tracing
Tracing
Pub/Sub
Pub/Sub
Container Runtime
Container Runtime
Kubernetes Control Plane
Kubernetes Control Plane
MQTT Broker (Mosquitto)
MQTT Broker (Mosquitto)
Vehicle Models
Vehicle Models
Vehicle Models (*)
Vehicle Models (*)
Vehicle Model Ontology
Vehicle Model Ont...
KUKSA Databroker Client
KUKSA Databroker...
Vehicle App Abstraction
Vehicle App Abstr...(*) based on semantic models (VSS, ...)
Vehicle Networks (CAN, ...)
Vehicle Networks (CAN, ...)Text is not SVG - cannot display diff --git a/static/assets/project-overview.svg b/static/assets/project-overview.svg index fbf87b5e5..0aec47908 100644 --- a/static/assets/project-overview.svg +++ b/static/assets/project-overview.svg @@ -1,4 +1,4 @@ -
extends
extends
Vehicle App SDK
Vehicle App SDK
Seat Adjuster Vehicle App
Seat Adjuster Vehicl...
uses
uses
uses
uses
Devcontainer
Devcontainer
KUKSA Data Broker
KUKSA Data Broker
Seats Service
Seats Service
install KUKSA Data Broker
install KUKSA Data Broker
install Seats Service
install Seats Service
Developer Manual
Developer Manual
Unit tests
Unit tests
Integration tests
Integration tests
test
test
test
test
SDV package
SDV package
Unit tests
Unit tests
Integration tests
Integration tests
test
test
test
test
uses
uses
uses
uses
GH Workflows
GH Workflows
Render Action
Render Action
Package Action
Package Action
release-documentation-action
[Repository]
release-documentation-action...
KUKSA.VAL
[Repository]
KUKSA.VAL
vehicle-app-python-template
[Repository]
vehicle-app-python-template...
sdv-vehicle-app-python-sdk
[Repository]
sdv-vehicle-app-python-sdk...
Unit tests
Unit tests
Integration tests
Integration tests
SDV package
SDV package
Unit tests
Unit tests
Integration tests
Integration tests
KUKSA Data Broker
KUKSA Data Broker
Render Action
Render Action
Package Action
Package Action
Developer Manual
Developer Manual
Data Feeder
Data FeederText is not SVG - cannot display +
extends
extends
Vehicle App SDK
Vehicle App SDK
Seat Adjuster Vehicle App
Seat Adjuster Vehicl...
uses
uses
uses
uses
Devcontainer
Devcontainer
KUKSA Databroker
KUKSA Databroker
Seats Service
Seats Service
install KUKSA Databroker
install KUKSA Databroker
install Seats Service
install Seats Service
Developer Manual
Developer Manual
Unit tests
Unit tests
Integration tests
Integration tests
test
test
test
test
SDV package
SDV package
Unit tests
Unit tests
Integration tests
Integration tests
test
test
test
test
uses
uses
uses
uses
GH Workflows
GH Workflows
Render Action
Render Action
Package Action
Package Action
release-documentation-action
[Repository]
release-documentation-action...
KUKSA.VAL
[Repository]
KUKSA.VAL
vehicle-app-python-template
[Repository]
vehicle-app-python-template...
sdv-vehicle-app-python-sdk
[Repository]
sdv-vehicle-app-python-sdk...
Unit tests
Unit tests
Integration tests
Integration tests
SDV package
SDV package
Unit tests
Unit tests
Integration tests
Integration tests
KUKSA Databroker
KUKSA Databroker
Render Action
Render Action
Package Action
Package Action
Developer Manual
Developer Manual
Data Feeder
Data FeederText is not SVG - cannot display diff --git a/static/assets/sdk_overview.drawio.svg b/static/assets/sdk_overview.drawio.svg index 1dcd4b6bc..e93a705ba 100644 --- a/static/assets/sdk_overview.drawio.svg +++ b/static/assets/sdk_overview.drawio.svg @@ -1,4 +1,4 @@ -
Vehicle App SDK
Vehicle App SDK
Vehicle Model
Vehicle Model
based on
based on
Semantic Model (e.g. DTDL, VSC, VSS)
Semantic Model (e.g....
KUKSA Data Broker
KUKSA Data Broker
Root Model
Root Model
Vehicle Services
Vehicle Services
Vehicle Model Ontology

- Model
- DataPoint
- DataPointInt32
- DataPointString
-DataPointArray
...
Vehicle Model Ontolo...
Fluent query & rule construction

Example: 
vehicle.Cabin.Seat.Base
.subscribe()
Fluent query & rule construction...
gRPC
gRPC
Publish & subscribe messaging
Publish & subscribe...
MQTT Broker
MQTT Broker
MQTT
MQTT
Vehicle App
abstraction
Vehicle App...
Cabin: Model
Cabin: Model
Seat: Model
Seat: Model
Base: DataPointInt32
Base: DataPointInt32
Back: DataPointInt32
Back: DataPointInt32
SeatService: Service
SeatService: Service
CurrentLocation: Model
CurrentLocation: Model
Vehicle: Model
Vehicle: Model
Latitude: DataPointDouble
Latitude: DataPointDouble
Longitude: DataPointDouble
Longitude: DataPointDouble
Data Points
Data Points
Methods
Methods
Models
Models
Services
Services
gRPC 
(subscribe(rule = 'SELECT Vehicle.Cabin.Seat.Base')
gRPC...
Example:
Example:
Base classes
Base clas...Text is not SVG - cannot display +
Vehicle App SDK
Vehicle App SDK
Vehicle Model
Vehicle Model
based on
based on
Semantic Model (e.g. DTDL, VSC, VSS)
Semantic Model (e.g....
KUKSA Databroker
KUKSA Databroker
Root Model
Root Model
Vehicle Services
Vehicle Services
Vehicle Model Ontology

- Model
- DataPoint
- DataPointInt32
- DataPointString
-DataPointArray
...
Vehicle Model Ontolo...
Fluent query & rule construction

Example: 
vehicle.Cabin.Seat.Base
.subscribe()
Fluent query & rule construction...
gRPC
gRPC
Publish & subscribe messaging
Publish & subscribe...
MQTT Broker
MQTT Broker
MQTT
MQTT
Vehicle App
abstraction
Vehicle App...
Cabin: Model
Cabin: Model
Seat: Model
Seat: Model
Base: DataPointInt32
Base: DataPointInt32
Back: DataPointInt32
Back: DataPointInt32
SeatService: Service
SeatService: Service
CurrentLocation: Model
CurrentLocation: Model
Vehicle: Model
Vehicle: Model
Latitude: DataPointDouble
Latitude: DataPointDouble
Longitude: DataPointDouble
Longitude: DataPointDouble
Data Points
Data Points
Methods
Methods
Models
Models
Services
Services
gRPC 
(subscribe(rule = 'SELECT Vehicle.Cabin.Seat.Base')
gRPC...
Example:
Example:
Base classes
Base clas...Text is not SVG - cannot display diff --git a/static/assets/seat_adjuster_dataflow.svg b/static/assets/seat_adjuster_dataflow.svg index 871765ab3..3e56a964d 100644 --- a/static/assets/seat_adjuster_dataflow.svg +++ b/static/assets/seat_adjuster_dataflow.svg @@ -1,4 +1,4 @@ -
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
Generic CAN
Feeder
Vehicle Abstraction Layer
Middelware
MQTT
gRPC
CAN
ECU
 +
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
Generic CAN
Feeder
Vehicle Abstraction Layer
Middelware
MQTT
gRPC
CAN
ECU
 diff --git a/static/assets/seat_adjuster_dataflow_1.svg b/static/assets/seat_adjuster_dataflow_1.svg index faa9eae09..be893636c 100644 --- a/static/assets/seat_adjuster_dataflow_1.svg +++ b/static/assets/seat_adjuster_dataflow_1.svg @@ -1,4 +1,4 @@ -
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
2a
5
7a
6b
Generic
CAN Feeder
Vehicle Abstraction Layer
Middelware
4a
4b
6a
3e
3c
3d
8
1
2b
MQTT
gRPC
CAN
7b
ECU
3a
3b
 +
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
2a
5
7a
6b
Generic
CAN Feeder
Vehicle Abstraction Layer
Middelware
4a
4b
6a
3e
3c
3d
8
1
2b
MQTT
gRPC
CAN
7b
ECU
3a
3b
 diff --git a/static/assets/seat_adjuster_dataflow_2.svg b/static/assets/seat_adjuster_dataflow_2.svg index ead154066..5ee9d2f89 100644 --- a/static/assets/seat_adjuster_dataflow_2.svg +++ b/static/assets/seat_adjuster_dataflow_2.svg @@ -1,4 +1,4 @@ -
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
9
12a
Vehicle Abstraction Layer
Middelware
10a
11b
11a
10b
MQTT
gRPC
CAN
13
12b
 +
Seat Adjuster
VehicleApp
VehicleApp SDK
Seats Service
Customer
Vehicle Data
Broker
Seat
MQTT Broker
9
12a
Vehicle Abstraction Layer
Middelware
10a
11b
11a
10b
MQTT
gRPC
CAN
13
12b
 From b0ccef7d84853328bc4c4d0595dc7d8db34c186e Mon Sep 17 00:00:00 2001 From: Andre Weber <138565883+wba2hi@users.noreply.github.com> Date: Mon, 29 Apr 2024 14:34:36 +0200 Subject: [PATCH 04/10] Add Section about 'velocitas init' with package parameter (#121) * Add Section about 'velocitas init' with package parameter --- .../lifecycle_management/velocitas_cli.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/lifecycle_management/velocitas_cli.md b/content/en/docs/concepts/lifecycle_management/velocitas_cli.md index e31b341dd..6f9056c6a 100644 --- a/content/en/docs/concepts/lifecycle_management/velocitas_cli.md +++ b/content/en/docs/concepts/lifecycle_management/velocitas_cli.md @@ -43,7 +43,7 @@ Config 'src' for interface 'vehicle-signal-interface': URI or path to VSS json ( ### velocitas init -Download packages configured in your `.velocitas.json` to [VELOCITAS_HOME](https://github.com/eclipse-velocitas/cli/blob/main/README.md#changing-default-velocitas_home-directory) +#### Download packages configured in your `.velocitas.json` to [VELOCITAS_HOME](https://github.com/eclipse-velocitas/cli/blob/main/README.md#changing-default-velocitas_home-directory) ```bash vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init @@ -57,6 +57,19 @@ Running 'install-deps' ... ``` +#### Single Package Init + +Single packages can also easily be initialized or re-initialized using the _package parameter_ `-p / --package` and the _specifier parameter_ `-s / --specifier`. The _specifier parameter_ can be either a git tag or a git hash. If the _specifier parameter_ is omitted either the version defined in `.velocitas.json` resp. the latest version of the specified package will be used automatically. After initialisation the package and it's resolved version will be written to `.velocitas.json`. If the package already exists in `.velocitas.json`, however the versions differ it will be automatically updated to the specified version. If no components from the specified package are added to `.velocitas.json` all components from this package are automatically written to it. + +```bash +vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init -p devenv-runtimes -s v3.0.0 +Initializing Velocitas packages ... +... Package 'devenv-runtimes:v3.0.0' added to .velocitas.json +... Downloading package: 'devenv-runtimes:v3.0.0' +... > Running post init hook for ... +... +``` + ### velocitas sync If any package provides files they will be synchronized into your repository. From 28f3b437f421ce4c95b14eb4d0b82f97d6da7633 Mon Sep 17 00:00:00 2001 From: dennismeister93 Date: Wed, 8 May 2024 10:25:29 +0200 Subject: [PATCH 05/10] Update seat adjuster development and lifecycle management section (#123) Signed-off-by: Dennis Meister --- .../vehicle_app_sdk/_index.md | 4 +- .../VADF_Lifecycle_Flow.drawio.svg | 5 +- .../project_configuration.md | 33 +++++++----- .../lifecycle_management/troubleshooting.md | 17 ++++++ .../lifecycle_management/velocitas_cli.md | 13 +++-- .../python_development.md | 52 +++++++++++-------- .../vehicle_app_runtime/local_runtime.md | 2 + 7 files changed, 77 insertions(+), 49 deletions(-) diff --git a/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md b/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md index acea4a93e..a715184c6 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md +++ b/content/en/docs/concepts/development_model/vehicle_app_sdk/_index.md @@ -434,11 +434,11 @@ The SDK supports publishing messages to a MQTT broker and subscribing to topics ### Publish MQTT Messages -MQTT messages can be published easily with the `publish_mqtt_event()` method, inherited from `VehicleApp` base class: +MQTT messages can be published easily with the `publish_event()` method, inherited from `VehicleApp` base class: {{< tabpane langEqualsHeader=true >}} {{< tab "Python" >}} -await self.publish_mqtt_event( +await self.publish_event( "seatadjuster/currentPosition", json.dumps(req_data)) {{< /tab >}} {{< tab "C++" >}} diff --git a/content/en/docs/concepts/lifecycle_management/VADF_Lifecycle_Flow.drawio.svg b/content/en/docs/concepts/lifecycle_management/VADF_Lifecycle_Flow.drawio.svg index b2bb6e5d5..bdb883cb2 100644 --- a/content/en/docs/concepts/lifecycle_management/VADF_Lifecycle_Flow.drawio.svg +++ b/content/en/docs/concepts/lifecycle_management/VADF_Lifecycle_Flow.drawio.svg @@ -1,4 +1 @@ - - - -
DevContainer
DevContainer
velocitas upgrade --dry-run
velocitas upgrade --dry-run
velocitas sync
velocitas sync
velocitas upgrade
velocitas upgrade
onCreateCommand
onCreateCommand
velocitas init
velocitas init
velocitas sync
velocitas sync
Check for updates
Check for...
Update components & sync files
Update components & sync filesText is not SVG - cannot display +
DevContainer
DevContainer
velocitas upgrade --dry-run
--ignore-bounds
velocitas upgrade --dry-ru...
velocitas init && velocitas sync
velocitas init && ve...
velocitas upgrade --ignore-bounds
velocitas upgrade --ignor...
onCreateCommand
onCreateCommand
velocitas init
velocitas init
velocitas sync
velocitas sync
Check for updates
Check for...
Update components & sync files
Update components & sync filesText is not SVG - cannot display diff --git a/content/en/docs/concepts/lifecycle_management/project_configuration.md b/content/en/docs/concepts/lifecycle_management/project_configuration.md index 1468d95c3..8137d9962 100644 --- a/content/en/docs/concepts/lifecycle_management/project_configuration.md +++ b/content/en/docs/concepts/lifecycle_management/project_configuration.md @@ -8,26 +8,31 @@ aliases: - /docs/concepts/lifecycle_management/project_configuration.md --- -Every _Vehicle App_ repo comes with a [`.velocitas.json`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.velocitas.json) which is the project configuration of your app. It holds references to the packages and their respective versions you are using in your project. +Every _Vehicle App_ repo comes with a [`.velocitas.json`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.velocitas.json) which is the project configuration of your app. It holds references to the packages and their respective versions as well as components you are using in your project. Here is an example of this configuration: ```json { - "packages": [ - { - "name": "devenv-devcontainer-setup", - "version": "v1.0.0" + "packages": { + "devenv-runtimes": "v3.1.0", + "devenv-devcontainer-setup": "v2.1.0" }, - { - "name": "devenv-runtimes", - "version": "v1.0.0" - } - ], - "variables": { - "foo": "bar", - "baz": 2 - } + "components": [ + "runtime-local", + "devcontainer-setup", + "vehicle-signal-interface", + "sdk-installer", + "grpc-interface-support" + ], + "variables": { + "language": "python", + "repoType": "app", + "appManifestPath": "app/AppManifest.json", + "githubRepoId": "eclipse-velocitas/vehicle-app-python-template", + "generatedModelPath": "./gen/vehicle_model" + }, + "cliVersion": "v0.9.0" } ``` diff --git a/content/en/docs/concepts/lifecycle_management/troubleshooting.md b/content/en/docs/concepts/lifecycle_management/troubleshooting.md index 23c7386e1..33fb52351 100644 --- a/content/en/docs/concepts/lifecycle_management/troubleshooting.md +++ b/content/en/docs/concepts/lifecycle_management/troubleshooting.md @@ -38,3 +38,20 @@ or vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas sync ``` + +### Debugging inside installed packages + +Open up a seperate VScode window where you can debug installed toolchain packages. + +```bash +vscode ➜ /workspaces/vehicle-app-python-template (main) $ code ~/.velocitas/packages +``` + +### Solution to (almost) all problems + +The following would clean up the [VELOCITAS_HOME](/docs/concepts/lifecycle_management/packages/usage/#velocitas-home-directory) but afterwards a new project initialization is required. + +```bash +vscode ➜ /workspaces/vehicle-app-python-template (main) $ rm -rf ~/.velocitas +vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init +``` diff --git a/content/en/docs/concepts/lifecycle_management/velocitas_cli.md b/content/en/docs/concepts/lifecycle_management/velocitas_cli.md index 6f9056c6a..77035a07a 100644 --- a/content/en/docs/concepts/lifecycle_management/velocitas_cli.md +++ b/content/en/docs/concepts/lifecycle_management/velocitas_cli.md @@ -90,13 +90,12 @@ Syncing Velocitas components! Updates Velocitas components. ```bash -vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas upgrade --dry-run -Checking for updates! -... 'devenv-runtimes' is up to date! -... 'devenv-github-workflows' is up to date! -... 'devenv-github-templates' is up to date! -... 'devenv-devcontainer-setup' is currently at v1.1.6, can be updated to v1.1.7 -... Do you wish to continue? [y/n] [y]: y +vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas upgrade --dry-run [--ignore-bounds] +Checking .velocitas.json for updates! +... devenv-devcontainer-setup:vx.x.x → up to date! +... devenv-runtimes:vx.x.x → vx.x.x +... devenv-github-templates:vx.x.x → up to date! +... devenv-github-workflows:vx.x.x → up to date! ``` ### velocitas package diff --git a/content/en/docs/tutorials/vehicle_app_development/python_development.md b/content/en/docs/tutorials/vehicle_app_development/python_development.md index 835d1ee3a..7869cb0a3 100644 --- a/content/en/docs/tutorials/vehicle_app_development/python_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/python_development.md @@ -29,7 +29,7 @@ A detailed explanation of the use case and the example is available [here](/docs {{% alert title="Note" %}} If you don't like to do the following steps by yourself, you can use the `Import example app from SDK` task within VS Code to get a working copy of this example into your repository.
-(For details about the import of an example from the SDK look [here](/docs/tutorials/quickstart/import_examples).) +For details about the import of an example from the SDK look [here](/docs/tutorials/quickstart/import_examples) {{% /alert %}} ## Setting up the basic skeleton of your app @@ -55,12 +55,12 @@ import json import logging import signal -from sdv.util.log import ( # type: ignore +from velocitas_sdk.util.log import ( # type: ignore get_opentelemetry_log_factory, get_opentelemetry_log_format, ) -from sdv.vdb.reply import DataPointReply -from sdv.vehicle_app import VehicleApp, subscribe_topic +from velocitas_sdk.vdb.reply import DataPointReply +from velocitas_sdk.vehicle_app import VehicleApp, subscribe_topic from vehicle import Vehicle, vehicle # type: ignore ``` @@ -121,15 +121,15 @@ The first thing you need to do is to get access to the Vehicle Model. If you der If you want to access a single [DataPoint](/docs/concepts/development_model/vehicle_app_sdk/#datapoint) e.g. for the vehicle speed, this can be done via ```Python -vehicle_speed = await self.Vehicle.Speed.get() +vehicle_speed = (await self.Vehicle.Speed.get()).value ``` -As the `get()` method of the DataPoint-class there is a coroutine you have to use the `await` keyword when using it. +As the `get()` method of the DataPoint-class there is a coroutine you have to use the `await` keyword when using it and access its `.value`. If you want to get deeper inside the vehicle, to access a single seat for example, you just have to go the model-chain down: ```Python -self.DriverSeatPosition = await self.vehicle_client.Cabin.Seat.Row1.Pos1.Position.get() +self.DriverSeatPosition = await self.Vehicle.Cabin.Seat.Row1.DriverSide.Position.get() ``` ## Subscription to Data Points @@ -139,7 +139,7 @@ If you want to get notified about changes of a specific `DataPoint`, you can sub ```Python async def on_start(self): """Run when the vehicle app starts""" - await self.Vehicle.Cabin.Seat.Row1.Pos1.Position.subscribe( + await self.Vehicle.Cabin.Seat.Row1.DriverSide.Position.subscribe( self.on_seat_position_changed ) ``` @@ -152,21 +152,21 @@ Therefore the `on_seat_position_changed` callback function needs to be implement async def on_seat_position_changed(self, data: DataPointReply): # handle the event here response_topic = "seatadjuster/currentPosition" - position = data.get(self.Vehicle.Cabin.Seat.Row1.Pos1.Position).value + position = data.get(self.Vehicle.Cabin.Seat.Row1.DriverSide.Position).value # ... ``` ## Subscription using Annotations -The Python SDK also supports annotations for subscribing to data point changes with `@subscribe_data_points` defined by the whole path to the `DataPoint` of interest. +The Python SDK also supports annotations for subscribing to data point changes with `@subscribe_data_points` defined by the whole path to the `DataPoint` of interest. This would replace the implementation of the [Subscription to Data Points](#subscription-to-data-points) ```Python -@subscribe_data_points("Vehicle.Cabin.Seat.Row1.Pos1.Position") -async def on_vehicle_seat_change(self, data: DataPointReply): +@subscribe_data_points("Vehicle.Cabin.Seat.Row1.DriverSide.Position") +async def on_seat_position_changed(self, data: DataPointReply): response_topic = "seatadjuster/currentPosition" - response_data = {"position": data.get(self.Vehicle.Cabin.Seat.Row1.Pos1.Position).value} + response_data = {"position": data.get(self.Vehicle.Cabin.Seat.Row1.DriverSide.Position).value} - await self.publish_mqtt_event(response_topic, json.dumps(response_data)) + await self.publish_event(response_topic, json.dumps(response_data)) ``` Similarly, subscribed data is available in the respective _DataPointReply_ object and needs to be accessed via the reference to the subscribed data point. @@ -178,7 +178,8 @@ Services are used to communicate with other parts of the vehicle via remote func {{% alert title="Note" %}} Services are not supported by our [automated vehicle model lifecycle](/docs/tutorials/vehicle_model_creation/automated_model_lifecycle) for the time being. If you need access to services please read [here](/docs/tutorials/vehicle_model_creation/manual_model_creation) how you can create a model and add services to it manually. {{% /alert %}} - +You can ignore the following step if you would like to reach the final implementation of the [example](https://github.com/eclipse-velocitas/vehicle-app-python-sdk/tree/main/examples/seat-adjuster). +
The following code snippet shows how to use the `MoveComponent()` method of the `SeatService` from the vehicle model: ```Python @@ -196,7 +197,7 @@ In order to define which seat you like to move, you have to pass a `SeatLocation Interaction with other _Vehicle Apps_ or with the cloud is enabled by using the Mosquitto MQTT Broker. The MQTT broker runs inside a docker container, which is started as part of one of our [predefined runtimes](../../vehicle_app_runtime/). -In the [quickstart section](/docs/tutorials/quickstart/#how-to-debug-_vehicle-app_) about the _Vehicle App_, you already tested sending MQTT messages to the app. +In the [quickstart section](/docs/tutorials/quickstart/quickstart/#how-to-debug-your-_vehicle-app_) about the _Vehicle App_, you already tested sending MQTT messages to the app. In the previous sections, you generally saw how to use `Vehicle Models`, `DataPoints` and `Services`. In this section, you will learn how to combine them with MQTT. In order to receive and process MQTT messages inside your app, simply use the `@subscribe_topic` annotations from the SDK for an additional method `on_set_position_request_received()` you have to implement: @@ -204,6 +205,7 @@ In order to receive and process MQTT messages inside your app, simply use the `@ ```Python @subscribe_topic("seatadjuster/setPosition/request") async def on_set_position_request_received(self, data_str: str) -> None: + logger.info(f"Got message: {data_str!r}") data = json.loads(data_str) response_topic = "seatadjuster/setPosition/response" response_data = {"requestId": data["requestId"], "result": {}} @@ -213,13 +215,13 @@ In order to receive and process MQTT messages inside your app, simply use the `@ The `on_set_position_request_received` method will now be invoked every time a message is published to the subscribed topic `"seatadjuster/setPosition/response"`. The message data (string) is provided as parameter. In the example above the data is parsed from json (`data = json.loads(data_str)`). -In order to publish data to topics, the SDK provides the appropriate convenience method: `self.publish_mqtt_event()` which will be added to the `on_seat_position_changed` callback function from before. +In order to publish data to topics, the SDK provides the appropriate convenience method: `self.publish_event()` which will be added to the `on_seat_position_changed` callback function from before. ```Python async def on_seat_position_changed(self, data: DataPointReply): response_topic = "seatadjuster/currentPosition" - position = data.get(self.Vehicle.Cabin.Seat.Row1.Pos1.Position).value - await self.publish_mqtt_event( + position = data.get(self.Vehicle.Cabin.Seat.Row1.DriverSide.Position).value + await self.publish_event( response_topic, json.dumps({"position": position}), ) @@ -258,9 +260,9 @@ async def test_for_publish_to_topic(): # Disable no-value-for-parameter, seems to be false positive with mock lib with mock.patch.object( - VehicleApp, "publish_mqtt_event", new_callable=mock.AsyncMock, return_value=-1 + VehicleApp, "publish_event", new_callable=mock.AsyncMock, return_value=-1 ): - response = await VehicleApp.publish_mqtt_event( + response = await VehicleApp.publish_event( str("sampleTopic"), get_sample_request_data() # type: ignore ) assert response == -1 @@ -272,6 +274,7 @@ def get_sample_request_data(): Looking at a test you notice the annotation `@pytest.mark.asyncio`. This is required if the test is defined as a coroutine. The next step is to create a mock from all the external dependencies. The method takes 4 arguments: first is the object to be mocked, second the method for which you want to modify the return value, third a callable and the last argument is the return value. After creating the mock, you can test the method and check the response. Use asserts to make your test fail if the response does not match. +Check the [`seat-adjuster` unit tests](https://github.com/eclipse-velocitas/vehicle-app-python-sdk/blob/main/examples/seat-adjuster/tests/unit/test_run.py) to see a more detailed implementation. ## See the results @@ -279,7 +282,12 @@ Once the implementation is done, it is time to run and debug the app. ### Run your App -In order to run the app make sure the `devenv-runtimes` package is part of your [`.velocitas.json`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.velocitas.json) (which should be the default) and the runtime is up and running. Read more about it in the [run runtime services](/docs/tutorials/vehicle_app_runtime/local_runtime) section. +In order to run the app: + +- Make sure the `devenv-runtimes` & `devenv-devcontainer-setup` packages are part of your [`.velocitas.json`](https://github.com/eclipse-velocitas/vehicle-app-python-template/blob/main/.velocitas.json) (which should be the default). +- Have a correctly configured [`app/AppManifest.json`](https://github.com/eclipse-velocitas/vehicle-app-python-sdk/blob/main/examples/seat-adjuster/AppManifest.json). [See more](/docs/concepts/development_model/vehicle_app_manifest/) +- Trigger our [automated vehicle model lifecycle](/docs/tutorials/vehicle_model_creation/automated_model_lifecycle). (e. g. `velocitas init`) +- A runtime needs to be up and running. Read more about it in the [run runtime services](/docs/tutorials/vehicle_app_runtime/local_runtime) section. Now chose one of the options to start the VehicleApp under development: diff --git a/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md b/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md index 7c8dd4183..c23328e35 100644 --- a/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md +++ b/content/en/docs/tutorials/vehicle_app_runtime/local_runtime.md @@ -14,6 +14,8 @@ aliases: **Start local runtime:** To start local runtime, a task called `Local Runtime - Up` is available. This task runs the runtime services in the correct order. You can run this task by clicking `F1` and choose `Tasks: Run task`, then select `Local Runtime - Up`. +**Stop local runtime:** To stop local runtime, a task called `Local Runtime - Down` is available. This task stops running runtime services gracefully. You can run this task by clicking `F1` and choose `Tasks: Run task`, then select `Local Runtime - Down`. + **Tasks Management:** Visual Studio Code offers various other commands concerning tasks like Start/Terminate/Restart/... You can access them by pressing F1 and typing `task`. A list with available task commands will appear. **Logging:** Running tasks appear in the Terminals View of Visual Studio Code. From there, you can see the logs of each running task. More detailed logs can be found inside your workspace's logs directory `./logs/*` From 352e00c1b55c24896cb5c4702227bdb9a5a306f0 Mon Sep 17 00:00:00 2001 From: BjoernAtBosch Date: Fri, 31 May 2024 11:36:38 +0200 Subject: [PATCH 06/10] Describe signal error handling (#124) Co-authored-by: dennismeister93 Co-authored-by: Dominic Sudy <99014187+doosuu@users.noreply.github.com> --- .../cpp_development.md | 140 +++++++++++++++--- 1 file changed, 123 insertions(+), 17 deletions(-) diff --git a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md index 01357d519..1654c662b 100644 --- a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md @@ -58,7 +58,7 @@ class MyVehicleApp : public VehicleApp { public: // private: - ::Vehicle Vehicle; // this member exists to provide simple access to the vehicle model + vehicle::Vehicle Vehicle; // this member exists to provide simple access to the vehicle model } ``` @@ -73,8 +73,6 @@ MyVehicleApp() ``` {{% alert title="Note" %}} -The middleware abstraction of the C++ SDK is incomplete: Pub/sub abstraction is just supporting MQTT (but no Dapr pub/sub), currently. - The URI of the MQTT broker is by default `localhost:1883` and can be set to another address via the environment variable `SDV_MQTT_ADDRESS` (beginning with C++ SDK v0.3.3) or `MQTT_BROKER_URI` (SDKs before v0.3.3). {{% /alert %}} @@ -96,31 +94,129 @@ With this your app can now be started. In order to provide some meaningful behav ## Vehicle Model Access -In order to facilitate the implementation, the whole vehicle is abstracted into model classes. Please check the [tutorial about creating models](/docs/tutorials/vehicle_model_creation) for more details. In this section, the focus is on using the model. +In order to facilitate the implementation, the whole set of vehicle signals is abstracted into model classes. Please check the [tutorial about creating models](/docs/tutorials/vehicle_model_creation) for more details. In this section, the focus is on using the model. -The first thing you need to do is to get access to the Vehicle Model. If you derived your project repository from our template, we already provide a generated model in the folder `app/vehicle_model/include/`. This folder is already configured as "include folder" of the CMake tooling. Hence, in most cases no additional setup is necessary. How to tailor the model to your needs or how you could get access to vehicle services is described in the tutorial linked above. +The first thing you need to do is to get access to the Vehicle Model. If you derived your project repository from our template, we already provide a generated model as a Conan source package. The library is already referenced as "include folder" in the CMake files. Hence, in most cases no additional setup is necessary. How to tailor the model to your needs or how you could get access to vehicle services is described in the tutorial linked above. In your source code the model is included via `#include "vehicle/Vehicle.hpp"` (as shown above). -If you want to access a single [DataPoint](/docs/concepts/development_model/vehicle_app_sdk/#datapoint) e.g. for the vehicle speed, this can be done via +If you want to read a single [signal/data point](/docs/concepts/development_model/vehicle_app_sdk/#datapoint) e.g. for the vehicle speed, the simplest way is to do it via a blocking call and directly accessing the value of the speed: ```Cpp -auto vehicleSpeedBlocking = getDataPoint(Vehicle.Speed)->await(); +auto vehicleSpeed = Vehicle.Speed.get()->await().value(); ``` -or +Lets have a look, what this line contains: +* The term `Vehicle.Speed` addresses the signal we like to query, i.e. the current speed of the vehicle. +* The term `.get()` tells that we want to get/read the current state of that signal from the Data Broker. + Behind the scenes this triggers a request-response flow via IPC with the Data Broker. +* The term `->await()` blocks the execution until the response was received. +* Finally, the term `.value()` tries to access the returned speed value. + +The `get()` returns a `shared_ptr` to an `AsyncResult` which, as the name implies, is the result of an asynchronous operation. We have two options to access the value of the asynchronous result. First we can use `await()` and block the calling thread until a result is available or use `onResult(...)` which allows us to inject a function pointer or a lambda which is called once the result is available: ```Cpp -getDataPoint(Vehicle.Speed)->onResult([](auto vehicleSpeed){ - logger().info("Got speed!"); -}) +Vehicle.Speed.get() + ->onResult([](auto vehicleSpeed){ + logger().info("Got speed!"); + }) + ->onError(auto status){ + logger().info("Something went wrong communicating to the data broker!"); + }); ``` -`getDataPoint()` returns a `shared_ptr` to an `AsyncResult` which, as the name implies, is the result of an asynchronous operation. We have two options to access the value of the asynchronous result. First we can use `await()` and block the calling thread until a result is available or use `onResult(...)` which allows us to inject a function pointer or a lambda which is called once the result is available. - If you want to get deeper inside to the vehicle, to access a single seat for example, you just have to go the model-chain down: ```Cpp -auto driverSeatPosition = getDataPoint(Vehicle.Cabin.Seat.Row1.Pos1.Position)->await(); +auto driverSeatPosition = Vehicle.Cabin.Seat.Row1.Pos1.Position.get()->await(); +``` + +### Class TypedDataPointValue + +If you have a detailed look at the `AsyncResult` class, you will observe that the object returned by the `await()` or passed to the `onResult` callback is not directly the current value of the signal, but instead an object of type `TypedDataPointValue`. This object does not only contain the current value of the signal but also some additional metadata accessible via these functions: +* `getPath()` provides the signal name, i.e. the complete path, +* `getType()` provides the data type of the signal, +* `getTimeStamp()` provides the timestamp when the current state was received by the data broker, +* `isValid()` returns `true` if the current state represents a valid value of the signal or `false` otherwise, +* `getFailure()` returns the reason, why the current state does **not** represent a valid value (it returns `NONE` if the value is valid), +* `getValue()` returns the a valid current value. It will throw an `InvalidValueException` if the current value is invalid for whatever reason. + +The latter three points lead us to the next chapter. + +### Failure Handling + +As indicated above, there might be reasons/situations why the get operation is not able to deliver a valid value for the requested signal. Those shall be handled properly by any application (that wants "to be more" than a prototype). + +There are two ways to handle the failure situations: +* Either you can catch the exception thrown by the `.value()` function: +```Cpp +try { + auto vehicleSpeed = Vehicle.Speed.get()->await().value(); + // use the speed value +} catch (AsyncException& e) { + // thrown by the await(): Something went wrong on communication level with the data broker +} catch (InvalidValueException& e) { + // thrown by .value(): The vehicle speed signal does not contain a valid value, currently +} +``` +* Throwing the `InvalidValueException` can be avoided if you first check that `.isValid()` returns true before calling `.value()`: +```Cpp +auto vehicleSpeed = Vehicle.Speed.get()->await(); +if (vehicleSpeed.isValid()) + // Accessing .value() now wont throw an exception + auto speed = vehicleSpeed.value() + ... +} else { + // Do your failure handling here + switch (vehicleSpeed.getFailure()) { + case Failure::INVALID_VALUE: + ... + break; + case ... + default: + ... + } +} ``` +(`isValid()` is a convenience function for checking `.getFailure() == Failure::NONE`.) + +{{% alert title="Note" %} +If you use the asynchroneous variant, the callback passed to `onError` is just called to report errors on communication level with the data broker. The validity of the returned signal's/data point's value needs to be checked separatly (e.g. via 'isValid()')! +{{% alert %} + +## Failure Reasons + +There are two levels where errors accessing signal/data points might occure. + +### Communication with the Data Broker (IPC Level) + +The data broker might be (temporarly) unavailable because +* it's not yet started up, +* temporary "stopped" due to a crash or a "live update", +* some temporary network issues (if running on a different hardware node), +* ... + +Errors on the IPC level between the application and the data broker will be reported either via +* an `AsyncException` thrown by the `await()` function of the `AsyncResult` class or +* calling the function passed to the `onError` function of the `AsyncResult`/`AsyncSubscription` class. + +Errors on this level always make the overall call fail: If getting/setting multiple data points in a single call, the overall operation will fail. In case of setting multiple signals/data points, this means that none of the signals/data points are set. In case of an error on a subscription, this means that the overall subscription could not be established or is terminated now. + +### Signal / Data Point Level + +Failures on signal/data point level are always reported individually per signal/data point. If accessing multiple signals/data points in a single call, getting or setting some certain signal might be successfully done but another one will report an error or failure. + +The reasons why a valid value of signal/data point can be missing are explained here: +{{
}} +| Reported failure | Reason | Explanation | +|------------------------------|--------|-------------| +| `Failure::UNKNOWN_DATAPOINT` | The addressed signal/data point is "unknown" on the system. | This can be a hint for a misconfiguration of the overall system, because no provider is installed in that system which will provide this signal. It can be acceptable, if an application does just "optionally" require access to that signal and would work properly without it being present. +| `Failure::ACCESS_DENIED` | The application does not have the necessary access rights to the addressed signal/data point. | This can be a hint for a misconfiguration of the overall system, but could be also a "normal" situation if the user of the vehicle blocks access to certain signals for that application. +| `Failure::NOT_AVAILABLE` | The addressed signal/data point is temporary not available. | This is a normal situation which will arise, while the provider of that signal is
- not yet started up or has not yet passed a value to the data broker,
- temporary "stopped" due to a crash or a "live update",
- some temporary network issues (e.g. if the provider is running on a different hardware node),
- ... +| `Failure::INVALID_VALUE` | The addressed signal/data point might currently not represent a valid value. | This situation means, that the signal is currently provided but just the value itself is not representable, e.g. because the hardware sensor delivers implausible values. +| `Failure::INTERNAL_ERROR` | The value is missing because of some internal issue in the data broker. | This typically points out some misbehaviour within the broker's implementation - call it "bug". +| `Failure::NONE` | No failure state - a valid value is provided. | This "failure" reason is used to represent a signal state where a valid value is provided. | +{{
}} + +It is the application developer's decision if it makes sense to distinguish between the different failure reasons or if some or all of them can be handled as "just one". ## Subscription to DataPoints @@ -141,16 +237,26 @@ void onSeatPositionChanged(const DataPointsResult& result) { ``` -The `VehicleApp` class provides the `subscribeDataPoints()` method which allows to listen for changes on one or many data points. Once a change in any of the data points is registered, the callback registered via `AsyncSubscription::onItem()` is called. Conversely, the callback registered via `AsyncSubscription::onError()` is called once there is any error during communication with the KUKSA Databroker. +The `VehicleApp` class provides the `subscribeDataPoints()` method which allows to listen for changes on one or multiple data points. Once a change in any of the data points is registered, the callback registered via `AsyncSubscription::onItem()` is called. Conversely, the callback registered via `AsyncSubscription::onError()` is called once there is an error during communication with the KUKSA Databroker. -The result passed to the callback registered via `onItem()` is an object of type `DataPointsResult` which holds all data points that have changed. Individual data points can be accessed directly by their reference: `result.get(Vehicle.Cabin.Seat.Row1.Pos1.Position)`) +The result passed to the callback registered via `onItem()` is an object of type `DataPointsResult` which holds the current state of all data points that were part of the respective subscription. The state of individual data points can be accessed by their reference: `result.get(Vehicle.Cabin.Seat.Row1.Pos1.Position)`) + +{{% alert title="Note" %} +If you select multiple signals/data points in a single subscription be aware that: +1. The update notification will not only contain those data points whose states were updated, but the state of all data points selected in the belonging subscription. If you don't want this behaviour, you must subscribe to change notifications for each signal/data point separately. +2. A possible failure state will be reported individually per signal/data point. The reason is, that each signal/data point might come from a different provider, has individual access rights and individual reasons to become invalid. This is also true, if requesting multiple signal/data point states via a single get call. +{{% /alert %}} ## Services Services are used to communicate with other parts of the vehicle via remote procedure calls (RPC). Please read the basics about them [here](/docs/tutorials/vehicle_model_creation/manual_model_creation/manual_creation_python/#add-a-vehicle-service). {{% alert title="Note" %}} -Services are not supported by our [automated vehicle model lifecycle](/docs/tutorials/vehicle_model_creation/automated_model_lifecycle) for the time being. If you need access to services please read [here](/docs/tutorials/vehicle_model_creation/manual_model_creation) how you can create a model and add services to it manually. +This description is outdated! + +Services were not supported by our [automated vehicle model lifecycle](/docs/tutorials/vehicle_model_creation/automated_model_lifecycle) for some time and could be made available via the [description](/docs/tutorials/vehicle_model_creation/manual_model_creation) how you can create a model and add services to it manually. + +In-between we provide a way to refer gRPC based services by referencing the required proto files from the AppManifest and auto-generated the language-specific stubs. The necessary steps need being described here. {{% /alert %}} The following code snippet shows how to use the `moveComponent()` method of the `SeatService` from the vehicle model: From ddb90a9265087f06150dab1cff0491eab74fd79b Mon Sep 17 00:00:00 2001 From: BjoernAtBosch Date: Fri, 31 May 2024 11:48:31 +0200 Subject: [PATCH 07/10] Fix cpp_development.md (#125) --- .../tutorials/vehicle_app_development/cpp_development.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md index 1654c662b..f65a16bb8 100644 --- a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md @@ -178,9 +178,9 @@ if (vehicleSpeed.isValid()) ``` (`isValid()` is a convenience function for checking `.getFailure() == Failure::NONE`.) -{{% alert title="Note" %} +{{% alert title="Note" %}} If you use the asynchroneous variant, the callback passed to `onError` is just called to report errors on communication level with the data broker. The validity of the returned signal's/data point's value needs to be checked separatly (e.g. via 'isValid()')! -{{% alert %} +{{% alert %}} ## Failure Reasons @@ -241,7 +241,7 @@ The `VehicleApp` class provides the `subscribeDataPoints()` method which allows The result passed to the callback registered via `onItem()` is an object of type `DataPointsResult` which holds the current state of all data points that were part of the respective subscription. The state of individual data points can be accessed by their reference: `result.get(Vehicle.Cabin.Seat.Row1.Pos1.Position)`) -{{% alert title="Note" %} +{{% alert title="Note" %}} If you select multiple signals/data points in a single subscription be aware that: 1. The update notification will not only contain those data points whose states were updated, but the state of all data points selected in the belonging subscription. If you don't want this behaviour, you must subscribe to change notifications for each signal/data point separately. 2. A possible failure state will be reported individually per signal/data point. The reason is, that each signal/data point might come from a different provider, has individual access rights and individual reasons to become invalid. This is also true, if requesting multiple signal/data point states via a single get call. From 1aed30661feb65d2bc91f50457a2e151d03d9d3c Mon Sep 17 00:00:00 2001 From: BjoernAtBosch Date: Fri, 31 May 2024 12:04:36 +0200 Subject: [PATCH 08/10] Another fix of cpp_development.md (#126) --- .../docs/tutorials/vehicle_app_development/cpp_development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md index f65a16bb8..68b352855 100644 --- a/content/en/docs/tutorials/vehicle_app_development/cpp_development.md +++ b/content/en/docs/tutorials/vehicle_app_development/cpp_development.md @@ -180,7 +180,7 @@ if (vehicleSpeed.isValid()) {{% alert title="Note" %}} If you use the asynchroneous variant, the callback passed to `onError` is just called to report errors on communication level with the data broker. The validity of the returned signal's/data point's value needs to be checked separatly (e.g. via 'isValid()')! -{{% alert %}} +{{% /alert %}} ## Failure Reasons From bcdd9fe9f7e58386f5705668f57c95dd174327db Mon Sep 17 00:00:00 2001 From: lukasmittag Date: Mon, 6 May 2024 13:54:55 +0200 Subject: [PATCH 09/10] Update vehicle-signal-interface configuration options --- .../vehicle_app_manifest/interfaces/vehicle_signal_interface.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md index de6f7061b..b0d28ac80 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md +++ b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md @@ -27,6 +27,7 @@ More information: [Vehicle Model Creation](/docs/tutorials/vehicle_model_creatio | Attribute | Type | Example value | Description | |-|-|-|-| | `src` | string | `"https://github.com/COVESA/vehicle_signal_specification/releases/download/v3.0/vss_rel_3.0.json"` | URI of the used COVESA Vehicle Signal Specification JSON export. URI may point to a local file or to a file provided by a server. | +| `unit_src` | string | ["abs_path_unit_file_1", "abs_path_unit_file_2", "uri_unit_file_3"] | An array of URI's/absolute path's of the used COVESA Vehicle Signal Specification unit file(s) in yaml format. URI may point to a local file or to a file provided by a server. | | `datapoints` | object | Object containing both required and provided datapoints. | | `datapoints.required` | array | Array of required datapoints. | | `datapoints.required.[].path` | string | `Vehicle.Speed` | Path of the VSS datapoint. | From 133b2e2d0f70ac33466cacbdb859b0f7617598f7 Mon Sep 17 00:00:00 2001 From: lukasmittag Date: Tue, 4 Jun 2024 09:51:59 +0200 Subject: [PATCH 10/10] Rework findings --- .../interfaces/vehicle_signal_interface.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md index b0d28ac80..a56e7a8c4 100644 --- a/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md +++ b/content/en/docs/concepts/development_model/vehicle_app_manifest/interfaces/vehicle_signal_interface.md @@ -27,7 +27,7 @@ More information: [Vehicle Model Creation](/docs/tutorials/vehicle_model_creatio | Attribute | Type | Example value | Description | |-|-|-|-| | `src` | string | `"https://github.com/COVESA/vehicle_signal_specification/releases/download/v3.0/vss_rel_3.0.json"` | URI of the used COVESA Vehicle Signal Specification JSON export. URI may point to a local file or to a file provided by a server. | -| `unit_src` | string | ["abs_path_unit_file_1", "abs_path_unit_file_2", "uri_unit_file_3"] | An array of URI's/absolute path's of the used COVESA Vehicle Signal Specification unit file(s) in yaml format. URI may point to a local file or to a file provided by a server. | +| `unit_src` | string | `["abs_path_unit_file_1", "abs_path_unit_file_2", "uri_unit_file_3"]` | An array of URI's/absolute path's of the used COVESA Vehicle Signal Specification unit file(s) in yaml format. URI may point to a local file or to a file provided by a server. If none is provided a default one will be used (https://github.com/COVESA/vehicle_signal_specification/blob/v4.0/spec/units.yaml). | | `datapoints` | object | Object containing both required and provided datapoints. | | `datapoints.required` | array | Array of required datapoints. | | `datapoints.required.[].path` | string | `Vehicle.Speed` | Path of the VSS datapoint. | @@ -65,3 +65,6 @@ More information: [Vehicle Model Creation](/docs/tutorials/vehicle_model_creatio } } ``` + +## Different VSS versions +The model generation is supported for VSS versions up to v4.0. There are some changes for some paths from v3.0 to v4.0. For example `Vehicle.Cabin.Seat.Row1.Pos1.Position` in v3.0 is `Vehicle.Cabin.Seat.Row1.DriverSide.Position` in v4.0. If you are using the mock provider you would need to take that into account when you sepcify your mock.py.