Quickstart

Learn how to setup and explore the provided development environment.

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:

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.

  1. Open the main source file and set a breakpoint in the given method:
    • Python main source file: /app/src/main.py, set breakpoint in method: on_get_speed_request_received
    • C++: Continue on the Seat Adjuster tab.
  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 Visual Studio 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.

For Python: Follow the guide provided in: Import examples and import seat-adjuster.
For C++: Continue with the next steps.

  1. Open the main source file and set a breakpoint in the given method:
    • Python main source file: /app/src/main.py, set breakpoint in method: on_set_position_request_received
    • C++ main source file: /app/src/VehicleApp.cpp, set breakpoint in 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 Visual Studio 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": "xyz" }
    
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


Import examples

Learn how to import examples provided by the Vehicle App SDK.

Working behind proxy

Learn how to setup your docker desktop and Visual Studio Code behind a coorperate proxy.

Last modified January 17, 2023: Changed overview picture (#51) (ea5274b)