Tutorials

• 1: Getting Started
• 1.1: Quickstart
• 1.2: Import examples
• 1.3: Install a working container runtime
• 1.4: Working behind proxy
• 2: Prototyping
• 2.1: digital.auto
• 2.2: Service Integration
• 3: Vehicle App Development
• 3.1: Python Vehicle App Development
• 3.2: C++ Vehicle App Development
• 3.3: Vehicle App Integration Testing
• 4: Vehicle Model Creation
• 4.1: Automated Vehicle Model Lifecycle
• 4.2: Manual Vehicle Model Creation
• 4.2.1: C++ Manual Vehicle Model Creation
• 4.2.2: Python Manual Vehicle Model Creation
• 4.2.3: Vehicle Model Distribution
• 4.2.3.1: C++ Vehicle Model Distribution
• 4.2.3.2: Python Vehicle Model Distribution
• 5: Vehicle App Runtime
• 5.1: Local Runtime
• 5.2: Kanto Runtime
• 6: Vehicle App Deployment

1 - Getting Started

1.1 - Quickstart

This page describes

• how to create a GitHub repository for your Vehicle App development,
• how to set up and configure the DevContainer-based development environment , and
• how to build, customize and test the sample Vehicle App included in your freshly created Vehicle App repository.

You will learn how to use the Vehicle App SDK, interact with the Vehicle API and work with CI/CD using the pre-configured GitHub Workflows that come with the template repository.

Once you have completed all steps, you will have a solid understanding of the development workflow, and you will be able to use one of our template repositories as a starting point for your own Vehicle App development project.

Prerequisites

Please make sure you did all the prerequisite steps to create comprehensive development environment for your Vehicle App:

• Install VS Code

• Install a working container runtime

• Add the Remote-Containers extension to VS Code via the marketplace or using the command line:

  code --install-extension ms-vscode-remote.remote-containers
  

How to create your Vehicle App repository?

For your (GitHub) organization and Vehicle App repository the name MyOrg/MyFirstVehicleApp is used as a place holder during the rest of the document.

You can create your own repository using one of our provided templates or start prototyping via digital.auto.

• Using Template
• Velocitas CLI create
• digital.auto

How to start developing?

In this section you will learn different possibilities to start developing based on your repository. Basically you can work on your own machine using VS Code’s DevContainer or you can set up the environment on a remote agent, using GitHub Codespaces .

• VS Code
• GitHub Codespaces

You can find more information about the Vehicle App development in the respective pages .

How to start the runtime services?

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 or via the Kanto runtime .

• Local Runtime
• Kanto Runtime

$ velocitas exec runtime-local up

Hint: Log files can be found in your workspace's logs directory
> mqtt-broker running
> vehicledatabroker running
> seatservice running
> feedercan running
✅ Runtime is ready to use!

$ velocitas exec runtime-kanto up

Hint: Log files can be found in your workspace's logs directory
> Checking Kanto registry... registry already exists.
> Checking Kanto registry... starting registry.
> Checking Kanto registry... started.
✅ Configuring controlplane for Kanto...
⠇ Starting Kanto...waiting
✅ Kanto is ready to use!

More information about the runtimes are available here .

How to debug your Vehicle App?

Now that the runtime services are all up and running, let’s start a debug session for the Vehicle App.

• Python
• C++

How to trigger the CI Workflow?

The provided GitHub workflows are used to build the container image for the Vehicle App, run unit and integration tests and collect the test results.

The CI Workflow will be triggered by pushing a change to the main branch of your repository:

1. Make modification in any of your files

2. Navigate in your terminal to your repository

3. Commit and push your change

   git add .
   git commit -m "<explain your changes>"
   git push origin
   

To see the results open the Actions page of your repository on GitHub, go to CI Workflow and check the workflow output.

How to release your Vehicle App?

Now that the CI Workflow was successful, you are ready to build your first release. The goal is to build a ready-to-deploy container image that is published in the GitHub container registry.

1. Open the Code page of your repository on GitHub
2. Click on Create a new release in the Releases section on the right side
3. Enter a version (e.g. v1.0.0) and click on Publish release
   • GitHub will automatically create a tag using the version number

The provided release workflow will be triggered by the release. It creates a release documentation and publishes the container image of the Vehicle App to the GitHub container registry. A detailed description of the workflow can be found here .

How to deploy your Vehicle App?

After releasing the Vehicle App to the GitHub container registry you might ask how to bring the Vehicle App and the required runtime stack on a device. Here, Eclipse Leda comes into the game.

Please read the documentation of Eclipse Leda to get more information.

Next steps

• Tutorial: Creating a Vehicle Model
• Tutorial: Create a Vehicle App
• Tutorial: Develop and run integration tests for a Vehicle App

1.2 - Import examples

This guide will help you to import examples provided by the SDK package into your template repository.

A Visual Studio Code task called Import example app from SDK is available in the /.vscode/tasks.json which can replace your /app directory in your template repository with some example Vehicle Apps from the SDK package.

1. Press F1
2. Select command Tasks: Run Task
3. Select Import example app from SDK
4. Choose Continue without scanning the output
5. Select seat-adjuster

Run the Vehicle App from SDK example

The launch settings are already prepared for the VehicleApp in the template repository /.vscode/launch.json. The configuration is meant to be as generic as possible to make it possible to run all provided example apps.

Every example app comes with its own /app/AppManifest.json to see which Vehicle Services are configured and needed as a dependency.

To start the app: Just press F5 to start a debug session of the example Vehicle App.

To debug example, please check How to debug Vehicle App?

1.3 - Install a working container runtime

In the past the recommended runtime would for sure be Docker Desktop . But since Docker Inc. changed their license model it is fair enough for an open source project to look for free alternatives.

Linux

The obvious (and our recommended) “alternative” to Docker Desktop on Linux is to just use the Docker Engine (without Docker Desktop), a pure CLI-based solution available for most popular Linux distributions licensed under the Apache License, version 2.0. Installation instructions can be found here .

MacOS

Since the Docker Engine is not working out of the box on MacOS, a virtualizations tool which helps emulating linux is needed. Fortunately there are several solutions on the market. Good results could be achieved using Colima .

Setup Colima

Please uninstall or at least quit Docker Desktop if you already used it, before starting the setup.

For Colima to work properly you need Colima itself and a container client e.g. the Docker client, which is still free to use:

    brew install colima
    brew install docker

After the installation you need to start the runtime:

    colima start --cpu x --memory y

For M1 Macs it might be necessary to add --arch aarch64

Docker Desktop uses 5 cores and 12 GB of RAM by default on an M1 MacBook Pro. The equivalent in Colima can be achieved with

    colima start --cpu 5 --memory 12

