Quickstart

The following information describes how to setup and configure the Development Container (DevContainer), and how to build, customize and test the sample Vehicle App, which is included in this repository. You will learn how to use the Vehicle App SDK, how to interact with the vehicle API and how to do CI/CD using the pre-configured GitHub workflows that come with the repository.

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 develpment project.

Creating Vehicle App Repository

For the orginization and Vehicle App repository the name MyOrg/MyFirstVehicleApp is used as a reference during the rest of the document.

Create your own repository copy from the template repository of your choice Python/C++ 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.

Starting Development Environment

In the following you will learn different possibilities to work with the repo. Basically you can work on your own machine using just Visual Studio Code or you can set up the environment on a remote agent, using GitHub Codespaces.

Visual Studio Code

The Visual Studio Code Development Containers makes it possible to package a complete Vehicle App development environment, including Visual Studio Code extensions, Vehicle App SDK, Vehicle App runtime and all other development & testing tools into a container that is then started within your Visual Studio Code session.

To be able to use the DevContainer, you have to make sure that you fulfill the following prerequisites:

• Install Docker Engine / Docker Desktop

• Install Visual Studio Code

• Add Remote-Containers extension via the marketplace or using the command line

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

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

1. Clone the repo locally using your favorite Git tooling
2. Start Visual Studio Code
3. Select Open Folder from the File menu
4. Open the root of the cloned repo
5. A popup appears on the lower left side of Visual Studio Code. If the popup does not appear, you can also hit F1 and run the command Dev-Containers: Open Folder in Container
6. Click on Reopen in Container
7. Wait for the container to be set up

The first time initializing the container will take a few minutes to build the image and to provision the tools inside the container.

Codespaces

Another possibility to use your newly created repository is via GitHub Codespaces. You can either try it out directly in the browser or also use it inside Visual Studio Code. The main thing to remember is that everything is executed on a remote agent and the browser or Visual Studio Code just act as frontends.

To get started with 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 see the logs for setting up the container. On this window you could now also choose to work with Visual Studio Code. The environment remains on a remote agent and Visual Studio 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 Visual Studio Code.

Starting runtime services

The runtime services (like KUKSA Data Broker or Vehicle Services) are required to develop vehicle apps and run integration tests.

A Visual Studio Code task called Start Vehicle App runtime is available to run these in the correct order.

1. Press F1
2. Select command Tasks: Run Task
3. Select Start VehicleApp runtime
4. Choose Continue without scanning the output

You should see the tasks run-mosquitto, run-vehicledatabroker, run-vehicleservices and run-feedercan being executed in the Visual Studio Code output panel.

More information about the tasks are available here.

Debugging Vehicle App

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

• Template
• Seat Adjuster

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.

Triggering CI Workflow

The provided GitHub workflows are used to build the container image for the Vehicle App, run unit and integration tests, collect the test results and create a release documentation and publish the Vehicle App. A detailed description of the workflow you can find here.

By pushing a change to GitHub the CI Workflow will be triggered:

1. Make modification in any of your files

2. Commit and push your change

   git add .
   git commit -m "removed emtpy line"
   git push
   

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

Releasing Vehicle App

Now that the CI Workflow was successful, you are ready to build your first release. Your 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. The release workflow creates a release documentation and publish the container image of the Vehicle App to the GitHub container registry. Open Actions on the repoitory and see the result.

Deploying Vehicle App

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

Please checkout 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