diff --git a/README.md b/README.md index a7711a38..ca18a291 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,8 @@
  • Usage
  • Building
    • +
  • Performance
    • +
  • Additional Documentation
  • Contributing
  • License
  • Contact
    • @@ -88,18 +90,30 @@ Data is usually exchanged with ECUs by means of a CAN bus or Ethernet based prot

    (back to top)

    - -## 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: +Kuksa Databroker provides [gRPC](https://grpc.io/) based API endpoints which can be used by +clients to interact with the server. gRPC services are specified by means of `.proto` files which define the services and the data +exchanged between server and client. +[Tooling](https://grpc.io/docs/languages/) is available for most popular programming languages to create +client stubs for invoking the services. +The Databroker uses gRPC's default HTTP/2 transport and [protocol buffers](https://developers.google.com/protocol-buffers) for message serialization. +The same `.proto` file can be used to generate server skeleton and client stubs for other transports and serialization formats as well. -- 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) +HTTP/2 is a binary replacement for HTTP/1.1 used for handling connections, multiplexing (channels) and providing a standardized way to add headers for authorization and TLS for encryption/authentication. +It also supports bi-directional streaming between client and server. + +Kuksa Databroker implements the following gRPC service interfaces: + +- Enabled on Databroker by default [kuksa.val.v2.VAL](proto/kuksa/val/v2/val.proto) +- Enabled on Databroker by default [kuksa.val.v1.VAL](proto/kuksa/val/v1/val.proto) (Deprecated!) +- Disabled on Databroker by default [sdv.databroker.v1.Broker](proto/sdv/databroker/v1/broker.proto) (Deprecated!) +- Disabled on Databroker by default [sdv.databroker.v1.Collector](proto/sdv/databroker/v1/collector.proto) (Deprecated!) + +In addition to the gRPC interfaces the Kuksa Databroker also supports a subset of the [COVESA VISS v2 Protocol[(https://github.com/COVESA/vehicle-information-service-specification) +using WebSocket. +Please visit the [user guide](doc/user_guide.md) for more information on how the interfaces can be enabled and configured in the Databroker. +Please visit the [protocol documentation](doc/protocol.md) for more information on the APIs.

    (back to top)

    @@ -130,7 +144,7 @@ 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!* +*[protocols](doc/protocol.md) for more information!* ### Reading and writing VSS data using the CLI @@ -277,12 +291,23 @@ Signal Consumer(stream subscribe) <- Databroker <- Provider(stream publish) Feel free to use it and share your results with us! +## Additional Documentation + +Additional documentation is available in the [repository documentation folder](doc). + +

    (back to top)

    + ## Contributing Please refer to the [Kuksa Contributing Guide](CONTRIBUTING.md).

    (back to top)

    + + +## 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. + ## License Kuksa Databroker is provided under the terms of the [Apache Software License 2.0](LICENSE). diff --git a/databroker/src/grpc/kuksa_val_v2/val.rs b/databroker/src/grpc/kuksa_val_v2/val.rs index b2d8c5bc..809fae4f 100644 --- a/databroker/src/grpc/kuksa_val_v2/val.rs +++ b/databroker/src/grpc/kuksa_val_v2/val.rs @@ -2368,7 +2368,9 @@ mod tests { .await .map(|res| res.into_inner()) { - Ok(_) => {} + Ok(_) => { + panic!("We shall not succeed with a blank before *") + } Err(error) => { assert_eq!( error.code(), @@ -2397,7 +2399,9 @@ mod tests { .await .map(|res| res.into_inner()) { - Ok(_) => {} + Ok(_) => { + panic!("Success not expected!") + } Err(error) => { assert_eq!(error.code(), tonic::Code::NotFound, "unexpected error code"); assert_eq!( diff --git a/doc/QUERY.md b/doc/QUERY.md index c2a9c3a0..a64ae41c 100644 --- a/doc/QUERY.md +++ b/doc/QUERY.md @@ -1,4 +1,7 @@ -# 1. Data Broker Query Syntax +# 1. Databroker sdv.databroker.v1 Query Syntax + +*Note! This document is only relevant for the [sdv.databroker.v1](../proto/sdv/databroker/v1) API!* + - [1. Data Broker Query Syntax](#1-data-broker-query-syntax) - [1.1. Intro](#11-intro) diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..490f7ca4 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,19 @@ +# KUKSA Documentation + +This folder contain various documents related to KUKSA + +Document | Content/Comment +----------|-------------------- +[Eclipse Kuksa™ Databroker User Guide](user_guide.md) | Guide on how to start and configure Kuksa Databroker +[Kuksa Quickstart](quickstart.md) | Introduction on how to interact with Kuksa Databroker +[Kuksa System Components and Deployment](system-architecture.md) | Description of the Kuksa Architecture +[Supported Protocols](protocol.md) | Protocols supported by Kuksa Databroker +[Databroker sdv.databroker.v1 Query Syntax](QUERY.md) | Query syntax available in `sdv.databroker.v1` +[Kuksa TLS concept](tls.md) | Introduction to the Kuksa TLS Concept +[Kuksa Authorization Concept](authorization.md) | Introduction to the Kuksa Token Concept +[Runtime behavior and potential attacks](behavior.md) | Description of the runtime behavior of Kuksa Databroker +[Deployment Blueprints](deployment.md) | Logical description of possible deployments of Kuksa +[Kuksa Analysis](kuksa_analysis.md) |Functional requirements, design topics and use case diagrams +[Mapping VSS data types to protobuf Types](TYPES.md) | How VSS datatypes are represented internally in Kuksa Databroker +[Terminology](terminology.md) | Description of terms commonly used in Kuksa Documentation +[Wildcard Matching Rules](wildcard_matching.md) | Wildcard matching rules for `sdv.databroker.v1` and `kuksa.val.v1` diff --git a/doc/TYPES.md b/doc/TYPES.md index 2e25de4c..1e99f26e 100644 --- a/doc/TYPES.md +++ b/doc/TYPES.md @@ -1,4 +1,4 @@ -# Mapping data types +# Mapping VSS data types to Protobuf Types This is how [VSS data types](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_types/) defined by [COVESA VSS](https://covesa.github.io/vehicle_signal_specification/) are mapped to the data types used by @@ -37,4 +37,4 @@ See `enum DataType` in [types.proto](../proto/kuksa/val/v1/types.proto) for the | uint64[] | UINT64_ARRAY | - | | float[] | FLOAT_ARRAY | - | | double[] | DOUBLE_ARRAY | - | -| timestamp[] | TIMESTAMP_ARRAY | - | \ No newline at end of file +| timestamp[] | TIMESTAMP_ARRAY | - | diff --git a/doc/authorization.md b/doc/authorization.md index 46b8eb08..e9f9bc8e 100644 --- a/doc/authorization.md +++ b/doc/authorization.md @@ -1,4 +1,4 @@ -# Authorization in KUKSA.VAL +# Kuksa Authorization Concept * [Background](#background) * [Introduction to OAuth2](#introduction) @@ -64,7 +64,7 @@ orientation around how it fits into the overall OAuth 2.0 Authorization Framewor # Introduction to OAuth2 Using an authorization framework like OAuth2 is well suited for an environment where third party applications need delegated access to a resource, while at the same time restricting the scope -of this access to minimum. +of this access to minimum. See [The OAuth 2.0 Authorization Framework](#the-oauth-20-authorization-framework) for a more detailed description of the benefits, and the problems the framework aims to solve. @@ -75,7 +75,7 @@ OAuth 2.0 defines four roles: > An entity capable of granting access to a protected resource. > When the resource owner is a person, it is referred to as an > end-user. - + The resource owner in this context could be the OEM or the owner of a vehicle. * **Resource server** @@ -421,19 +421,19 @@ Example: > * Third-party applications are required to store the resource > owner's credentials for future use, typically a password in > clear-text. -> +> > * Servers are required to support password authentication, despite > the security weaknesses inherent in passwords. -> +> > * Third-party applications gain overly broad access to the resource > owner's protected resources, leaving resource owners without any > ability to restrict duration or access to a limited subset of > resources. -> +> > * Resource owners cannot revoke access to an individual third party > without revoking access to all third parties, and must do so by > changing the third party's password. -> +> > * Compromise of any third-party application results in compromise of > the end-user's password and all of the data protected by that > password. @@ -462,47 +462,47 @@ Example: > represent specific scopes and durations of access, granted by the > resource owner, and enforced by the resource server and authorization > server. -> +> > The token may denote an identifier used to retrieve the authorization > information or may self-contain the authorization information in a > verifiable manner (i.e., a token string consisting of some data and a > signature). Additional authentication credentials, which are beyond > the scope of this specification, may be required in order for the > client to use a token. -> +> > The access token provides an abstraction layer, replacing different > authorization constructs (e.g., username and password) with a single > token understood by the resource server. This abstraction enables > issuing access tokens more restrictive than the authorization grant > used to obtain them, as well as removing the resource server's need > to understand a wide range of authentication methods. - + [[RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-1.4)] #### Roles > OAuth defines four roles: -> +> > * **resource owner** -> +> > An entity capable of granting access to a protected resource. > When the resource owner is a person, it is referred to as an > end-user. -> +> > * **resource server** -> +> > The server hosting the protected resources, capable of accepting > and responding to protected resource requests using access tokens. -> +> > * **client** -> +> > An application making protected resource requests on behalf of the > resource owner and with its authorization. The term "client" does > not imply any particular implementation characteristics (e.g., > whether the application executes on a server, a desktop, or other > devices). -> +> > * **authorization server** -> +> > The server issuing access tokens to the client after successfully > authenticating the resource owner and obtaining authorization. @@ -515,13 +515,13 @@ Example: > This specification defines a profile for issuing OAuth 2.0 access tokens in JSON Web Token (JWT) format. Authorization servers and resource servers from different vendors can leverage this profile to issue and consume access tokens in an interoperable manner. -> +> > The original OAuth 2.0 Authorization Framework [RFC6749] specification does not mandate any specific format for access tokens. While that remains perfectly appropriate for many important scenarios, in-market use has shown that many commercial OAuth 2.0 implementations elected to issue access tokens using a format that can be parsed and validated by resource servers directly, without further authorization server involvement. -> +> > This specification aims to provide a standardized and interoperable profile as an alternative to the proprietary JWT access token layouts going forward. Besides defining a common set of mandatory and optional claims, the profile provides clear indications on how authorization @@ -557,4 +557,3 @@ Example: * [The OAuth 2.0 Authorization Framework [RFC 6749]](https://www.rfc-editor.org/rfc/rfc6749) * [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens [RFC 9068]](https://datatracker.ietf.org/doc/html/rfc9068) - diff --git a/doc/deployment.md b/doc/deployment.md index e3b32f33..4b35a278 100644 --- a/doc/deployment.md +++ b/doc/deployment.md @@ -1,6 +1,5 @@ # Deployment Blueprints - - [Deployment Blueprints](#deployment-blueprints) - [Deployed Elements](#deployed-elements) - [KUKSA.val databroker (or server)](#kuksaval-databroker-or-server) @@ -45,37 +44,37 @@ Intuitively, it can be seen that the security and safety requirements in an end- # Deployment Blueprint 1: Internal API -You are using VSS and KUKSA.val as an internal API in your system to ease system development. You control the whole system/system integration. +You are using VSS and KUKSA.val as an internal API in your system to ease system development. You control the whole system/system integration. ![Deployment Blueprint 1: Internal API](./pictures/deployment_blueprint1.svg) | Aspect | Design Choice | | ---------------- | ------------- | -| Users | You | -| System Updates | Complete | -| Security | None/Fixed | -| VSS model | Static | -| KUKSA deployment | Firmware | +| Users | You | +| System Updates | Complete | +| Security | None/Fixed | +| VSS model | Static | +| KUKSA deployment | Firmware | You are not exposing any VSS API to external parties, you control all components interacting with VSS, the system state/composition is under your control. In this case you make KUKSA APIs available only within your system. You might even opt to disabling encryption for higher performance and not using any tokens for authentication. We would still recommend leaving basic security measures intact, but this deployment does not need fine-grained control of permission rights or fast rotation/revocation of tokens. # Deployment Blueprint 2: Exposing a subset of VSS to another system -You control the system (e.g. Vehicle Computer), that has KUKSA.val deployed. You want to make a subset of capabilities available to another system or middleware, that may have its own API/security mechanisms. An example would be an Android Automotive based IVI system, +You control the system (e.g. Vehicle Computer), that has KUKSA.val deployed. You want to make a subset of capabilities available to another system or middleware, that may have its own API/security mechanisms. An example would be an Android Automotive based IVI system, ![Deployment Blueprint 2: Exposing a subset of VSS to another system](./pictures/deployment_blueprint2.svg) | Aspect | Design Choice | | ----------------- | ------------- | | Users | Other trusted platforms | -| System Updates | Firmware on controlled system, unknown on third party system | -| Security | TLS+Foreign platform token | -| VSS model | Static | -| KUKSA deployment | Firmware or Software package | +| System Updates | Firmware on controlled system, unknown on third party system | +| Security | TLS+Foreign platform token | +| VSS model | Static | +| KUKSA deployment | Firmware or Software package | In this deployment the foreign system is treated as a single client, which has a certain level of access and trust. Whether that system restricts access further for certain hosted apps is opaque to KUKSA.val. In this deployment you need to enable and configure TLS to provide confidentiality, as well as providing a single token limiting the access of the foreign platform. -If the token is time limited, the foreign platform needs to be provided with a new token in time. In case certificates on the KUKSA.val side are changed, the foreign system needs to be updated accordingly. +If the token is time limited, the foreign platform needs to be provided with a new token in time. In case certificates on the KUKSA.val side are changed, the foreign system needs to be updated accordingly. Doing so, you are using KUKSA to enable other ecosystems, while making the usage of KUKSA transparent to application in that ecosystem. @@ -87,11 +86,11 @@ You control the system running KUKSA.val. You intend to integrate applications f | Aspect | Design Choice | | ---------------- | ------------- | -| Users | 3rd parties | | -| System Updates | App-level | -| Security | TLS+Individual Consumer tokens | -| VSS | Static | -| KUKSA deployment | Software package | +| Users | 3rd parties | | +| System Updates | App-level | +| Security | TLS+Individual Consumer tokens | +| VSS | Static | +| KUKSA deployment | Software package | In this deployment you need to enable and configure TLS to provide confidentiality, as well as providing an individual security token to each VSS consumer, limiting the access of each app. @@ -99,7 +98,7 @@ The scope (and longevity) of those tokens will likely depend on the relationship When you update/rotate the keys for the VSS server you need a process to make sure to update customers at the same time. -In this blueprint you expose an attack surface to a larger group of potential adversaries. To be able to react to security issues faster, you might want to deploy KUKSA.val in a way that allows you to update it individually (i.e. deploy it as a container), instead of just baking it into firmware. +In this blueprint you expose an attack surface to a larger group of potential adversaries. To be able to react to security issues faster, you might want to deploy KUKSA.val in a way that allows you to update it individually (i.e. deploy it as a container), instead of just baking it into firmware. # Deployment Blueprint 4: Dynamic Applications and VSS extensions @@ -112,14 +111,14 @@ This is similar to the *Individual Applications* Use Case with the added capabil | Aspect | Design Choice | | -------------- | ------------- | | Users | 3rd parties | -| System Updates | App-level | -| Security | Individual App tokens | -| VSS | Dynamic | -| KUKSA deployment | Software package | +| System Updates | App-level | +| Security | Individual App tokens | +| VSS | Dynamic | +| KUKSA deployment | Software package | The main difference to the previous use case is allowing providers to add datapoints to the VSS tree managed by KUKSA.val. -This could be a very elegant setup, even in a more static deployment, where KUKSA.val starts with an empty tree, and once the relevant software components come up, it is extended step by step. +This could be a very elegant setup, even in a more static deployment, where KUKSA.val starts with an empty tree, and once the relevant software components come up, it is extended step by step. However, the security and safety implications in such a scenario are the highest: While the security aspect can be handled by KUKSA.val, giving specific applications the right to extend the tree, the overall requirements on system design get harder: @@ -130,5 +129,5 @@ However, the security and safety implications in such a scenario are the highest # Mixing The aforementioned blueprints are examples and any specific deployment might combine aspects of several of them. - - There could be many domains in a vehicle, where a fully static "walled" deployment as described in Blueprint 1 is the right thing to do, while other use cases in the same vehicle require the capabilities found in Blueprint 4. In that case, the right design choice could be to deploy several KUKSA.val instances in a car as sketched in [System Architecture -> (Distributed) KUKSA.val deployment](./system-architecture.md#distributed-kuksaval-deployment). \ No newline at end of file + + There could be many domains in a vehicle, where a fully static "walled" deployment as described in Blueprint 1 is the right thing to do, while other use cases in the same vehicle require the capabilities found in Blueprint 4. In that case, the right design choice could be to deploy several KUKSA.val instances in a car as sketched in [System Architecture -> (Distributed) KUKSA.val deployment](./system-architecture.md#distributed-kuksaval-deployment). diff --git a/doc/kuksa_analysis.md b/doc/kuksa_analysis.md index 9b075abd..af6534d8 100644 --- a/doc/kuksa_analysis.md +++ b/doc/kuksa_analysis.md @@ -11,14 +11,6 @@ The extended list of design topics for Kuksa Databroker is available in the [Kuk ### 3. Use Cases The use cases for Kuksa Databroker is available in the [Kuksa use cases](./kuksa_analysis/kuksa_use_cases.md) -### 4. New API Definition -The latest and new API `kuksa.val.v2` for Kuksa Databroker is available in [kuksa.val.v2](../proto/kuksa/val/v2/val.proto) - -This API is under development and will eventually replace: -[kuksa.val.v1](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/kuksa/val/v1) API. -[sdv.databroker.v1](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/sdv/databroker/v1) API. - - ### Documentation #### [Terminology](./terminology.md) #### [System Architecture](./system-architecture.md) diff --git a/doc/protocol.md b/doc/protocol.md new file mode 100644 index 00000000..eafe4b1f --- /dev/null +++ b/doc/protocol.md @@ -0,0 +1,77 @@ +# Supported protocols in Kuksa Databroker + +This file contains an overview of the protocols supported by Kuksa Databroker. +To be able to understand the differences between protocols it is required to understand the data handling in Kuksa Databroker. The Databroker use datapoints defined by the [COVESA VSS syntax](https://github.com/COVESA/vehicle_signal_specification), and handles them from three perspectives: + +Perspective | Meaning | Set Supported | Get Supported | Subscribe Supported +-------------------|---------|---------------|---------------|-------------------- +Current Value | Current value of a property, for example current window position | Yes | Yes, latest value is stored but not persisted in Databroker | Yes +Target Value | Wanted value of a property, for example wanted window position | Yes (for VSS actuator)| Yes, latest value is stored but not persisted in Databroker | Yes +Actuation Value | Wanted value of a property, for example wanted window position | Yes (for VSS actuator)| No, value is not stored in Databroker | Yes + +*Target Value* and *Actuation Value* are quite similar. They both represent the wanted value of a property they are handled as separate "channels" in the Databroker. +This means that if a someone provides a wanted value to Databroker using an Actuation method, only subscribers for Actuation will be notified. +An API typically supports either *Target Value* or *Actuation Value*, not both! + +Use of the *Target Value* perspective is deprecated! + +## Overview + +This is an overview of the APIs supported described using the perspectives above + +| Protocol | Current Value - Set | Current Value - Get | Current Value - Subscribe | Target Value - Set | Target Value - Get | Target Value - Subscribe | Actuation Value - Set | Actuation Value - Get | Actuation Value - Subscribe +| ------------------------ |-----|-----|-----|-----|-----|-----|-----|-----|-----| +| gRPC (kuksa.val.v2) | Yes | Yes | Yes | No | No | No | Yes | No | Yes +| gRPC (kuksa.val.v1) *Deprecated!* | Yes | Yes | Yes | Yes | Yes | Yes | No | No | No +| gRPC (sdv.databroker.v1) *Deprecated!* | Yes | Yes | Yes | Yes | No | No | No | No | No +| VISS v2 | No | Yes | Yes | Yes | No | No | No | No | No + +In general it is possible to mix protocols in a deployment, as long as the difference concerning Target/Actuation values are observed. +That means, if you want to manage the wanted value of a Datapoint in the system, you must decide if you should use protocols that support the *Target Value* perspective or protocols that support the *Actuation Value* perspective for those Datapoints. + +## `kuksa.val.v2` gRPC Protocol + +The `kuksa.val.v2` is the newest protocol supported by Kuksa Databroker, and the only protocol which may be further developed. +It was created as the `kuksa.val.v1` protocol was not optimal from performance perspective. +For more information see the `kuksa.val.v2` [documentation](../proto/kuksa/val/v2/README.md). + +## `kuksa.val.v1` gRPC Protocol + +This is the predecessor to `kuksa.val.v2`. +For more information see the `kuksa.val.v1` [documentation](../proto/kuksa/val/v1/README.md). + +## `sdv.databroker.v1` gRPC Protocol + +This is the predecessor to `kuksa.val.v1`. +For more information see the `sdv.databroker.v1` [documentation](../proto/sdv/databroker/v1/README.md). + +To enable the legacy `sdv.databroker.v1` API you must start Databroker with the `--enable-databroker-v1` argument. + +### VISS v2 + +KUKSA databroker aims to provide a standards compliant implementation of [VISS](https://github.com/COVESA/vehicle-information-service-specification) v2 (using the websocket transport). + +It supports authorization using the access token format specified in [authorization.md](authorization.md). + +VISSv2 support in databroker is included by building it with the `viss` feature flag. + +```shell +$ cargo build --features viss +``` + +The `enable-viss` flag must be provided at startup in order to enable the VISSv2 websocket interface. + +```shell +$ databroker --enable-viss +``` + +The arguments `--viss-address` and `--viss-port` can be used if you want to use a different address or port than default for VISS. +If not specified, the address `127.0.0.1` will be used unless otherwise specified with `--address`, and the port 8090 will be used. + +Using kuksa-client, the VISSv2 interface of databroker is available using the `ws` protocol in the uri, i.e.: + +```shell +$ kuksa-client ws://127.0.0.1:8090 +``` + +TLS is currently not supported. diff --git a/doc/protocol/README.md b/doc/protocol/README.md deleted file mode 100644 index 8090b933..00000000 --- a/doc/protocol/README.md +++ /dev/null @@ -1,92 +0,0 @@ -## Supported protocols - -This file contains an overview what the KUKSA Server and databroker each supports. It focuses on gRPC and VISS support and also what feeders are supported. - -| Protocol | KUKSA server | KUKSA databroker | -| ------------------------ | :----------: | :--------------: | -| VISS V1 | - | - | -| VISS V2 | x/- | x/- | -| gRPC (kuksa) | x | - | -| gRPC (kuksa.val.v2) | - | x | -| gRPC (kuksa.val.v1) | - | x | -| gRPC (sdv.databroker.v1) | - | x | - -x = supported; x/- = partially supported; - = not supported - -### VISSv2 support (websocket transport) - -| Feature | KUKSA server | KUKSA databroker | -| ------------------------- | :-------------: | :--------------: | -| Read | | | -| - Authorized Read | x1,2 | x | -| - Search Read | - | - | -| - History Read | - | - | -| - Static Metadata Read | - | x | -| - Dynamic Metadata Read | - | - | -| Update | | | -| - Authorized Update | x1,2 | x | -| Subscribe | | | -| - Authorized Subscribe | x1,2 | x | -| - Curve Logging Subscribe | - | - | -| - Range Subscribe | - | - | -| - Change Subscribe | - | - | -| Unsubscribe | x | x | -| Subscription | x | x | -| Error messages | x | x | -| Timestamps | x | x | - -x = supported - -x1 Authorization is done using a non-standard standalone call which is incompatible with standards compliant clients. - -x2 Relies on the non-standard `attribute` values which doesn't work with standards compliant clients. - -For a more detailed view of the supported JSON-schemas [click here](https://github.com/eclipse/kuksa.val/blob/master/kuksa-val-server/include/VSSRequestJsonSchema.hpp) - -### sdv.databroker.v1 in KUKSA Databroker - -To enable the legacy `sdv.databroker.v1` API you must start Databroker with the `--enable-databroker-v1` argument. - -### VISSv2 in KUKSA Databroker - -KUKSA databroker aims to provide a standards compliant implementation of VISSv2 (using the websocket transport). - -It supports authorization using the access token format specified in [authorization.md](../authorization.md). - -VISSv2 support in databroker is included by building it with the `viss` feature flag. - -```shell -$ cargo build --features viss -``` - -The `enable-viss` flag must be provided at startup in order to enable the VISSv2 websocket interface. - -```shell -$ databroker --enable-viss -``` - -The arguments `--viss-address` and `--viss-port` can be used if you want to use a different address or port than default for VISS. -If not specified, the address `127.0.0.1` will be used unless otherwise specified with `--address`, and the port 8090 will be used. - -Using kuksa-client, the VISSv2 interface of databroker is available using the `ws` protocol in the uri, i.e.: - -```shell -$ kuksa-client ws://127.0.0.1:8090 -``` - -TLS is currently not supported. - -### KUKSA databroker gRPC API - -The VISS Standard is not applicable for gRPC protocols. Here is an overview what the gRPC API in KUKSA databroker is capable of: - -- Read: Reading VSS datapoints - - Reading value for actuators (for kuksa.val.v1 current or target values) - - Reading some metadata information from VSS datapoints -- Write: Writing VSS datapoints - - Writing sensor values - - Writing value for actuators (for kuksa.val.v1 current or target value) - - Soon: Writing some metadata information from VSS datapoints -- Subscription: Subscribing VSS datapoints - - Subscribing sensor values - - Subscribing value for actuators (for kuksa.val.v1 current or target value) diff --git a/doc/quickstart.md b/doc/quickstart.md index f7995e06..40477391 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -1,4 +1,4 @@ -# KUKSA.val Quickstart using kuksa.val.v1 API +# KUKSA quickstart using kuksa.val.v1 API The quickest possible way to get KUKSA.val up and running diff --git a/doc/system-architecture.md b/doc/system-architecture.md index caca40cb..f05a2d52 100644 --- a/doc/system-architecture.md +++ b/doc/system-architecture.md @@ -1,4 +1,4 @@ -# KUKSA System Components and Deployment +# Kuksa System Components and Deployment This document shows basic KUKSA deployments and gives examples for provider components. diff --git a/doc/tls.md b/doc/tls.md index e176f89e..dca1411b 100644 --- a/doc/tls.md +++ b/doc/tls.md @@ -1,4 +1,4 @@ -# KUKSA TLS concept +# Kuksa TLS concept This page describes the TLS support in KUKSA diff --git a/doc/user_guide.md b/doc/user_guide.md index 1fdbedc2..cc8fd644 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -14,11 +14,12 @@ The following sections provide information for running and configuring Databroke
  • Running Databroker
  • Enabling Authorization
  • Enabling TLS
    • -
  • Query Syntax
    • +
  • APIs supported by Databroker
    • +
  • Current and target value concept vs data value concept
  • Using Custom VSS Data Entries
    • -
  • Configuration Reference
  • Signal Change Types
    • -
  • API
    • +
  • Configuration Reference
    • +
  • Troubleshooting
  • Known Limitations
    • @@ -147,24 +148,30 @@ docker run --rm -it --network kuksa -v ./certificates:/opt/kuksa ghcr.io/eclipse

    (back to top)

    -## Query Syntax +## APIs supported by Databroker -Clients can subscribe to updates of data entries of interest using an SQL-based [query syntax](./QUERY.md). +Kuksa Databroker provides [gRPC](https://grpc.io/) based API endpoints which can be used by +clients to interact with the server. -You can try it out using the `subscribe` command in the client: +Kuksa Databroker implements the following service interfaces: -```shell -subscribe -SELECT - Vehicle.ADAS.ABS.IsError -WHERE - Vehicle.ADAS.ABS.IsEngaged -``` +- Enabled on Databroker by default [kuksa.val.v2.VAL](../proto/kuksa/val/v2/val.proto) (recommended to use but still not supported by databroker-cli) +- Enabled on Databroker by default [kuksa.val.v1.VAL](../proto/kuksa/val/v1/val.proto) +- Disabled on Databroker by default, use `--enable-databroker-v1` to enable [sdv.databroker.v1.Broker](../proto/sdv/databroker/v1/broker.proto) +- Disabled on Databroker by default, use `--enable-databroker-v1` to enable [sdv.databroker.v1.Collector](../proto/sdv/databroker/v1/collector.proto) -```console -[subscribe] OK -Subscription is now running in the background. Received data is identified by [1]. -``` +Please visit [protocol documentation](protocol.md) for more information on the APIs. + +

    (back to top)

    + +## Current and target value concept vs data value concept. +For some of the APIs (`sdv.databroker.v1` and `kuksa.val.v1`), the concepts of `current_value` and `target_value` were introduced to differentiate between the expected or desired value for an actuator and the current value published by the provider (both stored in the Databroker’s database). + +This concept has been removed in `kuksa.val.v2`. Now, there is only a single `data_value` for sensors and actuators, meaning that desired actuator values are simply forwarded from the Signal Consumer to the Databroker and then to the Provider. The Provider is responsible for updating on Databroker the `data_value` received from the vehicle network. + +**Kuksa does not guarantee that the desired actuator value will be fully updated on the vehicle network; it only forwards actuator values from the Signal Consumer to the vehicle network.** + +**Do not mix different versions of APIs for providers and clients, as this will cause issues; kuksa.val.v2 is not backward compatible with sdv.databroker.v1 and kuksa.val.v1**

    (back to top)

    @@ -254,31 +261,6 @@ The default configuration can be overridden by means of setting the correspondin

    (back to top)

    -## API - -Kuksa Databroker provides [gRPC](https://grpc.io/) based API endpoints which can be used by -clients to interact with the server. - -gRPC services are specified by means of `.proto` files which define the services and the data -exchanged between server and client. - -[Tooling](https://grpc.io/docs/languages/) is available for most popular programming languages to create -client stubs for invoking the services. - -The Databroker uses gRPC's default HTTP/2 transport and [protocol buffers](https://developers.google.com/protocol-buffers) for message serialization. -The same `.proto` file can be used to generate server skeleton and client stubs for other transports and serialization formats as well. - -HTTP/2 is a binary replacement for HTTP/1.1 used for handling connections, multiplexing (channels) and providing a standardized way to add headers for authorization and TLS for encryption/authentication. -It also supports bi-directional streaming between client and server. - -Kuksa Databroker implements the following service interfaces: - -- [kuksa.val.v1.VAL](../proto/kuksa/val/v1/val.proto) -- [sdv.databroker.v1.Broker](../proto/sdv/databroker/v1/broker.proto) -- [sdv.databroker.v1.Collector](../proto/sdv/databroker/v1/collector.proto) - -

    (back to top)

    - ## Troubleshooting ### 'h2 protocol error: http2 error: connection error detected: frame with invalid size' diff --git a/doc/wildcard_matching.md b/doc/wildcard_matching.md index 640cfb08..15b1fa1c 100644 --- a/doc/wildcard_matching.md +++ b/doc/wildcard_matching.md @@ -1,4 +1,8 @@ -### Matching rules +# Wildcard Matching rules + +*Note! This document applies to `sdv.databroker.v1` and `kuksa.val.v1`!* +*It also currently applies to `root` in `ListMetadata` in `kuksa.val.v2` but that may change in the future.* + * An empty pattern "" will match any signal. * A pattern without any asterisk - a path in other words - matches either a signal directly or any signal that is a direct or indirect child of the branch with that path. diff --git a/proto/kuksa/val/v1/README.md b/proto/kuksa/val/v1/README.md index 777187d2..a93e2e42 100644 --- a/proto/kuksa/val/v1/README.md +++ b/proto/kuksa/val/v1/README.md @@ -1,7 +1,6 @@ # kuksa.val.v1 protobuf API -This directory contain a Protobuf API supported by KUKSA.val Databroker, KUKSA.val Python Client and KUKSA.val Go Client. +This directory contain a Protobuf API supported by KUKSA Databroker. -This API may in the future be deprecated. It is recommended to use -the [kuksa.val.v2](../v2/val.proto) API, unless you need -functionality currently only provided by this API. +This API is deprecated. It is recommended to use +the [kuksa.val.v2](../v2/val.proto). diff --git a/proto/kuksa/val/v2/README.md b/proto/kuksa/val/v2/README.md index 10e87723..23f57247 100644 --- a/proto/kuksa/val/v2/README.md +++ b/proto/kuksa/val/v2/README.md @@ -1,7 +1,7 @@ # kuksa.val.v2 protobuf API -This directory contain a Protobuf API supported by KUKSA.val Databroker and KUKSA.val Python Client. +This directory contain a Protobuf API supported by KUKSA Databroker. -This API is under development and will eventually replace: -[kuksa.val.v1](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/kuksa/val/v1) API. +This API replaces: +[kuksa.val.v1](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/kuksa/val/v1) API and [sdv.databroker.v1](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/sdv/databroker/v1) API. diff --git a/proto/kuksa/val/v2/val.proto b/proto/kuksa/val/v2/val.proto index 8c37e19a..2756ac19 100644 --- a/proto/kuksa/val/v2/val.proto +++ b/proto/kuksa/val/v2/val.proto @@ -249,7 +249,13 @@ message BatchActuateResponse { } message ListMetadataRequest { + // Root path to be used when listing metadata + // Shall correspond to a VSS branch, e.g. "Vehicle", "Vehicle.Cabin" + // Metadata for all signals under that branch will be returned unless filtered by filter. + // NOTE: Currently Databroker supports also signals and wildcards in root but that may + // be removed in a future release! string root = 1; + // NOTE : Currently not considered by Databroker, all signals matching root are returned string filter = 2; } diff --git a/proto/sdv/databroker/v1/README.md b/proto/sdv/databroker/v1/README.md index 440b77bb..2fd44c87 100644 --- a/proto/sdv/databroker/v1/README.md +++ b/proto/sdv/databroker/v1/README.md @@ -1,7 +1,8 @@ # sdv.databroker.v1 protobuf API -This directory contain a Protobuf API supported by KUKSA.val Databroker. +This directory contain a Protobuf API supported by KUKSA Databroker. -This API may in the future be deprecated. It is recommended to use -the [kuksa.val.v2](../../../kuksa/val/v2/val.proto) API, unless you need -functionality currently only provided by this API. +To enable the legacy `sdv.databroker.v1` API you must start Databroker with the `--enable-databroker-v1` argument. + +This API is deprecated. It is recommended to use +the [kuksa.val.v2](../../../kuksa/val/v2/val.proto).