That’s all you have to do. After these few steps you can go on with the devcontainer setup.

Microsoft Windows

There is currently no recommended alternative for Windows except using GitHub codespaces, a cloud-based development environment.

An option would be to setup a VM (e.g. with VirtualBox or VMWare) running a Linux system with Docker Engine (see above).

Other alternatives

Besides our recommendations above, there are further alternatives, which are not yet evaluated by this project or have some other drawbacks, blocking a recommendation.

For example, you could try Podman / Buildah , which can replace docker run and docker build, respectively. Podman is available for MacOS, Windows, and several Linux distributions. Buildah seems just being available for several Linux distributions.

1.4 - Working behind proxy

We know what a pain and how time consuming it can be to setup your environment behind a cooperate proxy. This guide will help you to set it up correctly.

Be aware that correct proxy configuration depends on the setup of your organization and of course of your personal development environment (hardware, OS, virtualization setup, …). So, we most probably do not cover all issues out there in the developers world. So, we encourage you to share hints and improvements with us.

HTTP(s) proxy server

Install and configure the proxy server as recommended or required by your company. For example you could use PX , which is a HTTP(s) proxy server that allows applications to authenticate through an NTLM or Kerberos proxy server, typically used in corporate deployments, without having to deal with the actual handshake. Px leverages Windows SSPI or single sign-on and automatically authenticates using the currently logged in Windows user account. It is also possible to run Px on Windows, Linux and MacOS without single sign-on by configuring the domain, username and password to authenticate with. (Source: PX )

• Install your HTTP(s) proxy server
• Start your HTTP(s) proxy server

Docker Desktop

You need to install Docker Desktop using the right version. As we recognized a proxy issue in Docker Desktop #12672 we strongly recommend to use a Docker Desktop version >= 4.8.2. In case you have an older version on your machine please update to the current version.

In the next step you need to enter your proxy settings:

• Open Docker Desktop and go to the Settings
• From Resources, select Proxies
• Enable Manual proxy configuration
• Enter your proxy settings, this depends on the configuration you did while setting up your proxy tool e.g.:
  • Web Server (HTTP): http://localhost:3128
  • Secure Web Server (HTTPS): http://localhost:3128
  • Bypass: localhost,127.0.0.1
• Apply & Restart.

Docker daemon

You also have to configure the Docker daemon, which is running the containers basically, to forward the proxy settings. For this you have to add the proxy configuration to the ~/.docker/config.json. Here is an example of a proper config (Port and noProxy settings might differ for your setup):

• Windows
• MacOS
• Linux

{
 "proxies":{
      "default":{
         "httpProxy":"http://host.docker.internal:3128",
         "httpsProxy":"http://host.docker.internal:3128",
         "noProxy":"host.docker.internal,localhost,127.0.0.1"
      }
   }
}

{
 "proxies":{
      "default":{
         "httpProxy":"http://host.docker.internal:3128",
         "httpsProxy":"http://host.docker.internal:3128",
         "noProxy":"host.docker.internal,localhost,127.0.0.1"
      }
   }
}

{
 "proxies":{
      "default":{
         "httpProxy":"http://172.17.0.1:3128",
         "httpsProxy":"http://172.17.0.1:3128",
         "noProxy":"host.docker.internal,localhost,127.0.0.1"
      }
   }
}

For more details see: Docker Documentation

Environment Variables

It is required to set the following environment variables:

• HTTP_PROXY - proxy server, e.g. http://localhost:3128
• HTTPS_PROXY - secure proxy server, e.g. http://localhost:3128

• Windows
• MacOS
• Linux

set
setx HTTP_PROXY "http://localhost:3128"
setx HTTPS_PROXY "http://localhost:3128"

echo "export HTTP_PROXY=http://localhost:3128" >> ~/.bash_profile
echo "export HTTPS_PROXY=http://localhost:3128" >> ~/.bash_profile
source ~/.bash_profile

echo "export HTTP_PROXY=http://localhost:3128" >> ~/.bash_profile
echo "export HTTPS_PROXY=http://localhost:3128" >> ~/.bash_profile
source ~/.bash_profile

Troubleshooting

Solving issues with TLS (SSL) certificate validation using https connections from containers

If you are behind a so-called intercept proxy (which you most probably are), you can run into certificate issues: Your corporate proxy works as a “man-in-the-middle” to be able to check the transferred data for malicious content. Means, there is a protected connection between the application in your local runtime environment and the proxy and another from the proxy to the external server your application wants to interact with.

