Lifecycle Management

• 1: Project Configuration
• 2: Velocitas CLI
• 3: Phases
• 3.1: Create
• 4: Packages
• 4.1: Usage
• 4.2: Development
• 5: Troubleshooting

1 - Project Configuration

Every Vehicle App repo comes with a .velocitas.json which is the project configuration of your app. It holds references to the packages and their respective versions as well as components you are using in your project.

Here is an example of this configuration:

{
    "packages": {
        "devenv-runtimes": "v3.1.0",
        "devenv-devcontainer-setup": "v2.1.0"
    },
    "components": [
        "runtime-local",
        "devcontainer-setup",
        "vehicle-signal-interface",
        "sdk-installer",
        "grpc-interface-support"
    ],
    "variables": {
        "language": "python",
        "repoType": "app",
        "appManifestPath": "app/AppManifest.json",
        "githubRepoId": "eclipse-velocitas/vehicle-app-python-template",
        "generatedModelPath": "./gen/vehicle_model"
    },
    "cliVersion": "v0.9.0"
}

More detailed information and explanation about the project configuration and fields of the .velocitas.json can be found here .

Next steps

• Lifecycle Management: Usage of Packages
• Lifecycle Management: Development of Packages

2 - Velocitas CLI

Background

Our Velocitas CLI is introduced to support the process of the lifecycle of a Vehicle App as a project manager.

Commands

You can find all information about available commands here .

CLI Flow examples

velocitas create

Create a new Velocitas Vehicle App project.

vscode ➜ /workspaces/vehicle-app-template (main) $ velocitas create
Interactive project creation started
> What is the name of your project? MyApp
> Which programming language would you like to use for your project? (Use arrow keys)
❯ python
  cpp
