service-to-signal-blueprint

In this Service-To-Signal Blueprint we show how one can implement a service over Eclipse uProtocol where the interface definition is part of the COVESA uServices. We use the Rust implementation of the Eclipse Zenoh transport of Eclipse uProtocol. The service implementation further relies on the interaction with VSS Signals, brokered in an Eclipse Kuksa Databroker.

In order to apply the requested changes we need a so-called Eclipse Kuksa Provider to communicate the requested changes from the Kuksa Databroker to the underlying hardware. In many current vehicles this might be done over a CAN-bus. Since this blueprint focuses more on future vehicle generations and is intended as a technology showcase, we use Eclipse Zenoh instead. We use the Eclipse Kuksa Zenoh Provider which forwards messages between the gRPC-API of the Eclipse Kuksa Databroker and topics in the Zenoh network concerning the relevant and configurable VSS signals.

Translating between the HTTP/2 based gRPC communication and Eclipse Zenoh makes it possible to connect embedded devices like an Arduino or ESP32 which can use the PicoZenoh implementation. If you do not have such hardware available, there is also the option to use a Zenoh client in software as the software horn.

Components

In the following, we give a more detailed overview of the different involved components.

Horn Service Implementation

The horn service implementation provides the interfaces defined in the COVESA Horn uService. The implementation utilizes the Vehicle.Body.Horn.IsActive COVESA VSS Signal managed by the Eclipse KUKSA Databroker. We use Eclipse Zenoh as transport for the provided Horn service over Eclipse uProtocol.

Horn Client (App)

The App is a consumer of the Horn service and triggers the execution of specific Horn sequences through this interface. There is the horn-client which interacts with the horn service in a pre-defined way and serves as a basic example of how an app can use the horn service.

Kuksa Databroker

The Kuksa Databroker acts as a vehicle abstraction layer and manages the interaction between applications and vehicle signals defined in the Vehicle Signal Specification. Consumers of the kuksa.val.v1 API, implemented by the Kuksa Databroker, can get, subscribe and write to the target or the current value of such a signal within the Kuksa Databroker.

Embedded Horn Activator

We need one component which actually performs the signaling of the Horn. In the easiest setup this is a small program which writes to the console whenever the VSS signal Vehicle.Body.Horn.IsActive is True. To make the setup a bit more realisitic we decided to integrate hardware like an ESP32 for which there is the actuator-provider

These smaller hardware platforms struggle with running a full HTTP/2 based gRPC stack which is one of the reasons to utilize Zenoh with the Zenoh-Pico implementation as transport here.

Software Horn

To allow a quick setup of the overall system and in case you do not have an ESP32 hardware available to run the embedded horn activator, there is an alternative software horn. This components connects to the Zenoh router as well and logs the state of the Horn to the console. Optionally, the software horn can play a sound when the horn is active.

Kuksa Zenoh Provider

For the integration of the hardware controlling the horn, we use Zenoh as transport. So the horn actuator provider publishes and subscribes on a Zenoh topic which is derived from the respective COVESA VSS signal in the Kuksa Databroker. In the case of the Horn, the topic is Vehicle/Body/Horn/IsActive. It is then the responsibility of the Zenoh-Kuksa-Provider to listen to these topics and forward the messages between the Zenoh network and the Kuksa Databroker using gRPC.

Zenoh Router

The Zenoh router routes message between the Kuksa-Zenoh-Provider and the Horn (Embedded Horn Activator or Software Horn). We use the upstream available Docker image of the Zenoh router and reference it in the Docker Compose file.

Quick Start

Configuring the zenoh-kuksa-provider

1. Initialize the kuksa-incubation submodule to add the zenoh-kuksa-provider to your components directory:

git submodule update --init

As an alternative you can pull the service-to-signal repository directly by executing:

git clone --recurse-submodules https://github.com/eclipse-sdv-blueprints/service-to-signal.git

2. After that, the easiest way to set up and start the services is by means of using the Docker Compose file in the top level directory:

docker compose -f service-to-signal-compose.yaml up --build --detach

This will pull or build (if necessary) the container images, create, and start the required components, namely:

• horn-service-kuksa
• Kuksa Databroker
• Kuksa-Zenoh Provider
• Zenoh Router
• Software Horn

As a result the horn-service-kuksa becomes available on port 15000 on the host machine. You can then run the horn client to invoke the horn-service-kuksa.

3. In components/horn-client/ run:

cargo run 

For more details read the documentation in the horn client Readme.

This requires that you installed the Rust toolchain on your computer. As an alternative you can umcomment the section for the horn-client in the service-to-signal-compose.yaml and re-deploy the modified Docker Compose setup.

4. Check logs for Horn

To see the status of the Horn and check whether the setup worked you can read the logs of the software-horn. To do this run:

docker logs software-horn