For the authentication corporate proxies often use self-signed certificates (certificates which are not signed by a (well-known official) certificate authority. Those kind of certificates need to be added to the database of trusted certificates of your local runtime environment. This task is typically handled by the IT department of your corporation (if the OS and software installed on it is managed by them) and you will not run into problems, normally.

If it comes to executing containers, those are typically not managed by your IT department and the proxy certificate(s) is/are missing. So, you need to find a way to install those into the (dev) container you want to execute.

See (one of) those articles to get how to achieve that:

• Overcoming Proxy Issues with Docker Containers
• Docker behind SSL intercepting proxy

Initial DevContainer build issue

If you experience issues during initial DevContainer build, clean all images and volumes otherwise cache might be used:

• Open Docker Desktop
• From Troubleshooting choose Clean / Purge data

GitHub rate limit exceeded

How to fix can be found at Lifecycle Management Troubleshooting .

2 - Prototyping

2.1 - digital.auto

The open and web based digital.auto offers a rapid prototyping environment to explore and validate ideas of a Vehicle App.
digital.auto interacts with different vehicle sensors and actuators via standardized APIs specified by the COVESA Vehicle Signal Specification (VSS) without custom setup requirements.
Within the platform you can:

• browse, navigate and enhance vehicle signals (sensors, actuators and branches) in the Vehicle API Catalogue mapped to a 3D model of the vehicle.
• build Vehicle App prototypes in the browser using Python and the Vehicle API Catalogue.
• test the Vehicle App prototype in a dashboard with 3D animation for API calls.
• create new plugins, which usually represent UX widgets or remote server communication to enhance the vehicle mockup experience in the playground.
• collect and evaluate user feedback to prioritize your development portfolio.

Start the journey of a Vehicle App

As first step open digital.auto , select Get Started in the prototyping section of the landing page and use the Vehicle Model of your choice.

You now have the possibility to browse existing vehicle signals for the selected vehicle model which you can use for prototyping your Vehicle App by clicking on Vehicle APIs.

Add additional Vehicle APIs

If the ideation of your Vehicle App prototype comes with any new Vehicle API which is not part of the standard VSS you also have the option to include it into your pre-selected model by clicking the + New Wishlist API button. After filling out all required fields, simply click the create button - this will commit the new API to the existing model.

Prototype an idea of a Vehicle App

The next step would be to prototype your idea. To do so:

• Click on Prototype Library of your selected model.
• Create a new prototype, by clicking on New Prototype and filling out the information or select one from the list.
• Click on the Open button.
• Go to the Code section and start your prototype right away.

Test the prototype of a Vehicle App

Testing of your prototype starts in the Run section.
You will find a dashboard consisting all vehicle and application components similar to mockups.
The control center on the right side has an integrated terminal showing all of your prototyped outputs as well as a list of all called VSS API’s.
The Run button executes all your prototype code from top to bottom. The Debug button allows you to step through your prototype line by line.

To get started quickly, the digital.auto team has added a number of widgets to simulate related elements of the vehicle – like doors, seats, light, etc. – and made them available in the playground.

Feel free to add your own Plugins with widgets for additional car features (maybe an antenna waving a warm “welcome”…?).

Transfer your prototype into a Velocitas Vehicle App

In the previous steps you started with envisioning and prototyping your Vehicle App idea and tested it against mocked vehicle components in digital.auto.
The Velocitas team provides a project generator to transfer the prototype from digital.auto into your own development environment where you are able to test it with real Vehicle Services .
The generator creates a Vehicle App GitHub repository using your prototype code based on our vehicle-app-python-template .
In the ‘Code’ section of your prototype in digital.auto you have the button ‘Create Eclipse Velocitas Project’.

After pressing the button you will be forwarded to GitHub .
Login with your GitHub Account and authorize velocitas-project-generator to create the repository for you.
You will be redirected to digital.auto and asked for a repository name (equals to the name of the Vehicle App).
By clicking on “Create repository”:

• the project generator takes over your prototype code.
• the code is adapted to the structure in the vehicle-app-python-template .
• a new private repository under your specified GitHub User will be created.

A successful generation of the repository is followed by a pop-up dialogue with the URL of your repository.

Among other things the newly created repository will contain:

Your prototype Vehicle App transferred into a GitHub repository is now ready to be extended.
Clone your newly created repository and open the Vehicle App in Microsoft Visual Studio Code and start to extend it.

You can proceed with the following topics:

• Starting development environment
• Vehicle App Development

2.2 - Service Integration

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 .

Our maintained devenv-runtimes package ( Velocitas Lifecycle Management ) comes with the support of adding further Vehicle Services to the runtime.json of a package. More information here .

Modify existing services

For more advanced usage you can also try to modify existing services. Check out the seat service for example, modify it and integrate it into your Vehicle App repository.

Create your own services

If you want to create your own service the KUKSA.VAL Services repository 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 with any programming language of your choice (learn more about gRPC ).

Mock Provider and Mock Provider Integration

The Vehicle 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

The Mock Provider is already integrated in all our Vehicle Runtimes . 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.

3 - Vehicle App Development

Please visit first Getting Started page if you don’t know where to start.

3.1 - Python Vehicle App Development

We recommend that you make yourself familiar with the Vehicle App SDK first, before going through this tutorial.

The following information describes how to develop and test the sample Vehicle App that is included in the Python template repository . You will learn how to use the Vehicle App Python SDK and how to interact with the Vehicle Model.

Once you have completed all steps, you will have a solid understanding of the development workflow and you will be able to reuse the template repository for your own Vehicle App development project.

Develop your first Vehicle App

This section describes how to develop your first Vehicle App. Before you start building a new Vehicle App, make sure you have already read this manual:

• Quickstart

Once you have established your development environment, you will be able to start developing your first Vehicle App.

For this tutorial, you will recreate the Vehicle App that is included with the SDK repository : The Vehicle App allows to change the position of the driver’s seat in the car and also provides its current positions to other applications. A detailed explanation of the use case and the example is available here .

Setting up the basic skeleton of your app

At first, you have to create the main Python script called main.py in /app/src. All the relevant code for your new Vehicle App goes there.

If you’ve created your app development repository from our Python template repository , the Velocitas CLI create command or via digital.auto prototyping a file with this name is already present and can be adjusted to your needs.

Setting up the basic skeleton of an app consists of the following steps:

1. Manage your imports
2. Enable logging
3. Initialize your class
4. Define the entry point of your app

Manage your imports

Before you start development in the main.py you just created, it will be necessary to include the imports required, which you will understand better later through the development:

import asyncio
import json
import logging
import signal

from velocitas_sdk.util.log import (  # type: ignore
    get_opentelemetry_log_factory,
    get_opentelemetry_log_format,
)
from velocitas_sdk.vdb.reply import DataPointReply
from velocitas_sdk.vehicle_app import VehicleApp, subscribe_topic
from vehicle import Vehicle, vehicle  # type: ignore

Enable logging

The following logging configuration applies the default log format provided by the SDK and sets the log level to INFO:

logging.setLogRecordFactory(get_opentelemetry_log_factory())
logging.basicConfig(format=get_opentelemetry_log_format())
logging.getLogger().setLevel("INFO")
logger = logging.getLogger(__name__)

Initialize your class

The main class of your new Vehicle App needs to inherit the VehicleApp provided by the Python SDK .

class MyVehicleApp(VehicleApp):

In class initialization, you have to pass an instance of the Vehicle Model:

def __init__(self, vehicle_client: Vehicle):
    super().__init__()
    self.Vehicle = vehicle_client

We save the vehicle object to use it in our app. Now, you have initialized the app and can continue developing relevant methods.

Entry point of your app

Here’s an example of an entry point to the MyVehicleApp that we just developed:

async def main():
    """Main function"""
    logger.info("Starting my VehicleApp...")
    vehicle_app = MyVehicleApp(vehicle)
    await vehicle_app.run()

LOOP = asyncio.get_event_loop()
LOOP.add_signal_handler(signal.SIGTERM, LOOP.stop)
LOOP.run_until_complete(main())
LOOP.close()

With this your app can now be started. In order to provide some meaningful behaviour of the app, we will enhance it with more features in the next sections.

Vehicle Model Access

In order to facilitate the implementation, the whole vehicle is abstracted into model classes. Please check tutorial about creating models for more details about this topic. 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 installed as a Python package named vehicle. 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.

If you want to access a single DataPoint e.g. for the vehicle speed, this can be done via

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 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:

self.DriverSeatPosition = await self.Vehicle.Cabin.Seat.Row1.DriverSide.Position.get()

Subscription to Data Points

If you want to get notified about changes of a specific DataPoint, you can subscribe to this event, e.g. as part of the on_start() method in your app.

    async def on_start(self):
        """Run when the vehicle app starts"""
        await self.Vehicle.Cabin.Seat.Row1.DriverSide.Position.subscribe(
            self.on_seat_position_changed
        )

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 Databroker. Therefore the on_seat_position_changed callback function needs to be implemented like this:

    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.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. This would replace the implementation of the Subscription to Data Points

@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.DriverSide.Position).value}

    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.

