Vehicle App Python Sdk

The Vehicle App SDK reduces the effort required to implement Vehicle Apps by using the Velocitas development model for the Python programming language. To create a Vehicle App, please use our Vehicle App Template which uses this sdk.

This includes the following packages:

• velocitas_sdk.vehicle_app - Vehicle App abstraction
• velocitas_sdk.model - Vehicle Model ontology
• velocitas_sdk.config - Vehicle App configuration
• velocitas_sdk.base - Base classes for middleware abstraction
• velocitas_sdk.native - Native middleware definition
• velocitas_sdk.vdb - Vehicle Data Broker integration
• velocitas_sdk.test - Integration test support
• velocitas_sdk.util - Logging and other utilities

Status

Note: The Vehicle App Python SDK is currently under active development in alpha phase.

Prerequisites

• Python 3.10 or later is required to use this package.

Install the package

Install the Vehicle App Python SDK with pip:

pip install git+https://github.com/eclipse-velocitas/vehicle-app-python-sdk.git@<version>

Documentation

• Velocitas Development Model: Learn more about the Velocitas programming model and the SDK
• Velocitas Tutorials: Learn how to get started, including setting up the development environment, creating a Vehicle Model as well as developing and deploying a Vehicle App.

Python Vehicle App SDK Examples

These examples demonstrate how to use the Python Vehicle App SDK:

Example	Description
Array Datatype	Shows a Vehicle Data Broker query that returns an array data point.
Atomic Set	Shows how to set the values of multiple datapoint actuators in one "atomic" step.
DataPoint Set	Shows how to set the value of the datapoint actuator value API.
Dog Mode	Dog-Mode App that demonstrates MQTT communication and invocation of a Vehicle Service over gRPC, the app also subscribes for vehicle data points and sets the cabin temperature.
Dynamic Rule	Create a Vehicle Data Broker rule with the fluent query methods.
Static Rule	Create a Vehicle Data Broker rule with the subscribe_to_data_point annotation.
VDB Queries	Demonstrates various aspects of creating Vehicle Data Broker queries.
Seat Adjuster	Seat-Adjuster App that demonstrates MQTT communication and seat control via actuator data points. 👉 This example can only be run from the Vehicle App Template. 👈

All examples (except the Seat Adjuster) can be run via

cd examples
./run-app.sh -a <example-folder-name>

By default the examples are started using the native middleware. Dapr middleware support was recently removed.

Contribution

• GitHub Issues
• Mailing List
• Contribution

Creating a new release

1. Update examples

This repository contain some example requirement files that reference the velocitas-sdk package created when we release the repository. Update velocitas-sdk version number in the following files:

• .project-creation/.skeleton/requirements-velocitas.txt
• examples/seat-adjuster/requirements-velocitas.txt

Use the version number intended to be used for the release.

2. Create a PR with the required changes

Note: The project creation workflow will fail, since the new tag is required by the workflow but not yet available. Since these checks are not mandatory to be able to merge the PR, you can still release your changes.

3. Once the PR is merged: Tag the commit and upload to GitHub

Create a release in the GitHub UI and use the new tag of the form vX.Y.X. That will trigger the release workflow. If the action is successfully executed a new version of velocitas-sdk is published in PyPI.

4. Re-run project creation tests

Now, when the updated PyPI package exists, the project creation workflow is expected to succeed if run manually for main. If not you need to troubleshoot why it doesn't.

Updating Dependencies

This repository specifies exact Python versions in setup.py and other files. If a version needs to be updated, for example if a vulnerability is detected, the following approach needs to be followed

1. Update version in setup.py if needed
2. Update generated requirement files.

pip-compile -U --extra=dev

3. Update version in examples/seat-adjuster/requirements.in if needed
4. Update generated file for Seat Adjuster

cd examples/seat-adjuster
pip-compile -U

5. Update version in .project-creation/.skeleton/requirements.in if needed
6. Update generated file for Skeleton

cd .project-creation/.skeleton/
pip-compile -U

7. Update NOTICE-3RD-PARTY-CONTENT.md

The easiest way to do it is to create a Pull Request. Then the check license workflow will fail as versions used no longer match versions stated in the file. Copy output from the workflow to the NOTICE-3RD-PARTY-CONTENT.md file and update the Pull Request.

8. Update examples and create a new release

As we explicitly use our "own" PyPI package we need to udpate references and create a new release, see release section above.