Merge pull request #101 from eclipse-kuksa/feature/databroker-api-v2

Feature/databroker api v2

Author: argerus

Cargo.lock

@@ -60,7 +60,7 @@ The [COVESA Vehicle Signal Specification](https://covesa.github.io/vehicle_signa
 
 However, VSS does not define how these signals are to be collected and managed within a vehicle, nor does it prescribe how other components in the vehicle can read or write signal values from and to the tree.
 
-**Kuksa Databroker** is a resource efficient implementation of the VSS signal tree and is intended to be run within a vehicle on a microprocessor based platform. It allows applications in the vehicle to interact with the vehicle's sensors and actuators using a uniform, high level gRPC API for querying signals, updating current and target values of sensors and actuators and getting notified about changes to signals of interest.
+**Kuksa Databroker** is a resource efficient implementation of the VSS signal tree and is intended to be run within a vehicle on a microprocessor based platform. It allows applications in the vehicle to interact with the vehicle's sensors and actuators using a uniform, high level gRPC API for querying signals, updating values of sensors and actuators and getting notified about changes to signals of interest.
 
 <!-- black box diagram -- inputs/outputs -->
 
@@ -88,6 +88,21 @@ Data is usually exchanged with ECUs by means of a CAN bus or Ethernet based prot
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+<!-- KUKSA ANALYSIS -->
+## Kuksa analysis
+Extended [Kuksa analysis](./doc/kuksa_analysis.md) containing functional requirements, use cases diagrams, latest and new API definition `kuksa.val.v2` as well as new design discussions for future developments and improvements.
+
+### APIs supported by Databroker
+
+Kuksa Databroker implements the following service interfaces:
+
+- Enabled on Databroker by default [kuksa.val.v2.VAL](proto/kuksa/val/v2/val.proto) (recommended to use)
+- Enabled on Databroker by default [kuksa.val.v1.VAL](proto/kuksa/val/v1/val.proto)
+- Disabled on Databroker by default [sdv.databroker.v1.Broker](proto/sdv/databroker/v1/broker.proto)
+- Disabled on Databroker by default [sdv.databroker.v1.Collector](proto/sdv/databroker/v1/collector.proto)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 <!-- GETTING STARTED -->
 
 ## Getting started
@@ -120,7 +135,8 @@ The quickest possible way to get Kuksa Databroker up and running.
 ### Reading and writing VSS data using the CLI
 
 1. Start the CLI in a container attached to the _kuksa_ bridge network and connect to the Databroker container:
-   The databroker supports both of `sdv.databroker.v1` and `kuksa.val.v1` as an API. Per default the databroker-cli uses the `sdv.databroker.v1` interface. To change it use `--protocol` option when starting. Choose either one of `kuksa-val-v1` and `sdv-databroker-v1`.
+
+   The databroker supports the lastest new API `kuksa.val.v2` and `kuksa.val.v1` by default, `sdv.databroker.v1` must be enabled using `--enable-databroker-v1`. Per default the databroker-cli uses the `kuksa.val.v1` interface, which can be changed by supplying the `--protocol` option when starting. Choose either `kuksa.val.v1` or `sdv.databroker.v1`, as databroker-cli still does not support  `kuksa.val.v2`.
 
    ```sh
    # in a new terminal
@@ -252,6 +268,15 @@ cargo test --all-targets
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+## Performance
+The Kuksa team has released an official tool to measure the latency and throughput of the Databroker for all supported APIs:
+[kuksa-perf](https://github.com/eclipse-kuksa/kuksa-perf)
+
+The use case measures the time it takes for a signal to be transferred from the Provider to the Signal Consumer
+Signal Consumer(stream subscribe) <- Databroker <- Provider(stream publish)
+
+Feel free to use it and share your results with us!
+
 ## Contributing
 
 Please refer to the [Kuksa Contributing Guide](CONTRIBUTING.md).

README.md

@@ -60,7 +60,7 @@ use the full name. When official release is created replace the copied *.json-fi
 Build and run kuksa_databroker using the new VSS file according to [documentation](../../README.md), e.g.
 
 ```sh
-$cargo run --bin databroker -- --metadata ../data/vss-core/vss_release_4.0.json
+$cargo run --bin databroker -- --metadata ./data/vss-core/vss_release_4.0.json
 ```
 
 Use the client to verify that changes in VSS are reflected, by doing e.g. set/get on some new or renamed signals.

data/vss-core/README.md

@@ -1263,6 +1263,8 @@ mod test {
                 change_type: proto::v1::ChangeType::OnChange.into(),
                 description: "".into(),
                 allowed: None,
+                min: None,
+                max: None,
             },
             proto::v1::Metadata {
                 id: 2,
@@ -1272,6 +1274,8 @@ mod test {
                 change_type: proto::v1::ChangeType::OnChange.into(),
                 description: "".into(),
                 allowed: None,
+                min: None,
+                max: None,
             },
             proto::v1::Metadata {
                 id: 3,
@@ -1281,6 +1285,8 @@ mod test {
                 change_type: proto::v1::ChangeType::OnChange.into(),
                 description: "".into(),
                 allowed: None,
+                min: None,
+                max: None,
             },
         ]
         .to_vec();

databroker-cli/src/sdv_cli.rs

@@ -11,6 +11,8 @@
 * SPDX-License-Identifier: Apache-2.0
 ********************************************************************************/
 
+use std::{env, path::PathBuf};
+
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     std::env::set_var("PROTOC", protobuf_src::protoc());
     tonic_build::configure()
@@ -23,8 +25,23 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                 "proto/sdv/databroker/v1/collector.proto",
                 "proto/kuksa/val/v1/val.proto",
                 "proto/kuksa/val/v1/types.proto",
+                "proto/kuksa/val/v2/val.proto",
+                "proto/kuksa/val/v2/types.proto",
             ],
             &["proto"],
         )?;
+
+    let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
+    tonic_build::configure()
+        .file_descriptor_set_path(out_dir.join("kuksa.val.v2_descriptor.bin"))
+        .compile(
+            &[
+                "proto/kuksa/val/v2/val.proto",
+                "proto/kuksa/val/v2/types.proto",
+            ],
+            &["proto"],
+        )
+        .unwrap();
+
     Ok(())
 }

databroker-proto/build.rs

@@ -143,5 +143,11 @@ pub mod kuksa {
                 }
             }
         }
+        pub mod v2 {
+            tonic::include_proto!("kuksa.val.v2");
+
+            pub const FILE_DESCRIPTOR_SET: &[u8] =
+                tonic::include_file_descriptor_set!("kuksa.val.v2_descriptor");
+        }
     }
 }

databroker-proto/src/lib.rs

@@ -27,6 +27,7 @@ kuksa-common = { path = "../lib/common"}
 kuksa = { path = "../lib/kuksa"}
 databroker-proto = { workspace = true }
 tonic = { workspace = true, features = ["transport", "channel", "prost"] }
+tonic-reflection = "0.11.0"
 prost = { workspace = true }
 prost-types = { workspace = true }
 tokio = { workspace = true, features = [
@@ -60,9 +61,11 @@ jemallocator = { version = "0.5.0", optional = true }
 lazy_static = "1.4.0"
 thiserror = "1.0.47"
 
+futures = { version = "0.3.28" }
+async-trait = "0.1.82"
+
 # VISS
 axum = { version = "0.6.20", optional = true, features = ["ws"] }
-futures = { version = "0.3.28", optional = true }
 chrono = { version = "0.4.31", optional = true, features = ["std"] }
 uuid = { version = "1.4.1", optional = true, features = ["v4"] }
 
@@ -74,7 +77,7 @@ sd-notify = "0.4.1"
 default = ["tls"]
 tls = ["tonic/tls"]
 jemalloc = ["dep:jemallocator"]
-viss = ["dep:axum", "dep:chrono", "dep:futures", "dep:uuid"]
+viss = ["dep:axum", "dep:chrono", "dep:uuid"]
 libtest = []
 
 [build-dependencies]