Services

Services are used to communicate with other parts of the vehicle via remote function calls (RPC). Please read the basics about them here .

location = SeatLocation(row=1, index=1)
await self.vehicle_client.Cabin.SeatService.MoveComponent(
    location, BASE, data["position"]
    )

In order to define which seat you like to move, you have to pass a SeatLocation object as the first parameter. The second argument specifies the component of the seat to be moved. The possible components are defined in the proto files. The last parameter to be passed into the method is the desired position of the component.

Make sure to use the await keyword when calling service methods, since these methods are asynchronously working coroutines.

MQTT

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 .

In the quickstart section 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:

    @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": {}}

        # ...

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_event() which will be added to the on_seat_position_changed callback function from before.

    async def on_seat_position_changed(self, data: DataPointReply):
        response_topic = "seatadjuster/currentPosition"
        position = data.get(self.Vehicle.Cabin.Seat.Row1.DriverSide.Position).value
        await self.publish_event(
            response_topic,
            json.dumps({"position": position}),
        )

The above example illustrates how one can easily publish messages. In this case, every time the seat position changes, the new position is published to seatadjuster/currentPosition

Your main.py should now have a full implementation for class MyVehicleApp(VehicleApp): containing:

• __init__()
• on_start()
• on_seat_position_changed()
• on_set_position_request_received()

and last but not least a main() method to run the app.

Check the seat-adjuster example to see a more detailed implementation including error handling.

UnitTests

Unit testing is an important part of the development, so let’s have a look at how to do that. You can find some example tests in /app/tests/unit. First, you have to import the relevant packages for unit testing and everything you need for your implementation:

from unittest import mock

import pytest
from sdv.vehicle_app import VehicleApp
from sdv_model.Cabin.SeatService import SeatService  # type: ignore
from sdv_model.proto.seats_pb2 import BASE, SeatLocation  # type: ignore

@pytest.mark.asyncio
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_event", new_callable=mock.AsyncMock, return_value=-1
    ):
        response = await VehicleApp.publish_event(
            str("sampleTopic"), get_sample_request_data()  # type: ignore
        )
        assert response == -1


def get_sample_request_data():
    return {"position": 330, "requestId": 123}

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 to see a more detailed implementation.

See the results

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 & devenv-devcontainer-setup packages are part of your .velocitas.json (which should be the default).
• Have a correctly configured app/AppManifest.json . See more
• Trigger our automated vehicle model lifecycle . (e. g. velocitas init)
• A runtime needs to be up and running. Read more about it in the run runtime services section.

Now chose one of the options to start the VehicleApp under development:

1. Press F5

or:

1. Press F1
2. Select command Tasks: Run Task
3. Select Local Runtime - Run VehicleApp

Debug your Vehicle App

In the introduction about debugging , you saw how to start a debugging session. In this section, you will learn what is happening in the background.

The debug session launch settings are already prepared for the VehicleApp in /.vscode/launch.json.

{
    "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.

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.

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.

Next steps

• Concept: SDK Overview
• Tutorial: Deploy runtime services in Kanto
• Tutorial: Start runtime services locally
• Tutorial: Creating a Python Vehicle Model
• Tutorial: Develop and run integration tests for a Vehicle App
• Concept: Deployment Model

3.2 - C++ Vehicle App Development

We recommend that you make yourself familiar with the Vehicle App SDK first, before going through this tutorial.

The following information describes how to develop and test the sample Vehicle App that is included in the C++ template repository . You will learn how to use the Vehicle App C++ SDK and how to interact with the Vehicle Model.

Once you have completed all steps, you will have a solid understanding of the development workflow and you will be able to reuse the template repository for your own Vehicle App development project.

Develop your first Vehicle App

This section describes how to develop your first Vehicle App. Before you start building a new Vehicle App, make sure you have already read this manual:

• Quickstart

For this tutorial, you will recreate the Vehicle App that is included in the template repository : The Vehicle App allows you to change the position of the driver’s seat in the car and also provides its current positions to other applications. A detailed explanation of the use case and the example is available here .

Setting up the basic skeleton of your app

At first, you have to create the main C++ file which we will call App.cpp in /app/src. All the relevant code for your new Vehicle App goes there. Afterwards, there are several steps you need to consider when developing the app:

1. Manage your includes
2. Initialize your class
3. Define the entry point of your app

Manage your includes

Before you start development in the App.cpp you just created, it will be necessary to include all required header files, which you will understand better later through the development:

#include "sdk/VehicleApp.h"
#include "sdk/IPubSubClient.h"
#include "sdk/IVehicleDataBrokerClient.h"
#include "sdk/Logger.h"

#include "vehicle/Vehicle.hpp"

#include <memory>

using namespace velocitas;

Initialize your class

The main class of your new Vehicle App needs to inherit the VehicleApp provided by the C++ SDK .

class MyVehicleApp : public VehicleApp {
public:
    // <remaining code in this tutorial goes here>
private:
    ::Vehicle Vehicle; // this member exists to provide simple access to the vehicle model
}

In your constructor, you have to choose which implementations to use for the VehicleDataBrokerClient and the PubSubClient. By default we suggest you use the factory methods to generate the default implementations: IVehicleDataBrokerClient::createInstance and IPubSubClient::createInstance. These will create a VehicleDataBrokerClient which connects to the VAL via gRPC and an MQTT-based pub-sub client.

MyVehicleApp()
    : 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
    {}
{}

Now, you have initialized the app and can continue developing relevant methods.

Entry point of your app

Here’s an example of an entry point to the MyVehicleApp that we just developed:

int main(int argc, char** argv) {
    MyVehicleApp app;
    app.run();
    return 0;
}

With this your app can now be started. In order to provide some meaningful behaviour of the app, we will enhance it with more features in the next sections.

Vehicle Model Access

In order to facilitate the implementation, the whole vehicle is abstracted into model classes. Please check the tutorial about creating models 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.

If you want to access a single DataPoint e.g. for the vehicle speed, this can be done via

auto vehicleSpeedBlocking = getDataPoint(Vehicle.Speed)->await();

or

getDataPoint(Vehicle.Speed)->onResult([](auto vehicleSpeed){
    logger().info("Got speed!");
})

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:

auto driverSeatPosition = getDataPoint(Vehicle.Cabin.Seat.Row1.Pos1.Position)->await();

Subscription to DataPoints

If you want to get notified about changes of a specific DataPoint, you can subscribe to this event, e.g. as part of the onStart() method in your app:

void onStart() override {
    subscribeDataPoints(QueryBuilder::select(Vehicle.Cabin.Seat.Row1.Pos1.Position).build())
        ->onItem([this](auto&& item) { onSeatPositionChanged(std::forward<decltype(item)>(item)); })
        ->onError([this](auto&& status) { onError(std::forward<decltype(status)>(status)); });
}

void onSeatPositionChanged(const DataPointsResult& result) {
    const auto dataPoint = result.get(Vehicle.Cabin.Seat.Row1.Pos1.Position);
    logger().info(dataPoint->value());
    // do something with the data point value
}

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))

