Initiate Comprehensive Kuksa Requirements Analysis for Enhanced Version Development

README.md

@@ -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
@@ -114,10 +129,13 @@ The quickest possible way to get Kuksa Databroker up and running.
 
    > :bulb: **Tip:** You can stop the container using `ctrl-c`.
 
+*Note that not all APIs are enabled by default, see [user guide](doc/user_guide.md) and*
+*[protocols](doc/protocol/README.md) for more information!*
+
 ### 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. Chosse eihter 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 `sdv.databroker.v1` interface. To change it use `--protocol` option when starting. Choose either one of `kuksa-val-v1` and `sdv-databroker-v1`, databroker-cli still does not support  `kuksa.val.v2`.
 
    ```sh
    # in a new terminal
@@ -249,6 +267,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).

doc/diagrams/consumer_actuate.drawio

@@ -0,0 +1,131 @@
+<mxfile host="65bd71144e">
+    <diagram name="Seite-1" id="DjCrLJOEe4nHxTjUXNSd">
+        <mxGraphModel dx="1956" dy="1169" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="sU0O0qOnpkfrYUOIyIDh-27" value=":DataBroker" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;collapsible=0;recursiveResize=0;outlineConnect=0;rounded=1;" parent="1" vertex="1">
+                    <mxGeometry x="360" y="40" width="100" height="550" as="geometry"/>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-17" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" parent="sU0O0qOnpkfrYUOIyIDh-27" vertex="1">
+                    <mxGeometry x="45" y="120" width="10" height="370" as="geometry"/>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-10" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" parent="sU0O0qOnpkfrYUOIyIDh-27" vertex="1">
+                    <mxGeometry x="39" y="250" width="10" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="sU0O0qOnpkfrYUOIyIDh-33" value=":Signal Consumer" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;collapsible=0;recursiveResize=0;outlineConnect=0;rounded=1;" parent="1" vertex="1">
+                    <mxGeometry y="40" width="100" height="550" as="geometry"/>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-4" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" parent="sU0O0qOnpkfrYUOIyIDh-33" vertex="1">
+                    <mxGeometry x="45" y="250" width="10" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="sU0O0qOnpkfrYUOIyIDh-39" value=":Provider" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;collapsible=0;recursiveResize=0;outlineConnect=0;rounded=1;" parent="1" vertex="1">
+                    <mxGeometry x="885" y="40" width="100" height="550" as="geometry"/>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-18" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" parent="sU0O0qOnpkfrYUOIyIDh-39" vertex="1">
+                    <mxGeometry x="45" y="120" width="10" height="370" as="geometry"/>
+                </mxCell>
+                <mxCell id="THUKiZGTHPrwo03LJUuz-1" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" parent="sU0O0qOnpkfrYUOIyIDh-39" vertex="1">
+                    <mxGeometry x="51" y="250" width="10" height="110" as="geometry"/>
+                </mxCell>
+                <mxCell id="3" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" vertex="1" parent="sU0O0qOnpkfrYUOIyIDh-39">
+                    <mxGeometry x="56" y="300" width="10" height="60" as="geometry"/>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-2" value=":Vehicle Network" style="shape=umlLifeline;perimeter=lifelinePerimeter;whiteSpace=wrap;html=1;container=1;collapsible=0;recursiveResize=0;outlineConnect=0;rounded=1;" parent="1" vertex="1">
+                    <mxGeometry x="1118" y="40" width="106" height="550" as="geometry"/>
+                </mxCell>
+                <mxCell id="4" value="" style="html=1;points=[[0,0,0,0,5],[0,1,0,0,-5],[1,0,0,0,5],[1,1,0,0,-5]];perimeter=orthogonalPerimeter;outlineConnect=0;targetShapes=umlLifeline;portConstraint=eastwest;newEdgeStyle={&quot;curved&quot;:0,&quot;rounded&quot;:0};" vertex="1" parent="56O69Gt65AHP2GdqeosO-2">
+                    <mxGeometry x="48" y="300" width="10" height="60" as="geometry"/>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-14" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="405" y="330" as="sourcePoint"/>
+                        <mxPoint x="49.700000000000045" y="330" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-15" value="ActuateResponse" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="56O69Gt65AHP2GdqeosO-14" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-9" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-12" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="55" y="289.9999999999999" as="sourcePoint"/>
+                        <mxPoint x="400" y="290" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-13" value="Actuate(ActuateRequest=actuator_path)" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="56O69Gt65AHP2GdqeosO-12" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-9" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-19" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1" source="56O69Gt65AHP2GdqeosO-18">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="925" y="160" as="sourcePoint"/>
+                        <mxPoint x="415" y="160" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-20" value="OpenProviderStream(&lt;b&gt;&lt;font color=&quot;#007fff&quot;&gt;stream&lt;/font&gt;&lt;/b&gt;&amp;nbsp;OpenProviderStreamRequest=ProvideActuationRequest(actutators))" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="56O69Gt65AHP2GdqeosO-19" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="10" y="-11" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-22" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1" target="56O69Gt65AHP2GdqeosO-18">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="415.0348837209301" y="180" as="sourcePoint"/>
+                        <mxPoint x="924.9999999999995" y="179.99999999999977" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-23" value="&lt;b&gt;&lt;font color=&quot;#007fff&quot;&gt;stream&lt;/font&gt;&lt;/b&gt;&amp;nbsp;OpenProviderStreamResponse=ProvideActuationResponse" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="56O69Gt65AHP2GdqeosO-22" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-10" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-38" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1" source="THUKiZGTHPrwo03LJUuz-1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="932" y="329.22" as="sourcePoint"/>
+                        <mxPoint x="410" y="330" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-39" value="&lt;b&gt;&lt;font color=&quot;#007fff&quot;&gt;stream&lt;/font&gt;&lt;/b&gt;&amp;nbsp;OpenProviderStreamRequest=BatchActuateStreamResponse" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="56O69Gt65AHP2GdqeosO-38" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-8" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-40" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" source="56O69Gt65AHP2GdqeosO-10" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="415" y="290" as="sourcePoint"/>
+                        <mxPoint x="940" y="290" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="56O69Gt65AHP2GdqeosO-41" value="&lt;b&gt;&lt;font color=&quot;#007fff&quot;&gt;stream&lt;/font&gt;&lt;/b&gt;&amp;nbsp;OpenProviderStreamResponse=BatchActuateStreamRequest(actuator_path, value)" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="56O69Gt65AHP2GdqeosO-40" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-8" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="THUKiZGTHPrwo03LJUuz-2" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="950" y="340" as="sourcePoint"/>
+                        <mxPoint x="1164" y="340" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="THUKiZGTHPrwo03LJUuz-3" value="write_data_frame(data)" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="THUKiZGTHPrwo03LJUuz-2" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-8" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="THUKiZGTHPrwo03LJUuz-4" value="" style="endArrow=classic;html=1;rounded=0;" parent="1" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="1164.5" y="399.9999999999999" as="sourcePoint"/>
+                        <mxPoint x="947" y="399.9999999999999" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="THUKiZGTHPrwo03LJUuz-5" value="ack_write_operation" style="edgeLabel;resizable=0;html=1;;align=center;verticalAlign=middle;" parent="THUKiZGTHPrwo03LJUuz-4" connectable="0" vertex="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint y="-8" as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+</mxfile>