Quickstart

Learn how to setup and explore the provided development environment.

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:

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.

Create your own repository copy from the template repository of your choice:

by clicking the green button Use this template. You don’t have to include all branches. For more information on Template Repositories take a look at this GitHub Tutorial .

Create your Vehicle App project via our Velocitas CLI create command from within vehicle-app-template’s devcontainer:

  • velocitas create interactive mode.
  • velocitas create -n MyApp -l python for a skeleton vehicle application.
  • velocitas create -n MyApp -l python -e seat-adjuster for a vehicle application based on the seat adjuster example .

To learn how to start prototyping with the playground of digital.auto and integrate it into Velocitas please take a look here .

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 .

The VS Code DevContainer makes it possible to package a complete Vehicle App development environment, including VS Code extensions, Vehicle App SDK , Vehicle App Runtimes and all other development and testing tools into a container which is started directly in VS Code.

Proxy Configuration

A non proxy configuration is used by default. If you are working behind a corporate proxy you will need to specify proxy settings:

Working behind a proxy

With following steps you will clone and set up your development environment on your own machine using VS Code.

  1. Clone created MyOrg/MyFirstVehicleApp repository locally using your favorite Git tool
  2. Switch the directory to the cloned repository folder, e.g. $ cd MyFirstVehicleApp
  3. Open the repository in VS Code via $ code . or via VS Code user interface .
  4. A popup appears in the lower right corner with the button Reopen in Container.
  5. Click on Reopen in Container. If the popup does not appear, you can also hit F1 and perform the command Dev-Containers: Reopen in Container
  6. Wait for the container to be set up

The first initializing of the container will take some minutes to build the image and provision all the integrated tools.

If the DevContainer build process fails, press F1 and run the command Dev-Containers: Rebuild Container Without Cache. The DevContainer is using the

docker-in-docker feature to run docker containers within the container.

One of the possibilities to use your newly created repository is to use it inside a GitHub Codespace . You can either try it out directly in the browser or also use it inside VS Code. The main thing to remember is that everything is executed on a remote agent and the browser or VS Code just acts as a “thin-client”.

To get started with GitHub Codespaces, you just have to follow a few steps:

  1. Open your repository on GitHub (e.g. https://github.com/MyOrg/MyFirstVehicleApp )
  2. Click on the green Code button and select Codespaces on the top
  3. Configure your Codespace if needed (defaults to the main branch and a standard agent)
  4. Click on create

A new window will open where you can see logs for setting up the container. On this window you could now also choose to work with VS Code. The environment remains on a remote agent and VS Code establishes a connection to this machine.

Once everything is set up in the Codespace, you can work with it in the same way as with the normal DevContainer inside VS Code.

Be careful with using GitHub Codespaces in a browser and VS Code locally at the same time: Tasks that are started using a browser session will not show in VS Code environment and vice versa. This might lead to problems.

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 Data Broker or Vehicle Services) are required to develop Vehicle Apps and run integration tests.

Currently, the supported options to run these services is either locally , in a Kubernetes (K3D) cluster or via the Kanto runtime .

A VS Code task called Local Runtime - Up is available to start all necessary services in the correct order.

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

You should see the task Local Runtime - Up being executed on a separate VS Code terminal with the following content:

$ 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!

To stop the runtime simply press Ctrl + C.

A VS Code task called K3D Runtime - Up is available to start all necessary services in the correct order.

  1. Press F1
  2. Select command Tasks: Run Task
  3. Select K3D Runtime - Up

You should see the task K3D Runtime - Up being executed on a separate VS Code terminal with the following content:

$ velocitas exec runtime-k3d up

Hint: Log files can be found in your workspace's logs directory
> Checking K3D registry... created.
> Creating cluster with proxy configuration.
> Checking K3D cluster... created.
> Checking zipkin deployment... deployed.
> Checking dapr... initialized.
✅ Configuring controlplane for k3d...
> Deploying runtime... installed.
✅ Starting k3d runtime...

You need to perform the task K3D Runtime - Down to properly stop all runtime activities.

A VS Code task called Kanto Runtime - Up is available to start all necessary services in the correct order.

  1. Press F1
  2. Select command Tasks: Run Task
  3. Select Kanto Runtime - Up

You should see the task Kanto Runtime - Up being executed on a separate VS Code terminal with the following content:

$ 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!

To stop the runtime simply press Ctrl + C or execute the task Kanto Runtime - Down.

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.

  1. Open the main source file /app/src/main.py and set a breakpoint in the given method on_get_speed_request_received
  2. Press F5 to start a debug session of the Vehicle App and see the log output on the DEBUG CONSOLE

To trigger this breakpoint, let’s send a message to the Vehicle App using the mqtt broker that is running in the background.

  1. Open VSMqtt extension in VS Code and connect to mosquitto (local)
  2. Set Subscribe Topic = sampleapp/getSpeed/response and click subscribe
  3. Set Publish Topic = sampleapp/getSpeed
  4. Press publish with an empty payload field.
  1. Open the main source file /app/src/VehicleApp.cpp and set a breakpoint in the given method onSetPositionRequestReceived
  2. Press F5 to start a debug session of the Vehicle App and see the log output on the DEBUG CONSOLE

To trigger this breakpoint, let’s send a message to the Vehicle App using the mqtt broker that is running in the background.

  1. Open VSMqtt extension in VS Code and connect to mosquitto (local)
  2. Set Subscribe Topic = seatadjuster/setPosition/response and click subscribe
  3. Set Subscribe Topic = seatadjuster/currentPosition and click subscribe
  4. Set Publish Topic = seatadjuster/setPosition/request
  5. Set and publish a dummy payload: { "position": 300, "requestId": 123 }
Now your breakpoint in the Vehicle App gets hit and you can inspect everything in your debug session. After resuming execution (F5), a response from your Vehicle App is published to the response topic. You can see the response in the MQTT window.

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

Last modified February 27, 2024: Version fixes and removal of strange header of rendered page (#117) (383f29a)