Services

Services are used to communicate with other parts of the vehicle via remote procedure calls (RPC). Please read the basics about them here .

The following code snippet shows how to use the moveComponent() method of the SeatService from the vehicle model:

vehicle::cabin::SeatService::SeatLocation location{1, 1};
Vehicle.Cabin.SeatService.moveComponent(
    location, vehicle::cabin::SeatService::Component::Base, 300
    )->await();

In order to define which seat you like to move, you have to pass a SeatLocation object as the first parameter. The second argument specifies the component of the seat to be moved. The possible components are defined in the proto-files. The last parameter to be passed into the method is the final position of the component.

Make sure to call the await() method when calling service methods or register a callback via onResult() otherwise you don’t know when your asynchronous call will finish.

MQTT

Interaction with other Vehicle Apps or with the cloud is enabled by using the Mosquitto MQTT Broker. When using the provided template repository you can start a MQTT Broker as part the local runtime. More information can be found here .

In the quickstart section 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 GRPC 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 VehicleApp::subscribeTopic(<topic>) method provided by the SDK:

void onStart() override {
    subscribeTopic("seatadjuster/setPosition/request")
        ->onItem([this](auto&& item){ onSetPositionRequestReceived(std::forward<decltype(item)>(item);)});
}

void onSetPositionRequestReceived(const std::string& data) {
    const auto jsonData = nlohmann::json::parse(data);
    const auto responseTopic = "seatadjuster/setPosition/response";
    nlohmann::json respData({{"requestId", jsonData["requestId"]}, {"result", {}}});
}

The onSetPositionRequestReceived method will now be invoked every time a message is created on the subscribed topic seatadjuster/setPosition/response. The message data is provided as a string parameter. In the example above the data is parsed to json (data = json.loads(data_str)).

In order to publish data to other subscribers, the SDK provides the appropriate convenience method: VehicleApp::publishToTopic(...)

void MyVehicleApp::onSeatPositionChanged(const DataPointsResult& result):
    const auto responseTopic = "seatadjuster/currentPosition";
    nlohmann::json respData({"position": result.get(Vehicle.Cabin.Seat.Row1.Pos1.Position)->value()});

    publishToTopic(
        responseTopic,
        respData.dump(),
    );

The above example illustrates how one can easily publish messages. In this case, every time the seat position changes, the new position is published to seatadjuster/currentPosition

See the results

Once the implementation is done, it is time to run and debug the app.

Build your App

Before you can run the Vehicle App you need to build it first. To do so, simply run the provided build.sh script found in the root of the SDK. It does accept some arguments, but that is out of scope for this tutorial.

Run your App

In order to run the app make sure the devenv-runtimes package is part of your .velocitas.json (which should be the default) and the runtime is up and running. Read more about it in the run runtime services section.

Now chose one of the options to start the VehicleApp under development:

1. Press F5

or:

1. Press F1
2. Select command Tasks: Run Task
3. Select Local Runtime - Run VehicleApp

Debug your Vehicle App

In the introduction about debugging , you saw how to start a debugging session. In this section, you will learn what is happening in the background.

The debug session launch settings are already prepared for the VehicleApp.