> Would you like to use a provided example? No
> Which functional interfaces does your application have? (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◉ Vehicle Signal Interface based on VSS and KUKSA Databroker
 ◯ gRPC service contract based on a proto interface description
...
Config 'src' for interface 'vehicle-signal-interface': URI or path to VSS json (Leave empty for default: v3.0)
...

velocitas init

Download packages configured in your .velocitas.json to VELOCITAS_HOME

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init
Initializing Velocitas packages ...
... Downloading package: 'devenv-runtimes:v1.0.1'
... Downloading package: 'devenv-github-workflows:v2.0.4'
... Downloading package: 'devenv-github-templates:v1.0.1'
... Downloading package: 'devenv-devcontainer-setup:v1.1.7'
Running post init hook for model-generator
Running 'install-deps'
...

Single Package Init

Single packages can also easily be initialized or re-initialized using the package parameter -p / --package and the specifier parameter -s / --specifier. The specifier parameter can be either a git tag or a git hash. If the specifier parameter is omitted either the version defined in .velocitas.json resp. the latest version of the specified package will be used automatically. After initialisation the package and it’s resolved version will be written to .velocitas.json. If the package already exists in .velocitas.json, however the versions differ it will be automatically updated to the specified version. If no components from the specified package are added to .velocitas.json all components from this package are automatically written to it.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init -p devenv-runtimes -s v3.0.0
Initializing Velocitas packages ...
... Package 'devenv-runtimes:v3.0.0' added to .velocitas.json
... Downloading package: 'devenv-runtimes:v3.0.0'
... > Running post init hook for ...
...

velocitas sync

If any package provides files they will be synchronized into your repository.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas sync
Syncing Velocitas components!
... syncing 'devenv-github-workflows'
... syncing 'devenv-github-templates'
... syncing 'devenv-devcontainer-setup'

velocitas upgrade

Updates Velocitas components.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas upgrade --dry-run [--ignore-bounds]
Checking .velocitas.json for updates!
... devenv-devcontainer-setup:vx.x.x → up to date!
... devenv-runtimes:vx.x.x → vx.x.x
... devenv-github-templates:vx.x.x → up to date!
... devenv-github-workflows:vx.x.x → up to date!

velocitas package

Prints information about packages.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas package devenv-devcontainer-setup
devenv-devcontainer-setup
    version: v1.1.7
    components:
      - id: devcontainer-setup
        type: setup
        variables:
            language
                type: string
                description: The programming language of the project. Either 'python' or 'cpp'
                required: true
            repoType
                type: string
                description: The type of the repository: 'app' or 'sdk'
                required: true
            appManifestPath
                type: string
                description: Path of the AppManifest file, relative to the .velocitas.json
                required: true

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas package devenv-devcontainer-setup -p
/home/vscode/.velocitas/packages/devenv-devcontainer-setup/v1.1.7

velocitas exec

Executes a script contained in one of your installed components.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas exec runtime-local run-vehicledatabroker
#######################################################
### Running Databroker                              ###
#######################################################
...

More detailed usage can be found at the Velocitas CLI README .

Additional Information

Cache Usage

The Velocitas CLI supports caching data for a Vehicle App project.
The cache data makes it easy for any script/program of a component to read from or write to.
More detailed information about the Project Cache can be found here .

Built-In Variables

The Velocitas CLI also creates default environment variables which are available to every script/program.

More detailed information about Built-In Variables can be found here .

Next steps

• Lifecycle Management: Troubleshooting

3 - Phases

3.1 - Create

To be filled.

Template based creation flow

Bootstrapping creation flow

Resulting Velocitas CLI and Velocitas Package changes

• velocitas create command shall be introduced

  • it will guide through the project creation process, allowing the developer to add APIs and services at creation time which will reference the correct Velocitas CLI packages (either provided by Velocitas or by a 3rd party).
  • in addition to an interactive mode where create is invoked without arguments, there shall be a CLI mode where all of the arguments shall be passable as arguments

• Packages need to be available in a central registry (i.e. a new git repository) otherwise step 3 (depicted below) is not possible.

• Packages need to expose which dependency types they are providing in their manifest. For each dependency type a human readable name for the type shall be exposed.

Interaction mockup

> velocitas create
... Creating a new Velocitas project!
> What is the name of your project?
MyApp

> 1. Which programming language would you like to use for your project?
[ ] Python
[x] C++

> 2. Which integrations would you like to use? (multiple selections possible)
[x] Github
[x] Gitlab
[ ] Gitee

> 3. Which API dependencies does your project have?
[x] gRPC service
[ ] uProtocol service

> 4. Add an API dependency (y/n)?
y

> 5. What type of dependency?
[x] gRPC-IF

> 6. URI of the .proto file?
https://some-url/if.proto

> 7. Add an(other) API dependency (y/n)?
n

... Project created!

Arguments mockup:

$ velocitas create \
    --name MyApp \
    --lang cpp \
    --package grpc-service-support \
    --require grpc-interface:https://some-url/if.proto

> Project created!

4 - Packages

4.1 - Usage

Overview

After you have set up the .velocitas.json for your project configuration , using packages is pretty straight forward.

Currently, the packages provided by the Velocitas team are the following:

To see how these provided packages are used inside a .velocitas.json you can use the Python template repository as a reference.

Installation

The Velocitas CLI - acting as a package manager for Vehicle App repositories - is installed inside our devcontainer-base-images .
After creation of a devcontainer a postCreateCommand is configured to be executed which runs:

• velocitas init which will initialize all packages referenced in your .velocitas.json. That means, it will download them and run their respective onPostInit programs, if any. (e.g, automated model generation )
• velocitas sync to sync files provided by some packages.

Check the section about our Velocitas CLI to learn more about the background and usage of it.

Velocitas Home Directory

The packages will be downloaded by the Velocitas CLI to ~/.velocitas/packages/<package_name>. More Information: VELOCITAS_HOME .

Next steps

• Lifecycle Management: Development of Packages
• Lifecycle Management: Velocitas CLI

4.2 - Development

Getting started

First thing you need to do is to create a repository at e.g., https://github.com/my-organisation/my-velocitas-package. The URL needs to be referenced in the .velocitas.json of your Vehicle App repository.

General configuration of Packages

Every Package repository needs a manifest.json at their root. The manifest.json is the package configuration and holds package relevant information and its behaviour.

Here are examples of this configuration:

• devenv-runtimes manifest
• devenv-devcontainer-setup manifest

The manifest of a package describes a list of components. They are a collection of programs or files that serve a similar purpose or are inheritly connected. I.e. they provide a single runtime, a deployment for a runtime or add configuration required for Github Workflows or the devcontainer.

More detailed information and explanation about configuration fields of the manifest.json and package development can be found here .

Configuration of Runtime Packages

If you want to add a new service, adapt runtime.json and manifest.json . In order to use a newly created or updated service, new changes on devenv-runtimes need to be tagged and referenced inside .velocitas.json of the respective package version via a tag or branch name of the repository. When a version is changed in your .velocitas.json you have to initialize it through velocitas init from the terminal so the new package version will be installed. A new service can be started by using velocitas cli command velocitas exec runtime-local <service_id> <args> which can be also configured inside your ./.vscode/tasks.json.

If you plan to develop a Package with the purpose of managing the runtime used together with your Vehicle App the package needs a runtime.json at their root. The runtime.json is the runtime configuration containing all information for the relevant service dependencies with the following three required attributes:

Supported config keys of a service

Runtime configuration helper

{
    "id": "<service_id>",
    "interfaces": [
        "<interface>"
    ],
    "config": [
        {
            "key": "image",
            "value": "<image>:<tag>"
        },
        {
            "key": "port",
            "value": "<port_number>"
        },
        {
            "key": "port-forward",
            "value": "<source_port>:<target_port>"
        },
        {
            "key": "env",
            "value": "<env_key>=<env_value>"
        },
        {
            "key": "mount",
            "value": "<source_path>:<target_path>"
        },
        {
            "key": "arg",
            "value": "<arg>"
        },
        {
            "key": "start-pattern",
            "value": ".*Listening on \\d+\\.\\d+\\.\\d+\\.\\d+:\\d+"
        }
    ]
}

In order to use a newly created or updated service, changes on the respective Package need to be tagged and referenced inside the .velocitas.json of your Vehicle App repository via a tag or branch name of the repository. More info about installation: Usage .

Next steps

• Lifecycle Management: Velocitas CLI

5 - Troubleshooting

GitHub rate limit exceeded

To avoid exceeding GitHubs rate limit we suggest to generate a personal access token in your GitHub settings and set it as an environment variable:

• Mac/Linux
• Windows

After you have set the ENV consider to restart VS Code.

It is important that VS Code has access to this ENV during the postCreateCommand inside the devcontainer. If you experienced this error and the devcontainer still has started correctly please run either:

vscode ➜ /workspaces/vehicle-app-python-template (main) $ ./.devcontainer/scripts/postCreateCommand.sh

or

vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init
vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas sync

Debugging inside installed packages

Open up a seperate VScode window where you can debug installed toolchain packages.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ code ~/.velocitas/packages

Solution to (almost) all problems

The following would clean up the VELOCITAS_HOME but afterwards a new project initialization is required.

vscode ➜ /workspaces/vehicle-app-python-template (main) $ rm -rf ~/.velocitas
vscode ➜ /workspaces/vehicle-app-python-template (main) $ velocitas init