{
    "configurations": [
        {
            "name": "VehicleApp - Debug (Native)",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/build/bin/app",
            "args": [ ],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [
                {
                    "name": "SDV_MIDDLEWARE_TYPE",
                    "value": "native"
                },
                {
                    "name": "SDV_VEHICLEDATABROKER_ADDRESS",
                    "value": "127.0.0.1:55555"
                },
                {
                    "name": "SDV_MQTT_ADDRESS",
                    "value": "127.0.0.1:1883"
                }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [ ],
        }
    ]
}

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.

Next steps

• Concept: SDK Overview
• Concept: Deployment Model
• Tutorial: Deploy runtime services in Kanto
• Tutorial: Start runtime services locally
• Tutorial: Creating a Vehicle Model
• Tutorial: Develop and run integration tests for a Vehicle App

3.3 - Vehicle App Integration Testing

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.

Writing Test Cases

To write an integration test, you should check the sample that comes with the template ( /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:

  • publish_and_wait_for_response: publishes the specified payload to the given request topic and waits (till timeout) for a message to the response topic. The payload of the first message that arrives in the response topic will be returned. If the timeout expires before, an empty string ("") is returned.

  • publish_and_wait_for_property: publishes the specified payload to the given request topic and waits (till timeout) until the given property value is found in an incoming message to the response topic. The path describes the property location within the response message, the value the property value to look for.

    Example:

    {
        "status": "success",
        "result": {
            "responsecode": 10
        }
    }
    

    If the responsecode property should be checked for the value 10, the path would be ["result", "responsecode"], property value would be 10. When the requested value has been found in a response message, the payload of that message will be returned. If the timeout expires before receiving a matching message, an empty string ("") is returned.

  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 Databroker.

  • register_datapoint: registers a new data point with given name and type ( here 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.

  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.

Runtime components

To be able to test the Vehicle App in an integrated way, the following components should be running:

• Mosquitto
• Databroker
• Vehicle Mock Provider

We distinguish between two environments for executing the Vehicle App and the runtime components:

• Local execution: components are running locally in the development environment
• Kanto execution: components (and application) are deployed and running in a Kanto control plane

Local execution

First, make sure that the runtime services are configured and running like described here .

The application itself can be executed by using a Visual Studio Launch Config (by pressing F5) or by executing the provided task Local Runtime - Run VehicleApp.

When the runtime services and the application are running, integration tests can be executed locally via

  pytest ./app/tests/integration

or using the testing tab in the sidebar to the left.

Kanto runtime

First, make sure that the runtime and the services are up and running, like described here .

The application itself can be deployed by executing the provided task Kanto Runtime - Deploy VehicleApp or Kanto Runtime - Deploy VehicleApp (without rebuild). Depending on whether your app is already available as a container or not.

When the runtime services and the application are running, integration tests can be executed locally via

  pytest ./app/tests/integration

or using the testing tab in the sidebar to the left.

Integration Tests in CI pipeline

The tests will be discovered and executed automatically in the provided CI pipeline . 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 Kanto runtime
2. deploy the Vehicle App container
3. set the correct MQTT and Databroker ports
4. execute the integration tests

Finally the test results are collected and published as artifacts of the workflow.

Troubleshooting

Troubleshoot IntTestHelper

• 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).

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.
• 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
• Concept: Build and release process

4 - Vehicle Model Creation

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) . 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 .

The previous approach, using pre-generated model repositories, is deprecated as of now. But is still available and is described in section Manual Vehicle Model Creation . Please be aware, that you would either have to use template versions before the above mentioned release, or you need to adapt the newer versions of the template using the old approach.

4.1 - Automated Vehicle Model Lifecycle

This tutorial will show you how:

• the vehicle API used as the source to generate the model is referenced in the app manifest,
• the automatic generation of the model works,
• you can trigger manual recreation of the model (after adding extensions to the API required by your project)

How to Reference a Model Specification

The model specification defines the vehicle API to be used by your project. It is referenced in the AppManifest.json via a URI or local file path like this:

• URI reference
• Local file reference

"vehicleModel": {
    "src": "<https://github.com/COVESA/vehicle_signal_specification/releases/download/v3.0/vss_rel_3.0.json>"
}

"vehicleModel": {
    "src": "./my_model/my_model.json"
}

Model Creation

The generation of the model is taking place:

• through a onPostInit hook when velocitas init is called:
  • either triggered manually or
  • automatically during the instantiation of the devContainer through our Velocitas Lifecycle Management , or
• when you trigger the VS Code task (Re-)generate vehicle model explicitly.

The model generation is a three step process:

1. The model generator is installed as a Python package (if not already present)
2. The referenced model specification is downloaded (if no local reference)
3. The model code is generated and installed.

The model is generated using our Velocitas vehicle-model-generator . The used version and also the repository of the generator can be altered via the variables section of the project configuration in the .velocitas.json. The default values for those are defined in the manifest.json of the devContainer setup package . Also, the target folder for the generated model source code is specified here:

{
    "variables": {
        "modelGeneratorGitRepo": "https://github.com/eclipse-velocitas/vehicle-model-generator.git",
        "modelGeneratorGitRef": "v0.3.0",
        "generatedModelPath": "./gen/vehicle_model"
    }
}

In Python template based projects the generated model is finally installed in the site-packages folder, while in C++ projects it is made available as a CMake include folder.

Further information

• Concept: SDK Overview
• Tutorial: Quickstart
• Tutorial: Create a Vehicle App

4.2 - Manual Vehicle Model Creation

This tutorial will show you how to:

• Create a Vehicle Model
• Add a Vehicle Service to the Vehicle Model
• Distribute your Python Vehicle Model

Create a Vehicle Model from VSS specification

A Vehicle Model can be generated from a COVESA Vehicle Signal Specification (VSS). VSS introduces a domain taxonomy for vehicle signals, in the sense of classical attributes, sensors and actuators with the raw data communicated over vehicle buses and data. The Velocitas vehicle-model-generator creates a Vehicle Model from the given specification and generates a package for use in Vehicle App projects.

Follow the steps to generate a Vehicle Model.

1. Clone the vehicle-model-generator repository in a container volume.

2. In this container volume, clone the vehicle-signal-specification repository and if required checkout a particular branch:

   git clone https://github.com/COVESA/vehicle_signal_specification
   
   cd vehicle_signal_specification
   git checkout <branch-name>
   

   In case the VSS vspec doesn’t contain the required signals, you can create a vspec using the VSS Rule Set .

3. Execute the command

   python3 gen_vehicle_model.py -I ./vehicle_signal_specification/spec ./vehicle_signal_specification/spec/VehicleSignalSpecification.vspec -l <lang> -T sdv_model -N sdv_model
   

   or if you want to generate it from a .json file

   python3 gen_vehicle_model.py <path_to_your_json_file> -l <lang> -T sdv_model
   

   Depending on the value of lang, which can assume the values python and cpp, this creates a sdv_model directory in the root of repository along with all generated source files for the given programming language.

   Here is an overview of what is generated for every available value of lang:

   lang	output
   python	Python sources and a setup.py ready to be used as Python package
   cpp	C++ sources, headers and a CMakeLists.txt ready to be used as a CMake project

   To have a custom model name, refer to README of vehicle-model-generator repository.

4. For Python: Change the version of package in setup.py manually (defaults to 0.1.0).

5. Now the newly generated sdv_model can be used for distribution. (See Distributing your Vehicle Model )

Create a Vehicle Model Manually

Alternative to the generation from a VSS specification you could create the Vehicle Model manually. The following sections describing the required steps.

• Python

Distributing your Vehicle Model

Once you have created your Vehicle Model either manually or via the Vehicle Model Generator, you need to distribute your model to use it in an application. Follow the links below for language specific tutorials on how to distribute your freshly created Vehicle Model.

• Python
• C++

Further information

• Concept: SDK Overview
• Tutorial: Quickstart
• Tutorial: Create a Vehicle App

4.2.1 - C++ Manual Vehicle Model Creation

Not yet done for C++

4.2.2 - Python Manual Vehicle Model Creation

Setup a Python Package manually

A Vehicle Model should be defined in its own Python Package. This allows to distribute the Vehicle Model later as a standalone package and to use it in different Vehicle App projects.

The name of the Vehicle Model package will be my_vehicle_model for this walkthrough.

1. Start Visual Studio Code

2. Select File > Open Folder (File > Open… on macOS) from the main menu.

3. In the Open Folder dialog, create a my_vehicle_model folder and select it. Then click Select Folder (Open on macOS).

4. Create a new file setup.py under my_vehicle_model:

   from setuptools import setup
   
   setup(name='my_vehicle_model',
       version='0.1',
       description='My Vehicle Model',
       packages=['my_vehicle_model'],
       zip_safe=False)
   

   This is the Python package distribution script.

5. Create an empty folder my_vehicle_model under my_vehicle_model.

6. Create a new file __init__.py under my_vehicle_model/my_vehicle_model.

At this point the source tree of the Python package should look like this:

my_vehicle_model
├── my_vehicle_model
│   └── __init__.py
└── setup.py

To verify that the package is created correctly, install it locally:

pip3 install .

The output of the above command should look like this:

Defaulting to user installation because normal site-packages is not writeable
Processing /home/user/projects/my-vehicle-model
Preparing metadata (setup.py) ... done
Building wheels for collected packages: my-vehicle-model
Building wheel for my-vehicle-model (setup.py) ... done
Created wheel for my-vehicle-model: filename=my_vehicle_model-0.1-py3-none-any.whl size=1238 sha256=a619bc9fbea21d587f9f0b1c1c1134ca07e1d9d1fdc1a451da93d918723ce2a2
Stored in directory: /home/user/.cache/pip/wheels/95/c8/a8/80545fb4ff73c974ac1716a7bff6f7f753f92022c41c2e376f
Successfully built my-vehicle-model
Installing collected packages: my-vehicle-model
Successfully installed my-vehicle-model-0.1

Finally, uninstall the package again:

pip3 uninstall my_vehicle_model

Add Vehicle Models manually

1. Install the Python Vehicle App SDK:

   pip3 install git+https://github.com/eclipse-velocitas/vehicle-app-python-sdk.git
   

   The output of the above command should end with:

   Successfully installed sdv-x.y.z
   

   Now it is time to add some Vehicle Models to the Python package. At the end of this section you will have a Vehicle Model, that contains a Cabin model, a Seatmodel and has the following tree structure:

    Vehicle
    └── Cabin
        └── Seat (Row, Pos)
   

2. Create a new file Seat.py under my_vehicle_model/my_vehicle_model:

   from sdv.model import Model
   
   class Seat(Model):
   
       def __init__(self, parent):
           super().__init__(parent)
           self.Position = DataPointFloat("Position", self)
   

   This creates the Seat model with a single data point of type float named Position.

3. Create a new file Cabin.py under my_vehicle_model/my_vehicle_model:

   from sdv.model import Model
   
     class Cabin(Model):
         def __init__(self, parent):
             super().__init__(parent)
             self.Seat = SeatCollection("Seat", self)
   
     class SeatCollection(Model):
         def __init__(self, name, parent):
             super().__init__(parent)
             self.name = name
             self.Row1 = self.RowType("Row1", self)
             self.Row2 = self.RowType("Row2", self)
   
         def Row(self, index: int):
             if index < 1 or index > 2:
                 raise IndexError(f"Index {index} is out of range")
             _options = {
                 1 : self.Row1,
                 2 : self.Row2,
             }
             return _options.get(index)
   
         class RowType(Model):
             def __init__(self, name, parent):
                 super().__init__(parent)
                 self.name = name
                 self.Pos1 = Seat("Pos1", self)
                 self.Pos2 = Seat("Pos2", self)
                 self.Pos3 = Seat("Pos3", self)
   
             def Pos(self, index: int):
                 if index < 1 or index > 3:
                     raise IndexError(f"Index {index} is out of range")
                 _options = {
                     1 : self.Pos1,
                     2 : self.Pos2,
                     3 : self.Pos3,
                 }
                 return _options.get(index)
   

   This creates the Cabin model, which contains a set of six Seat models, referenced by their names or by rows and positions:

   • row=1, pos=1
   • row=1, pos=2
   • row=1, pos=3
   • row=2, pos=1
   • row=2, pos=2
   • row=2, pos=3

4. Create a new file vehicle.py under my_vehicle_model/my_vehicle_model:

   from sdv.model import Model
   from my_vehicle_model.Cabin import Cabin
   
   
   class Vehicle(Model):
       """Vehicle model"""
   
       def __init__(self, name):
           super().__init__()
           self.name = name
           self.Speed = DataPointFloat("Speed", self)
           self.Cabin = Cabin("Cabin", self)
   
   vehicle = Vehicle("Vehicle")
   

The root model of the Vehicle Model tree should be called Vehicle by convention and is specified, by setting parent to None. For all other models a parent model must be specified as the 2nd argument of the Model constructor, as can be seen by the Cabin and the Seat models above.

A singleton instance of the Vehicle Model called vehicle is created at the end of the file. This instance is supposed to be used in the Vehicle Apps. Creating multiple instances of the Vehicle Model should be avoided for performance reasons.

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 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 provided by the KUKSA.VAL services which describes a seat control service .

3. Install the grpcio tools including mypy types to generate the Python classes out of the proto-file:

   pip3 install grpcio-tools mypy_protobuf
   

4. Generate Python classes from the SeatService message definition:

   python3 -m grpc_tools.protoc -I my_vehicle_model/proto --grpc_python_out=./my_vehicle_model/proto --python_out=./my_vehicle_model/proto --mypy_out=./my_vehicle_model/proto my_vehicle_model/proto/seats.proto
   

   This creates the following gRPC files under the proto folder:

   • seats_pb2.py
   • seats_pb2_grpc.py
   • seats_pb2.pyi

5. Create the SeatService class and wrap the gRPC service:

   from sdv.model import Service
   
   from my_vehicle_model.proto.seats_pb2 import (
       CurrentPositionRequest,
       MoveComponentRequest,
       MoveRequest,
       Seat,
       SeatComponent,
       SeatLocation,
   )
   from my_vehicle_model.proto.seats_pb2_grpc import SeatsStub
   
   
   class SeatService(Service):
       "SeatService model"
   
       def __init__(self):
           super().__init__()
           self._stub = SeatsStub(self.channel)
   
       async def Move(self, seat: Seat):
           response = await self._stub.Move(MoveRequest(seat=seat), metadata=self.metadata)
           return response
   
       async def MoveComponent(
           self,
           seatLocation: SeatLocation,
           component: SeatComponent,
           position: int,
       ):
           response = await self._stub.MoveComponent(
               MoveComponentRequest(
                   seat=seatLocation,
                   component=component,  # type: ignore
                   position=position,
               ),
               metadata=self.metadata,
           )
           return response
   
       async def CurrentPosition(self, row: int, index: int):
           response = await self._stub.CurrentPosition(
               CurrentPositionRequest(row=row, index=index),
               metadata=self.metadata,
           )
           return response
   

   Some important remarks about the wrapping SeatService class shown above:

   • The SeatService class must derive from the Service class provided by the Python SDK.
   • The SeatService class must use the gRPC channel from the Service base class and provide it to the _stub in the __init__ method. This allows the SDK to manage the physical connection to the gRPC service and use service discovery of the middleware.
   • Every method needs to pass the metadata from the Service base class to the gRPC call. This is done by passing the self.metadata argument to the metadata of the gRPC call.

4.2.3 - Vehicle Model Distribution

4.2.3.1 - C++ Vehicle Model Distribution

Now that you have created your own Vehicle Model, we can distribute it to make use of it in Vehicle Apps.

Copying the folder to your Vehicle App repo

The easiest way to get started quickly is to copy the created model, presumably stored in vehicle_model into your Vehicle App repository to use it. To do so, simply copy and paste the directory into the <sdk_root>/app directory and replace the existing model.

Using a git submodule

A similar approach to the one above but a bit more difficult to set up is to create a git repository for the created model. The advantage of this approach is that you can share the same model between multiple Vehicle Apps without any manual effort.

1. Create a new git repository on i.e. Github
2. Clone it locally, add the created vehicle_model folder to the git repository
3. Commit everything and push the branch

In your Vehicle App repo, add a new git submodule via

git submodule add <checkout URL of your new repo> app/vehicle_model
git submodule init

Now you are ready to develop new Vehicle Apps with your custom Vehicle Model!

4.2.3.2 - Python Vehicle Model Distribution

Now you a have a Python package containing your first Python Vehicle Model and it is time to distribute it. There is nothing special about the distribution of this package, since it is just an ordinary Python package. Check out the Python Packaging User Guide to learn more about packaging and package distribution in Python.

Distribute to single Vehicle App

If you want to distribute your Python Vehicle Model to a single Vehicle App, you can do so by copying the entire folder my_vehicle_model under the /app/src folder of your Vehicle App repository and treat it as a sub-package of the Vehicle App.

1. Create a new folder my_vehicle_model under /app/src in your Vehicle App repository.
2. Copy the my_vehicle_model folder to the /app/src folder of your Vehicle App repository.
3. Import the package my_vehicle_model in your Vehicle App:

from <my_app>.my_vehicle_model import vehicle

...

my_app = MyVehicleApp(vehicle)

Distribute inside an organization

If you want to distribute your Python Vehicle Model inside an organization and use it to develop multiple Vehicle Apps, you can do so by creating a dedicated Git repository and copying the files there.

1. Create new Git repository called my_vehicle_model

2. Copy the content under my_vehicle_model to the repository.

3. Release the Vehicle Model by creating a version tag (e.g., v1.0.0).

4. Install the Vehicle Model package to your Vehicle App:

   pip3 install git+https://github.com/<yourorg>/my_vehicle_model.git@v1.0.0
   

5. Import the package my_vehicle_model in your Vehicle App and use it as shown in the previous section.

Distribute publicly as open source

If you want to distribute your Python Vehicle Model publicly, you can do so by creating a Python package and distributing it on the Python Package Index (PyPI) . PyPi is a repository of software for the Python programming language and helps you find and install software developed and shared by the Python community. If you use the pip command, you are already using PyPI.

Detailed instructions on how to make a Python package available on PyPI can be found here .

5 - Vehicle App Runtime

5.1 - Local Runtime

Using tasks in Visual Studio Code

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 .

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/*

Add/Change runtime service configuration

The configuration for services of our provided local runtime are defined in the runtime.json at the root of the repository devenv-runtimes . For a more detailed view on how to change or add runtime service configuration, please visit: Lifecycle Management Package Development

Using KUKSA Databroker CLI

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

Integration of a new runtime service can be done by duplicating one of the existing tasks.

• Create a new service in either a new created Package or branch/fork of devenv-runtimes as already explained above
• In .vscode/tasks.json, duplicate section from task e.g. Local Runtime - Up, Local Runtime - Run VehicleApp or Local Runtime - VehicleDataBroker CLI
• Correct names in a new code block
• Disclaimer: Problem Matcher defined in tasks.json is a feature of the Visual Studio Code Task, to ensure that the process runs in background
• Run task using [F1 -> Tasks: Run Task -> <Your new task label>]
• Task should be visible in Terminal section of Visual Studio Code

Task CodeBlock helper

{
    "label": "<task_name>",
    "detail": "<task_description>",
    "type": "shell",
    "command": [
        "velocitas exec runtime-local <service_id> <args>"
    ],
    "presentation": {
        "close": true,
        "reveal": "never"
    },
    "problemMatcher": []
}

Troubleshooting

Problem description: When integrating new services into an existing dev environment, it is highly recommended to use the Visual Studio Code Task Feature. A new service can be easily started by calling it from bash script, however restarting the same service might lead to port conflicts (GRPC Port or APP port). That can be easily avoided by using the Visual Studio Code Task Feature.

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. 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: Quickstart
• Concept: Deployment Model
• Concept: Build and release process

5.2 - Kanto Runtime

Besides starting the vehicle runtime components locally , another way is to deploy them as containers using Kanto . To start the runtime, we provide VS Code Tasks, a feature of Visual Studio Code. Additional information on tasks can be found here .

Quick Start: Each step has a task that is defined in /.vscode/tasks.json:

• Core tasks (dependent on each other in the given order):

  • Kanto - Runtime Up: Starts up the Kanto runtime and deploys the runtime components.
  • Kanto - Build VehicleApp: Builds the VehicleApp.
  • Kanto - Deploy VehicleApp: Deploys the VehicleApp as container in the Kanto runtime.

• Optional helper tasks:

  • Kanto - Deploy VehicleApp (without rebuild): Deploys the VehicleApp as container in the Kanto runtime but does not build it upfront. That requires, that the task Kanto - Build VehicleApp has been executed once before.
  • Kanto - Runtime Down: Stops the Kanto runtime and all deployed containers.

Run as Bundle: To orchestrate these tasks, you can use the task Kanto - 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 Kanto - 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/*

KantUI

The Leda team developed a tool to easily work with Kanto. It is similar to K9S for Kubernetes. You can find more details about KantUI in the documentation of Leda .

In the devcontainer KantUI is already installed and it can be started via:

sudo kantui

After starting the Kanto runtime with the mentioned tasks above, you will directly see all the running containers in KantUI. Now you could also take a look at the logs, delete or stop single containers. After you deployed your application to Kanto, this container will also show up and can be handled with KantUI.

Mounting folders for FeederCAN

Some applications (e.g. FeederCAN) might make it necessary to load custom files from a mounted volume. All the files that are located in [./config/feedercan](https://github.com/eclipse-velocitas/devenv-runtimes/tree/main/config/feedercan) will be automatically mounted into the container. In order to mount files to the directory that is accessible by the application, please refer to the deployment configuration file: runtime-kanto/src/runtime/deployment/feedercan.json .

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
2. Restarting Kanto (execute the tasks Kanto - Runtime Down and Kanto - Runtime Up)

More information about the CAN Provider can be found here

Next steps

• Concept: Deployment Model
• Concept: Build and release process
• Tutorial: Start runtime services locally
• Tutorial: Quickstart

6 - Vehicle App Deployment

See the Kanto container configuration for details how to write Kanto deployment files.