This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

Eclipse Leda

The Eclipse Leda project provides system image “recipes” to deliver a functional and always-available Linux-based image/distribution in the context of SDV (Software Defined Vehicle), by pulling together individual contributor pieces from Eclipse SDV and the larger OSS community.

The quickstart images help to learn how the SDV development, test and deployment lifecycle works from an E2E perspective, including the deployment of applications into the container runtimes on constrained embedded devices.

The ready images are also useful for quickly setting up showcases with virtual or real hardware devices.

Eclipse Leda provides a Poky-based reference build pipeline and an OpenEmbedded Metalayer meta-leda for integration into existing Yocto-based projects.

Usage

  1. Download latest Eclipse Leda release
  2. Run Eclipse Leda
  3. Configure device, e.g. provision the device
  4. Explore the device tools
  5. Develop your first Vehicle App using Eclipse Velocitas template
  6. Deploy a Vehicle App to the device

Supported Machines / Build Configurations

  • Emulated Qemu: x86-64, ARM64, ARM
  • Raspberry Pi 4

Introduction Video

Components Overview

Eclipse Leda Component Overview

Features

  • Publish/Subscribe infrastructure for local messaging and cloud connectivity
  • Lightweight container runtime
  • Vehicle Update Manager to orchestrate deployments of Vehicle Applications over the air (SOTA)
  • Self Update Agent for firmware-over-the-air (FOTA) updates
  • Example Vehicle Seat Service implementation
  • Metrics and logs collector for Vehicle Apps

See About - Features for more details about current implementation and About - Roadmap for our future work.

This program and the accompanying materials are made available under the terms of the Apache License 2.0 which is available at https://www.apache.org/licenses/LICENSE-2.0

For details, please see our license NOTICE

1 - About Leda

The Eclipse Leda project will provide system image “recipes” to deliver a functional Linux-based image/distribution in the context of SDV (Software Defined Vehicle), by pulling together individual contributons from the SDV and the larger OSS community.

The Eclipse Leda distribution will work with build scripts, package definitions, image build pipelines, etc, with the goal to pull SDV projects and dependecies from the larger OSS community into a working Linux system. Such system images (or other useful forms of delivery, as determined by the project) will be made available for consumption for anyone who is interested in working with the SDV tech stack. These deliveries take the form of container (base) images, installable/flashable image files, etc (again to be evolved by the project team according to community needs). Also in scope is concise and useful documentation for consumers of the project’s deliverables, plus a method of delivering that documentation.

In the context described above - the ambition of SDV to build a technology ecosystem for software-defined vehicle concern - a prime challenge will be the combination of these initially diverse components into a coherent and useful whole: all the software components in the world will not have the impact needed to transform the automotive industry unless we can make them play together coherently an form a functional portfolio. As a first step towards that goal, this proposal (Eclipse Leda) is for a “SDV distribution” project that pulls together individual contributor pieces from SDV and the larger OSS community, to deliver a functional and always-available Linux-based image/distribution with two primary goals:

  • be the crystalization point for functionally integrating diverse SDV-scope projects into a working whole

  • deliver a continually available, always working starting image for developers interested in getting going with the SDV tech stack

1.1 - Architecture

Runtime Overview

Eclipse Leda SDV Reference Implementation

The runtime overview shows the general layer architecture for the runtime of the SDV edge stack as implemented by the Leda quickstart image. Dotted lines indicate out-of-scope components. They may be non-Edge components (such as cloud services, or SDKs and additional development tooling for vehicle applications). Dotted lines for in-vehicle edge components indicate that they may be used, but are not pre-installed or pre-configured on the Leda quickstart image.

Deployment Overview

Eclipse Leda can be used in different deployment scenarios: on physical hardware, on virtual machines or installed on existing Linux distributions. Depending on the specific deployment, some features may not be applicable. Each deployment option is meant for different uses. The applicabability depend to your specific requirements.

Eclipse Leda Quickstart Deployment View

  • Option 1: Hardware - Suitable for proof-of-concepts, system integration tasks, access to actual physical actuators and sensors. However, an automated setup is much harder to realize, as additional hardware for remote controlling of power supply is needed. The constrained environment of a physical device is good to verify accidental assumptions made by application developers, such as resource consumptions (CPU, memory) or the existence of Linux tools, Kernel modules or device drivers.
  • Option 2: Docker Containers - Good for quick startup and throw-away (ephemeral) uses, such as automated system testing or one-off troubleshooting. The access to physical hardware is limited and more complicated to set up. QEMU provides emulation of devices, such as CAN-Bus. Due to multiple nesting of abstraction technology (Docker + QEMU + OS), additional configuration of networking and device pass-thrus are necessary. It’s easy and cheap to spin-off many separate instances to simulate a whole vehicle system with multiple vehicle computers and simulated ECUs in the same vehicle network.
  • Option 3: Package Installation - Good for existing devices with feature-rich functionality where the original OS should be used. Leda does not support self-update for this deployment option, as it relies on the master OS distribution channels. The constraints of an embedded device are not replicable easily on a PC-style host machine without additional effort. Package installation is good when the focus is on exploring the Vehicle Applications, SDKs, Vehicle Signal Abstractions etc.
Option 1: Hardware Option 2: Docker Containers Option 3: Package Installation
Target use case PoC Automation Existing devices
Cloud communication ++ ++ +++
Automation +++ ++
Device provisioning ++ ++ +++
Access to hardware +++ - ++
Container isolation +++ ++ +++
Network flexibility +++ - ++
Self update +++ +
Realistic constrains +++ - -

Build Environment Overview

Eclipse Leda Build Infrastructure View

1.2 - Features

  • Publish/Subscribe messaging infrastructure for cloud connectivity by Eclipse Kanto
    • local messaging for applications and SDV system components via an MQTT message broker
    • connection to a backend messaging hub, such as Azure IoT Hub or the IoT Suite
    • device identification and authentication for cloud connectivity by using TLS device certificates
  • Container runtime
    • An OCI-compliant container orchestration for vehicle applications and services by Eclipse Kanto
    • containerd.io as the default container runtime. Both layers of container runtimes can be exchanged with other implementations
  • A Vehicle Update Manager to orchestrate deployments of Vehicle Applications, configurations and base operating system updates
  • An example Vehicle Seat Service implementation to showcase
  • A Self Update Agent for firmware-over-the-air (FOTA) updates, using an A/B deployment strategy
    • Integration with RAUC
  • An OpenTelemetry collector and example configurations to collect and publish logs and metrics of containerized Vehicle Applications to the cloud backend for further processing

The features of the reusable build recipes implemented as an OpenEmbedded metalayer meta-leda are:

  • Build recipes for a Yocto-based distribution to build SDV-related software components
  • Build recipes for customizations of the target device’s storage structure to enable A/B system updates
  • Build recipes for pre-packaging container images into the device during the manufacturing process to minimize initial online provisioning time
  • A customized minimal setup for use on constrained devices and a full setup with convenient developer tools
  • Ready images for virtual devices, for automated testing and evaluation purposes, eg QEMU ARM-64
  • Ready images for physical devices, for evaluation and demo purposes, eg Raspberry Pi 4

1.3 - Goals

The project aims to provide an integration point for Open Source components for the Software Defined Vehicle ecosystem.

In a complex architecture, there are many different ways of implementations and alternative solutions possible.

For embedded vehicle computer systems and their software stack, there are a lot of requirements to consider, depending on the actual use cases:

  • Integration and High-Level Testing (System Integrators, Suppliers)
  • Proof-of-Concept projects (Integrators, OEMs, ISVs)
  • Experiments and Hackathons (Developers, Research)
  • Development phase (Developers, OEMs)
  • Open Source Collaboration (Developers, OEMs, ISVs, Open Source Organizations, Standardization Organizations)

Some of the requirements derived from the above are taken into account for Leda’s quickstart setups. Thereas some other requirements can only be met once the project is in a nearer production environment and by customizing the target device image. The following document will list some of these requirements and give an explanation on why they are set as goals in the Leda quickstart distribution.

Overview

  • Provide an example operating system build and configuration for constrained in-vehicle devices: Suppliers and system integrators want a way to cusomize and optimize the base operating system as much as possible. This is to achieve a high efficiency, high level of reuse and cost benefits of the planned hardware. The build system for the operating system, and the selection of the underlying distribution is key to the convenience for new users, but also commercially a business decision with an impact on the future maintainability of the platform. The Yocto Project has been chosen as an established de-facto standard for customized Linux distributions for embedded systems. Leda provides an OpenEmbedded Meta-Layer, which can be used with many existing SDKs of SoC manufacturers. Additionally, Leda will strive for being easy to install on low-cost “evaluation boards” such as the Raspberry Pi, or development environments such as a virtual machine in the cloud.
  • Integrate software-defined-vehicle Open Source components to showcase the available features and their state of maturity: The SDV ecosystem will grow and a lot of new software projects will be needed to solve the current problems and challenges. The Eclipse SDV ecosystem already contains many software packages, which independently make sense for their set goals. With Leda, we want to increase the integrational aspect, helping project leads, developers, contributors, users and architects to evaluate the SDV portfolio, how it can be integrated with each other and how a possible reference architecture implementation might be loooking like.
  • Demonstrate the use and interaction of open protocols and specifications:
    • Vehicle Signal Specifications from the The Connected Vehicle Systems Alliance (COVESA) to establish a semantically useful abstraction model for vehicle signals.
    • OpenTelemetry specs and components, to show the possibilities of applying DevOps methodologies and technologies to operate, monitor and maintain fleets of vehicles and their distributed software applications
    • Eclipse IoT related specifications for software rollouts and digital twin representations

1.4 - Roadmap

  • Initial Open Source contribution expected by Q2 2022 (Done)
  • A first milestone build is expected end of 2022 (Done)
  • Plan for the first release cycle to be created in Q1/2023 (In Progress - Q2/2023)
  • Release cycles are planned every 3-6 months
  • Release planning will be conducted together with corresponding Eclipse projects

Backlog

The Leda team maintains a backlog roadmap using GitHub projects at https://github.com/orgs/eclipse-leda/projects/1/views/1

Future Work

The project intends to be the integration and collaboration platform for Software defined Vehicle functionality.

Exemplary future work:

  • Migrate to official Eclipse Kanto releases for Cloud Connector, Container Management and Vehicle Update Manager
  • Include reference implementations from the Eclipse Software Defined Vehicle working group projects:
    • Eclipse Velocitas
    • Eclipse Kuksa
    • Eclipse SommR
    • Eclipse Chariott
    • Eclipse Muto
    • Eclipse Backend function Bindings (BfB)
    • Eclipse SDV Blueprints
  • Include and showcase more features regarding development, operation and monitoring of Vehicle Services and Vehicle Applications

If you have feedback, please use GitHub Issues

1.5 - Releases

The Eclipse Leda project follows the Eclipse Release process. Please see Eclipse Project handbook for details about the process.

The release plans overview for Eclipse Leda is available at https://projects.eclipse.org/projects/automotive.leda/governance

1.5.1 - Milestone 0.1.0-M1

Release artifacts: https://github.com/eclipse-leda/leda-distro/releases/tag/v0.1.0-M1

Artifact Download Size
Leda Raspberry Pi 4 eclipse-leda-raspberrypi.tar.xz 578 MB
Leda QEMU ARM64 eclipse-leda-qemu-arm64.tar.xz 381 MB
Leda QEMU x86_64 eclipse-leda-qemu-x86_64.tar.xz 465 MB

Note: You need to uncompress eclipse-leda-raspberrypi.tar.xz multiple times until the plain .wic file is extracted, which can be flashed.

After download, continue with Getting Started

Release Notes

First pre-release of Eclipse Leda quickstart images, based on Yocto LTS release Kirkstone with Long Term Support until at least April 2024.

Minimal feature set to run software-defined-vehicle applications (such as Eclipse Velocitas apps) using COVESA Vehicle Signal Specification and the Eclipse Kuksa.VAL Databroker on virtual devices (QEMU), in Docker, or on physical consumer-grade devices (Raspberry Pi 4 64-Bit) for development, demonstration and prototyping purposes.

Includes example applications from Kuksa:

  • Example Seat Service
  • Example HVAC Service
  • DBC Feeder replays a Tesla Model 3 CAN-Dump and feeds it into Kuksa.VAL Databroker

Change log

  • Replaced k3s with Eclipse Kanto Container Management
  • Replaced packages licensed under GPLv3 and similar licenses with alternatives
    • Replaced Grub with U-Boot
    • Replaced nano with kibi
    • Removed readline library
    • Removed bash
  • RAUC Updates
    • Bundles available for each image type (Full, Minimal, Rescue)
    • Enabled verity format by default
    • Fixed the compatible configuration string
  • Added and updated Leda utilities
  • Build infrastructure improvements
    • Builds for Dockerized images
    • Switched to a BitBake build using kas for layer management
    • Added automated system tests using Robot framework and Dockerized environments
    • General cleanup of recipes, dependencies and structuring of the meta-leda sublayers to improve reusability
  • Automatic deployment of containers based on container manifests with ad-hoc updates (filewatcher in kanto-auto-deployer)
  • Preparation for AirGap installation of containers
  • General improvements, such as Wifi network management

Known Issues

The following issues were known to the development team before starting the 0.1.0-M1 build cycle. They have been prioritized as non-critical and may be fixed for later releases.

OSS IP Compliance Report

Report scan-report-web-app_0.1.0-M1.html

  1. Incorrectly detected license “biosl-4.0”

    • Rule: OCaaS Policy A9 License with no classification
    • Message: The license LicenseRef-scancode-biosl-4.0 found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is not categorized and / or evaluated for usage.
    • Evaluation: This license seems to be detected incorrectly by the tool being used, as it is an internal, proprietary license which is not used in the Eclipse Leda project.
  2. Incorrectly detected license “GPL-1.0” for ORT configuration file

    • Rule: OCaaS Policy C1 Strict Copyleft
    • Message: License GPL-1.0-only found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is categorized as strict-copyleft which must not be used for BT11 Open Source Development service applications.
    • Evaluation: The scan tool incorrectly detects its own configuration file (.ort.original.yml) as being licensed under GPL-v1.0
  3. Incorrectly detected license “GPL-2.0-only” for standard Leda license header (which is Apache Software License)

    • Rule: OCaaS Policy C1 Strict Copyleft
    • Message: License GPL-2.0-only found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is categorized as strict-copyleft which must not be used for BT11 Open Source Development service applications.
    • Evaluation: The scan tool incorrectly detects the Apache License header as GPL-2.0 license text
  4. Incorrectly detected license “proprietary”

    • Rule: OCaaS Policy C3 Commercial
    • Message: License LicenseRef-scancode-proprietary-license found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is categorized as commercial and requires special handling.
    • Evaluation: The scan tool incorrectly detects its own configuration file (.ort.original.yml) as being licensed under proprietary licenses.

1.5.2 - Milestone 0.1.0-M2

Release artifacts: https://github.com/eclipse-leda/leda-distro/releases/tag/v0.1.0-M2

Artifact Download Size
Leda Raspberry Pi 4 eclipse-leda-raspberrypi.tar.xz 578 MB
Leda QEMU ARM64 eclipse-leda-qemu-arm64.tar.xz 381 MB
Leda QEMU x86_64 eclipse-leda-qemu-x86_64.tar.xz 465 MB

Note: You need to uncompress eclipse-leda-raspberrypi.tar.xz multiple times until the plain .wic file is extracted, which can be flashed.

After download, continue with Getting Started

Release Notes

First pre-release of Eclipse Leda quickstart images, based on Yocto LTS release Kirkstone with Long Term Support until at least April 2024.

Minimal feature set to run software-defined-vehicle applications (such as Eclipse Velocitas apps) using COVESA Vehicle Signal Specification and the Eclipse Kuksa.VAL Databroker on virtual devices (QEMU), in Docker, or on physical consumer-grade devices (Raspberry Pi 4 64-Bit) for development, demonstration and prototyping purposes.

Includes example applications from Kuksa:

  • Example Seat Service
  • Example HVAC Service
  • DBC Feeder replays a Tesla Model 3 CAN-Dump and feeds it into Kuksa.VAL Databroker

Change log 0.1.0-M2

  • Remove skopeo dependency from packagegroup-sdv-tools.bb
  • Fix typo in SRCREV_FORMAT for pahocpp
  • dd kernel config for RAUC stream mode to raspberrypi4-64 and qemuarm64
  • Adding extra space in RPi for RAUC updates
  • Backport Go 1.20 from Poky Mickledore
  • Adding seatadjuster-app
  • seatadjuster-app distribution

Change log 0.1.0-M1

  • Replaced k3s with Eclipse Kanto Container Management
  • Replaced packages licensed under GPLv3 and similar licenses with alternatives
    • Replaced Grub with U-Boot
    • Replaced nano with kibi
    • Removed readline library
    • Removed bash
  • RAUC Updates
    • Bundles available for each image type (Full, Minimal, Rescue)
    • Enabled verity format by default
    • Fixed the compatible configuration string
  • Added and updated Leda utilities
  • Build infrastructure improvements
    • Builds for Dockerized images
    • Switched to a BitBake build using kas for layer management
    • Added automated system tests using Robot framework and Dockerized environments
    • General cleanup of recipes, dependencies and structuring of the meta-leda sublayers to improve reusability
  • Automatic deployment of containers based on container manifests with ad-hoc updates (filewatcher in kanto-auto-deployer)
  • Preparation for AirGap installation of containers
  • General improvements, such as Wifi network management

Known Issues

The following issues were known to the development team before starting the 0.1.0-M1 build cycle. They have been prioritized as non-critical and may be fixed for later releases.

OSS IP Compliance Report

Report scan-report-web-app_0.1.0-M1.html

  1. Incorrectly detected license “biosl-4.0”

    • Rule: OCaaS Policy A9 License with no classification
    • Message: The license LicenseRef-scancode-biosl-4.0 found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is not categorized and / or evaluated for usage.
    • Evaluation: This license seems to be detected incorrectly by the tool being used, as it is an internal, proprietary license which is not used in the Eclipse Leda project.
  2. Incorrectly detected license “GPL-1.0” for ORT configuration file

    • Rule: OCaaS Policy C1 Strict Copyleft
    • Message: License GPL-1.0-only found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is categorized as strict-copyleft which must not be used for BT11 Open Source Development service applications.
    • Evaluation: The scan tool incorrectly detects its own configuration file (.ort.original.yml) as being licensed under GPL-v1.0
  3. Incorrectly detected license “GPL-2.0-only” for standard Leda license header (which is Apache Software License)

    • Rule: OCaaS Policy C1 Strict Copyleft
    • Message: License GPL-2.0-only found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is categorized as strict-copyleft which must not be used for BT11 Open Source Development service applications.
    • Evaluation: The scan tool incorrectly detects the Apache License header as GPL-2.0 license text
  4. Incorrectly detected license “proprietary”

    • Rule: OCaaS Policy C3 Commercial
    • Message: License LicenseRef-scancode-proprietary-license found for package ‘Unmanaged::leda-distro-fork:0716b55ff8f57319263d67ee16d90e64588b391d’ is categorized as commercial and requires special handling.
    • Evaluation: The scan tool incorrectly detects its own configuration file (.ort.original.yml) as being licensed under proprietary licenses.

1.5.3 - Release Plan 0.1.0

The release plan is available at https://projects.eclipse.org/projects/automotive.leda/releases/0.1.0

Release Date

-Thursday, June 1, 2023- - We didn’t meet the planned release date. Work is in progress on IT build infrastructure and OSS IP and license compliance.

New: Tuesday, August 1, 2023

Deliverables

The team plans to deliver the following features:

  • Leda Quickstart Images for Qemu (x86_64, arm64), Raspberry Pi and Docker
  • Yocto / OpenEmbedded meta-layer for better reusability of the Eclipse SDV Vehicle.Edge stack in customized distributions for constrained devices
  • User documentation (Reference, Example Use Cases)
  • Automated system tests using Robot Framework
  • IP scanning with Eclipse Oniro Compliance Toolchain
  • Pre-Integrated Eclipse SDV Vehicle.Edge stack

The core SDV.EDGE stack in Leda would contain the following components for the first release (based upon availability):

  • Eclipse Kuksa.VAL: Data Broker
  • Eclipse Kanto: Container Management, Vehicle Update Manager
  • Eclipse Leda Incubator: Cloud Connector (Azure), Self Update Agent, Utilities (e.g kantui)

The following components are not yet released in public or did not yet finished the project review, and may only be added to the release on shorter notice:

  • (Eclipse Backend-Function-Bindings)
  • (Eclipse SommR)
  • (OTA Client)

Compatibility

Compatibility to previous versions is not considered for this first release.

Internationalization

No efforts towards i18n are done in this release.

Target Environments

  • Linux (virtual, qemu)
  • Raspberry Pi 4 (consumer grade)

2 - Getting Started

  1. Download latest Eclipse Leda release
  2. Run Eclipse Leda
  3. Configure device, e.g. provision the device
  4. Explore the device tools
  5. Develop your first Vehicle App using Eclipse Velocitas template
  6. Deploy a Vehicle App to the device

2.1 - Introduction to SDV concepts

This page introduces the main concepts around Eclipse Leda, Eclipse Kuksa, Eclipse Velocitas, and Eclipse Kanto for developing and deploying applications for a software defined vehicle (SDV). The intention is to introduce the main concepts and how these projects interact. When you are already familiar with the general ideas of the Eclipse SDV, you can also jump to a hands-on tutorial on how to develop a seat adjuster application or replicate an Eclipse SDV Blueprint for managing vehicle fleets using Eclipse SDV concepts and technologies.

Abstract Architecture

For the software defined vehicle we may assume the following abstract architecture.

Abstract Architecture

The architecture evolves around actuators and sensors in a vehicle, like the state of a passenger seat or a door, which get controlled by connected ECUs. These ECUs react to and produce signals, which they communicate over automotive communication systems like CAN or SOME/IP. To establish a more flexible interaction between these ECUs and make the overall vehicle more software-defined, we assume various vehicle applications which want to interact with the actuators and sensors, e.g., to control a seat based on a saved driver profile. The architecture contains a vehicle abstraction layer between the ECUs and the vehicle applications. This abstraction layer introduces a potential control point for security and safety considerations and generally decouples the application logic from the more deeply embedded soft- and hardware layers.

Vehicle Abstraction Layer

As the name implies the vehicle abstraction layers offers abstract ways to interact with the underlying vehicle.

Vehicle Signal Specification (VSS)

We need a joint data model for the potential signals with which an application can interact. We propose to use the Vehicle Signal Specification (VSS) from the Connected Vehicle Systems Alliance (COVESA) for this.

VSS Tree

VSS essentially defines a rule set of how to express the definition of signals in a vehicle. This definition bases a tree structure where each domain, like body control, gets an individual sub-tree. The authors of VSS further provide a default tree of signals to be expected in a vehicle. However, it is common practice to tailor the default tree for a specific vehicle model by adding overlays.

VSS allows modeling and structuring of the data from a vehicle but does not define interfaces for the interaction with this data since this depends on the used communication technology and further circumstances like whether VSS data gets processed inside the vehicle or off-board.

For our architecture, we therefore add the Eclipse Kuksa.val databroker from the Eclipse Kuksa project.

Eclipse KUKSA.val databroker

The Eclipse Kuksa.val databroker acts as a vehicle abstraction layer by brokering VSS signals between vehicle applications and deeply embedded systems in the vehicle. Enabling this abstraction requires a vehicle-specific component to translate between the Kuksa.val databroker and the underlying transport systems and ECUs.
With Eclipse Kuksa, we refer to these software components as providers and further differentiate between actuation and data providers.

Eclipse Kuksa Actuation

For actuators, the Kuksa.val databroker stores the desired and the current state. Typically, an application would perform a control operation by setting the target state and monitoring the current state. It is then the task of the actuation provider to perform the action while the data provider updates the current state according to signals sent on the vehicle bus. To get notified of any changes, applications, and providers can subscribe to specific signals at the Kuksa.val databroker.

The Kuksa.val databroker is written in Rust and offers communication over gRCP. To make life easier for developers using the Kuksa.val databroker there is a Python-client which can be integrated in own applications. When developing with other languages, you may have to generate client code yourself with the gRPC tooling. Either way, these clients allow the development of vehicle applications and providers.

Vehicle Application Development

When developing an application to interact with the abstraction layer, there are a couple of aspects to cover, which are not specific to a single application. Because of that, some projects are evolving around the application development phase.

Eclipse Autowrx and digital.auto Playground

A good starting point to figure out what signals are available is the website of the digital.auto playground based on Eclipse Autowrx.

digital.auto Vehicle API

In the next step, you can ideate on new applications, start coding, and get fast feedback using the prototyping feature of the playground. Once you are confident with the initial version, you can continue the development journey with the help of Eclipse Velocitas, which comes with several features making the life of vehicle application developers easier.

digital.auto Prototyping

Eclipse Velocitas

Eclipse Velocitas™ is an open source project providing a development tool chain to create containerized Vehicle Apps, offering a development experience to increase the speed of a development team (velocity).

Among other things, Eclipse Velocitas provides a template repository. To kick-start the development of a new application, you can create an individual repository from this template. As an alternative, Eclipse Velocitas provides a CLI application with which you can configure the creation of a tailored vehicle application repository. Either way, the resulting repository contains skeleton code for the actual application and comes with pre-defined GitHub Actions workflows to automate the testing and releasing of applications as containers. The repository further contains the Dockerfile for a dev container that setups a development and vehicle environment on the developer machine. It is then possible to interact with this container through VSCode.

Another aspect of Eclipse Velocitas is the so-called vehicle model. Here it becomes possible to take a custom vehicle model expressed in VSS and generate a tailored SDK with specific domain classes to interact with a Kuksa.val databroker using the same model. This way, we can directly develop against the used vehicle model.

Velocitas Flow

A typical Eclipse Velocitas application development flow then may contain the following steps:

  • create Repository
  • build and run Dev Container locally from VSCode
  • start vehicle runtime in Dev container
  • develop vehicle application and integration tests
  • commit and push vehicle applications to trigger tests in GitHub Actions workflows
  • trigger release workflow in GitHub

As a result of the Release workflow, the generated repository contains a Container image with the vehicle application. A target device, e.g., a vehicle or test device, can pull and execute this container.

Vehicle Providers and Emulation

The underlying assumption when developing a vehicle application against the vehicle abstraction layer is that components below the abstraction fulfill the requests coming from the application. In other words: Developers have to assume that there are providers for the signals with which their application interacts. For a production-ready vehicle, this should be the case. But during development and testing the creation of such providers adds overhead and is a potential cause for further errors. An alternative is to use pre-developed services or even a generalized vehicle mock service which acts as such a provider. Developers can alter the vehicle mock service by defining the desired behavior through a Python-based DSL.

Vehicle Mock

Vehicle Application Runtime

The next step is to bring the application to the target device and the vehicle. There are various options for how to run and orchestrate vehicle application containers. Some originate from general IT scenarios like Kubernetes or Docker Compose, and others focus more on automotive and IoT-use cases like Eclipse Kanto. So a vehicle application developer now faces the challenge of picking a runtime and integrating this runtime with required infrastructure components like the Kuksa.val databroker or respective Kuksa.val providers to enable the vehicle application.

Eclipse Leda

Among other things, Eclipse Leda already provides such a target platform through a Linux-based distribution of pre-integrated Eclipse SDV components. See the architecture page for more details on the elements in Eclipse Leda. For the container execution, Eclipse Leda utilizes Eclipse Kanto, which implements lightweight management of OCI-compliant containers and comes by default with containerd. It is possible to manage the containers either through a CLI or by writing container manifest files and placing them in a dedicated folder on the file system from where Eclipse Kanto automatically performs them.

Service Exchange

Another challenge when deploying multiple components that need to collaborate as services is how they find and communicate with each other. In Eclipse Kanto, the discovery and exchange can happen over container indetifiers or topics on a local MQTT broker. The Eclipse SDV community already came up with other approaches for the service exchange topic like Eclipse uProtocol, Eclipse Chariott or Eclipse Zenoh.

Seat Adjuster

To see the explained concepts in action, it is best to build your own application. The Seat Adjuster is good starting point with specific examples.

2.2 - Download latest release

Latest Release Artifacts

Note: There are no official releases yet. The artifacts available on the Release page are for testing the build and release workflows. They should be considered as unstable nightly builds from the main branch. Releases marked -M1, -M2, -RC1 etc. are preparations for official releases according to the Eclipse Release process.

Go to the Eclipse Leda Releases page and download the release archive for the respective machine. The release archives container the disk image and the respective Linux kernel:

Machine Filename Description
QEMU x86_64 eclipse-leda-qemu-x86_64.tar.xz For running QEMU x86 64-Bit
QEMU ARM 64 eclipse-leda-qemu-arm64.tar.xz For running QEMU ARM 64-Bit
Raspberry Pi 4 eclipse-leda-raspberrypi.tar.xz For running on Raspberry Pi 4 (SD-Card Image)

Using GitHub CLI tool

To download all files of the latest release using the GitHub CLI:

  • Install GitHub CLI, e.g. for Ubuntu:

    curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
    sudo apt update
    sudo apt install gh
    
  • Authenticate to GitHub:

    gh auth login
    
  • Download Leda latest release:

    On Linux:

    mkdir leda && cd leda
    
    gh release download \
      --pattern '*.zip' \
      --pattern 'eclipse-leda-*' \
      --repo eclipse-leda/leda-distro
    

    On Windows:

    gh release download --pattern "*.zip" --pattern "eclipse-leda-*" --repo eclipse-leda/leda-distro
    
  • Continue with Running Eclipse Leda on QEMU or Running Eclipse Leda on Raspberry Pi 4

2.3 - Running on Docker

By using the dockerized Leda quickstart images, the SDV vehicle edge components can be evaluated on emulated X86-64 and ARM64 system images, without having to install QEMU and dependencies manually.

Eclipse Leda Docker Compose Up

If you want to execute the image without Docker, please see Running on QEMU. This allows to tweak the startup script, modify the emulated hardware device and set up advanced network configurations.

There are two options to run Leda:

  • Docker: Simple, restricted to one container
  • Docker Compose: Advanced, allows networking between containers

Recommendations

  • A Linux host with 4 vCPUs, 8GB of RAM and SSD storage is recommended
  • Docker

Docker

The easiest way is to run a single instance of Leda in a Docker container:

  • Run the Leda Docker quickstart image:

    docker run -it ghcr.io/eclipse-leda/leda-distro/leda-quickstart-x86
    
  • Login with root

  • Stop the Docker container

    shutdown now
    

    Note: If you need to stop the container from outside, use the docker stop <id> command from a separate terminal.

Privileged Containers

When run as a privileged container, QEMU will try to set up a TAP network and use KVM acceleration. Network and CPU will be faster, depending on the host system.

To be able to use these host devices, QEMU needs access to the following devices:

  • /dev/kvm
  • /dev/net/tun

Example command:

docker run -it --privileged --device=/dev/kvm:/dev/kvm --device=/dev/net/tun:/dev/net/tun ghcr.io/eclipse-leda/leda-distro/leda-quickstart-x86

Exposing additional ports

To also expose ports to connect to ssh, mqtt or the Kuksa databroker, add the port mappings to the Docker command:

docker run -it --privileged -p 2222:2222 -p 1883:1883 -p 30555:30555 ghcr.io/eclipse-leda/leda-distro/leda-quickstart-x86:latest

The following ports are specifically of interest and exposed by the docker container:

  • 2222 for SSH (mapped internally to 22)
  • 1880 - free slot reserved for user service
  • 1883 for MQTT
  • 8888 - free slot reserved for user service
  • 30555 for Kuksa Databroker

Note: In unprivileged mode, only these ports are mapped by the Docker container and forwarded to the Leda system. In privileged mode, all TCP ports can be exposed, which will then be forwarded from the Docker container into the Leda system. See the entrypoint script for details.

Running ARM-64 version

To run the ARM-64 bit version of the image, use the leda-quickstart-arm64 container image:

docker run -it ghcr.io/eclipse-leda/leda-distro/leda-quickstart-arm64:latest

Docker Compose

A more convenient way to setup advanced scenarios is to use Docker Compose. There is a Docker Compose configuration for an Eclipse Leda setup in resources/docker-compose.

It will start up the following containers:

  • Leda Quickstart image (QEMU x86-64)
  • Leda Quickstart image (QEMU ARM-64)
  • Web Server with pre-built RAUC Update Bundles
  • MQTT Bridge
  • DNS Proxy (Allows QEMU to use the Docker DNS)

Usage

Get the Docker Compose configuration file and additional dockerfiles from the https://github.com/eclipse-leda/leda-distro repository:

git clone --filter=blob:none https://github.com/eclipse-leda/leda-distro
cd leda-distro/resources/docker-compose

Starting the containers with:

docker compose up --detach --wait

Log in to a development shell inside of the docker network:

docker compose run --rm devshell

Stopping the containers:

docker compose down

Docker Compose Services

Checking all containers are running or exited successfully:

$ docker compose ps
NAME                 COMMAND                  SERVICE              STATUS              PORTS
leda-arm64           "/docker/leda-quicks…"   leda-arm64           running (healthy)   1883/tcp, 0.0.0.0:2002->2222/tcp, 0.0.0.0:30556->30555/tcp
leda-bundle-server   "/docker-entrypoint.…"   leda-bundle-server   running (healthy)   0.0.0.0:8080->80/tcp
leda-dns-proxy       "dnsmasq -k"             dns-proxy            running             53/tcp, 0.0.0.0:5353->53/udp
leda-initializer     "/bin/sh -c /root/le…"   leda-initializer     exited (0)          
leda-mqtt-broker     "/docker-entrypoint.…"   mqtt-broker          running (healthy)   0.0.0.0:1883->1883/tcp
leda-x86             "/docker/leda-quicks…"   leda-x86             running (healthy)   1883/tcp, 0.0.0.0:30555->30555/tcp, 0.0.0.0:2001->2222/tcp

Network setup

As the networking is a bit more complicated to set up with emulated network inside of QEMU, the following explanation is helpful to understand networking better.

  • All docker compose containers are attached to a network called leda-bridge and leda-network and can see each other
  • The QEMU instances use a TAP network inside of each leda-quickstart-xxx container and do a NAT network translation to their own container
  • The Docker internal DNS server is being used. This is implemented by a DNS Proxy container, which will forward incoming DNS requests to the Docker DNS running on the 127.0.0.x network.
  • In unprivileged mode: Only the exposed ports are forwarded from the docker container into the QEMU process: mosquitto 1883, ssh 2222 and kuksa.val databroker 30555. In privileged mode, all TCP ports are forwarded from the Docker container into the QEMU process and the special port 2222 is forwarded to ssh port.

Developer Shell

Developer Shell:

docker compose run --rm devshell

From there, you can log in to either Leda on QEMU x86-64, or log in to Leda on QEMU ARM-64.

ssh leda-x86
ssh leda-arm64

To run an additional terminal in the developer shell, execute this:

docker compose exec devshell /bin/bash

Interacting with Eclipse Leda

  1. Check the general system status
sdv-health

Device Provisioning

  1. Run the provisioning script:

    sdv-provision
    
  2. Copy the fingerprints

  3. Go to Azure IoT Hub, create a new device

  4. Use the certificate’s common name (CN) as Device Id - on Leda, this defaults to a part of the MAC Address

  5. Select X.509 Self-Signed authentication type and enter both fingerprints

  6. Click Save

MQTT Broker Bridge

graph LR; A["MQTT Container
on docker host
localhost:1883"] -- Bridge --> B[leda-x86:31883]; A -- Bridge --> C[leda-arm64:31883]; B-->B1[mosquitto service
leda-x86:1883]; C-->C1[mosquitto service
leda-arm64:1883];

The Docker Compose setup will also start an Eclipse Mosquitto message broker as a bridge to both Leda instances. This allows a user or developer to monitor messages sent by or received by both virtual devices.

Connect your MQTT client to mqtt-broker.leda-network by using the exposed port 1883 on the host:

mosquitto_sub -h localhost -p 1883 -t '#' -v

Docker Networking

You need to enable IP forwarding from Docker containers to make networking work. The containers (leda-arm64, leda-x86) need to run with --privileged as they change iptables rules for proper forwarding of network packets.

See Docker documentation for bridge networking for details.

sudo sysctl net.ipv4.conf.all.forwarding=1
sudo iptables -P FORWARD ACCEPT

Each Eclipse Leda instance (ARM64, x86_64) is running within a QEMU emulated network (192.168.7.2), which itself is contained in a containerized network called leda-network (192.168.8.x).

The containers wrapping the QEMU instances will forward the following ports to the respective QEMU process:

  • SSH on port 2222
  • Mosquitto on port 1883

DHCP and DNS setup

Each Leda-QEMU container is running a local DHCP on the tap0 network interface and listens for DHCP requests by the Leda Distro running inside of QEMU. The DHCP server will respond with the same IP address (192.168.7.2) to the request from QEMU.

The DHCP response contains a DNS nameserver pointing to the dns-proxy.leda-network (192.168.8.14) IP, which in turn forwards to Docker’s internal 127.0.0.11 nameserver. This allows the QEMU guests to resolve Docker Compose Services by their service name, e.g. leda-bundle-server.leda-network.

Volumes

The /root path inside of the Leda containers is mounted as a volume and contains the raw disk image and runner scripts for the QEMU Leda distribution. Changes on the QEMU filesystem are made persistent on a copy of the QCOW2 disk image, so that restarting the device will keep any changes.

To reset to the original state, delete the respective docker volumes and restart the containers:

docker compose down
docker compose rm --force --stop --volumes
docker volume rm leda-arm64
docker volume rm leda-x86

Profiles

Profiles can be used to determine which containers (services) docker compose should be starting by default. This is mostly used to have the devshell container not start up by default.

  • tools: Contains docker containers which are not essential at runtime, must useful for testing and development purposes

2.4 - Running on Raspberry Pi

What you need:

  • A Raspberry Pi 4B (64 Bit) with 2 GiB of RAM or more, recommended is 8 GiB
  • Network connection (Ethernet or Wifi) with transparent internet access
  • Optional keyboard and display (makes it easier to troubleshoot)

Steps:

  • Download the latest released SD-Card Image: eclipse-leda-raspberrypi.tar.xz

  • Uncompress the SD Card image:

    apt-get install -y xz-utils
    tar xf eclipse-leda-raspberrypi.tar.xz
    bzip2 -d -f sdv-image-all-raspberrypi4-64.wic.bz2
    
  • Flash the sdv-image-all-raspberrypi4.wic file to an SD-Card

    • On Linux:
      • Install bmap tools: sudo apt-get install -y bmap-tools
      • Insert SD Card and check which device is mounted: sudo fdisk -l
      • Unmount the device: sudo umount /dev/mmcblk[X]
      • sudo bmaptool copy --bmap sdv-image-all-raspberrypi4-64.wic.bmap sdv-image-all-raspberrypi4-64.wic /dev/mmcblk[X]
      • Note: Using bmap is much faster but works the same as with plain dd if=<wic-file> of=dev/mmcblk[x].
    • On Windows:
  • Optional: If you need to adapt the network configuration eg Wifi credentials, edit the configuration files on the boot partition.

  • Shutdown the Raspberry and insert the SD-Card into the Raspberry Pi SD-Card slot at the bottom

  • Power on your Raspberry to boot the image

  • Login with root

  • Check disk space:

    • The raspberry-growdisk system service will do this automatically on first boot.

    • To manually enlarge the available disk space on the SD-Card, resize the disk partition: parted /dev/mmcblk0 resizepart 6 100% && resize2fs /dev/mmcblk0p6.

      Note: Due to changes in the disk partition, the partition number (6 in the example) may have changed.

    • Verify with df -h.

  • Verify and wait until container runtime is started: systemctl status container-management

  • Optional: Check the system health: sdv-health

  • Continue with Device Provisioning

2.4.1 - CAN-Bus extensions

The Eclipse Leda quickstart image has CAN-Bus kernel modules and some CAN hardware drivers pre-installed. However, some hardware configuration needs to be adapted at boot time depending on the specific CAN-Extension being attached to the device.

On Raspberry Pi, there is a /boot/config.txt file where you can configure the dtoverlay options accordingly.

Note: After modification, the device requires rebooting for the changes to take effect.

MCP2515 based modules

Products:

dtoverlay=mcp2515-can0,oscillator=12000000,interrupt=25,spimaxfrequency=2000000

MCP2518FD based modules

Products:

dtoverlay=2xMCP2517FD
#dtoverlay=2xMCP2518FD-spi0

2.5 - Running on QEMU

If you want to execute the image without building first, grab the latest release or build artifacts from https://github.com/eclipse-leda/leda-distro/

Recommendations

  • A Linux host with 8 vCPUs, 16GB of RAM and SSD storage is recommended
  • Your Linux user should be sudoer to allow TAP network interfaces to be set up

QEMU x86_64

  • Install Qemu, e.g. for Ubuntu:

    sudo apt-get update -y
    sudo apt-get install -y xz-utils qemu-system-x86-64
    
  • Download latest Eclipse Leda release

  • Uncompress the archive

    tar xf eclipse-leda-qemu-x86_64.tar.xz
    
  • Run QEMU on Linux:

    ./run-leda.sh
    
  • Run QEMU on Windows:

    run-leda.cmd
    

    Leda boot sequence

  • Login as root without password on login prompt

  • Verify and wait until container runtime is started: systemctl status container-management

  • Optional: Check the system health: sdv-health

    sdv-health

    Note: The status of some containers (e.g. cloud connector) are expected to stay in FAILED status as long as the Device Provisioning steps are not completed.

  • Continue with Device Provisioning

QEMU ARM 64-Bit

  • Install Qemu, e.g. for ARM 64-Bit: sudo apt install qemu-system-aarch64

  • Download latest Eclipse Leda release

  • Uncompress the archive

    tar xf eclipse-leda-qemu-arm64.tar.xz
    
  • Run QEMU on Linux:

    ./run-leda.sh
    
  • Run QEMU on Windows:

    run-leda.cmd
    
  • Login as root without password on login prompt

  • Verify and wait until container runtime is started: systemctl status container-management

  • Optional: Check the system health: sdv-health

    Note: The status of some containers (e.g. cloud connector) are expected to stay in FAILED status as long as the Device Provisioning steps are not completed.

  • Continue with Device Provisioning

2.5.1 - CAN Bus

Note: The configuration mentioned in this chapter is already enabled in the run-leda.sh script.

QEMU

General documentation about using CAN-Bus in Qemu: https://www.qemu.org/docs/master/system/devices/can.html

Enabling Virtual CAN Bus interfaces (vcan)

No special parameters are necessary for qemu, as vcan is virtual:

runqemu qemux86-64 nographic slirp qemuparams="-m 2048"

Bring interface up:

ip link add dev vcan0 type vcan
ip link set vcan0 up

Enabling CAN Bus interfaces (can)

Standalone CAN within Qemu

To run a standalone CAN setup, qemu must be instructed to emulate a specific CAN hardware device. We will be using the kvaser_pci device in this example:

runqemu qemux86-64 nographic slirp qemuparams="-m 2048 -object can-bus,id=canbus0 -device kvaser_pci,canbus=canbus0"

After the image has booted, load the Linux Kernel Module kvaser_pci device driver and configure the CAN-Bus device (eg bitrate) before bringing the interface up:

root@qemux86-64:~# modprobe kvaser_pci

root@qemux86-64:~# dmesg | grep kvaser
[    9.565149] kvaser_pci 0000:00:04.0: initializing device 10e8:8406
[    9.569308] kvaser_pci 0000:00:04.0: reg_base=00000000d5a68095 conf_addr=000000002b3c7ef6 irq=20
[    9.596942] kvaser_pci 0000:00:04.0: xilinx version=13 number of channels=0

root@qemux86-64:~# ip link show type can
4: can0: <NOARP,ECHO> mtu 16 qdisc noop state DOWN mode DEFAULT group default qlen 10
    link/can

Configure the interface:

root@qemux86-64:~# ip link set can0 type can bitrate 1000000
[  165.519919] kvaser_pci 0000:00:04.0 can0: setting BTR0=0x00 BTR1=0x14

root@qemux86-64:~# ip link set can0 up
[  186.906065] IPv6: ADDRCONF(NETDEV_CHANGE): can0: link becomes ready

root@qemux86-64:~# ip link show type can
4: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP mode DEFAULT group default qlen 10
    link/can 

Tunneling a CAN Interface from the Host

runqemu qemux86-64 nographic slirp qemuparams="-m 2048 -object can-bus,id=canbus0 -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0 -device kvaser_pci,canbus=canbus0"

Bring interface up:

ip link add dev can0 type can
ip link set can0 type can bitrate 1000000
ip link set can0 up
ip link show type can

Raspberry Pi CAN HAT Extensions

Supported boards:

  • Boards with a Microchip MCP251x based CAN chip, such as Waveshare CAN HAT or PiCAN 2

Verify driver is loaded:

# dmesg | grep mcp
[    8.23543] mcp251x spi0.0 can0: MCP2515 successfully initialized

Verify SocketCAN network interface shows up:

# ip link show type can
3: can0: <NOARP,ECHO> mtu 16 qdisc noop state DOWN mode DEFAULT roup default qlen 10

Continue with configuring the CAN chip and bring up the SocketCAN network interface:

# ip link set can0 type can bitrate 1000000
# ip link set can0 up
# ip link show type can

Linux Kernel Modules

The following Linux Kernel modules are available on the quickstart images:

Note: For QEMU, only kvaser_pci is used

Leda main Kernel

  • peak_pciefd - Socket-CAN driver for PEAK PCAN PCIe/M.2 FD family cards
  • m_can - CAN bus driver for Bosch M_CAN controller
  • m_can_pci - CAN bus driver for Bosch M_CAN controller on PCI bus
  • m_can_platform - M_CAN driver for IO Mapped Bosch controllers
  • softing - Softing DPRAM CAN driver
  • cc770_platform - Socket-CAN driver for CC770 on the platform bus
  • cc770_isa - Socket-CAN driver for CC770 on the ISA bus
  • cc770 - cc770CAN netdevice driver
  • ifi_canfd - CAN bus driver for IFI CANFD controller
  • kvaser_usb - CAN driver for Kvaser CAN/USB devices
  • etas_es58x - Socket CAN driver for ETAS ES58X USB adapters
  • ucan - Driver for Theobroma Systems UCAN devices
  • peak_usb - CAN driver for PEAK-System USB adapters
  • kvaser_pciefd - CAN driver for Kvaser CAN/PCIe devices
  • kvaser_pci - Socket-CAN driver for KVASER PCAN PCI cards
  • f81601 - Fintek F81601 PCIE to 2 CANBUS adaptor driver
  • sja1000_isa - Socket-CAN driver for SJA1000 on the ISA bus
  • plx_pci - Socket-CAN driver for PLX90xx PCI-bridge cards with the SJA1000 chips
  • sja1000 - sja1000CAN netdevice driver
  • ems_pci - Socket-CAN driver for EMS CPC-PCI/PCIe/104P CAN cards
  • peak_pci - Socket-CAN driver for PEAK PCAN PCI family cards
  • sja1000_platform - Socket-CAN driver for SJA1000 on the platform bus
  • vxcan - Virtual CAN Tunnel
  • c_can_platform - Platform CAN bus driver for Bosch C_CAN controller
  • c_can - CAN bus driver for Bosch C_CAN controller
  • c_can_pci - PCI CAN bus driver for Bosch C_CAN/D_CAN controller
  • slcan - serial line CAN interface
  • can_dev - CAN device driver interface
  • vcan - virtual CAN interface
  • can-isotop - PF_CAN isotp 15765-2:2016 protocol
  • can-gw - PF_CAN netlink gateway
  • can-j1939 - PF_CAN SAE J1939
  • can-raw - PF_CAN raw protocol
  • can-bcm - PF_CAN broadcast manager protocol
  • can - Controller Area Network PF_CAN core

Raspberry Pi

The following Linux Kernel modules are available on the quickstart image for Raspberry Pi:

  • can - Controller Area Network PF_CAN core
  • vxcan - Virtual CAN Tunnel
  • can-dev - CAN device driver interface
  • can-bcm - PF_CAN broadcast manager protocol
  • can-gw - PF_CAN netlink gateway
  • can-raw - PF_CAN raw protocol
  • can-isotop - PF_CAN isotp 15765-2:2016 protocol
  • can-j1939 - PF_CAN SAE J1939
  • vcan - virtual CAN interface
  • slcan - serial line CAN interface
  • mcp251x - Microchip 251x/25625 CAN driver
  • mcp251xfd - Microchip 251xFD Family CAN controller driver
  • ems_usb - CAN driver for EMS Dr. Thomas Wuensche CAN/USB interfaces
  • gs_usb - Socket CAN device driver for Geschwister Schneider UG
  • peak_usb - CAN driver for PEAK-System USB adapters

2.5.2 - Transferring Files

Sharing a directory with the guest

When you want to copy files between the host and the guest, an easy way is to use an SFTP tunnel. With sshfs, you can mount a local directory to a remote directory via SSH.

Pre-Requisites

Installation of needed packages:

  • Run apt-get install sshfs on your host
  • Enable CORE_IMAGE_EXTRA_INSTALL += " openssh-sftp-server" in local.conf of your image (e.g. in the local_conf_header section in your kas file)
  • Verify SFTP connection working with sftp -P 2222 root@localhost

Transfering files from host to guest

When you want to copy files from the host to the guest, an easy way is to use an SFTP tunnel. With sshfs, you can mount a local directory to a remote directory via SSH.

  • Create a mount point on your host: mkdir remote
  • Open the SSH Filesystem tunnel: sshfs root@localhost:/ remote/ -p 2222
  • Check files: ls -al remote/ - you should see the root filesystem of the device now
  • You can now easily copy files: cp foo.txt remote/home/root/

Transfering files from guest to host

Note: The reverse direction, e.g. initiating an SSH tunnel from within the device to the host, is currently not supported by the installed software on the image.

2.6 - Running on Linux

To run the main components of the SDV EDGE stack on an existing Linux distribution (e.g. Debian, Ubuntu, Raspberry Pi OS), you need to install the following packages.

Please note that since this is not a full-system installation, but an additional installation, there are some differences compared to the usual Leda installation on Docker/QEMU/Devices using our Quickstart image:

  • The Self-Update use case is not used, as the distribution-specific channels apply. E.g. it does not make sense to use the Leda infrastructure to flash a full system image.
  • The configuration differs slightly and you need to put some more work into getting the examples to work out of the box. This may include different port numbers, different paths of volume mounts for containers etc.

Debian-based Linux distributions

Tested on x86_64 via Docker:

  • Debian 11
  • Debian 12
  • Ubuntu 20.04
  • Ubuntu 22.04
  • Ubuntu 23.10

Note: Ubuntu 18.04 is not supported, as the glibc is outdated.

Pre-Requisuites

The SDV stack requires the following packages to be present on the target system:

  • Mosquitto (adapt configuration, see below)

  • Data folders

    • Storage for Self Update Bundles: mkdir -p /data/selfupdates

    • Device Certificates Folder:

      # Required by Cloud Connector
      mkdir -p /data/var/certificates/
      touch /data/var/certificates/device.crt
      touch /data/var/certificates/device.key
      
  • systemd (Optional: You can also manually start the services)

  • D-Bus (Optional: This is for Self Update Agent to RAUC integration)

  • RAUC (Optional: Only for Self-Update Use Case or testing purposes)

Installation Steps

Note: The steps below are examples for x86 platform. If you deploy on ARM64 platform, adapt the filenames accordingly.

  1. Update repository and install dependencies:

    apt-get update
    apt-get -y install ca-certificates mosquitto wget
    
    # Optional:
    apt-get -y install dbus rauc
    
  2. Download the Debian package from the Eclipse Kanto release page

    wget "https://github.com/eclipse-kanto/kanto/releases/download/v0.1.0-M3/kanto_0.1.0-M3_linux_x86_64.deb"
    apt-get install -y ./kanto_0.1.0-M3_linux_x86_64.deb
    
    # Check if Kanto has been installed
    command -v container-management
    command -v kanto-cm
    systemctl status container-management
    

    Note: This will also install containerd.

  3. Download the Debian packages from the Eclipse Leda Utilities release page:

    wget "https://github.com/eclipse-leda/leda-utils/releases/download/v0.0.2/eclipse-leda-utils_0.0.2.0.00680_all.deb"
    apt-get install -y ./eclipse-leda-utils_0.0.2.0.00680_all.deb
    command -v sdv-health
    
    wget "https://github.com/eclipse-leda/leda-utils/releases/download/v0.0.2/eclipse-leda-kantui_0.0.2.0.00680_amd64.deb"
    apt-get install -y ./eclipse-leda-kantui_0.0.2.0.00680_amd64.deb
    command -v kantui
    
    wget "https://github.com/eclipse-leda/leda-utils/releases/download/v0.0.2/eclipse-leda-kanto-auto-deployer_0.0.2.0.00680_amd64.deb"
    apt-get install -y ./eclipse-leda-kanto-auto-deployer_0.0.2.0.00680_amd64.deb
    command -v kanto-auto-deployer
    
  4. Download the Debian package eclipse-leda-container-*.deb from the Eclipse Meta-Leda release page:

    wget "https://github.com/eclipse-leda/meta-leda/releases/download/0.1.0-M2/eclipse-leda-containers_0.1.0.2.0.422_all.deb"
    apt-get install -y ./eclipse-leda-containers_0.1.0.2.0.422_all.deb
    
  5. Run the kanto-auto-deployer to deploy the core components:

    kanto-auto-deployer /var/containers/manifests
    

    To install the example containers, run the following:

    kanto-auto-deployer /var/containers/manifests/examples
    

Configuration Hacks

  • Mosquitto must be configured to allow anonymous access and listen on the network interface available to the containers. The easiest (and least secure!) configuration would be:

    /etc/mosquitto/conf.d/public.conf:

    listener 1883 0.0.0.0
    allow_anonymous true
    

    Attention: Only apply this configuration on a device in a secured network, or adapt the configuration accordingly (e.g. specify internal IP address)

2.7 - Cheatsheet

This cheat sheet gives you an overview of common command line commands to interact with the tools available on the quickstart image.

General Commands

Category Task Command
General Overall info sdv-health
Show device info sdv-device-info
Device provisioning sdv-provision
Switch Keyboard layout loadkeys de
System System load htop
Disk free df -h -t ext4
Memory free free -h
Network Interfaces summary networkctl
Ethernet status networkctl status enp0s2
Routing table route
Active listeners netstat -l -n -t
Multicast for Some/IP route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0
Kanto-CM Show all containers kanto-cm list
User interface kantui
Service logs journalctl -f -l -t container-management
Auto deployments See /data/var/containers/manifests/
Development deployments See /data/var/containers/manifests_dev/
Restart a container kanto-cm restart -n <containername>
Manage config sdv-kanto-ctl
Shell in container sdv-ctr-exec <containerId> <command>
Add Private Registry sdv-kanto-ctl add-registry -h <host> -u <user> -p <pass>
ContainerD Show images ctr --address /data/run/containerd/containerd/containerd.sock --namespace=kanto-cm i ls
Import local archive ctr --address /data/run/containerd/containerd.sock --namespace=kanto-cm i import <docker.tar>
Prune containers nerdctl system prune --all
Mosquitto Show all messages mosquitto_sub -v -t '#' -h localhost
Send message mosquitto_pub -t '<target/topic>' -h localhost -m '{"foo":"bar"}'
Connectivity status mosquitto_rr --quiet -h localhost -t 'edge/thing/request' -e 'edge/thing/response' -m ''
RAUC Self Update Current boot status rauc status
Switch to other boot slot rauc status mark-active other
CAN-Bus CAN Dump candump -l any,0:0,#FFFFFFFF

Configuring NTP

A failed download of container images may be caused by out-of-sync clock, thus failing the TLS certificate validation. A hardware device without hardware clock (such as the Raspberry Pi) relies on network time. In some (corporate) networks, there might be rogue NTP servers and it might be necessary to override the NTP sources.

To reset NTP server to a public server, follow these steps:

# Check NTP clock sync
timedatectl timesync-status
# Add your NTP server
vi /etc/systemd/timesyncd.conf
# Restart container management
systemctl restart container-management
systemctl restart kanto-auto-deployer

Reset container deployment

When things go really wrong and the container runtime is unable deploy containers properly, it may be necessary to reset the internal state. This is achieved by stopping the container runtime(s) and deleting the /var/lib/container-management folder:

# Stop all container runtimes
systemctl stop container-management 
systemctl stop containerd

# Delete the persistence of container management
# Attention! Here be dragons
rm -rf /var/lib/container-management

# Restart the container runtimes
systemctl start containerd
systemctl start container-management

# Redeploy the containers
systemctl restart kanto-auto-deployer

Running custom ad-hoc containers

To install arbitrary containers, create the container using the kanto-cm command line tool. If it’s not a background service, but a cli tool, adding the --t --i options allows console access.

root@qemux86-64:~# kanto-cm remove --name python
root@qemux86-64:~# kanto-cm create --name python --t --i --privileged docker.io/library/python:3.8.16-slim-bullseye
bf9deca4-dbf1-4132-9ba7-e0f378bd34a7
root@qemux86-64:~# kanto-cm start --name python --a --i
Python 3.8.16 (default, Jan 24 2023, 00:19:05) 
[GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> quit()

Raspberry Pi Overlays

Edit /boot/config.txt and reboot:

# Disable to fix non-working standard Raspberry Pi 7" display
# dtoverlay=vc4-kms-v3d

# PiCAN 2
# dtoverlay=mcp2515-can0,oscillator=16000000,interrupt=25

# Waveshare RS485 CAN Hat
# dtoverlay=mcp2515-can0,oscillator=12000000,interrupt=25,spimaxfrequency=2000000

2.8 - Utilities

The quickstart image contains the following utilities. These utility scripts are meant to be convenience tools for users and developers. They help to experiment with the container deployment, device provisioning or vehicle data access.

  • sdv-health: Show SDV software components health status
  • kantui: A text user interface for kanto-cm to manage containers (start, stop, logs, redeploy all)
  • sdv-device-info: Show and update device information
  • sdv-provision: Generate device certificates and configuration of cloud connection
  • sdv-motd: Message-of-the-Day shown after login prompt
  • can-forward: Forwarding a CAN-bus network interface into a containerized Vehicle Application
  • kanto-auto-deployer: Automatically deploys containers on boot. Runs as a systemd service, and can also be invoked by a user directly.
  • sdv-ctr-exec: Execute arbitrary commands in existing containers
  • sdv-kanto-ctl: Manage the Kanto Container Management configuration via CLI
  • blueprint-selector: Deploy and fetch new SDV blueprints easily with an interactive CLI

Note: These scripts are not meant to be reused or called from production software. Their behaviour or command line syntax is not a stable API and should not be trusted for automation purposes. For details, please see leda-utils

2.8.1 - SDV Health

Health check

The sdv-health utility displays a status overview of some important dependencies and device configurations for the SDV edge stack. The sdv health utility can be configured using the sdv.conf configuration file.

Usage:

# sdv-health

Example output:

SDV Health Example Output

Version Information

The Leda image version and build time will be displayed at the top in the first category:

  • OS Release: Year and codename of the release version
  • Image Version: Name of the image and more specific version information, such as the git tag or commit id
  • Build timestamp in yyyMMddHHmmss notation

Note: The information is read from the system base file in /etc/os-release:

root@qemux86-64:~# cat /etc/os-release 
BUILD_ID="20230309083051"
DISTRO_CODENAME="Dracon"
ID=leda
IMAGE_VERSION="0.0.5-41-g82f2b12"
NAME="Eclipse Leda"
PRETTY_NAME="Eclipse Leda 2023 (Dracon)"
VERSION="2023 (Dracon)"
VERSION_CODENAME="Dracon"
VERSION_ID=0.0.5-41-g82f2b12

Bus networks

If available, vehicle bus network information, such as the status of the CAN-Bus, will be displayed iin its own category. This helps to quickly identify if there problems with the hardware connectivity for automotive bus networks.

Ports

The health utility checks the TCP ports of specific services. This helps to identify if these services are up and running and potentiallyconnectable via external network interfaces.

Services and Containers

The services category shows the status of required and optional containers. The required containers are supposed to be up and running for the SDV.EDGE stack to be correctly up and running. If any of these core components have a failed state, the functionality is impacted.

The optional containers are for additional features and for example applications. These containers may not be necessary for each use case and hence will be marked as a warning if they are not up and running. The overview still helps to identify which containers are working properly.

Errors, Warnings, Failed states

When there are errors or warnings related to the status of SDV related components, the health utility will print out these error states, and if available also a more detailed error message.

In the following example, the health utility helps the troubleshooting process:

  • The container runtime is properly started: “Kanto CM” is OK in the “SDV Ports” section and the “container-management” service is OK in the “SDV Services” section".
  • Some containers are in state “OK”, which means there is no general issue with the container runtime.
  • The cloud connector is in a “Stopped” state, which indicates that the user manually stopped the container by using “kanto-cm stop -n cloud-connector”.
  • The sua container is in a “Exited” state, which indicates the process exited with an error code.

SDV Health Example Errors

2.8.2 - KantUI

The KantoUI tool is a text-based user interface for conveniently managing containers in the Kanto Container Management. It supports simple navigation using keyboard and mouse to select a specific container. Commands to start, stop, remove and re-deploy containers are available along with a functionality to retrieve the application logs of a selected container.

Kanto User Interface

Usage:

kantui

Example output:

KantoUI

Command Line Options

Print command line help:

root@qemux86-64:~# kantui --help
kantui 0.2.0
A TUI for Kanto CM that allows easier management of deployed containers. Requires root.

USAGE:
    kantui [OPTIONS]

OPTIONS:
    -c, --config-file-path <CONFIG_FILE_PATH>
            Set a custom path for the kantui configuration file [default:
            /etc/kantui/kantui_conf.toml]

    -h, --help
            Print help information

    -V, --version
            Print version information

Note: All config values can be overridden through env variables prefixed with KANTUI_,
e.g. KANTUI_STOP_TIMEOUT=5 overrides the timeout before SIGKILL is sent to be 5 seconds.

Keyboard commands

  • Arrow keys Up and Down to select a container
  • Arrow keys Left and Right to select a column
  • Enter to change the sort ordering of the currently selected column
  • S to start the selected container which is currently not running
  • P to stop the selected container
  • R to remove a container
  • L to show the log output of a container
  • D to redeploy an existing container (rereads deployment descriptor)
  • Q to quit kantui

Note: The mouse can be used to select ui items when holding the Shift key.

Starting, Stopping, Removing containers

To use the lifecycle commands on a container:

  1. Select a container by using the mouse or the arrow keys.
  2. The selected container is highlighted.
  3. Press one of the lifecycle commands, e.g. s, p or r
  4. Wait for the value in the State column to change, before issueing the next command.

Note: When using the lifecycle commands for containers (Start, Stop, Remove), it may take a few seconds before the UI is updated with the status changes. The amount of time before a container is forcefully killed is determined by the stop_timeout configuration option.

Show container Logs

To view the container’s log output:

  1. Select a container by using the mouse or the arrow keys.
  2. Press the L key
  3. Log output will be displayed (tail, oldest messages first)
  4. Use the arrow keys Up and Down or drag the scrollbar using your mouse to scroll through the log
  5. Close the Log viewer by pressing Enter or clicking on the OK button

Note: The log output is not followed automatically. Close the dialog and reopen to see new output.

Redeploying containers

To redeploy a container, e.g. when a deployment descriptor has changed on disk:

  1. Select a container by using the mouse or the arrow keys.
  2. Press the P key to stop the container
  3. Press the R key to remove the container
  4. Press the D key to invoke the Kanto Auto Deployer, which will redeploy the missing containers

Note: Only containers managed by Kanto Auto Deployer will be redeployed.

Column Sorting

To sort a column:

  1. Select the column using the Left and Right arrow keys
  2. Press Enter to activate sorting
  3. Press Enter again on a sorted column to invert sort order (Ascending -> Descending -> Ascending)

Note: The selected sort order is not persisted and will reset to the default on restart: By ID, ascending

Configuration File

The default location of the configuration file is /etc/kantui/kantui_conf.toml:

# General Configuration Options
socket_path = "/run/container-management/container-management.sock" # Path to kanto-cm unix socket
stop_timeout = 5 # timeout (integer) in seconds before a SIGKILL is sent after a SIGTERM

[keyconfig]
start_btn_name = "[S]tart"
start_kbd_key = "s"

stop_btn_name = "Sto[P]"
stop_kbd_key = "p"

remove_btn_name = "[R]emove"
remove_kbd_key = "r"

logs_btn_name = "[L]ogs"
logs_kbd_key = "l"

quit_btn_name = "[Q]uit"
quit_kbd_key = "q"

redeploy_btn_name = "Re[D]eploy"
redeploy_kbd_key = "d"
# Includes a shell lexer so anything that would be a valid shell command can be used
# No pipes/redirects allowed.
# N.B.: Command inherits kantui's privileges (root)
redeploy_command = "systemctl restart kanto-auto-deployer.service"

2.8.3 - SDV Device Info

Displays the current device configuration, such as Device ID.

Note: Requires the Cloud Connector component to be configured and running.

Usage:

sdv-device-info

Eclipse Leda Device Info Example Output

Usage

Synposis: ./sdv-device-info [options] [command]

Full help:

root@qemux86-64:~# sdv-device-info --help
sdv-device-info v0.2
Usage: /usr/bin/sdv-device-info [options] [command]
Show SDV device configuration information
Example: /usr/bin/sdv-device-info show

Commands:
 show                 : Display configuration (default command)
 help                 : This message
 env                  : Format output for use in scripts

Options:
 --ansi | -a      : Don't use colored output.
 --norestart | -n : Do not automatically restart services
 --verbose | -v   : Enable verbose mode.
 --help | -h      : This message.

Use in scripts

To use device information on other scripts, it may be useful to source the device information variables into the current environment variable context:

Synposis: source ./sdv-device-info env

Example:

$ source ./sdv-device-info env
$ echo $DEVICE_ID
exampledevice1

2.8.4 - SDV Provision

The provisioning helper script can be used to manually perform a device provisioning with a cloud backend.

It is meant as a convenient tool for developers, who wish to connect their device to a selfmanaged cloud backend directly. In a production environment, the device provisioning functionality is implemented either by the Cloud Connector component.

The provisioning script currently supports the following backend and authentication options:

  • Azure IoT Hub
    • Connection String
    • Device Certificates
  • Azure IoT Device Provisioning Service
    • Device Certificates

Usage

The sdv-provision script is interactive and asks for the type of backend and authentication option:

root@qemux86-64:~# sdv-provision 
Checking Eclipse Leda Device Provisioning configuration...
- Certificates directory exists
Checking Device ID
- Based on network device: eth0
- Device ID: 52-54-21-4c-f9-5a
Checking whether either IdScope or ConnectionString is configured
 - Neither Id Scope file nor ConnectionString found, needs manual configuration
Do you want to use the global Azure IoT Device Provisioning Service (DPS) by using an Id Scope, or do you want to use a direct connection to a specific Azure IoT Hub using a Connection String?
d) Azure IoT Device Provisioning Service (DPS) with Id Scope
h) Azure IoT Hub with Connection String
Choose:d
Please enter your Id Scope of the Azure IoT Device Provisioning Service:example
Recreating the Cloud Connector container...
Checking device certificates
- All device certificates are present
- Primary device certificate: /data/var/certificates/device.crt
- Primary device private key: /data/var/certificates/device.key
- Secondary device certificate: /data/var/certificates/device2.crt
- Secondary device private key: /data/var/certificates/device2.key
Fingerprints (add these to the Azure IoT Hub Device)
- Primary thumbprint: 1B172ED3D06F4E25AFFEF675ADCE519457FFFFFF
- Secondary thumbprint: B6CD5EACE96E9D0448BCB0BAED2DEE87AFFFFFFF

Once a configuration has been selected, the script will:

  • Generate a random Device Id (based on physical network address)
  • Store the Device Id in /etc/deviceid
  • Generate a primary self-signed device certificate pair
  • Generate a secondary self-signed device certificate pair
  • Store the certificates in /data/var/certificates/
  • Reconfigure the container descriptor in /data/var/containers/manifests_dev/cloudconnector.json
  • Restarting the Cloud Connector container
  • Print the key fingerprints, used for onboarding the device in Azure IoT Device Provisioning Service

Reconfiguration

Note: Re-running the script will only print the existing configuration.

To reconfigure the device and use different options, perform the following steps:

  1. Delete the generated files

    rm /data/var/certificates/azure.idscope
    rm /data/var/certificates/azure.connectionstring
    rm /data/var/certificates/device*.crt
    rm /data/var/certificates/device*.key
    
  2. Rerun the script

    sdv-provision
    

2.8.5 - SDV MotD

The sdv-motd script provides an alternative motd profile, which displays some additional information after login.

The script does not have any command line options.

Example output:

Eclipse Leda Message Of The Day

2.8.6 - CAN Forward

The can-forward help script can be used to forward an existing CAN-Bus interface on the host system to a container process.

Note: Warning! The script does not yet support Kanto (or containerd) as a container runtime. It has been implemented for k3s.

Usage

root@qemux86-64:~# can-forward --help

Usage:  /usr/bin/can-forward {-h} {-p PID} {-c container} <hw_can>

  hw_can          Host CAN hw interface to forward. Default: can0
  -c container    Attemmpt to get netns PID from a running container: (docker, ctr). Default: seat_service
  -p PID          Use provided PID for transferring vxcan interface (e.g.: docker inspect -f '{{ .State.Pid }}' container)
  -h              Prints this message

The script performs the following steps:

  • Find the process ID of the target container process
  • Check and modprobe vxcan
  • Check and modprobe can-gw
  • Create a new virtual CAN interface (vxcanX)
  • Create a new virtual CAN interface (vxcanX+1)
  • Link both interfaces together
  • Move the second interface (vxcanX+1) into the namespace of the target container
  • Set up a bi-directional CAN-Bus packet forwarding between both interfaces using cangw

2.8.7 - Kanto Auto Deployer (KAD)

Automatically deploys containers to the Kanto Container Management based on deployment descriptors from a given path. All deployment descriptors in the manifests folder will be deployed (created and started) on startup of the service. The directory will then be monitored for creation of/changes to manifests and those changes will be redeployed.

Usage

Usage:

$ kanto-auto-deployer --help
kanto-auto-deployer 0.2.0
Automated deployment of Kanto Container Management Manifests

USAGE:
    kanto-auto-deployer [OPTIONS] [MANIFESTS_PATH]

ARGS:
    <MANIFESTS_PATH>    Set the path to the directory containing the manifests [default: .]

OPTIONS:
    -d, --daemon                   Run as a daemon that continuously monitors the provided path for
                                   changes
    -h, --help                     Print help information
    -s, --socket-cm <SOCKET_CM>    Set the path to the Kanto Container Management API socket
                                   [default: /run/container-management/container-management.sock]
    -V, --version                  Print version information

Example:

# Use container manifests from current working directory
root@qemux86-64:/data/var/containers/manifests# kanto-auto-deployer 
[2023-04-18T10:27:21Z INFO  kanto_auto_deployer] Running initial deployment of "/data/var/containers/manifests"
[2023-04-18T10:27:21Z INFO  kanto_auto_deployer] Reading manifests from [/data/var/containers/manifests]
[2023-04-18T10:27:21Z WARN  kanto_auto_deployer::manifest_parser] Failed to load manifest directly. Will attempt auto-conversion from init-dir format.
[2023-04-18T10:27:21Z INFO  kanto_auto_deployer] Already exists [cloudconnector]
[2023-04-18T10:27:21Z WARN  kanto_auto_deployer::manifest_parser] Failed to load manifest directly. Will attempt auto-conversion from init-dir format.
[2023-04-18T10:27:21Z INFO  kanto_auto_deployer] Already exists [databroker]

# Use container manifests from specified directory
root@qemux86-64:~# kanto-auto-deployer /data/var/containers/manifests/
[2023-04-18T10:27:44Z INFO  kanto_auto_deployer] Running initial deployment of "/data/var/containers/manifests"
[2023-04-18T10:27:44Z INFO  kanto_auto_deployer] Reading manifests from [/data/var/containers/manifests]
[2023-04-18T10:27:44Z WARN  kanto_auto_deployer::manifest_parser] Failed to load manifest directly. Will attempt auto-conversion from init-dir format.
[2023-04-18T10:27:44Z INFO  kanto_auto_deployer] Already exists [cloudconnector]
[2023-04-18T10:27:44Z WARN  kanto_auto_deployer::manifest_parser] Failed to load manifest directly. Will attempt auto-conversion from init-dir format.
[2023-04-18T10:27:44Z INFO  kanto_auto_deployer] Already exists [databroker]

Nоte: The warnings from the manifest_parser module are normal and expected when the manifest is in the Container Management Manifests Format

Usage as systemd service

In the Leda quickstart images, kanto-auto-deployer is installed as a systemd service.

Note the service uses the --daemon flag that asks KAD to continuously monitor the specified directory (see last line of logs).

The service unit configuration file is located in /lib/systemd/system/kanto-auto-deployer.service:

[Unit]
Description=Kanto Auto Deployer
After=network-online.target container-management.service
Wants=network-online.target container-management.service
Requires=container-management.service

[Install]
WantedBy=multi-user.target

[Service]
Restart=on-failure
RestartSec=5s
ExecStart=/usr/bin/kanto-auto-deployer /data/var/containers/manifests --daemon

Example output:

root@qemux86-64:/lib/systemd/system# systemctl status kanto-auto-deployer.service 
* kanto-auto-deployer.service - Kanto Auto Deployer
     Loaded: loaded (/lib/systemd/system/kanto-auto-deployer.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2023-04-18 10:22:10 UTC; 3min 55s ago
   Main PID: 525 (kanto-auto-depl)
      Tasks: 10 (limit: 4708)
     Memory: 1.4M
     CGroup: /system.slice/kanto-auto-deployer.service
             `- 525 /usr/bin/kanto-auto-deployer /data/var/containers/manifests --daemon

Apr 18 10:22:48 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:22:48Z INFO  kanto_auto_deployer] Creating [sua]
Apr 18 10:23:04 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:04Z INFO  kanto_auto_deployer] Created [sua]
Apr 18 10:23:04 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:04Z INFO  kanto_auto_deployer] Starting [sua]
Apr 18 10:23:05 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:05Z INFO  kanto_auto_deployer] Started [sua]
Apr 18 10:23:05 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:05Z WARN  kanto_auto_deployer::manifest_parser] Failed to load manifest directly. Will attempt auto-conversion from init-dir format.
Apr 18 10:23:05 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:05Z INFO  kanto_auto_deployer] Creating [vum]
Apr 18 10:23:10 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:10Z INFO  kanto_auto_deployer] Created [vum]
Apr 18 10:23:10 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:10Z INFO  kanto_auto_deployer] Starting [vum]
Apr 18 10:23:11 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:11Z INFO  kanto_auto_deployer] Started [vum]
Apr 18 10:23:11 qemux86-64 kanto-auto-deployer[525]: [2023-04-18T10:23:11Z INFO  kanto_auto_deployer] Running in daemon mode. Continuously monitoring "/data/var/containers/manifests"

2.8.8 - SDV Container Exec

The sdv-ctr-exec wrapper allows to execute arbitrary user commands in existing containers. Kanto Container Management cli tool (kanto-cm) only allows to manage the lifecycle of a container, but does not allow to specify or override the entrypoint or command definitions of an existing container. The ctr command line tool of containerd allows the execution of additional tasks in a running container.

Usage

As a convenient tool, sdv-ctr-exec allows the simple execution of arbitrary commands inside of containers. This is especially useful for non-service-containers, or containers which have additional binaries (e.g. cli tools) embedded.

Usage:

root@qemux86-64:~# sdv-ctr-exec 
/usr/bin/sdv-ctr-exec -h to print this message

Usage:
/usr/bin/sdv-ctr-exec <container-id> <command>
or
/usr/bin/sdv-ctr-exec -n <container-name> <command>

Example:

# Executing a containerized cli tool using sdv-ctr-exec
kanto-cm create --i --t --network=host --name=kuksa-client ghcr.io/eclipse/kuksa.val/kuksa-client:master
kanto-cm start --name=kuksa-client
sdv-ctr-exec -n kuksa-client /kuksa-client/bin/kuksa-client --port 30555 --protocol grpc --insecure

Alternatives

containerd: ctr

The above commands are equivalent to the following commands:

# Executing a containerized cli tool using ctr
ctr --namespace kanto-cm image pull ghcr.io/eclipse/kuksa.val/kuksa-client:master
ctr --namespace kanto-cm container create --net-host --tty ghcr.io/eclipse/kuksa.val/kuksa-client:master kuksa-client
ctr --namespace kanto-cm tasks start --detach kuksa-client
ctr --namespace kanto-cm tasks exec --tty --exec-id sometask kuksa-client /kuksa-client/bin/kuksa-client --port 30555 --protocol grpc --insecure

containerd: nerdctl

Note: nerdctl is currently not installed on the Leda Quickstart images.

containerd: ctr and mounting

To execute a binary natively (outside of a containerized environment), the container image may be mounted to the host filesystem using the ctr snapshots mount commands.

This approach only works if the binary is compatible with the host environment (dependencies, libraries etc.).

$CONTAINER_IMAGE="ghcr.io/my-org/my-project/my-container"
ctr --namespace kanto-cm image pull $CONTAINER_IMAGE
ctr --namespace kanto-cm container create --net-host --tty $CONTAINER_IMAGE my-container
mkdir my-container
ctr --namespace=kanto-cm snapshots mount my-container my-container | $SHELL
cd my-container
./bin/my-application --help

2.8.9 - SDV Kanto-Ctl

Manage the Kanto Container Management configuration via CLI.

Note: Requires jq to be installed.

Features:

  • Add and remove container registries (for authentication purposes)
  • Set primitive values in configuration
  • Restart container-management.service on configuration changes
  • Automatically back up configuration file
  • Display changes to user

Eclipse Leda Kanto Container Manager Configuration utility

Usage

Synposis: ./sdv-kanto-ctl <command> [<options>]

Full help:

$ ./sdv-kanto-ctl --help
Eclipse Kanto Container Manager Configuration Utility
See https://eclipse.dev/kanto/docs/references/containers/container-manager-config/
Usage: ./sdv-kanto-ctl <command> {options}
Commands:
        add-registry -h <hostname> -u <username> -p <password>
                Adds or replaces a container registry authentication configuration
                -h or --hostname: Configure the hostname of the container registry (e.g. hub.docker.io, ghcr.io, ...)
                -u or --username: Configure the username
                -p or --password: Configure the password
        remove-registry -h <hostname>
                Removes the specified container registry
                -h or --hostname: The hostname of the container registry
        remove-all-registries
                Removes all configured container registries
        list-registries
                Prints all configured container registries
        show-config
                Print the container management configuration
        set <key> <value>
                Set a primitive configuration value. Key in JSON Dot-Notation
                Examples: ./sdv-kanto-ctl set containers.registry_configurations.MyRegistry.credentials.password foobar
                          ./sdv-kanto-ctl set things.enable true
Options:
        --no-reload : Do not reload the configuration and restart the container-management service automatically
        --ansi : Don't use colored output.
        --verbose | -v : Enable verbose mode.
        --help : This message.

Example: Private Container Registries

To be able to pull container images, the container runtime needs access to the container registry. Some container registries require authentication. The Kanto Container Manager can be configured to use credentials when accessing remote container registries.

In the Leda images, the sdv-kanto-ctl tools allows to easily add authentication to the container manager configuration:

sdv-kanto-ctl add-registry -h <registryhostname> -u <your_username> -p <your_password>

For example, to access container images from GitHub Packages in a private repository, you need a GitHub Personal Access Token (PAT) with the read: packages scope. Then, add the repository as shown below:

sdv-kanto-ctl add-registry -h ghcr.io -u github -p <Your_GitHub_PersonalAccessToken>

sdv-kanto-ctl will make the necessary modifications to /etc/container-management/config.json and restarts the container-management.service systemd unit, so that the changes take effect. You may need to recreate or restart the container if a previous pull failed.

Please see the Eclipse Kanto Container Manager Configuration reference for details.

Example: Enabling Things management

Enable the container manager digital twin representation.

sdv-kanto-ctl set things.enable true

Example: Container Stop Timeout

Kanto waits for a timeout before forcefully stopping a container. The default is 30 seconds in Kanto, and 10 seconds in the Leda quickstart image.

To change this behavior at runtime:

sdv-kanto-ctl set manager.default_ctrs_stop_timeout 2

2.8.10 - Blueprint Selector

A Rust application that reads all blueprint files in a directory and provides the user with an interactive (supports filtering) menu to select the one to be deployed on the edge device via MQTT. If no directory is provided the default one on a Leda Quickstart Image is: /data/var/containers/blueprints.

Screenshot

The “blueprint” files are desired state messages, that have the extension “.blueprint.json” (configurable) and an additional metadata header (required):

{
  "blueprintMetadata": {
    "name": "<NAME>",
    "description": "<Short Description>"
  },
  "activityId": "correlation-id",
  "timestamp": 1235466
  "payload": {} // This is the desired state message
}

The metadata header will be used to construct the list of options presented to the user. You can find example blueprints under the example_blueprints directory in the leda-utils repository.

The selected blueprint is then published as an MQTT message on the vehicleupdate/desiredstate topic.

CLI options

To get all available configuration options use the --help/-h flag:

A user-friendly tool to select and deploy SDV blueprints

Usage: blueprint-selector [OPTIONS]

Options:
  -d, --blueprints-dir <BLUEPRINTS_DIR>
          The directory containing the SDV blueprints [default: /data/var/containers/blueprints]
  -f, --fetch-blueprints
          Start in fetch mode (presents a menu to fetch new/updated blueprints) from a remote repository
  -e, --blueprints-ext <BLUEPRINT_EXTENSION>
          Extension to use when iterating over the files in the blueprints directory [default: .blueprint.json]
      --mqtt-broker-host <HOST>
          Hostname/IP to the MQTT broker where the desired state message would be posted [default: 127.0.0.1]
      --mqtt-broker-port <PORT>
          Port for the MQTT broker [default: 1883]
      --mqtt-topic <TOPIC>
          Topic on which to publish the blueprint desired state message [default: vehicleupdate/desiredstate]
  -h, --help
          Print help
  -V, --version
          Print version

Normal mode

To run in normal mode use:

blueprint-selector

or if you’d like to provide a directory different from the default one, use:

blueprint-selector -d </path/to/dir>

Fetch mode

When starting the blueprint-selector with the -f/--fetch-blueprints flag, you will be presented with a selection of different fetchers that allow you to download/update blueprints directly in the directory specified with the -d/--blueprints-dir flag (or in the default directory if not specified). For example:

  blueprint-selector -fd </path/to/dir>

Selection

When you choose a fetcher, you will be asked for an URI and blueprint-selector will attempt to fetch the blueprints inside the directory specified by -d.

After providing a URI, pressing Enter, and a successful fetch, you will be brought back to the usual selector menu, this time including all successfully fetched manifests.

Success

2.9 - Wifi Configuration

BSP packages for emulated WiFi devices (QEMU) and hardware device drivers are provided in meta-leda for supported hardware. They usually do not require extra configuration.

For a guide on how to connect to a wireless network check the Connecting to Wi-Fi networks page.

Raspberry Pi 4B 64

The required kernel modules and binary blobs are provided with the sdv-wifi-kernel-config.inc config file and the packagegroup-sdv-rpi4wifi packagegroup. These are included in sdv-image-full.bb and sdv-image-minimal.bb by default.

If you, however, decide to define your own custom image based on Custom Distros, you would have to make sure the packagegroup is installed to enable WiFi connectivity.

QEMU

QEMU images provide the kernel modules necessary to set-up a virtual wlan interface and connect it to a virtual wifi network. This can be useful in various testing scenarios.

To create and link a virtual WiFi interface to eth0, boot your QEMU image and run:

$ ip link add link eth0 name wlan0 type virt_wifi

The SSID of the virtual network you can connect to is VirtWifi.

Note: Leda Quickstart QEMU images set the name of the default virtual ethernet interface to eth0 through kernel CMDLINE configurations (net.ifnames=0 biosdevname=0). If you are building a custom image with a different kernel CMDLINE replace eth0 with the name of your virtual interface (check ifconfig).

2.9.1 - Connecting to Wi-Fi networks

Here we will describe the basic steps on how to identify and connect to a WiFi network in interactive or headless mode.

Initial steps (identifying wlan interfaces)

Start by running:

$ ip a
 ...
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state DOWN group default qlen 1000
    link/ether <MAC> brd ff:ff:ff:ff:ff:ff
...

Note: Usually the name of the interface would be wlan0. It might however follow the newer “predictable interface names” standart. Then the interface name would start with wl* with the remaining characters identifying a physical bus/chip/number/etc corresponding to the interface. For simplicity we will wlan0 in all examples below.

Most likely your wlan interface would be in the state DOWN. To bring it up:

$ ip link set wlan0 up

Scanning for wireless networks

You can scan for wireless networks using either iw or wpa_cli.

$ iw wlan0 scan

Note: The output of this command can be quite verbose. You can grep for SSID to find the SSIDs of the networks around you.

$ wpa_cli scan && wpa_cli scan_results

The output of wpa_cli is cleaner and more readable so it is recommended to use that.

Connecting to a network

Once you have identified the SSID of your network you can connect to it by ussing the following commands:

$ wpa_passphrase <SSID> <Passphrase> >> /etc/wpa_supplicant.conf
$ systemctl restart wpa

You should now be connected to the wireless network. To confirm that, you can once again use ip a to check that wlan0 has been configured with an IP.

This configuration shall be remembered from now on and your interface will try to connect automaticatically to that network whenever it is available.

Headless Wi-Fi configuration

Similarly to the Raspbian, meta-leda provides a mechanism for headless configuration of Wi-Fi credentials for your device (Headless Raspberry Pi Setup).

To use this feature you have to prepapre your wpa_supplicant.conf ahead of time (check the reference above):

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
update_config=1

network={
        key_mgmt=NONE
}
network={
    ssid="<YOUR NETWORK NAME>"
    psk="<YOUR NETWORK PASSWORD>"
    key_mgmt=WPA-PSK
}

IMPORTANT: It is recommended that if you are creating this configuration file on Windows to use an editor such as Notepad++ that can save files using the “Unix Line endings” (DOS vs. Unix Line Endings), or run it through a tool such as dos2unix that can convert between the two file formats. Otherwise wpa_supplicant.conf might not be read properly in the Linux image.

Once you have your wpa_supplicant.conf put your SD-card in your Desktop machine and place the configuration file in the root of the BOOT partion.

When you boot your device it should now automatically connect to your Wi-Fi network.

2.10 - GPS Connectivity

GPSD

Leda Quickstart Images provide (within meta-leda) recipes for the integration and setup of GPSD. GPSD is a service daemon that monitors one or more GPSes or AIS receivers attached to a host computer through serial or USB ports, making all data on the location/course/velocity of the sensors available to be queried on TCP port 2947 of the host computer. To find out more about GPSD, check out its official documentation.

For easier interaction and debugging gpsd client utilities such as installed gpsfake, gpspipe, etc. are installed.

Service

GPSD is installed on Leda Quickstart Images as a service. To check its status and/or logs you can use the following two commands:

root@leda-525400123502:~# systemctl status gpsd.service
* gpsd.service - GPS (Global Positioning System) Daemon
     Loaded: loaded (/lib/systemd/system/gpsd.service; disabled; vendor preset: disabled)
     Active: active (running) since Mon 2023-10-02 11:19:54 UTC; 41min ago
     ...

and the socket:

root@leda-525400123502:~# systemctl status gpsd.socket
* gpsd.socket - GPS (Global Positioning System) Daemon Sockets
     Loaded: loaded (/lib/systemd/system/gpsd.socket; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2023-10-02 11:19:30 UTC; 42min ago
    ...

With the location of the default config file being:

/etc/default/gpsd.default

By default, the GPSD service on Leda is configured to automatically discover USB devices (plug-and-play). In some cases, a system reboot might be required after plugging the USB GPS device.

Kuksa.val FeederGPS

The Kuksa GPS Feeder consumes gpsd as a data source and pushes location data to the kuksa.val server (databroker). It is installed as a pre-configured container on Leda Images through the feedergps.json container manifest. The container has an internal gpsd server (on port 2948) that connects to the host’s gpsd instance (on port 2947). With the provided container manifest feedergps should be plug-and-play.

Using pre-recorded GPS traces with gpsfake

Recording NMEA traces

It sometimes might be useful to mock gps services when testing, especially on QEMU virtual machines where emulated USB GPS hardware is not available. Pre-recorded traces should be in the NMEA-format.

To record a GPS trace in the NMEA format, on a device with physical GPS hardware, gpsd, and gpsd-client utilities installed, run:

gpspipe -R > gps_log.nmea

A sample NEMA file that can be used for testing is provided in the kuksa.val.feeders repository - simplelog_example.nmea.

Feeding NMEA traces to feedergps

Since the running gpsd service will interfere with the following steps, make sure to stop it first by running:

systemctl stop gpsd.service
systemctl stop gpsd.socket

To start gpsfake on port 2946 with gps_log.nmea as an input, either in the background (by adding & at the end of the shell line) or in a separate shell session run:

root@leda-525400123502:~# gpsfake -P 2946 gps_log.nmea
/usr/bin/gpsfake:21: DeprecationWarning: The distutils package is deprecated and slated for removal in Python 3.12. Use setuptools or check PEP 632 for potential alternatives
  from distutils import spawn
Processing gps_log.nmea
gpsfake: log cycle of gps_log.nmea begins.

Note: you can safely ignore the distutils warning.

Then, run a foreground instance of gpsd that reads from gpsfake on port 2946 on the loopback interface only and forwards the traffic on port 2947 for all interfaces:

gpsd -GNS 2947 gpsd://127.0.0.1:2946

These extra steps are needed as feedergps requires the gpsd server on port 2947 to be available on the kanto-cm0 bridge, as it’s running as a container and gpsfake cannot be configured to listen on an interface different from the loopback.

Restart feedergps:

kanto-cm stop -n feedergps
kanto-cm start -n feedergps

Known issues

Sometimes the feedergps container is started before the databroker and/or gpsd which leads to the container not being able to connect to either of those services. In such cases, after you’ve made sure the databroker and gpsd are up and running, restart feedergps with:

kanto-cm stop -n feedergps
kanto-cm start -n feedergps

3 - Device Provisioning

The device needs to be configured before it can make a connection to the cloud.

The following initial configuration steps are required:

  • Create a device in the cloud backend, such as Azure IoT Hub
  • Configure authentication on device
  • Configure credentials for accessing private container registries

3.1 - Manual Provisioning

Follow these steps to do a manual device provisioning:

  • Generate the device certificate (eg using openssl) and sign it with your CA.
  • Log in to Azure Portal, Go to Azure Iot Hub and create a new device
  • Select the proper authentication type, e.g. X.509 Self-signed or X.509 CA Signed
  • Copy the device certificate (cert file and key file) to the device to /data/var/certificate
  • Restart cloud connector service or container.

Create a device in Azure IoT Hub

For the device to be connectable, it needs to be known to the cloud service first. In these steps, we will create a new device identity by using Azure IoT Hub.

Pre-Requisites:

  • Virtual device must already be started with runqemu ... or leda

    Note: For Raspberry Pi, please follow the manual steps below and adapt the SSH connection options to the IP of your Raspbery Pi.

  • The virtual device needs to be remotely accessible via ssh port 2222 on the host’s localhost (Qemu port forwarding in userspace) or via ssh port 22 on the IP address 192.168.7.2 (Qemu virtual networking using TAP network interface)

  • The container runtime needs to have started successfully, check with sdv-health

  • A Device has been created in Azure IoT Hub

    Note: Do NOT create an “edge” device.

Configure authentication on device

For the proper device authentication, the device management backend authority needs to issue a device-specific certificate and sign it. This is a complex process and subject to the specific situation.

For the Leda quickstart images, the software configuration is prepared with dummy certificates which need to be replaced.

ATTENTION: The Leda example device certificates are public and insecure, they only serve demonstration purposes. You need to replace the intermediate certificates and device certificates with your own.

  • Generate a device certificate using openssl
  • Sign it with your intermediate CA certificate
  • Put it into /data/var/certificate/
  • Restart the cloud connector service or container: systemctl restart cloud-connector or kanto-cm stop -n cloudconnector --force; kanto-cm start -n cloudconnector

When finished, continue with

Private container registries

Please refer to the Container Registries on how to configure private container registries.

3.2 - Provisioning with sdv-provision

Meta-leda and the Leda-quickstart image provide a utility sdv-provision that simplifies the device provisioning procedure.

Connecting to the device

Since the procedure includes copying and pasting device IDs, it is recommended to connect to the device over a ssh connection. sdv-motd provides an easy way to find your device’s ip. More information on connecting via ssh can be found here.

Provisioning via a connection string

Device-side

  1. After connecting via ssh run sdv-provision.

    Example output:

    root@qemux86-64:~# sdv-provision
    Checking Eclipse Leda Device Provisioning configuration...
    - Certificates directory exists
    Checking Device ID
    - Based on network device: eth0
    - File does not exist, creating: /etc/deviceid
    - Device ID: XX-XX-XX-XX-XX-XX
    Checking whether either IdScope or ConnectionString is configured
    - Neither Id Scope file nor ConnectionString found, needs manual configuration
    Do you want to use the global Azure IoT Device Provisioning Service (DPS) by using an Id Scope, or do you want to use a direct connection to a specific Azure IoT Hub using a Connection String?
    d) Azure IoT Device Provisioning Service (DPS) with Id Scope
    h) Azure IoT Hub with Connection String
    Choose:
    
  2. Note the generated Device ID (XX-XX-XX-XX-XX-XX).

  3. Type h /Azure IoT Hub with Connection String/ and press Enter.

  4. Paste your Azure IoT Hub Connection String: HostName=<IoT Hub in Azure>.azure-devices.net;DeviceId=<XX-XX-XX-XX-XX-XX> and press enter. Where <IoT Hub in Azure> is your Azure IoT Hub name.

Azure Portal

  1. Go to https://portal.azure.com/ and to your Azure IoT Hub named <IoT Hub in Azure>.
  2. Choose Devices -> Add Device.
  3. Enter the Device ID XX-XX-XX-XX-XX-XX generated on the previous step as Device ID.
  4. Pick X.509 Self-Signed and paste the two thumbprints generated by sdv-provision.
  5. Save.

Device-Side

After all of the above steps have been completed, connect back to your device and restart the cloudconnector container by running:

kanto-cm stop -n cloudconnector --force
kanto-cm start -n cloudconnector

Or alternatively use:

$ kantui

And restart the container from the TUI.

3.3 - Vehicle Update Manager

The Vehicle Update Manager delegates two different types of updates:

  1. The Desired State on the container layer
  2. The Self Update on operating system layer

Vehicle Update Manager Architecture Overview

Desired State

The Desired State is applied at runtime on the container layer.

This type of update mechanism can update vehicle applications, vehicle services and other containers together with configuration resources or data files at runtime. If the applications support it, the rollout can also use high-availability strategies, such as rolling deployments. You can find out more about more about the Container Update Agent here.

Self Update

The Self Update is applied on reboot of the device only.

This type of update mechanism is used for system-level updates which require the operating system to be rebooted to take effect. You can find out more about the Self Update Agent in the tutorial.

3.3.1 - Configuration

Config file

The default location for the VUM service on the Leda Distro image can be found at /etc/update-manager/config.json. The location of the config file is specified with the --cfg-file [PATH] flag when starting the binary.

Minimal configuration

A minimal configuration (that is used by the Leda Distro) is the following:

{
    "log": {
      "logFile": "/var/log/update-manager/update-manager.log"
    },
    "domain": "vehicle",
    "agents": {
        "containers": {
            "name": "containers",
            "rebootRequired": false,
            "readTimeout": "30s"
        },
        "self-update": {
            "name": "self-update",
            "rebootRequired": true,
            "readTimeout": "30s"
        }
    },
    "thingsEnabled": false
}

Where:

  • “domain”: specifies the prefix for the MQTT topic, e.g. in this case it’s set to vehicle, so all VUM related topic are prefixed with vehicleupdate/[TOPIC]
  • “agents”: configures the update agents that would be available to VUM. Here the “readTimeout” key specifies how long should VUM wait for a response from the configured agent.
  • “thingsEnabled”: whether VUM should use the Kanto Things API for communication or not.

Full configuration

An example configuration file for VUM with all available options is the following one:

{
  "log": {
    "logFile": "log/update-manager.log",
    "logLevel": "ERROR",
    "logFileSize": 3,
    "logFileCount": 6,
    "logFileMaxAge": 29
  },
  "connection": {
    "broker":"www",
    "keepAlive": 500,
    "disconnectTimeout": 500,
    "username":"username",
    "password":"pass",
    "connectTimeout": 500,
    "acknowledgeTimeout": 500,
    "subscribeTimeout": 500,
    "unsubscribeTimeout": 500
  },
  "domain": "vehicle",
  "thingsEnabled": false,
  "rebootEnabled": true,
  "rebootAfter": "1m",
  "reportFeedbackInterval": "2m",
  "currentStateDelay": "1m",
  "phaseTimeout": "2m",
  "agents": {
    "self-update": {
      "rebootRequired": false,
      "readTimeout": "20s"
    },
    "containers": {
      "rebootRequired": true,
      "readTimeout": "30s"
    }
  }
}

Here keys (other the ones above) are self-explanatory. The “connection” section object specifies configuration options for the MQTT connection. Allowed log leves (in order of increasing verbosity)are: ERROR, WARN, INFO, DEBUG, TRACE.

3.3.2 - Message Flow

Note: This part of the Leda OSS stack is still in active development and there might be differences between the documented and the current version.

As described in Vehicle Update Manager takes a full update message for all domains, identifies the domains affected, the current component versions, actions to be taken, etc., and delegates those actions to the correct update agent (e.g. self-update/container update).

The update manager (UM) in Leda-distro is configured as specified in UM’s config.json, which on the final image is usually located in /etc/update-manager/config.json. The standard two domains supported are containers and self-update, with the latter requiring a reboot on a successful update.

Note: UM allows a custom prefix for all of its topics to be defined (“domain”) in its config.json On the Leda Distro image the default prefix is “vehicle”. If you decide to change it, replace “vehicle” in all MQTT topics mentioned below with your custom prefix.

A full specification of UM’s API and the relevant MQTT topics can be found in its documentation.

Update Message

The general structure of the update message is as follows:

{
  "activityId": "correlation-activity-uuid",
  "timestamp": 123456789,
  "payload": {
    "domains": [
      {
        "id": "domain",
        "config": [],
        "components": [
            {
                "id": "component1",
                "version": "component1-version",
                "config": [
                    {
                        "key": "component1-config-key-1",
                        "value": "component1-config-value-1"
                    }
                ]
            }
        ]
      }
    ]
  }
}

Where multiple domains and components per domain (each with multiple configuration key-value pairs) are allowed. To trigger an update, publish your full update message on the vehicleupdate/desiredstate MQTT topic. When UM receives your message, it splits it across the required domains and publishes messages to the topics that the domain-specific agents are monitoring.

Similarly, update progress can be monitored on the vehicleupdate/desiredstatefeedback topic.

Self-update

The messages for triggering a self-update (image update) are the same as in The Self Update Tutorial. The only difference here is that when you publish a self-update message on the vehicleupdate/desiredstate topic, UM will automatically take care to forward your message to the self-update agent, including forwarding back the update feedback on the vehicleupdate/-namespaced topics.

Containers update (desired state)

Similarly to the self-update, you should start by understanding the operation of the Container Update Agent. After constructing the desired state message you can publish it on the vehicleupdate/desiredstate and UM will, again, forward it to CUA automatically, based on the domain specified in the update message.

Combined update messages

The real strength of UM is deploying updates accross multiple domains with a single update message. For example, if you’d like to deploy an image update bundle (self-update) and a single hello-world container image with the environment variable FOO=BAR set, you can construct the following message:

{
   "activityId":"random-uuid-as-string",
   "timestamp":123456789,
   "payload":{
      "domains":[
         {
            "id":"self-update",
            "components":[
               {
                  "id":"os-image",
                  "version":"${VERSION_ID}",
                  "config":[
                     {
                        "key":"image",
                        "value":"https://leda-bundle-server/sdv-rauc-bundle-minimal-qemux86-64.raucb"
                     }
                  ]
               }
            ]
         },
         {
            "id":"containers",
            "config":[],
            "components":[
               {
                  "id":"hello-world",
                  "version":"latest",
                  "config":[
                     {
                        "key":"image",
                        "value":"docker.io/library/hello-world:latest"
                     },
                     {
                        "key":"env",
                        "value":"FOO=BAR"
                     }
                  ]
               }
            ]
         }
      ]
   }
}

And publish the message on the MQTT topic vehicleupdate/desiredstate. UM will take actions to identify the affected update domains and publish the correct messages on the respective topics. All feedback from the specific update agents will be forwarded back to the UM and published on the vehicleupdate/desiredstatefeedback topic. All these messages will use the same activityId so they can be correlated with each other.

3.4 - Self Updates

In general, the self-update mechanism for operating system level updates is done with two separate partitions. While one partition is the actively booted partition and in use, the other partition can be updated by writing a partition image to it, as it is unused or inactive.

Once the download and writing is done, a reboot is triggered and the boot loader will now switch to the newly updated partition.

If the booting of the updated partition fails, the self update mechanism can revert back to the previous partition or boot to a rescue partition.

Leda Self Update

As updating the running operating system cannot be done at runtime, the approach requires additional disk space, a second partition and also requires the device to be rebooted for the updates to take effect.

In a vehicle, the self-updater cannot decide on its own when to do a reboot, as the vehicle must be in a safe condition (eg parked, state of charge etc.). Hence, the trigger for performaing the switch to another slot and a subsequent reboot is handed over to a higher level component, such as the vehicle update manager, which may in turn rely on driver feedback or other conditions.

Implementation with RAUC Update Service

RAUC is a lightweight update client that runs on your embedded device and reliably controls the procedure of updating your device with a new firmware revision.

For general usage of the RAUC tool, please see the RAUC User manual

Reference configuration

The project contains an example reference implementation and configuration using RAUC, which allows the evaluation of the concepts, mechanisms and involved software components in an emulated, virtual environment.

The Leda quickstart image contains the following disk partitions:

  • a small rescue partition
  • a full SDV installation with a container runtime, pre-loaded SDV container images and deployment specifications and additional developer tools such as nerdctl and kantui.
  • a minimal SDV installation with a container runtime, but no additional examples or developer tools. This partition is used to demonstrate the self-update functionality.
  • additional boot and data partitions for keeping system state information

Note: All three rootfs partitions (rootfs) initially contain the same identical copies of the base operating system. Both SDV Root partitions will use the same shared data partition for the container persistent state.

3.4.1 - Self Update Tutorial

This chapter describes the steps necessary to perform a local (without cloud) self update of the operating system.

Self Update Architecture

Self-Update using RAUC Update Bundles

  • On host: Update bundle sdv-rauc-bundle-qemux86-64.raucb is in current folder

    Note: In the development environment, the update RAUC Update Bundle is located in the BitBake machine-specific output folder Example location is tmp/deploy/images/qemux86-64

  • On host: Start a dummy web server for serving the update file

    python3 -m http.server --bind 192.168.7.1
    
  • On host: open two new terminals - one for monitoring and one for triggering the self-update

    • Terminal 1: To view the progress, watch the MQTT topics selfupdate/desiredstate and selfupdate/desiredstatefeedback:

      mosquitto_sub -h 192.168.7.2 -p 1883 -t "selfupdate/#"
      
    • Terminal 2: Trigger the actual self update process by publishing an MQTT message to selfupdate/desiredstate:

      mosquitto_pub -h 192.168.7.2 -p 1883 -t "selfupdate/desiredstate" -f start-update-example.json
      mosquitto_pub -h 192.168.7.2 -p 1883 -t "selfupdate/desiredstate/command" -f download-command.json
      mosquitto_pub -h 192.168.7.2 -p 1883 -t "selfupdate/desiredstate/command" -f update-command.json
      mosquitto_pub -h 192.168.7.2 -p 1883 -t "selfupdate/desiredstate/command" -f activate-command.json
      mosquitto_pub -h 192.168.7.2 -p 1883 -t "selfupdate/desiredstate/command" -f cleanup-command.json
      

      Files:

      start-update-example.json

      download-command.json

      update-command.json

      activate-command.json

      cleanup-command.json

  • Switch to a terminal in the guest

  • On guest: After the self update process completed, check the status:

    rauc status --detailed
    

Self-Update Trigger Message

start-update-example.json file:

{
    "activityId": "random-uuid-as-string",
    "timestamp": 123456789,
    "payload": {
        "domains": [
            {
                "id": "self-update",
                "components": [
                    {
                        "id": "os-image",
                        "version": "${VERSION_ID}",
                        "config": [
                            {
                                "key": "image",
                                "value": "http://leda-bundle-server/sdv-rauc-bundle-minimal-qemux86-64.raucb"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Example Message Flows

Current State

  1. Initial response message on startup from self update agent in topic selfupdate/currentstate, or upon request by sending message to selfupdate/currentstate/get

     {
           "activityId": "1234567890",
           "timestamp": 1687510087
     }
    

    Response by Self Update Agent on topic selfupdate/currentstate

     {
           "activityId": "1234567890",
           "timestamp": 1687787461,
           "payload": {
                 "softwareNodes": [
                 {
                       "id": "self-update-agent",
                       "version": "build-152",
                       "name": "OTA NG Self Update Agent",
                       "type": "APPLICATION"
                 },
                 {
                       "id": "self-update:leda-deviceimage",
                       "version": "v0.0.10-194-g3d48cb8",
                       "name": "Official Leda device image",
                       "type": "IMAGE"
                 }
                 ],
                 "hardwareNodes": [],
                 "associations": [
                 {
                       "sourceId": "self-update-agent",
                       "targetId": "self-update:leda-deviceimage"
                 }
                 ]
           }
     }
    

Desired State

  1. External trigger to update via desired state on topic selfupdate/desiredstate:

     {
           "activityId": "<uuid>",
           "timestamp": 123456789,
           "payload": {
                 "domains": [
                       {
                       "id": "self-update",
                       "components": [
                             {
                                   "id": "os-image",
                                   "version": "${VERSION_ID}",
                                   "config": [
                                   {
                                         "key": "image",
                                         "value": "http://leda-bundle-server/sdv-rauc-bundle-qemux86-64.raucb"
                                   }
                                   ]
                             }
                       ]
                       }
                 ]
           }
     }
    

    Response on topic selfupdate/desiredstatefeedback

     {
           "activityId": "1234567890",
           "timestamp": 1687786390,
           "payload": {
                 "status": "IDENTIFYING",
                 "message": "Self-update agent has received new desired state request and is evaluating it.",
                 "actions": []
           }
     }
    
     {
           "activityId": "1234567890",
           "timestamp": 1687786390,
           "payload": {
                 "status": "IDENTIFIED",
                 "message": "Self-update agent is about to perform an OS image update.",
                 "actions": [
                 {
                       "component": {
                             "id": "self-update:os-image",
                             "version": "v0.0.10-194-g3d48cb8"
                       },
                       "status": "IDENTIFIED",
                       "progress": 0,
                       "message": "Self-update agent is about to perform an OS image update."
                 }
                 ]
           }
     }
    
  2. External trigger to download command on topic selfupdate/desiredstate/command:

     {
           "activityId": "1234567890",
           "timestamp": 1687510087,
           "payload": {
                 "baseline": "BASELINE NAME",
                 "command": "DOWNLOAD"
           }
     }
    

    Response on topic selfupdate/desiredstatefeedback

     {
           "activityId": "1234567890",
           "timestamp": 1687786931,
           "payload": {
                 "status": "DOWNLOADING",
                 "message": "Self-update agent is performing an OS image update.",
                 "actions": [
                 {
                       "component": {
                             "id": "self-update:os-image",
                             "version": "v0.0.10-194-g3d48cb8"
                       },
                       "status": "DOWNLOADING",
                       "progress": 0,
                       "message": "Downloading 0.0 MiB..."
                 }
                 ]
           }
     }     
    
    {
          "activityId": "1234567890",
          "timestamp": 1687786936,
          "payload": {
                "status": "DOWNLOAD_SUCCESS",
                "message": "Self-update agent is performing an OS image update.",
                "actions": [
                {
                      "component": {
                            "id": "self-update:os-image",
                            "version": "v0.0.10-194-g3d48cb8"
                      },
                      "status": "DOWNLOAD_SUCCESS",
                      "progress": 100,
                      "message": "Downloaded 106.3 MiB..."
                }
                ]
          }
    }
    
  3. External trigger to update command on topic selfupdate/desiredstate/command:

     {
           "activityId": "1234567890",
           "timestamp": 1687510087,
           "payload": {
                 "baseline": "BASELINE NAME",
                 "command": "UPDATE"
           }
     }
    

    Response on topic selfupdate/desiredstatefeedback

     {
           "activityId": "1234567890",
           "timestamp": 1687787145,
           "payload": {
                 "status": "UPDATING",
                 "message": "Self-update agent is performing an OS image update.",
                 "actions": [
                 {
                       "component": {
                             "id": "self-update:os-image",
                             "version": "v0.0.10-194-g3d48cb8"
                       },
                       "status": "UPDATING",
                       "progress": 0,
                       "message": "Checking bundle version and version in desired state request."
                 }
                 ]
           }
     }
    
    {
          "activityId": "1234567890",
          "timestamp": 1687787228,
          "payload": {
                "status": "UPDATE_SUCCESS",
                "message": "Self-update completed, reboot required.",
                "actions": [
                {
                      "component": {
                            "id": "self-update:os-image",
                            "version": "v0.0.10-194-g3d48cb8"
                      },
                      "status": "UPDATING",
                      "progress": 100,
                      "message": "Writing partition completed, reboot required."
                }
                ]
          }
    }
    
  4. External trigger to activate command on topic selfupdate/desiredstate/command:

     {
           "activityId": "1234567890",
           "timestamp": 1687510087,
           "payload": {
                 "baseline": "BASELINE NAME",
                 "command": "ACTIVATE"
           }
     }
    

    Response on topic selfupdate/desiredstatefeedback

     {
           "activityId": "1234567890",
           "timestamp": 1687787302,
           "payload": {
                 "status": "ACTIVATING",
                 "message": "Self-update agent is performing an OS image activation.",
                 "actions": [
                 {
                       "component": {
                             "id": "self-update:os-image",
                             "version": "v0.0.10-194-g3d48cb8"
                       },
                       "status": "UPDATING",
                       "progress": 0,
                       "message": "Self-update agent is performing an OS image activation."
                 }
                 ]
           }
     }
    
    {
          "activityId": "1234567890",
          "timestamp": 1687787303,
          "payload": {
                "status": "ACTIVATION_SUCCESS",
                "message": "Self-update agent has activated the new OS image.",
                "actions": [
                {
                      "component": {
                            "id": "self-update:os-image",
                            "version": "v0.0.10-194-g3d48cb8"
                      },
                      "status": "UPDATED",
                      "progress": 0,
                      "message": "Self-update agent has activated the new OS image."
                }
                ]
          }
    }
    
  5. External trigger to cleanup command on topic selfupdate/desiredstate/command:

     {
           "activityId": "1234567890",
           "timestamp": 1687510087,
           "payload": {
                 "baseline": "BASELINE NAME",
                 "command": "CLEANUP"
           }
     }
    

    Response on topic selfupdate/desiredstatefeedback

     {
           "activityId": "1234567890",
           "timestamp": 1687787382,
           "payload": {
                 "status": "CLEANUP_SUCCESS",
                 "message": "Self-update agent has cleaned up after itself.",
                 "actions": [
                 {
                       "component": {
                             "id": "self-update:os-image",
                             "version": "v0.0.10-194-g3d48cb8"
                       },
                       "status": "UPDATE_SUCCESS",
                       "progress": 0,
                       "message": "Self-update agent has activated the new OS image."
                 }
                 ]
           }
     }
    
    {
          "activityId": "1234567890",
          "timestamp": 1687787382,
          "payload": {
                "status": "COMPLETE",
                "message": "Self-update completed.",
                "actions": [
                {
                      "component": {
                            "id": "self-update:os-image",
                            "version": "v0.0.10-194-g3d48cb8"
                      },
                      "status": "UPDATE_SUCCESS",
                      "progress": 0,
                      "message": "Self-update agent has activated the new OS image."
                }
                ]
          }
    }
    

Rollback command

  • External trigger to rollback command on topic selfupdate/desiredstate/command:

     {
           "activityId": "1234567890",
           "timestamp": 1687510087,
           "payload": {
                 "baseline": "BASELINE NAME",
                 "command": "ROLLBACK"
           }
     }
    

    Self Update Agent returns in Idle state

Can be used from

  • Downloading (when it is waiting for DOWNLOAD command)
  • Installing (when it is waiting for UPDATE command)
  • Installed (when it is waiting for ACTIVATE command)
  • Failed (when it is waiting for CLEANUP command)

3.4.2 - RAUC Integration

Leda integrates RAUC as a reference implementation and example configuration. It allows the evaluation of the concepts, mechanisms and involved software components in an emulated, virtual environment or on physical devices.

Checking the RAUC Status

Get the current RAUC boot status:

rauc status

Example output:

root@qemux86-64:~# rauc status
=== System Info ===
Compatible:  Eclipse Leda qemu86-64
Variant:     
Booted from: rootfs.1 (SDV_B)

=== Bootloader ===
Activated: rootfs.1 (SDV_B)

=== Slot States ===

o [rootfs.1] (/dev/sda5, ext4, inactive)
        bootname: SDV_B
        mounted: /
        boot status: good

x [rootfs.0] (/dev/sda4, ext4, booted)
        bootname: SDV_A
        boot status: good

Forcing to boot the other slot

To manually force the device to boot into another slot, mark the current booted slot as bad, mark the other partitions as active and perform a reboot:

rauc status mark-bad booted
rauc status mark-active other
reboot now

Testing the rescue system

By marking both root slots as bad, the bootloader is supposed to boot the rescue system:

rauc status mark-bad rootfs.0
rauc status mark-bad rootfs.1
reboot now

Example output of rauc:

o [rootfs.1] (/dev/sda5, ext4, inactive)
        bootname: B
        boot status: bad

o [rootfs.0] (/dev/sda4, ext4, booted)
        bootname: A
        mounted: /
        boot status: bad

Customizations

The configurations can be customized by applying or patching the following files:

  • RAUC Configuration file: meta-leda/recipes-bsp/rauc/files/qemux86-64/system.conf
  • Bootloader Configuration file: meta-leda/recipes-bsp/grub/files/grub.cfg
  • The physical disk partition configuration: meta-leda/recipes-sdv/wic/qemux86-grub-efi.wks

RAUC System Configuration

The RAUC System Configuration is the central configuration of the RAUC Update system.

Example:

[system]
compatible=Eclipse Leda qemu86-64
bootloader=grub
grubenv=/grubenv/grubenv
statusfile=/data/rauc.status

[keyring]
path=ca.cert.pem

[slot.efi.0]
device=/dev/sda
type=boot-gpt-switch
region-start=4M
region-size=100M

[slot.rescue.0]
device=/dev/sda3
type=ext4
readonly=true

[slot.rootfs.0]
device=/dev/sda4
type=ext4
bootname=SDV_A

[slot.rootfs.1]
device=/dev/sda5
type=ext4
bootname=SDV_B

GRUB Bootloader Configuration

The GRUB bootloader has a configuration file which describes which partitions are bootable, which partition they are located at and a reference to RAUC’s slot name.

The configuration also contains RAUC specific logic and variables required for a proper integration. Please see the full grub.cfg in the source repository and RAUC Documentation - Integration - GRUB for details.

Excerpt:

...

menuentry "SDV Slot A (OK=$SDV_A_OK TRY=$SDV_A_TRY)" {
    linux (hd0,4)/boot/bzImage root=/dev/vda4 $CMDLINE rauc.slot=SDV_A
}

menuentry "SDV Slot B (OK=$SDV_B_OK TRY=$SDV_B_TRY)" {
    linux (hd0,5)/boot/bzImage root=/dev/vda5 $CMDLINE rauc.slot=SDV_B
}

U-Boot Bootloader Configuration

Similarly to GRUB, integration of RAUC with U-Boot requires custom boot scripting. A highly detailed explaination can, again, be found in the official RAUC Documentation - Integration - U-Boot.

Meta-Leda provides such integration recipes and scripts for all U-boot based targets, for which a Leda Quickstart image is available (qemuarm64, qemuarm and rpi4-64). For example:

Note: A custom U-Boot device defconfig might be required for some devices to be integrated with RAUC. Leda Quickstart images patch the default defconfigs for qemuarm64 and qemuarm to save the U-Boot environment in a VFAT BOOT partition.

Disk Partitioning with OpenEmbedded Image Creator (WIC)

The OpenEmbedded Image Creator is used in BitBake to actually create full disk images with multiple partitions.

These disk images are machine specific and the structure of the partitions are configured in OpenEmbedded Kickstart files (*.wks).

Excerpt qemux86-grub-efi.wks

Note: The excerpt is exemplary, please see the sources for a full representation and documentation.

bootloader --ptable gpt

part --fixed-size 50M --source rawcopy --sourceparams="file=efi-boot.vfat" --fstype=vfat --label boot --active

part --fixed-size 10M --source rawcopy --sourceparams="file=grubenv.vfat" --fstype=vfat --label grubenv

part /rescue --source rootfs --fstype=ext4 --label rescue

part / --source rootfs --fstype=ext4 --label root_a

part / --source rootfs --fstype=ext4 --label root_b

part /data --fixed-size 4G --fstype=ext4 --label data

3.4.3 - API Reference

The self update agent (SUA) is a component responsible for the OS Update process SUA is communicating on MQTT interface via usage of defined messages. Internally, SUA uses RAUC to perform the update

Following sequence diagram shows the happy path example of communication between components.

Process Overview

sequenceDiagram participant m as MQTT Broker participant s as SUA participant r as RAUC s -->> m: connect loop Wait for OTA trigger Note left of s: Initial start s ->> m: Current state (installed version from booted partition) Note left of s: Trigger for OTA m ->> s: Desired state request (new version and url to bundle) s ->> m: Feedback (update actions are identified) Note left of s: Command for Download m ->> s: Download command s ->> s: Download bundle s ->> m: Feedback (downloading/downloaded/failed) Note left of s: Command for Update m ->> s: Update command s ->> r: Flash image to partition r ->> r: Flashing... s ->> m: Feedback (updating with percentage) r ->> s: Flash completed/failed s ->> m: Feedback (updated/failed) Note left of s: Command for Activate m ->> s: Activate command s ->> r: Switch partitions (booted <-> other) r ->> s: Switch completed/failed s ->> m: Feedback (activated/failed) Note left of s: Command for Cleanup m ->> s: Cleanup command s ->> s: Remove temporary files s ->> m: Cleanup completed + status from previously failed state
(completed/failed) end
stateDiagram Uninitialized --> Connected: Connected Connected --> Identified: Start (OTA trigger) Identified --> Downloading: Command download Identified --> Failed: If OTA trigger is invalid Downloading --> Updating: Command update Downloading --> Failed: If download has failed Updating --> Activate: Command activate Updating --> Failed: If update has failed Activate --> Cleanup: Command cleanup Activate --> Failed: If activate has failed Failed --> Cleanup: Command cleanup Cleanup --> Idle

Important: Uninitialized state is the default entry state or state in case connection is lost. To simplify reading of the diagram arrows from other states to Unitialized have been removed.

MQTT communication is done over 5 MQTT topics:

Trigger OTA

Topic Direction Description
selfupdate/desiredstate IN This message triggers the update process
The payload shall contain all data necessary to obtain the update bundle and to install it

Trigger self-update step/action

Topic Direction Description
selfupdate/desiredstate/command IN This message triggers the single step in update process (download/flash/activate/cleanup)

Report current state

Topic Direction Description
selfupdate/currentstate OUT This message is being sent either once on SUA start or as an answer to response received by selfupdate/currentstate/get
It contains information about the currently installed OS version

Get current state

Topic Direction Description
selfupdate/currentstate/get IN This message can be received at any point of time
Indicates that SUA should send back the version of the installed OS as current state.

Report status of self-update process

Topic Direction Description
selfupdate/desiredstatefeedback OUT This message is being sent by SUA to share the current progress of the triggered update process
This is the OUT counterpart of selfupdate/desiredstate input message

Checkout

SUA links to some 3rd party libraries, which are fetched as submodules, therefore the cloning shall be performed with recursive option:

git clone --recursive https://github.com/eclipse-leda/leda-contrib-self-update-agent.git

or if was cloned non recursively

git submodule init
git submodule update

3.5 - Container Management

Leda is using Kanto Container Management as the upper-layer container runtime and container orchestration engine.

Besides the command line tool kanto-cm, Kanto also has remote interfaces to manage containers.

Remote Interface

Kanto’s container-management service offers a remote interface via local messaging (MQTT) to interact with a digital twin on the cloud side. This feature can be easily enabled by setting "things": { "enabled": true } in /etc/container-management/config.toml.

When one of the cloud connector components, such as leda-contrib-cloud-connector or Kanto’s azure-connector, is connected to a cloud backend, the container-management will publish its own information using Eclipse Ditto and Eclipse Hono messages. For this, container-management only needs the device Id, gateway Id and tenant Id.

3.5.1 - Cloud Connectivity

Simulation of cloud connectivity

  1. Container Management starts and subscribes to edge/thing/response
  2. Cloud Connector starts and publishes the following message to edge/thing/response as soon as the connection is online:
{
    "deviceId":"<namespace>:<gatewayId>:<deviceId>",
    "tenantId":"<tenantId>"
}
  • namespace is azure.edge for Kanto’s Azure Cloud Connector
  • gatewayId indicates the hostname of the Azure IoT Hub
  • deviceId is the identifier for the device, this can either be part of the Azure Connection String or part of the device authentication certificate (CN)
  • tenantId is a configuration setting in the cloud connector

Note: You can simulate the cloud connector trigger by issueing the MQTT message manually on command line:

mosquitto_pub -t 'edge/thing/response' -m '{"deviceId":"dummy-namespace:dummy-gateway:dummy-device-id","tenantId":"dummy-tenant-id"}'

3.5.2 - Container Update Agent

About the Container Update Agent (CUA)

The container update agent is a component of kanto container management, that can be enabled in the Container Management’s config.json. When it receives a desired state message on the containersupdate/desiredstate topic it compares the containers (with their current versions and configuration) that are managed by Kanto Container Management and those described in the desired state messages. When it has identified the differences between the two, it resolves them by deleting, downloading, or re-creating containers.

The desired state message

A basic desired state message has a similar structure to all update messages. To deploy the hello-world docker container (removing all other containers currently deployed on the device), you can publish the following desired state message:

{
   "activityId":"test-correlation-activity-uuid",
   "payload":{
      "domains":[
         {
            "id":"containers",
            "config":[],
            "components":[
               {
                  "id":"hello-world",
                  "version":"latest",
                  "config":[
                     {
                        "key":"image",
                        "value":"docker.io/library/hello-world:latest"
                     }
                  ]
               }
            ]
         }
      ]
   }
}

You can configure port mappings, environment variables, device mapping, logging, and more, by adding additional key-value pairs to the “config” array of the given container. For example, if you want to set the environment variable FOO="BAR" inside the container, you can specify:

{
   "activityId":"test-correlation-activity-uuid",
   "payload":{
      "domains":[
         {
            "id":"containers",
            "config":[],
            "components":[
               {
                  "id":"hello-world",
                  "version":"latest",
                  "config":[
                     {
                        "key":"image",
                        "value":"docker.io/library/hello-world:latest"
                     },
                     {
                        "key": "env",
                        "value": "FOO=BAR"
                     }
                  ]
               }
            ]
         }
      ]
   }
}

A full list of all key-value pairs with their defaults can be found in this doc for CUA.

System containers

If a container is not specified in the desired state message, it would be deleted by CUA when the message is received. This might be undesirable for containers that are supposed to run as system services from the first boot of the device through its operation. Such a container might be the Self Update Agent container on the Leda Distro image, which we do not want to specify in every desired state message and deleting/recreating-it during an update might lead to unexpected behaviour. That’s why in Container Management’s config.json in the CUA section, you can specify in the “system_containers” array the names of those containers that would like to be treated as such.

MQTT Topics

Since the MQTT interface of the update agent is abstract, the following message flows are similar to those for the self-update agent mentioned in its tutorial

Getting the current state

On initialization, CUA will publish the current state of all containers on the containersupdate/currentstate topic, the activityId for such a message would be initial-current-state-<TIMESTAMP>. This message can be understood as the “current container inventory”. An example inventory from a running Leda image is currentstate-leda.json.

You can request an update of the current state at any point by publishing an empty message on the: containersupdate/currentstate/get:

{
   "activityId": "<UUID>",
   "timestamp": 123456789,
   "payload": {}
}

The updated inventory will, again, be published on the containersupdate/currentstate topic with correlation ID of <UUID>.

Deploying a desired state message

A desired state message describing the containers and their environments of a typical Leda Distro deployment is leda-desired-state.json. To trigger a desired state deployment directly from CUA, publish the message above on containersupdate/desiredstate, e.g. by running:

   mosquitto_pub -t containersupdate/desiredstate -f leda-desired-state.json

You can monitor the update feedback from CUA, by listening on the topic containersupdate/desiredstatefeedback.

Note: Since the desired state feedback can be quite verbose and happens in real time during the update it could be hard to understand manually. However it’s structured json, so it could be easily machine-parsed and monitored for specific key-value pairs.

3.5.3 - Orchestration

Container Management

The container management will respond to the cloud connectivity status message by initially sending a list of containers:

  1. Container Management responds with a list of containers in the topic e/<tenantId>/<gatewayId>:<deviceId>:edge:containers
{
    "topic": "<tenantId>/<gatewayId>:<deviceId>:edge:containers/things/twin/commands/modify",
    "headers": {
        "response-required": false
    },
    "path": "/features/SoftwareUpdatable",
    "value": {
        "definition": [
            "org.eclipse.hawkbit.swupdatable:SoftwareUpdatable:2.0.0"
        ],
        "properties": {
            "status": {
                "softwareModuleType": "oci:container",
                "installedDependencies": {
                    "ghcr.io%2Feclipse%2Fkuksa.val%2Fdatabroker.<uuid>:0.2.5": {
                        "group": "ghcr.io/eclipse/kuksa.val/databroker",
                        "name": "<uuid>",
                        "version": "0.2.5"
                    },
                    "ghcr.io%2Feclipse%2Fkuksa.val.services%2Fseat_service.<uuid>:v0.1.0": {
                        "group": "ghcr.io/eclipse/kuksa.val.services/seat_service",
                        "name": "<uuid>",
                        "version": "v0.1.0"
                    },
                    "ghcr.io%2Feclipse-leda%2Fleda-contrib-cloud-connector%2Fcloudconnector.<uuid>:latest": {
                        "group": "ghcr.io/eclipse-leda/leda-contrib-cloud-connector/cloudconnector",
                        "name": "<uuid>",
                        "version": "latest"
                    },
                    "ghcr.io%2Feclipse-leda%2Fleda-contrib-self-update-agent%2Fself-update-agent.<uuid>:build-20": {
                        "group": "ghcr.io/eclipse-leda/leda-contrib-self-update-agent/self-update-agent",
                        "name": "<uuid>",
                        "version": "build-20"
                    },
                    "ghcr.io%2Feclipse-leda%2Fleda-contrib-vehicle-update-manager%2Fvehicleupdatemanager.<uuid>:latest": {
                        "group": "ghcr.io/eclipse-leda/leda-contrib-vehicle-update-manager/vehicleupdatemanager",
                        "name": "<uuid>",
                        "version": "latest"
                    }
                }
            }
        }
    }
}
  1. Container Management answers with an additional message for each container in the topic e/<tenantId>/<gatewayId>:<deviceId>:edge:containers
{
    "topic": "<tenantId>/<gatewayId>:<deviceId>:edge:containers/things/twin/commands/modify",
    "headers": {
        "response-required": false
    },
    "path": "/features/Container:<uuid>",
    "value": {
        "definition": [
            "com.bosch.iot.suite.edge.containers:Container:1.5.0"
        ],
        "properties": {
            "status": {
                "name": "seatservice-example",
                "imageRef": "ghcr.io/eclipse/kuksa.val.services/seat_service:v0.1.0",
                "config": {
                    "domainName": "seatservice-example-domain",
                    "hostName": "seatservice-example-host",
                    "env": [
                        "VEHICLEDATABROKER_DAPR_APP_ID=databroker",
                        "BROKER_ADDR=databroker-host:30555",
                        "RUST_LOG=info",
                        "vehicle_data_broker=info"
                    ],
                    "restartPolicy": {
                        "type": "UNLESS_STOPPED"
                    },
                    "extraHosts": [
                        "databroker-host:host_ip"
                    ],
                    "portMappings": [
                        {
                            "proto": "tcp",
                            "hostPort": 30051,
                            "hostPortEnd": 30051,
                            "containerPort": 50051,
                            "hostIP": "localhost"
                        }
                    ],
                    "networkMode": "BRIDGE",
                    "log": {
                        "type": "JSON_FILE",
                        "maxFiles": 2,
                        "maxSize": "1M",
                        "mode": "BLOCKING"
                    }
                },
                "createdAt": "2023-02-02T08:46:33.792687313Z",
                "state": {
                    "status": "RUNNING",
                    "pid": 13627,
                    "startedAt": "2023-02-02T09:51:08.049572297Z",
                    "finishedAt": "2023-02-02T09:50:51.752255799Z"
                }
            }
        }
    }
}    

3.5.4 - Container Metrics

Container Metrics

Container-level metrics, such as CPU utilization or memory usage, can be retrieved on-demand and continuously by enabling the container metrics events. This is done by sending a request to the topic command//<namespaceId>:<gatewayId>:<deviceId>:edge:containers/req/<correlationId>/request:

  1. Enable Container Metrics with a frequency of 5s:
{
    "topic": "dummy-namespace/dummy-gateway:dummy-device-id:edge:containers/things/live/messages/request",
    "headers": {
        "timeout": "10",
        "response-required": true,
        "content-type": "application/json",
        "correlation-id": "3fdc463c-293c-4f39-ab19-24aef7944550"
    },
    "path": "/features/Metrics/inbox/messages/request",
    "value": {
        "frequency": "5s"
    }
}

Example command line:

mosquitto_pub -t command//dummy-namespace:dummy-gateway:dummy-device-id:edge:containers/req/3fdc463c-293c-4f39-ab19-24aef7944550/request -m '{"topic":"dummy-namespace/dummy-gateway:dummy-device-id:edge:containers/things/live/messages/request","headers":{"timeout":"10","response-required":true,"content-type":"application/json","correlation-id":"3fdc463c-293c-4f39-ab19-24aef7944550"},"path":"/features/Metrics/inbox/messages/request","value":{"frequency":"5s"}}'
  1. Container Metrics answers with an additional message for each container in the topic e/<tenantId>/<gatewayId>:<deviceId>:edge:containers
{
    "topic": "<tenantId>/<gatewayId>:<deviceId>:edge:containers/things/twin/commands/modify",
    "headers": {
        "response-required": false
    },
    "path": "/features/Container:<uuid>",
    "value": {
        "definition": [
            "com.bosch.iot.suite.edge.containers:Container:1.5.0"
        ],
        "properties": {
            "status": {
                "name": "seatservice-example",
                "imageRef": "ghcr.io/eclipse/kuksa.val.services/seat_service:v0.1.0",
                "config": {
                    "domainName": "seatservice-example-domain",
                    "hostName": "seatservice-example-host",
                    "env": [
                        "VEHICLEDATABROKER_DAPR_APP_ID=databroker",
                        "BROKER_ADDR=databroker-host:30555",
                        "RUST_LOG=info",
                        "vehicle_data_broker=info"
                    ],
                    "restartPolicy": {
                        "type": "UNLESS_STOPPED"
                    },
                    "extraHosts": [
                        "databroker-host:host_ip"
                    ],
                    "portMappings": [
                        {
                            "proto": "tcp",
                            "hostPort": 30051,
                            "hostPortEnd": 30051,
                            "containerPort": 50051,
                            "hostIP": "localhost"
                        }
                    ],
                    "networkMode": "BRIDGE",
                    "log": {
                        "type": "JSON_FILE",
                        "maxFiles": 2,
                        "maxSize": "1M",
                        "mode": "BLOCKING"
                    }
                },
                "createdAt": "2023-02-02T08:46:33.792687313Z",
                "state": {
                    "status": "RUNNING",
                    "pid": 13627,
                    "startedAt": "2023-02-02T09:51:08.049572297Z",
                    "finishedAt": "2023-02-02T09:50:51.752255799Z"
                }
            }
        }
    }
}    
  1. To disable Container Metrics, send a request with frequency of 0s:

    mosquitto_pub -t command//dummy-namespace:dummy-gateway:dummy-device-id:edge:containers/req/3fdc463c-293c-4f39-ab19-24aef7944550/request -m '{"topic":"dummy-namespace/dummy-gateway:dummy-device-id:edge:containers/things/live/messages/request","headers":{"timeout":"10","response-required":true,"content-type":"application/json","correlation-id":"3fdc463c-293c-4f39-ab19-24aef7944550"},"path":"/features/Metrics/inbox/messages/request","value":{"frequency":"0s"}}'
    

3.5.5 - Container Registries

When deploying containerized applications, the container runtime will pull container images from a (remote) container registry.

The pulled container images and their layers are then stored in a local storage.

Private Container Registries

To be able to pull container images, the container runtime needs access to the container registry. Some container registries require authentication. The Kanto Container Manager can be configured to use credentials when accessing remote container registries.

In the Leda images, the sdv-kanto-ctl tools allows to easily add authentication to the container manager configuration:

sdv-kanto-ctl add-registry -h <registryhostname> -u <your_username> -p <your_password>

For example, to access container images from GitHub Packages in a private repository, you need a GitHub Personal Access Token (PAT) with the read: packages scope. Then, add the repository as shown below:

sdv-kanto-ctl add-registry -h ghcr.io -u github -p <Your_GitHub_PersonalAccessToken>

sdv-kanto-ctl will make the necessary modifications to /etc/container-management/config.json and restarts the container-management.service systemd unit, so that the changes take effect. You may need to recreate or restart the container if a previous pull failed.

Please see the Eclipse Kanto Container Manager Configuration reference for details.

4 - Vehicle Applications

This chapter contains use cases and examples for SDV applications.

Some of these example are taken from the following sources:

4.1 - Seat Adjuster

The seat adjuster is an example to showcase how to create a vehicle application which senses and actuates signals in the vehicle for Eclipse Leda with help of Eclipse Velocitas and Eclipse Kuksa . The aim is not to build the best available seat adjuster application possible but to show how one can use the applied technologies to build a companion app for the interaction with a vehicle. If you are new to the concepts around Eclipse SDV and the mentioned projects we recommend to read the SDV Tutorial first.

Description

The idea of the seat adjuster application is to have a custom application to move the driver seat to positions defined in a driver profile hosted by a third-party web service.

Leda Seat Adjuster Use Case

The setup contains the following components:

  • Cloud or mobile trigger: not part of the Leda image, but we simulate it by issuing MQTT messages
  • Seat Adjuster : Developed with Eclipse Velocitas to be deployed by user
  • Eclipse Kuksa.val - KUKSA Databroker (pre-installed with Eclipse Leda)
  • Mock Service: Example provider for Eclipse Kuksa.VAL which mocks the behavior of the vehicle.
  • Seat ECU and the separate Seat Motor hardware can be emulated using a virtual CAN-Bus, which is beyond the scope of this guide.

In the following paragraphs, we next introduce the architecture and the assumed data flow before we explain the development and deployment steps. If you are more interested in the general development steps, you may directly jump to the develop seat adjuster.

4.1.1 - Architecture of Seat Adjuster

The seat adjuster application interacts with the vehicle through a Vehicle Abstraction Layer created by the KUKSA Databroker, which uses the Vehicle Signal Specification (VSS) to express the current value and in case of actuators also the desired state of the vehicle signal. By developing against the abstraction layer, the application becomes independent from the actual physical seat.

To control the position of the driver seat, the seat adjuster sets the target value of the Vehicle.Cabin.Seat.Row1.Pos1.Position signal in the KUKSA Databroker.

The architecture assumes so-called actuation providers that apply the changes to the actual vehicle as indicated in the target value, e.g., through interaction with the responsible ECUs. For this tutorial, we do not expect you to interface with an actual vehicle and thus abstract the vehicle by using the Kuksa.Val vehicle mock service. This vehicle mock service allows the definition of behavior toward the KUKSA Databroker like we would expect from the vehicle, for example, setting the current value after reacting to changes to the target value of a signal.

flowchart TB client[Client] anotherClient[Another Client] seatadjuster[Seat Adjuster] databroker[(KUKSA
Databroker)] mqttRequest[[MQTT topic
seatadjuster/setPosition/request]] mockservice[Provider: Mock Service] client -- "JSON Request: position, requestId" --> mqttRequest anotherClient -.-> mqttRequest mqttRequest --> seatadjuster seatadjuster -- "Set Target
Vehicle.Cabin.Seat.Row1.Pos1.Position
gRPC" --> databroker databroker <-- "Set Current
Vehicle.Cabin.Seat.Row1.Pos1.Position

Notify subscriber of changed target
Vehicle.Cabin.Seat.Row1.Pos1.Position" --> mockservice

As interface to the user, we assume a client that can, for example, be a local app in the infotainment domain with a user interface or an off-board application sending the request from a backend. Either way, the client controls our seat adjuster application through a JSON encoded message over MQTT using the topic setPosition/request.

An example request looks like this:

mosquitto_pub -t seatadjuster/setPosition/request 
    -m '{"position": 1000, "requestId": "12345"}'

The position parameter can be any value between 0 and 1000.

Getting Seat Position

When the seat moves, the provider gets this information, for example, from the seat ECU over the CAN-bus. We use the mock service as a provider and configure it to set the current value for the Vehicle.Cabin.Seat.Row1.Pos1.Position signal in the KUKSA Databroker after the target value for the signal changes.

To receive the changes to the seat position, the seat adjuster application already subscribed to the current value of the signals and thus gets notified. As a result, the seat adjuster constructs a JSON message and sends the new seat position to the MQTT-topic seatadjuster/currentPosition where any client can consume it.

The seat adjuster also sends responses to each request received at the MQTT-topic seatadjuster/request with a message to the MQTT-topic seatadjuster/response indicating whether it accepted the incoming request and set the target value or whether there was an error like the vehicle currently moving.

flowchart TD client[Client] anotherClient[Another Client] seatadjuster[Seat Adjuster] databroker[(KUKSA
Databroker)] mqttResponse[[MQTT topic
seatadjuster/setPosition/response]] mqttCurrent[[MQTT topic
seatadjuster/currentPosition]] mockservice[Provider: Mock Service] mockservice -- "Feed/Set
Vehicle.Cabin.Seat.Row1.Pos1.Position
(Sensor)" --> databroker databroker -- "Notify Subscriber
Vehicle.Cabin.Seat.Row1.Pos1.Position" --> seatadjuster seatadjuster -- "Once after processing
/setPosition/request
message" --> mqttResponse seatadjuster -- "While seat is moving" --> mqttCurrent mqttResponse -- "SetPosition Response
(Accepted / Error)" --> client mqttCurrent --> client mqttCurrent -.-> anotherClient mqttResponse -.-> anotherClient

The next step is to develop the seat adjuster with the help of Eclipse Velocitas.

4.1.2 - Develop Seat Adjuster

The following pages show how to execute the explained setup using Eclipse Velocitas and Eclipse Leda 0.1.0-M2:

On a high level, you need to perform the following steps described in more detail in this guide:

  1. Use the Eclipse Velocitas template repository to develop, build and deploy your version of the seat adjuster example.

  2. Run Eclipse Leda, for example, as container or with other options like QEMU, physical hardware, etc..

  3. Manage the Eclipse Kanto container runtime to deploy your seat adjuster application.

  4. Test the deployed setup by interacting with the seat adjuster to change the seat position.

Setup Eclipse Velocitas from template repository

We use Eclipse Velocitas to develop the seat application against the API of the Kuksa.val Databroker:

In the first step, you create a copy of the Eclipse Velocitas template repository. You create the copy by opening the repository in GitHub and selecting: Use this template -> Create a new repository. In the next step, you choose under which organization to place the created repository and whether it should be public. If you set the repository to private, you have to perform additional configuration steps mentioned below.

The template repository contains skeleton code for the application, test and release workflows for GitHub actions, and the configuration of a development environment in a container.

In addition to the Python template used in this guide, there is a C++ template available.

Execute Development Container in VSCode

You then checkout the repository on your development machine and open it in VSCode. From VSCode you can execute the development container (DevContainer) configured in the repository. For this to function, you need to install the following tools on your computer:

In the best case, VSCode may detect that the repository contains a DevContainer configuration and ask you whether to execute it. Alternatively, you can press F1 in VSCode and then enter DevContainers: Reopen in container to start the DevContainer. In either case, VSCode should reopen and then connect to the DevContainer. Because of the DevContainer, we do not need to make further modifications to the developer machine.

Develop the application

In the next step, we work on the actual application. You find the skeleton code in /app/src/main.py of the Eclipse Velocitas template and thus the DevContainer.

Eclipse Velocitas provides the code to realize the described seat adjuster application. One way to get the code is to use a pre-configured task in VSCode by pressing ‘F1’ and then typing ‘Run Task’.

As an alternative, you can check the latest version of the seat adjuster example code in the Eclipse Velocitas SDK repository in the Velocitas SDK directory.

There is a chance that the latest code for the seat-adjuster example in the main-branch of the Eclipse Velocitas SDK is a bit different compared to the code snippets below.

Let us walk through some lines of the code where the logic is in the vapp.py while the entry point is in main.py.

In the on_start(self) function we subscribe to any changes of the current value of the VSS signal Vehicle.Cabin.Seat.Row1.Pos1.Position in the KUKSA Databroker.

async def on_start(self):
        """Run when the vehicle app starts"""
        await self.Vehicle.Cabin.Seat.Row1.Pos1.Position.subscribe(
            self.on_seat_position_changed
        )

When the seat position changes, the on_seat_position_changed function is triggered and publishes the new seat position value as MQTT-message to the topic seatadjuster/currentPosition.

 async def on_seat_position_changed(self, data: DataPointReply):
        response_topic = "seatadjuster/currentPosition"
        await self.publish_event(
            response_topic,
            json.dumps(
                {"position": data.get(self.Vehicle.Cabin.Seat.Row1.Pos1.Position).value}
            ),
        )

In addition, we have the function on_set_position_request_received which is triggered for every MQTT-message to the topic seatadjuster/setPosition/request.

 @subscribe_topic("seatadjuster/setPosition/request")
    async def on_set_position_request_received(self, data_str: str) -> None:
        data = json.loads(data_str)
        (...)
        vehicle_speed = (await self.Vehicle.Speed.get()).value

        position = data["position"]
        if vehicle_speed == 0:
                try:
                    await self.Vehicle.Cabin.Seat.Row1.Pos1.Position.set(position)
        (...)

If the vehicle speed is zero, meaning that the vehicle does not move, we set the target value in the KUKSA Databroker for the position signal of the seat to the value requested in the incoming MQTT message.

The get() and set() functions are created based on a VSS model, and we assume that the KUKSA Databroker instance uses the same VSS model. In many cases, like the default Eclipse Leda, one may rely on the upstream VSS model, but some scenarios require further signals, e.g., by applying an overlay.

You can configure the used VSS model in the app/AppManifest.json file. This file includes an interface definition with the entry for the default vehicle_signal_interface. The VSS signals in this guide are part of VSS in version 3.0.0. The DevContainer generates the respective Eclipse Velocitas SDK based on this configuration. For more details see the Eclipse Velocitas Model Generator.

At this point, you may wonder how the application actually knows to which MQTT broker to connect and where to find the correct instance of the KUKSA Databroker. This service discovery is abstracted within the Velocitas SDK and involves the usage of so-called middleware to find and call the other components. As of writing this page, Eclipse Velocitas supports DAPR as middleware or uses the native approach to configure the correct address directly. The details of how to set and configure the used middleware are part of the deployment.

Signal Description: The signal indicates the seat position on the vehicle x-axis, where the value 0 is the frontmost position supported by the seat.

The value is the distance measured in millimeters.

The example implementation supports values between 0 and 1000 millimeters.

Note: This range of valid values is not reflected in the standard Vehicle Signal Specification. OEMs would overlay the VSS tree with actual Min/Max values, depending on the seat hardware available in the vehicle model.

Start Runtime in DevContainer to test application

You may skip the application testing since we already provide the example code. But it still makes sense to get a general idea of how to test and debug the code with the tooling in the DevContainer.

As mentioned before, the execution and, thus, the testing of the application requires a set of other components to be available like the KUKSA Databroker or an MQTT-broker. Furthermore, the deployment, the configuration, and the behavior of the application may change depending on the used (container) management solution. Therefore, Eclipse Velocitas allows the deployment of the required components and the application with the container management approach of choice inside the DevContainer.

The different runtimes are maintained in a separate Eclipse Velocitas repository. To start a runtime, we use the Eclipse Velocitas CLI:

velocitas exec runtime-kanto up

We use the Eclipse Kanto runtime here since we later deploy the seat adjuster application to Eclipse Leda, which uses Eclipse Kanto for container management.

Once the runtime is available, we add our application by executing:

velocitas exec deployment-kanto build-vehicleapp
velocitas exec deployment-kanto deploy-vehicleapp

You can now test the application by interacting with it through the local MQTT broker. To send and receive MQTT messages, use the VSMQTT plugin with a cloud icon in the left side of the VSCode instance connected to the DevContainer. We do not get into details for the topics and messages here since we will run the application in Eclipse Leda again later in this guide.

Once you finish the application testing and development, you can shutdown the runtime with:

velocitas exec runtime-kanto down

Eclipse Velocitas provides Tasks to abstract the mentioned calls of the velocitas CLI. As an alternative you can thus press F1 -> Run Task and scroll for the respective task like Kanto runtime Up.

Commit and Release Application

When you are confident about the application, you want to be able to distribute it. Here, pre-configured workflows from Eclipse Velocitas for GitHub Actions are helpful.

You now commit your changes and push them to your copy of the Eclipse Velocitas template repository in GitHub. Before you create the commit, we recommend running the pre-commit task, which performs similar checks and linting as the CI workflow from Eclipse Velocitas. You can trigger the pre-commit as a task in VSCode:

  1. Press F1
  2. Write Tasks: Run Task and press enter
  3. Write Pre Commit Action and press enter

The pre commit action should start in a terminal inside VSCode.

You can check the available tasks configured by Eclipse Velocitas in .vscode/tasks.json.

If the pre-commit was successful, you may push your changes and open the repository in the browser. In the meantime, the push should trigger the CI workflow and the Build multiarch image workflow, which you can track in the Actions tab.

If you set your copy of the template repository to private, the CI workflow may fail due to missing permissions to write container images to GitHub packages. You can grant more Workflow permissions in the Settings tab of the repository under Actions-> General.

To deploy your application to a target and if the two workflows have finished successfully, you can perform a release in GitHub. The subsequent release workflow will make the application available as a built container in the container registry of GitHub (Code -> Packages). To do the release in GitHub, go to the Code tab and click Releases on the right side of the page. Then you can Draft a new release, create a new tag and title for the release, and click Publish Release, which triggers the Release workflow.

The next step is to deploy the seat adjuster in Eclipse Leda

4.1.3 - Deploy Seat Adjuster

We now want to deploy the application to a target device. You may follow the remainder of this guide on a separate device like a RaspberryPi, but you can emulate such a device on your development machine too. Either way, we use Eclipse Leda in version 0.1.0-M2 as the target system, which is a Linux-based distribution with pre-installed SDV components like the KUKSA Databroker and Eclipse Kanto for container management. For more details on how to download and run Eclipse Leda, follow the respective guides:

We recommend to get started with the QEMU setup. In any case, you now need to configure Eclipse Kanto to execute the application. For this, it helps to get an overview of which containers are currently running in Eclipse Kanto. You can get this either through the command:

kantui

or

kanto-cm list

From this list, ensure that at least the KUKSA Databroker runs, which should be the case since it is are pre-configured with the Eclipse Leda release.

In Eclipse Kanto, you can manage a container with the command line application kanto-cm or container manifest files describing a desired container execution. The advantage of using the container manifests is that the configuration is persisted across a reboot of the system and is easier to use to describe a desired software state for the overall vehicle.

Eclipse Leda has the kanto-auto-deployer systemd service, which applies any changes to the manifests in /data/var/containers/manifests to Eclipse Kanto. Thus, the typical way to add or adapt containers is to modify the corresponding container manifest.

Disable other containers

The release 0.1.0-M2 of Eclipse Leda comes with a number of pre-configured and automatically executed containers. One of these containers is the feedercan that feeds changing values from a recording for signals such as Vehicle.Speed to the KUKSA Databroker. These values interfere with the seat adjuster application, which only moves the seat if the vehicle speed is zero. Another interfering container is the seatservice-example which reacts to changes in the signal Vehicle.Cabin.Seat.Row1.Pos1.Position and which we replace later with the mock service.

Therefore, we need to stop the feedercan and the seatservice-example container. This is possible in kantui by selecting the respective entry and pressing R. In addition, you need to remove the corresponding container manifests in /data/var/containers/manifests to avoid that the Eclipse Kanto auto-deployer re-deploys these containers. Another approach is to change the ending of the not-needed manifests to something other than .json.

If the feedercan container still runs, the seat adjuster application app will later respond with the following error message:

seatadjuster/setPosition/response
 {"requestId": "12345", "result": {"status": 1, "message": "Not allowed to move seat because vehicle speed is 9.0 and not 0"}}

Since they consume resources and are not needed for the seat adjustment, you may remove the containers and manifests for cloudconnector, hvacservice-example, sua, or vum as well.

Starting of container

Use kanto-cm

kanto-cm create \
    --name seatadjuster-app \
    --e="SDV_SEATSERVICE_ADDRESS=grpc://seatservice-example:50051" \
    --e="SDV_MQTT_ADDRESS=mqtt://mosquitto:1883" \
    --e="SDV_VEHICLEDATABROKER_ADDRESS=grpc://databroker:55555" \
    --e="SDV_MIDDLEWARE_TYPE=native" \
    --hosts="databroker:container_databroker-host, mosquitto:host_ip, seatservice-example:container_seatservice-example-host" \
    ghcr.io/<YOUR_ORG>/seat-adjuster-app:latest

kanto-cm start --name seatadjuster-app
kanto-cm logs --name seatadjuster-app

Add manifest for seat adjuster

As an alternative to using kanto-cm, you can add a container manifest to the directoy watched by the kanto-auto-deployer (data/var/containers/manifests).

To add the container manifest, create a new file inside this folder.

touch seat-adjuster.json
nano seat-adjuster.json

and copy the manifest from below. You can save the file with strg+s and close the window with strg+q. You can create the file on the development machine and copy it via scp too:

scp -P 2222 myapp.json root@localhost:/data/var/containers/manifests/

The example deployment descriptor below is available in meta-leda-components too. An interesting aspect of the snippet is the config.env section at the bottom of the container manifest. There, we define a number of environment variables for the container which configures the Eclipse Velocitas SDK to use the native middleware and where to find the MQTT-broker and the KUKSA Databroker to use. We did the same in kanto-cm call behind the parameter --e=.

More details on the general deployment approach can be found in Leda Vehicle Applications

If the GitHub packages in which you stored the container image are private, Eclipse Kanto needs a valid access token to download the container image. You can create a personal access token in the Developer Settings of your GitHub account. Select Personal access token -> Tokens (classic) and generate a new token that at least has the read:packages permission. Copy the generated token to a secure location or to Eclipse Kanto because GitHub will not show it again. You can now configure Eclipse Kanto in Eclipse Leda to use the token by executing: sdv-kanto-ctl add-registry -h <registryhostname> -u <your_username> -p <your_password>. In the case of GitHub, the registryhostname is ghcr.io , the username is your GitHub handle, and the password is the generated token. See Container Registries for more details.

To make sure that Eclipse Kanto detects the changes in the manifests folder, you can restart the respective system services:

systemctl restart kanto-auto-deployer

Mock Service

As explained in the description of the code, the seat adjuster application sets the target value for the seat positions in the KUSKSA Datbroker and waits for the current position to update.

For this to function, there needs to be a component that reacts to this change by moving the seat and updating the current value accordingly. Because we cannot assume that you have an actual ECU availabe for running this guide, we mock the vehicle behavior with the vehicle mock service from the Eclipse Kuksa project.

The mock service allows the definition of custom interaction sequences with the KUKSA Databroker. For instance, one can react to changes to specific signals or update signals with a time trigger. You can define the sequences in a Python file like the example mock.py below. The snippet shows how to use a change to the target value for the seat position signal as a trigger to update the current value to the target value step-wise over a duration of 10 seconds.

For the deployment, you create another container manifest in /data/var/containers/manifest with the content from below. The container manifest also mounts a custom mock.py into the container to replace the configuration of the default mock.py. With the container manifest below, Eclipse Kanto instead mounts from /data/var/mock/mock.py. Therefore, you need to create this directory and the file with the content from below.

You may now check with kantui or kanto-cm list whether all components (databroker, seatadjuster-app, and mock-service) are running well. The next step is to interact with the seat adjuster.

seat-application.json

This is the Eclipse Kanto container manifest for the seat adjuster application.

{
    "container_id": "seatadjuster-app",
    "container_name": "seatadjuster-app",
    "image": {
        "name": "ghcr.io/<identifier-for-container>:<tag-for-container>"
    },
    "host_config": {
        "devices": [],
        "network_mode": "bridge",
        "privileged": false,
        "restart_policy": {
            "maximum_retry_count": 0,
            "retry_timeout": 0,
            "type": "unless-stopped"
        },
        "runtime": "io.containerd.runc.v2",
        "extra_hosts": [        
                "mosquitto:host_ip",
                "databroker:container_databroker-host",
                "seatservice-example:container_seatservice-example-host"
        ],
        "port_mappings": [
            {
              "protocol": "tcp",
              "container_port": 30151,
              "host_ip": "localhost",
              "host_port": 50151,
              "host_port_end": 50151
            }
        ],
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "1M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": ""
            }
        },
        "resources": null
    },
    "config": {
        "env": [
           "SDV_SEATSERVICE_ADDRESS=grpc://seatservice-example:50051",
           "SDV_VEHICLEDATABROKER_ADDRESS=grpc://databroker:55555",
           "SDV_MQTT_ADDRESS=mqtt://mosquitto:1883",
           "SDV_MIDDLEWARE_TYPE=native",
           "RUST_LOG=info",
           "vehicle_data_broker=info"
        ],
        "cmd": []
    }
}

mock.py

This is the example mock.py for mocking a seat provider:

from lib.animator import RepeatMode
from lib.dsl import (
    create_animation_action,
    create_behavior,
    create_event_trigger,
    create_set_action,
    get_datapoint_value,
    mock_datapoint,
)

from lib.trigger import ClockTrigger, EventType

mock_datapoint(
    path="Vehicle.Cabin.Seat.Row1.Pos1.Position",
    initial_value=0,
    behaviors=[
        create_behavior(
            trigger=create_event_trigger(EventType.ACTUATOR_TARGET),
            action=create_animation_action(
                duration=10.0,
                values=["$self", "$event.value"],
            ),
        )
    ],
)

mockservice.json

The container manifest for the mockservice may look like the following snippet. Note, that the files referenced in the source of the mount_points needs to be present in the file system of your Eclipse Leda instance.

{
    "container_id": "mockservice",
    "container_name": "mockservice",
    "image": {
        "name": "ghcr.io/eclipse/kuksa.val.services/mock_service:latest"
    },
    "mount_points": [
        {
            "source": "/data/var/mock/mock.py",
            "destination": "/mock.py",
            "propagation_mode": "rprivate"
        }
    ],
    "host_config": {
        "network_mode": "bridge",
        "privileged": false,
        "restart_policy": {
            "maximum_retry_count": 0,
            "retry_timeout": 0,
            "type": "unless-stopped"
        },
        "runtime": "io.containerd.runc.v2",
        "extra_hosts": [
            "databroker:container_databroker-host"
        ],
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "1M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": ""
            }
        }
    },
    "config": {
        "env": [
           "VDB_ADDRESS=databroker:55555"
        ]
    }
}

4.1.4 - Interact with Seat Adjuster

We interact with the seat application through MQTT messages to emulate the behavior of an offboard application. To see the responses from the seat adjuster app, subscribe to the MQTT topic `seatadjuster/#``.

mosquitto_sub -t 'seatadjuster/#' -v

To initiate the moving of the seat, publish an MQTT message for the seat adjuster application to set the position to 1000 (which is the equivalent of 100%):

mosquitto_pub -t seatadjuster/setPosition/request -m '{"position": 1000, "requestId": "12345"}'

You may need to open a second terminal session to send the message. In the QEMU setup, you can do this through an SSH connection from the host machine by running ssh -p 2222 root@localhost.

After publishing the setPosition-message, the expected output for the seatadjuster/# subscription should look like this:

seatadjuster/setPosition/request {"position": 1000, "requestId": "12345"}
seatadjuster/setPosition/response {"requestId": "12345", "result": {"status": 0, "message": "Set Seat position to: 1000"}}
seatadjuster/currentPosition {"position": 00}
seatadjuster/currentPosition {"position": 10}
seatadjuster/currentPosition {"position": 20}
seatadjuster/currentPosition {"position": 30}
seatadjuster/currentPosition {"position": 40}
seatadjuster/currentPosition {"position": 50}
...

If you encounter an issue or want to look deeper into the state of the container, you can check the logs by executing:

kanto-cm --name <container-name> logs

Run Kuksa Client

Besides trusting the log information and the MQTT messages that the seat position in the KUKSA Databroker has changed you can read the values directly from the KUKSA Databroker with the KUKSA Client. Through the sdv-ctr-exec it becomes possible to interact with the CLI of the Eclipse KUKSA Client:

kanto-cm create --i --t --network=host --name=kuksa-client ghcr.io/eclipse/kuksa.val/kuksa-client:master
kanto-cm start --name=kuksa-client
sdv-ctr-exec -n kuksa-client /kuksa-client/bin/kuksa-client --port 30555 --protocol grpc --insecure

Congratulations, you have reached the end of the seat adjuster guide. Based on the used code, you can now continue to realize other applications by using other signals. You may need to adapt your mock.py accordingly. In addition, you can connect the seat service to a CAN-environment.

References

4.1.5 - CAN Setup for Seat Adjuster

Within the seat adjuster guide, we so far mocked the behavior of the actual vehicle. In the following, we give an overview of how to create a virtual CAN-bus and interact with it to send CAN-frames for moving a seat.

Instead of the mock service you use the seat service as a provider, which is another pre-installed container acting as the connection between the KUKSA Databroker and the underlying hardware. More specifically, it subscribes to the target value of the Vehicle.Cabin.Seat.Row1.Pos1.Position signal, can send CAN-frames, and updates the current value of the signal in small steps until it is equal to the target value. For more details, visit the Kuksa.val.services repository, which hosts the code for the seat service.

With a new installation of Eclipse Leda, the seat adjuster comes by default. If you performed the steps from the deploy the seat adjuster in Eclipse Leda guide, you need to re-add the seatadjuster container manifest and remove the mockservice. More details on how to do this are available in that guide.

The setup then looks as follows:

flowchart TB client[Client] anotherClient[Another Client] seatadjuster[Seat Adjuster] databroker[(KUKSA
Databroker)] mqttRequest[[MQTT topic
seatadjuster/setPosition/request]] %% mqttResponse[[MQTT topic
seatadjuster/setPosition/response]] %% mqttCurrent[[MQTT topic
seatadjuster/currentPosition]] seatservice[Seat Service] canbus[CAN-Bus and Seat ECU] client -- "JSON Request: position, requestId" --> mqttRequest anotherClient -.-> mqttRequest mqttRequest --> seatadjuster seatadjuster -- "Set Target
Vehicle.Cabin.Seat.Row1.Pos1.Position
gRPC" --> databroker databroker <-- "Set Current
Vehicle.Cabin.Seat.Row1.Pos1.Position

Notify subscriber of changed target
Vehicle.Cabin.Seat.Row1.Pos1.Position" --> seatservice seatservice -- "CAN Frame: SECU1_CMD1
CAN-ID 0x705" --> canbus

Virtual CAN-Bus

To set upa virtual CAN-Bus

  1. You will have to generate initial CAN frames that will emulate the car ECU responding to the service:

    $ cangen -v can0 -L 8 -I 712 -D r -n 5
    can0  712#4F.BF.B0.6B.5F.2D.54.09
    can0  712#13.2E.98.7E.77.11.99.5B
    can0  712#15.70.87.07.73.24.3A.7A
    can0  712#99.7F.F5.3F.FB.99.00.04
    can0  712#FE.1C.D5.55.22.86.3A.1F
    
  2. You can now start tracing CAN frames written to the bus with candump can0

  3. From now on when a request to change the seat position is issued you will be able to see the corresponding CAN frames in the trace.

Note: On QEMU you can tunnel the host CAN bus to the guest: Tunneling a CAN Interface from the Host.

Hardware CAN-Bus

The default configuration of the Seat Service is using simulated VCAN. If you want to switch to a physical CAN-Bus interface, the container needs to have access to the CAN-Bus hardware.

Such a CAN-Bus device might be a Raspberry Pi setup with an MCP251x-based CAN-Hat extension or a QEMU image with an emulated kvaser_pci device (enabled on the Leda QEMU Quickstart images by default).

This setup would require some adjustments to the container manifest in order for the container to have access to the physical CAN-Bus.

  1. Make Seat Service container privileged and run on the host network interface:

    "host_config": {
    ...
    "network_mode": "host",
    "privileged": true,
    ...
    }
    
  2. Remove all port mappings and extra hosts (set "extra_hosts": [] and "port_mappings": []) for the container as it’s now running in host-networking mode (host_ip variable no longer available) and all ports are directly exposed.

  3. Set the address to the databroker to localhost:30555:

        "config": {
        "env": [
           ...
            "BROKER_ADDR=127.0.0.1:30555",
           ...
        ],
        ...
        }
    
  4. Reconfigure the seat controller application to use the physical CAN interface,please see Eclipse Kuksa.VAL seat_controller/README.md for details:

    SC_CAN=can0
    CAN=can0
    

    All the necessary changes combined for clarity as a single diff can be found below:

    --- ../meta-leda-fork/meta-leda-components/recipes-sdv/eclipse-leda/kanto-containers/example_dev/seatservice.json	2023-03-06 11:32:00.771754434 +0200
    +++ seatservice-new.json	2023-03-06 11:37:12.967182044 +0200
    @@ -14,26 +14,16 @@
        "hooks": [],
        "host_config": {
            "devices": [],
    -        "network_mode": "bridge",
    -        "privileged": false,
    +        "network_mode": "host",
    +        "privileged": true,
            "restart_policy": {
                "maximum_retry_count": 0,
                "retry_timeout": 0,
                "type": "unless-stopped"
            },
            "runtime": "io.containerd.runc.v2",
    -        "extra_hosts": [
    -            "databroker-host:host_ip"
    -        ],
    -        "port_mappings": [
    -            {
    -              "protocol": "tcp",
    -              "container_port": 50051,
    -              "host_ip": "localhost",
    -              "host_port": 30051,
    -              "host_port_end": 30051
    -            }
    -        ],
    +        "extra_hosts": [],
    +        "port_mappings": [],
            "log_config": {
                "driver_config": {
                    "type": "json-file",
    @@ -58,9 +48,11 @@
        },
        "config": {
            "env": [
    -           "BROKER_ADDR=databroker-host:30555",
    -           "RUST_LOG=info",
    -           "vehicle_data_broker=info"
    +            "CAN=can0",
    +            "SC_CAN=can0",
    +            "BROKER_ADDR=127.0.0.1:30555",
    +            "RUST_LOG=info",
    +            "vehicle_data_broker=info"
            ],
            "cmd": []
        },
    

Safety Considerations

Attention: Safety considerations are not in scope for this example tutorial. This example is for demonstrating the general approach. Actual safety requirements must be handled within the Seat ECU as the lowest level component to guard against non-safe use of the seat motors. Non-ASIL domains are not certified for safety requirements. Please pay attention when following the physical CAN tutorial and attaching physical actuators to not harm anybody by accidental movements of seat motors or any other actuator.

However, the Seat Adjuster example application contains a rudimentary “Safe State” condition check: it will only allow to move the seat when the vehicle is not moving.

The condition is using VSS path notation: Vehicle.Speed == 0 (see main.py#L82 in v0.9.0)

Note: The Kuksa.VAL CAN Feeder, which is deployed by default on Eclipse Leda is constantly updating the Vehicle.Speed You need to disable the feedercan container (see step 7 of Getting started), otherwise the Seat Adjuster application will decline the request and not move the seat.

4.2 - Dog Mode

The Dog Mode use case has been derived from the Eclipse Velocitas Dog Mode example and the Eclipse Kuksa.VAL HVAC Service example.

Description

In the Dog Mode use case, an existing vehicle service (such as HVAC for Heating, Ventilation and Air Conditioning) is used for another use case. When a driver enables the dog mode, the vehicle will keep the climate in a status to accomodates the pet while the driver is gone for a few minutes.

The focus on this example is to show how an additional application can reuse existing functionality for new use cases. The vehicle service being used does not need to be adapted for the new use case. The new use case is deployed as an additional functionality, separated from the rest of the existing system.

Architecture Overview

Leda Dog Mode Use Case

  • Cloud or mobile trigger: not part of the Leda image, but can be simulated by issueing MQTT messages
  • Eclipse Velocitas - Vehicle Application: Dog Mode (to be deployed by user as part of the Velocitas tutorial)
  • Eclipse Kuksa.VAL - Example Service: HVAC Service (pre-installed)
  • Eclipse Kuksa.VAL - Data Broker (pre-installed)

Getting started

  1. Follow the Velocitas tutorial: build and deploy your clone of the dog mode example

  2. Download and run the Leda quickstart image

  3. Deploy the application to the container runtime, either manually by using kanto-cm create or by providing a deployment descriptor in /var/containers/manifests. An example deployment descriptor can be found in meta-leda-components. Details on the deployment can be found in Leda Vehicle Applications

  4. Ensure the databroker and the service containers are running and you know how to check their log files

  5. Monitor vehicle data: mosquitto_sub -t dogmode/display

  6. Enable dog mode by using the databroker-cli

     connect
     set Vehicle.Cabin.DogMode 1
    

4.3 - VSS & Kuksa.VAL

To generically interact with the Vehicle Signals which are managed in the Eclipse Kuksa.VAL Databroker, you can either use the natively installed databroker-cli command line tool, or use the CLI tool from an updated and released containerized image.

Kuksa Databroker CLI

To install a new version of the Kuksa Databroker CLI container, follow these steps:

  1. Create the container in Kanto:

     kanto-cm create --i --t --network=host --name=databroker-cli ghcr.io/eclipse/kuksa.val/databroker-cli:master
    
  2. Start the command line tool within a container in interactive mode:

     kanto-cm start --a --i --name databroker-cli
    
  3. In the databroker shell, connect to the databroker via the URL http://127.0.0.1:30555/:

     connect http://127.0.0.1:30555/
    

Kuksa Databroker CLI Container

Kuksa Client

To install a new version of the Kuksa Client container, follow these steps:

  1. Pull the container image

     ctr --namespace kanto-cm image pull ghcr.io/eclipse/kuksa.val/kuksa-client:master
    
  2. Create the container in Kanto Namespace:

     ctr --namespace kanto-cm container create --net-host --tty ghcr.io/eclipse/kuksa.val/kuksa-client:master kuksa-client
    
  3. Start the container in detached mode:

     ctr --namespace kanto-cm tasks start --detach kuksa-client
    
  4. Start the command line tool with additional command line options:

     ctr --namespace kanto-cm tasks exec --tty --exec-id sometask kuksa-client /kuksa-client/bin/kuksa-client --port 30555 --protocol grpc --insecure
    

4.3.1 - Custom Vehicle Signals

The Vehicle Signal Specification has a lot of standard Vehicle Signals already defined.

However, if you want to add additional custom signals or mappings from CAN-Bus for the Kuksa.VAL dbc2val feeder, the VSS data model needs to be customized and regenerated.

The following steps can be performed on a development machine to regenerate VSS data model with custom a vspec mapping.

  1. Concepts
  2. Setup workspace
  3. Defining the VSS Overlay
  4. Regenerate VSpec JSON
  5. Generate a candump
  6. Databroker and dbc2val containers
  7. Testing with data

Concepts

VSS Overlay

The VSS Overlay concept allows to override the standard signals in the specification with custom signals. It defines metadata attributes like signal name, datatype, description etc.

In addition, the vspec file allows to add custom metadata, such as the dbc node in the following example:

Vehicle.Speed:
  type: sensor
  datatype: float
  dbc:
    message: Kombi_01
    signal: KBI_angez_Geschw
    interval_ms: 1000

See Eclipse Kuksa documentation about dbc2val mapping for details.

There are also ways to automatically transform the CAN-Bus signal values into VSS values:

  • Mapping of literal values, such as enums and booleans
  • Mathematical transformations
  • Full and partial transformations

Setup workspace

Required tools

  • Git
  • Docker
  • Python 3
  • can-utils
  • a YAML/JSON text editor

Depending on your host OS, you may need to install the packages first:

sudo apt-get update
sudo apt-get install can-utils git docker python3

Workspace structure

You need the following files in your workspace folder:

  • ./custom.dbc - The vehicle-specific DBC file. You can use the Tesla Model 3 example or check out the opendbc project.
  • ./custom.vspec - The VSS overlay from the previous step

Defining the VSS Overlay

The definition of an VSS overlay is a manual process. It requires research, browsing the existing VSS catalog and deep knowledge of the vehicle signals. Especially knowing the semantic of a signal and how to map it between DBC and VSS is a complex task.

Note: The Leda team is not aware of any advanced tooling to support the automation of this task.

  1. Create a new file custom.vspec. Use YAML format
  2. For each identified signal:
    1. Look up if there already is a corresponding signal in VSS. You may use the Digital.Auto Playground or the spec directly.
    2. Add a new top-level entry to the custom.vspec file. The key is the full VSS path name in dot notation.
    3. Add the corresponding dbc node
    4. Add the signal attribute and enter the name of the CAN-Bus signal name in the DBC
    5. Add additional attributes such as interval_ms, message or transform.

      Note: The attributes signal, interval_ms and transform are evaluated by dbc2val. The attribute message is only evaluated by the below demo script and is optional.

Example:

# CAN Message: Kombi_01
Vehicle.Speed:
  type: sensor
  datatype: float
  dbc:
    message: Kombi_01
    signal: KBI_angez_Geschw
    interval_ms: 1000

# CAN Message: FS_Position_01
Vehicle.Cabin.Seat.Row1.Pos1.Position:
  type: sensor
  datatype: float
  dbc:
    message: FS_Position_01
    signal: FSS_Laenge_Pos
    interval_ms: 1000

These two extensions will be added to the combined VSS tree:

VSS Overlay with custom CAN-Bus metadata

Regenerating VSpec

The script vspec2json.py from COVESA VSS Tools can then be used to merge the overlay file with the standard specification.

For Leda devices, you can use kanto-cm to run the tool as a container:

# Copy custom.dbc and custom.vspec to /home/root
# Run in /home/root
kanto-cm create --name vspec2json --rp no --mp="/home/root:/data" ghcr.io/eclipse-leda/leda-vss-vspec2json:main
kanto-cm start --a --i --name vspec2json

For developer workstations, there is a convenient pre-built Docker container:

docker run --name vspec2json --rm -v `pwd`:/data ghcr.io/eclipse-leda/leda-vss-vspec2json:main

Or, if you want to run vspec2json from the sources, clone the repository and invoke it like this:

git clone \
    --recurse-submodules \
    --branch v3.1 \
    --single-branch \
    --depth 1 \
    https://github.com/COVESA/vehicle_signal_specification

python3 vehicle_signal_specification/vss-tools/vspec2json.py \
    -e dbc \
    -o custom.vspec \
    --uuid \
    --json-pretty \
    --json-all-extended-attributes \
    ../vehicle_signal_specification/spec/VehicleSignalSpecification.vspec \
    custom_vss_dbc.json

With the resulting file custom_vss_dbc.json and the corresponding DBC file, the dbc2val feeder can relay the signals to the databroker. dbc2val can either read from a CAN-Dump file (generated by candump from can-utils) in an endless loop, or can listen on actual virtual or physical CAN interfaces.

The output should look like this:

$ ls
custom.dbc  custom.vspec
$ docker run --name vspec2json --rm -v `pwd`:/data ghcr.io/eclipse-leda/leda-vss-vspec2json:main
INFO     Output to json format
INFO     Known extended attributes: dbc
INFO     Added 54 units from /vss/spec/units.yaml
INFO     Loading vspec from /vss/spec/VehicleSignalSpecification.vspec...
INFO     Applying VSS overlay from /data/custom.vspec...
INFO     Autocreating implicit branch Vehicle
INFO     Autocreating implicit branch Cabin
INFO     Autocreating implicit branch Seat
INFO     Autocreating implicit branch Row1
INFO     Autocreating implicit branch Pos1
INFO     Calling exporter...
INFO     Generating JSON output...
INFO     Serializing pretty JSON...
INFO     All done.
$ ls
custom.dbc  custom.vspec  custom_vss_dbc.json

Databroker Container

Ensure the databroker container is up and running:

On developer workstation:

docker run --name databroker --detach --rm -p 55555:55555/tcp ghcr.io/eclipse/kuksa.val/databroker:0.3.1

On Leda device (if not already running)

kanto-cm start --name databroker

Testing with data

To see actual data, we need to use the candump or another CAN source and feed that data into the databroker. After that is running, we can use the databroker-cli tool to subscribe to the example VSS signals.

Generate a candump

To generate a candump for testing purposes, start the candump tool and listen for some packets.

In the following example, the first 20 CAN frames are being recorded and the command will exit.

candump -L -n 20 vcan0 > candump.log

If you do not have an external CAN source, you may want to simulate CAN frames. There is a Python library for parsing DBC files, which also let’s you encode and send the actual CAN messages.

An example script could look like this:

Note: Due to GPL-3 licensing, the Leda quickstart image does not contain some Python standard libraries. This script will not run on a Leda quickstart image.

import random
import time
from pprint import pprint

import yaml
import cantools
import can

can_bus = can.interface.Bus('vcan0', bustype='socketcan')
db = cantools.database.load_file('custom.dbc')
with open("custom.vspec", "r") as stream:
    try:
        vspec = yaml.safe_load(stream)

        for key in vspec:
            message_name=vspec[key]['dbc']['message']
            signal_name=vspec[key]['dbc']['signal']
            example_message = db.get_message_by_name(message_name)

            # Initialize an empty message
            data = {}
            for signal in example_message.signals:
                data[signal.name] = False

            pprint("Message: %s" % example_message)

            # Send 10 frames with random data
            for x in range(10):
                data[signal_name] = random.uniform(0,100)
                encoded_data = example_message.encode(data)
                message = can.Message(arbitration_id=example_message.frame_id, data=encoded_data)
                pprint("CAN Frame: %s" % message)
                can_bus.send(message)
                # Wait up to 1 second
                time.sleep(random.random())

    except yaml.YAMLError as exc:
        print(exc)

Example output:

"Message: message('Kombi_01', 0x30b, False, 8, {None: 'MQB'})"
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 b9 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 16 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 ca 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 ad 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 b0 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 79 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 1b 01')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 19 01')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 0a 00')
('CAN Frame: Timestamp:        0.000000    ID: 0000030b    X Rx                '
 'DL:  8    00 00 00 00 00 00 b0 00')
"Message: message('FS_Position_01', 0x6be, False, 8, None)"
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    59 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    31 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    29 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    07 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    40 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    55 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    54 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    07 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    62 00 00 00 00 00 00 00')
('CAN Frame: Timestamp:        0.000000    ID: 000006be    X Rx                '
 'DL:  8    59 00 00 00 00 00 00 00')

dbc2val on workstation

Get the latest sources:

git clone https://github.com/eclipse/kuksa.val.feeders

Looping a CAN dump recording:

kuksa.val.feeders/dbc2val/dbcfeeder.py \
    --dumpfile candump.log \
    --canport vcan0 \
    --server-type kuksa_databroker \
    --dbcfile custom.dbc \
    --mapping custom_vss_dbc.json

Listening on CAN interface:

# CAN must be set up up front, e.g.
# modprobe vcan
# ip link add dev vcan0 type vcan
# ip link set vcan0 up

kuksa.val.feeders/dbc2val/dbcfeeder.py \
    --canport vcan0 \
    --use-socketcan \
    --server-type kuksa_databroker \
    --dbcfile /custom/custom.dbc \
    --mapping /custom/custom_vss_dbc.json

dbc2val on Leda device

To run the dbc2val feeder on Leda, you can use kanto-cm (instead of docker) to create the respective containers.

Note: Due to Issue #73, the container ghcr.io/eclipse/kuksa.val.feeders/dbc2val:v0.1.1 cannot be used with SocketCAN. Please use a later release or build the container from the sources after fixing the bug. Alternatively, use the candump file instead of SocketCAN.

  1. Remove any existing dbc2val container:

    kanto-cm remove --force --name dbc2val
    
  2. Create the new container in Kanto Container Management:

    kanto-cm create \
        --name dbc2val \
        --mp="/home/root:/data" \
        --e=VDB_ADDRESS="databroker:30555" \
        --e=USECASE="databroker" \
        --network=host \
        --privileged \
        ghcr.io/eclipse/kuksa.val.feeders/dbc2val:v0.1.1 \
        /dist/dbcfeeder-exe \
        --canport vcan0 \
        --use-socketcan \
        --usecase databroker \
        --dbcfile /data/custom.dbc \
        --mapping /data/custom_vss_dbc.json
    

    Note: The host networking and privileged is used to allow the container access to the CAN sockets.

  3. Start the container:

    kanto-cm start --a --i --name dbc2val
    
  4. Check the logs to verify container is running:

    kanto-cm logs --name dbc2val
    

Querying via CLI

To be able to see the changes, you may want to use the Kuksa Databroker CLI:

docker run --rm -it --network host ghcr.io/eclipse/kuksa.val/databroker-cli:0.3.1

Now, depending on the way how the dbc2val feeder has been started (candump vs. socketcan), you will either already see data from the candump loop.

Eclipse Kuksa.VAL Databroker CLI

4.4 - CarSim

The CarSim example provides basic Vehicle Signals based on a physical model simulation and feeds them to the databroker.

Eclipse Leda CarSim Kinetics

Architecture Overview

Eclipse Leda CarSim DriverSim Architecture Overview

Description

CarSim is a simple physical model implementation, based on the kinematic bicycle model. It can be used as a mock implementation in development, testing and simulation scenarios.

It takes three external inputs:

  • accelerator position
  • brake position
  • steering wheel angle

It propagates the physical model in time with a pre-defined step interval (10ms), recalculates the acceleration components, speed and position, and finally publishes the numeric values as standard VSS datapoints to the databroker.

To simulate the input from a human driver, the optional DriverSim component can be run in parallel. DriverSim toggles between two different types of driver style in a pre-defined time interval:

  • Good driver - slowly accelerates and moves the steering angle accordingly and then slowly brakes.
  • Bad driver - accelerates hard (full throttle), moves the steering wheel randomly in both directions, brakes hard.

Background

Decoupled Design

CarSim and DriverSim only communicate through the databroker by using standardized Vehicle Signals.

Each component can be replaced individually at runtime, e.g. by more advanced or real implementations. There is no need to adapt, recompile or redeploy any of the other applications.

This is important for decoupling and standardizing vehicle signals, to enable future vehicle application platforms to evolve. Loose coupling and standardizing of vehicle signal interfaces enable thirdparty applications to use signals in higher-level applications or value-add services.

Both implementors (imagine separate organizations), can agree to use the Vehicle Signal Specification to decouple the development lifecycle for vehicle applications and vehicle services. This decoupling approach reduces the time and effort for proprietary design specifications processes tremendously.

Vehicle Signals

The CarSim application reads the following input signals from the databroker:

Input

“Human” driver input Python variable VSS subscription path VSS datatype
Brake pedal position DP_BRAKE_POS Vehicle.Chassis.Brake.PedalPosition uint8
Accelerator pedal position DP_ACCELR_POS Vehicle.Chassis.Accelerator.PedalPosition uint8
Steering wheel angle DP_STEER_ANGLE Vehicle.Chassis.SteeringWheel.Angle int16

Note: You can either provide these signals externally on your own, or use DriverSim to simulate them.

Output

The CarSim application feeds the following output signals to the databroker:

Python variable VSS feeding path VSS datatype
DP_SPEED Vehicle.Speed float
DP_ACCEL_LAT Vehicle.Acceleration.Lateral float
DP_ACCEL_LONG Vehicle.Acceleration.Longitudinal float
DP_ACCEL_VERT Vehicle.Acceleration.Vertical float

Getting started

  1. Start up Leda and wait for the runtime to be available. For other deployment options, see Getting Started

    docker run -it ghcr.io/eclipse-leda/leda-distro/leda-quickstart-x86
    
  2. Deploy the CarSim container:

    kanto-cm create --name carsim --e=DATABROKER_ADDRESS=databroker:55555 --hosts="databroker:container_databroker-host" ghcr.io/eclipse-leda/leda-example-applications/leda-example-carsim:v0.0.1
    kanto-cm start --name carsim
    
  3. Deploy DriverSim container:

    kanto-cm create --name driversim --e=DATABROKER_ADDRESS=databroker:55555 --hosts="databroker:container_databroker-host" ghcr.io/eclipse-leda/leda-example-applications/leda-example-driversim:v0.0.1
    kanto-cm start --name driversim
    
  4. Use kantui or kanto-cm logs --name <carsim|driversim> to view log files:

    Eclipse Leda KantUI CarSim Logs

    Eclipse Leda KantUI DriverSim Logs

  5. Use the databroker-cli to subscribe to the following VSS signals.

    Note: Separate multiple signals by commas. Use <TAB> to auto-complete signal names. See QUERY.md for the query syntax.

    $ databroker-cli
    connect localhost:30555
    subscribe
        SELECT
         Vehicle.Speed,
         Vehicle.Acceleration.Vertical,
         Vehicle.Acceleration.Longitudinal,
         Vehicle.Acceleration.Lateral
        WHERE
         Vehicle.Speed > 50
    

    Eclipse Leda CarSim Databroker-CLI

  6. Happy hacking!

    Need ideas? How about implementing your own driver simulation and integrate with existing open source simulation technologies from Autonomous Driving?

References

4.5 - Velocitas VApps

For local deployment without a cloud backend, deployment specifications for Eclipse Velocitas Vehicle Apps may be put directly onto the device.

  • Create a Kanto deployment specification for your vehicle app. You may copy one of the existing JSON files in /data/var/containers/manifests as a template
  • Copy the specification file to the device, e.g. scp -P 2222 myapp.json root@localhost:/data/var/containers/manifests/
  • Apply the specification: systemctl restart kanto-auto-deployer

To update an existing container when the configuration has changed, delete the container and restart kanto-auto-deployer:

kanto-cm remove -n myapp-example
# Edit /data/var/containers/manifests/myapp.json
kanto-auto-deployer

Configuration of Velocitas Middleware Type

The following Velocitas environment variables need to be set to configure the proper middleware type and hostnames of services:

SDV_MQTT_ADDRESS=mosquitto:1883
SDV_VEHICLEDATABROKER_ADDRESS=databroker:55555
SDV_MIDDLEWARE_TYPE=native

Example Deployment Specification

Attention: The current implementation requires all fields to be present in the JSON, even if the values are not set or used. Do not remove any fields, as it may break the functionality.

{
    "id": "",
    "name": "myapp-example",
    "image": {
        "name": "ghcr.io/my-org/my-repo/my-app:latest",
        "decrypt_config": null
    },
    "host_name": "",
    "domain_name": "",
    "resolv_conf_path": "",
    "hosts_path": "",
    "hostname_path": "",
    "mounts": [],
    "hooks": [],
    "host_config": {
        "devices": [],
        "network_mode": "bridge",
        "privileged": false,
        "restart_policy": {
            "maximum_retry_count": 0,
            "retry_timeout": 0,
            "type": "unless-stopped"
        },
        "runtime": "io.containerd.runc.v2",
        "extra_hosts": [],
        "port_mappings": [
            {
              "protocol": "tcp",
              "container_port": 30151,
              "host_ip": "localhost",
              "host_port": 50151,
              "host_port_end": 50151
            }
        ],
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "100M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": ""
            }
        },
        "resources": null
    },
    "io_config": {
        "attach_stderr": false,
        "attach_stdin": false,
        "attach_stdout": false,
        "open_stdin": false,
        "stdin_once": false,
        "tty": false
    },
    "config": {
        "env": [
           "VEHICLEDATABROKER_DAPR_APP_ID=vehicledatabroker",
           "SDV_MQTT_ADDRESS=mosquitto:1883",
           "SDV_VEHICLEDATABROKER_ADDRESS=databroker:55555",
           "SDV_MIDDLEWARE_TYPE=native"
        ],
        "cmd": []
    },
    "network_settings": null,
    "state": {
        "pid": -1,
        "started_at": "",
        "error": "",
        "exit_code": 0,
        "finished_at": "",
        "exited": false,
        "dead": false,
        "restarting": false,
        "paused": false,
        "running": false,
        "status": "",
        "oom_killed": false
    },
    "created": "",
    "manually_stopped": false,
    "restart_count": 0
}

4.6 - Cloud2Device Messages

c2d-overview

In order to verify that the device and the cloud connector can successfully receive messages sent by the cloud backend, we will send a dummy message to the device.

Pre-Requisites

Validating configuration

First, let’s check that the cloud connection is active.

  • Login as root

  • Run sdv-health and check for the SDV Connectivity section:

    sdv-health
    

    sdv-health-connectivity

  • Start watching the output of the cloud connector:

    kantui
    
  • Select the cloud-connector container and press L to watch the logs

    Note: When an unknown type of message is received, the cloud connector will log an error:

    2022/04/13 16:04:41.911727  [agent]  ERROR  Handler returned error err="cannot deserialize cloud message: invalid character 'H' looking for beginning of value
    
  • Start watching on the MQTT message broker:

    mosquitto_sub -h localhost -t '#' --pretty -v
    

    Note: When a known type of message is received, the cloud connector will forward the message to the MQTT broker into the corresponding topic $appId/$cmdName

Sending a Device Message

  • Go to the Web Console of Azure IoT Hub
  • Select the device
  • Click on “Send Message”
  • Enter a C2D payload and click “Send”

Alternatively, on command line, use the Azure CLI client. Replace DeviceId and IotHubName with the appropriate names of your IoT Hub and device.

az iot device c2d-message send \
 --device-id ${DeviceID} \
 --hub-name ${IotHubName} \
 --data 'Hello World'

5 - Vehicle Signals

This chapter contains a reference of the vehicle signal metadata from the Vehicle Signal Specification Release 3.1.

The Vehicle Signals Specification is a tree of standardized information signals.

It starts with the Vehicle root node.

5.1 - Vehicle

Full qualified VSS Path: Vehicle
Description: High-level vehicle data.
flowchart LR Vehicle

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle

Signal Information

The vehicle signal Vehicle is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle is ccc825f94139544dbb5f4bfd033bece6

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.1 - Connectivity

Full qualified VSS Path: Vehicle.Connectivity
Description: Connectivity data.
flowchart LR Vehicle-->Connectivity

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Connectivity

Signal Information

The vehicle signal Vehicle.Connectivity is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Connectivity is 89c267fccea35f3da9871cca2b4dc4df

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.1.1 - IsConnectivityAvailable

Full qualified VSS Path: Vehicle.Connectivity.IsConnectivityAvailable
Description: Indicates if connectivity between vehicle and cloud is available. True = Connectivity is available. False = Connectivity is not available.
Comment: This signal can be used by onboard vehicle services to decide what features that shall be offered to the driver, for example disable the ‘check for update’ button if vehicle does not have connectivity.
flowchart LR Vehicle-->Connectivity Connectivity-->IsConnectivityAvailable

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Connectivity.IsConnectivityAvailable
[get]  OK
Vehicle.Connectivity.IsConnectivityAvailable: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Connectivity.IsConnectivityAvailable false
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Connectivity.IsConnectivityAvailable

Data Type & Unit

Path Vehicle.Connectivity.IsConnectivityAvailable VSS: Addressing nodes
Data type boolean VSS: Datatypes

Note: The boolean datatype is a boolean value which technically allows values of either 0 and false; or 1 and true.

Signal Information

The vehicle signal Vehicle.Connectivity.IsConnectivityAvailable is a Sensor.

The vehicle signal Vehicle.Connectivity.IsConnectivityAvailable is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Connectivity.IsConnectivityAvailable is b6d11be2a6565996b68ffb07a96595a7

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.2 - Exterior

Full qualified VSS Path: Vehicle.Exterior
Description: Information about exterior measured by vehicle.
flowchart LR Vehicle-->Exterior

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Exterior

Signal Information

The vehicle signal Vehicle.Exterior is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Exterior is 06c5def549f3580e8cdaffa3e0f5d25c

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.2.1 - AirTemperature

Full qualified VSS Path: Vehicle.Exterior.AirTemperature
Description: Air temperature outside the vehicle.
flowchart LR Vehicle-->Exterior Exterior-->AirTemperature

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Exterior.AirTemperature
[get]  OK
Vehicle.Exterior.AirTemperature: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Exterior.AirTemperature 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Exterior.AirTemperature

Data Type & Unit

Path Vehicle.Exterior.AirTemperature VSS: Addressing nodes
Data type float VSS: Datatypes
Unit celsius VSS: Units
Label degree celsius
Description Temperature measured in degree celsius VSS: Sensors & Actuators
Domain temperature

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Exterior.AirTemperature is a Sensor.

The vehicle signal Vehicle.Exterior.AirTemperature is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Exterior.AirTemperature is a38d3f5dfeb35317aca8b90453dc1a75

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.2.2 - Humidity

Full qualified VSS Path: Vehicle.Exterior.Humidity
Description: Relative humidity outside the vehicle. 0 = Dry, 100 = Air fully saturated.
flowchart LR Vehicle-->Exterior Exterior-->Humidity

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Exterior.Humidity
[get]  OK
Vehicle.Exterior.Humidity: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Exterior.Humidity 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Exterior.Humidity

Data Type & Unit

Path Vehicle.Exterior.Humidity VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation
Minimum value 0 VSS: Sensors & Actuators
Maximum value 100 VSS: Sensors & Actuators

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Exterior.Humidity is a Sensor.

The vehicle signal Vehicle.Exterior.Humidity is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Exterior.Humidity is 6c785ec5d9a5534f98be7ce198d25d6b

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.2.3 - LightIntensity

Full qualified VSS Path: Vehicle.Exterior.LightIntensity
Description: Light intensity outside the vehicle. 0 = No light detected, 100 = Fully lit.
Comment: Mapping to physical units and calculation method is sensor specific.
flowchart LR Vehicle-->Exterior Exterior-->LightIntensity

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Exterior.LightIntensity
[get]  OK
Vehicle.Exterior.LightIntensity: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Exterior.LightIntensity 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Exterior.LightIntensity

Data Type & Unit

Path Vehicle.Exterior.LightIntensity VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation
Minimum value 0 VSS: Sensors & Actuators
Maximum value 100 VSS: Sensors & Actuators

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Exterior.LightIntensity is a Sensor.

The vehicle signal Vehicle.Exterior.LightIntensity is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Exterior.LightIntensity is 9b46b70490f853e891e1cc35dd08dddc

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.3 - Service

Full qualified VSS Path: Vehicle.Service
Description: Service data.
flowchart LR Vehicle-->Service

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Service

Signal Information

The vehicle signal Vehicle.Service is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Service is b6463772705b56a7a993e23601bd3d47

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.3.1 - DistanceToService

Full qualified VSS Path: Vehicle.Service.DistanceToService
Description: Remaining distance to service (of any kind). Negative values indicate service overdue.
flowchart LR Vehicle-->Service Service-->DistanceToService

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Service.DistanceToService
[get]  OK
Vehicle.Service.DistanceToService: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Service.DistanceToService 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Service.DistanceToService

Data Type & Unit

Path Vehicle.Service.DistanceToService VSS: Addressing nodes
Data type float VSS: Datatypes
Unit km VSS: Units
Label kilometer
Description Distance measured in kilometers VSS: Sensors & Actuators
Domain distance

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Service.DistanceToService is a Sensor.

The vehicle signal Vehicle.Service.DistanceToService is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Service.DistanceToService is 6f4347ce149759819572c8c3a17e8d93

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.3.2 - IsServiceDue

Full qualified VSS Path: Vehicle.Service.IsServiceDue
Description: Indicates if vehicle needs service (of any kind). True = Service needed now or in the near future. False = No known need for service.
flowchart LR Vehicle-->Service Service-->IsServiceDue

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Service.IsServiceDue
[get]  OK
Vehicle.Service.IsServiceDue: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Service.IsServiceDue false
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Service.IsServiceDue

Data Type & Unit

Path Vehicle.Service.IsServiceDue VSS: Addressing nodes
Data type boolean VSS: Datatypes

Note: The boolean datatype is a boolean value which technically allows values of either 0 and false; or 1 and true.

Signal Information

The vehicle signal Vehicle.Service.IsServiceDue is a Sensor.

The vehicle signal Vehicle.Service.IsServiceDue is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Service.IsServiceDue is 3e28f85ccccd5702b9adbe9a761ea1b4

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.3.3 - TimeToService

Full qualified VSS Path: Vehicle.Service.TimeToService
Description: Remaining time to service (of any kind). Negative values indicate service overdue.
flowchart LR Vehicle-->Service Service-->TimeToService

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Service.TimeToService
[get]  OK
Vehicle.Service.TimeToService: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Service.TimeToService 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Service.TimeToService

Data Type & Unit

Path Vehicle.Service.TimeToService VSS: Addressing nodes
Data type int32 VSS: Datatypes
Unit s VSS: Units
Label second
Description Time measured in seconds VSS: Sensors & Actuators
Domain time

Note: The int32 datatype is a signed 32-bit integer which technically allows values between -2147483648 and 2147483647 (inclusive).

Signal Information

The vehicle signal Vehicle.Service.TimeToService is a Sensor.

The vehicle signal Vehicle.Service.TimeToService is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Service.TimeToService is c968be91a5685fa9ae30b84a0f91934e

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4 - Driver

Full qualified VSS Path: Vehicle.Driver
Description: Driver data.
flowchart LR Vehicle-->Driver

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver

Signal Information

The vehicle signal Vehicle.Driver is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver is 1cac57e7b7e756dc8a154eaacbce6426

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.4.1 - AttentiveProbability

Full qualified VSS Path: Vehicle.Driver.AttentiveProbability
Description: Probability of attentiveness of the driver.
flowchart LR Vehicle-->Driver Driver-->AttentiveProbability

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.AttentiveProbability
[get]  OK
Vehicle.Driver.AttentiveProbability: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.AttentiveProbability 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.AttentiveProbability

Data Type & Unit

Path Vehicle.Driver.AttentiveProbability VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation
Minimum value 0 VSS: Sensors & Actuators
Maximum value 100 VSS: Sensors & Actuators

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Driver.AttentiveProbability is a Sensor.

The vehicle signal Vehicle.Driver.AttentiveProbability is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.AttentiveProbability is fcd202467afb533fbbf9e7da89cc1cee

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4.2 - DistractionLevel

Full qualified VSS Path: Vehicle.Driver.DistractionLevel
Description: Distraction level of the driver will be the level how much the driver is distracted, by multiple factors. E.g. Driving situation, acustical or optical signales inside the cockpit, phone calls.
flowchart LR Vehicle-->Driver Driver-->DistractionLevel

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.DistractionLevel
[get]  OK
Vehicle.Driver.DistractionLevel: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.DistractionLevel 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.DistractionLevel

Data Type & Unit

Path Vehicle.Driver.DistractionLevel VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation
Minimum value 0 VSS: Sensors & Actuators
Maximum value 100 VSS: Sensors & Actuators

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Driver.DistractionLevel is a Sensor.

The vehicle signal Vehicle.Driver.DistractionLevel is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.DistractionLevel is cb35ec0b924e58979e1469146d65c3fa

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4.3 - FatigueLevel

Full qualified VSS Path: Vehicle.Driver.FatigueLevel
Description: Fatigueness level of driver. Evaluated by multiple factors like trip time, behaviour of steering, eye status.
flowchart LR Vehicle-->Driver Driver-->FatigueLevel

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.FatigueLevel
[get]  OK
Vehicle.Driver.FatigueLevel: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.FatigueLevel 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.FatigueLevel

Data Type & Unit

Path Vehicle.Driver.FatigueLevel VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation
Minimum value 0 VSS: Sensors & Actuators
Maximum value 100 VSS: Sensors & Actuators

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.Driver.FatigueLevel is a Sensor.

The vehicle signal Vehicle.Driver.FatigueLevel is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.FatigueLevel is 49b1626295705a79ae20d8a270c48b6b

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4.4 - HeartRate

Full qualified VSS Path: Vehicle.Driver.HeartRate
Description: Heart rate of the driver.
flowchart LR Vehicle-->Driver Driver-->HeartRate

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.HeartRate
[get]  OK
Vehicle.Driver.HeartRate: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.HeartRate 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.HeartRate

Data Type & Unit

Path Vehicle.Driver.HeartRate VSS: Addressing nodes
Data type uint16 VSS: Datatypes

Note: The uint16 datatype is an unsigned 16-bit integer which technically allows values between 0 and 65535 (inclusive).

Signal Information

The vehicle signal Vehicle.Driver.HeartRate is a Sensor.

The vehicle signal Vehicle.Driver.HeartRate is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.HeartRate is d71516905f785c4da867a2f86e774d93

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4.5 - IsEyesOnRoad

Full qualified VSS Path: Vehicle.Driver.IsEyesOnRoad
Description: Has driver the eyes on road or not?
flowchart LR Vehicle-->Driver Driver-->IsEyesOnRoad

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.IsEyesOnRoad
[get]  OK
Vehicle.Driver.IsEyesOnRoad: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.IsEyesOnRoad false
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.IsEyesOnRoad

Data Type & Unit

Path Vehicle.Driver.IsEyesOnRoad VSS: Addressing nodes
Data type boolean VSS: Datatypes

Note: The boolean datatype is a boolean value which technically allows values of either 0 and false; or 1 and true.

Signal Information

The vehicle signal Vehicle.Driver.IsEyesOnRoad is a Sensor.

The vehicle signal Vehicle.Driver.IsEyesOnRoad is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.IsEyesOnRoad is 625e5009f1145aa0b797ee6c335ca2fe

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4.6 - Identifier

Full qualified VSS Path: Vehicle.Driver.Identifier
Description: Identifier attributes based on OAuth 2.0.
flowchart LR Vehicle-->Driver Driver-->Identifier

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.Identifier

Signal Information

The vehicle signal Vehicle.Driver.Identifier is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.Identifier is 89705397069c5ec58d607318f2ff0ea8

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.4.6.1 - Issuer

Full qualified VSS Path: Vehicle.Driver.Identifier.Issuer
Description: Unique Issuer for the authentication of the occupant. E.g. https://accounts.funcorp.com.
flowchart LR Vehicle-->Driver Driver-->Identifier Identifier-->Issuer

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.Identifier.Issuer
[get]  OK
Vehicle.Driver.Identifier.Issuer: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.Identifier.Issuer Foo
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.Identifier.Issuer

Data Type & Unit

Path Vehicle.Driver.Identifier.Issuer VSS: Addressing nodes
Data type string VSS: Datatypes

Note: The string datatype is a character string.

Signal Information

The vehicle signal Vehicle.Driver.Identifier.Issuer is a Sensor.

The vehicle signal Vehicle.Driver.Identifier.Issuer is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.Identifier.Issuer is ee7988d26d7156d2a030ecc506ea97e7

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.4.6.2 - Subject

Full qualified VSS Path: Vehicle.Driver.Identifier.Subject
Description: Subject for the authentication of the occupant. E.g. UserID 7331677.
flowchart LR Vehicle-->Driver Driver-->Identifier Identifier-->Subject

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.Driver.Identifier.Subject
[get]  OK
Vehicle.Driver.Identifier.Subject: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.Driver.Identifier.Subject Foo
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.Driver.Identifier.Subject

Data Type & Unit

Path Vehicle.Driver.Identifier.Subject VSS: Addressing nodes
Data type string VSS: Datatypes

Note: The string datatype is a character string.

Signal Information

The vehicle signal Vehicle.Driver.Identifier.Subject is a Sensor.

The vehicle signal Vehicle.Driver.Identifier.Subject is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.Driver.Identifier.Subject is b41ec688af265f10824bc9635989ac55

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5 - OBD

Full qualified VSS Path: Vehicle.OBD
Description: OBD data.
flowchart LR Vehicle-->OBD

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD

Signal Information

The vehicle signal Vehicle.OBD is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD is 7ad7c512ed5d52c8b31944d2d47a4bc3

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.5.1 - AbsoluteLoad

Full qualified VSS Path: Vehicle.OBD.AbsoluteLoad
Description: PID 43 - Absolute load value
flowchart LR Vehicle-->OBD OBD-->AbsoluteLoad

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.AbsoluteLoad
[get]  OK
Vehicle.OBD.AbsoluteLoad: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.AbsoluteLoad 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.AbsoluteLoad

Data Type & Unit

Path Vehicle.OBD.AbsoluteLoad VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.AbsoluteLoad is a Sensor.

The vehicle signal Vehicle.OBD.AbsoluteLoad is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.AbsoluteLoad is b3dd889a42ce5de9a7904b7196ae325c

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.2 - AcceleratorPositionD

Full qualified VSS Path: Vehicle.OBD.AcceleratorPositionD
Description: PID 49 - Accelerator pedal position D
flowchart LR Vehicle-->OBD OBD-->AcceleratorPositionD

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.AcceleratorPositionD
[get]  OK
Vehicle.OBD.AcceleratorPositionD: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.AcceleratorPositionD 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.AcceleratorPositionD

Data Type & Unit

Path Vehicle.OBD.AcceleratorPositionD VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.AcceleratorPositionD is a Sensor.

The vehicle signal Vehicle.OBD.AcceleratorPositionD is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.AcceleratorPositionD is 7e63256081ac5a7b8a28a6fa3c2c2ff9

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.3 - AcceleratorPositionE

Full qualified VSS Path: Vehicle.OBD.AcceleratorPositionE
Description: PID 4A - Accelerator pedal position E
flowchart LR Vehicle-->OBD OBD-->AcceleratorPositionE

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.AcceleratorPositionE
[get]  OK
Vehicle.OBD.AcceleratorPositionE: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.AcceleratorPositionE 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.AcceleratorPositionE

Data Type & Unit

Path Vehicle.OBD.AcceleratorPositionE VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.AcceleratorPositionE is a Sensor.

The vehicle signal Vehicle.OBD.AcceleratorPositionE is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.AcceleratorPositionE is 4104e7fc25355e25b4522d233565d84b

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.4 - AcceleratorPositionF

Full qualified VSS Path: Vehicle.OBD.AcceleratorPositionF
Description: PID 4B - Accelerator pedal position F
flowchart LR Vehicle-->OBD OBD-->AcceleratorPositionF

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.AcceleratorPositionF
[get]  OK
Vehicle.OBD.AcceleratorPositionF: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.AcceleratorPositionF 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.AcceleratorPositionF

Data Type & Unit

Path Vehicle.OBD.AcceleratorPositionF VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.AcceleratorPositionF is a Sensor.

The vehicle signal Vehicle.OBD.AcceleratorPositionF is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.AcceleratorPositionF is 95f5c2a209a857ff930e2f8e32ac2d3f

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.5 - AmbientAirTemperature

Full qualified VSS Path: Vehicle.OBD.AmbientAirTemperature
Description: PID 46 - Ambient air temperature
flowchart LR Vehicle-->OBD OBD-->AmbientAirTemperature

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.AmbientAirTemperature
[get]  OK
Vehicle.OBD.AmbientAirTemperature: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.AmbientAirTemperature 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.AmbientAirTemperature

Data Type & Unit

Path Vehicle.OBD.AmbientAirTemperature VSS: Addressing nodes
Data type float VSS: Datatypes
Unit celsius VSS: Units
Label degree celsius
Description Temperature measured in degree celsius VSS: Sensors & Actuators
Domain temperature

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.AmbientAirTemperature is a Sensor.

The vehicle signal Vehicle.OBD.AmbientAirTemperature is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.AmbientAirTemperature is 220a90f183c5583ea8b8b6454d774517

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.6 - CommandedEquivalenceRatio

Full qualified VSS Path: Vehicle.OBD.CommandedEquivalenceRatio
Description: PID 44 - Commanded equivalence ratio
flowchart LR Vehicle-->OBD OBD-->CommandedEquivalenceRatio

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.CommandedEquivalenceRatio
[get]  OK
Vehicle.OBD.CommandedEquivalenceRatio: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.CommandedEquivalenceRatio 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.CommandedEquivalenceRatio

Data Type & Unit

Path Vehicle.OBD.CommandedEquivalenceRatio VSS: Addressing nodes
Data type float VSS: Datatypes
Unit ratio VSS: Units
Label ratio
Description Relation measured as ratio VSS: Sensors & Actuators
Domain relation

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.CommandedEquivalenceRatio is a Sensor.

The vehicle signal Vehicle.OBD.CommandedEquivalenceRatio is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.CommandedEquivalenceRatio is 104e39e816f65fa791d0afa24603292b

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.7 - ControlModuleVoltage

Full qualified VSS Path: Vehicle.OBD.ControlModuleVoltage
Description: PID 42 - Control module voltage
flowchart LR Vehicle-->OBD OBD-->ControlModuleVoltage

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.ControlModuleVoltage
[get]  OK
Vehicle.OBD.ControlModuleVoltage: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.ControlModuleVoltage 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.ControlModuleVoltage

Data Type & Unit

Path Vehicle.OBD.ControlModuleVoltage VSS: Addressing nodes
Data type float VSS: Datatypes
Unit V VSS: Units
Label volt
Description Electric potential measured in volts VSS: Sensors & Actuators
Domain electric potential

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.ControlModuleVoltage is a Sensor.

The vehicle signal Vehicle.OBD.ControlModuleVoltage is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.ControlModuleVoltage is 59e072b932605ffc88a299c874d885c4

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.8 - DriveCycleStatus

Full qualified VSS Path: Vehicle.OBD.DriveCycleStatus
Description: PID 41 - OBD status for the current drive cycle
flowchart LR Vehicle-->OBD OBD-->DriveCycleStatus

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.DriveCycleStatus

Signal Information

The vehicle signal Vehicle.OBD.DriveCycleStatus is a Branch.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.DriveCycleStatus is 5215e28062f75154822789b8a5f30630

Children

This vehicle signal is a branch or structure and thus has sub-pages:

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

5.1.5.8.1 - DTCCount

Full qualified VSS Path: Vehicle.OBD.DriveCycleStatus.DTCCount
Description: Number of sensor Trouble Codes (DTC)
flowchart LR Vehicle-->OBD OBD-->DriveCycleStatus DriveCycleStatus-->DTCCount

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.DriveCycleStatus.DTCCount
[get]  OK
Vehicle.OBD.DriveCycleStatus.DTCCount: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.DriveCycleStatus.DTCCount 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.DriveCycleStatus.DTCCount

Data Type & Unit

Path Vehicle.OBD.DriveCycleStatus.DTCCount VSS: Addressing nodes
Data type uint8 VSS: Datatypes

Note: The uint8 datatype is an unsigned 8-bit integer which technically allows values between 0 and 255 (inclusive).

Signal Information

The vehicle signal Vehicle.OBD.DriveCycleStatus.DTCCount is a Sensor.

The vehicle signal Vehicle.OBD.DriveCycleStatus.DTCCount is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.DriveCycleStatus.DTCCount is 312856f746ff560e8098c19196964d3b

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.8.2 - IgnitionType

Full qualified VSS Path: Vehicle.OBD.DriveCycleStatus.IgnitionType
Description: Type of the ignition for ICE - spark = spark plug ignition, compression = self-igniting (Diesel engines)
flowchart LR Vehicle-->OBD OBD-->DriveCycleStatus DriveCycleStatus-->IgnitionType

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.DriveCycleStatus.IgnitionType
[get]  OK
Vehicle.OBD.DriveCycleStatus.IgnitionType: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.DriveCycleStatus.IgnitionType Foo
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.DriveCycleStatus.IgnitionType

Data Type & Unit

Path Vehicle.OBD.DriveCycleStatus.IgnitionType VSS: Addressing nodes
Data type string VSS: Datatypes
Allowed values ['SPARK', 'COMPRESSION'] VSS: Specifying allowed values

Note: The string datatype is a character string.

Signal Information

The vehicle signal Vehicle.OBD.DriveCycleStatus.IgnitionType is a Sensor.

The vehicle signal Vehicle.OBD.DriveCycleStatus.IgnitionType is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.DriveCycleStatus.IgnitionType is 1aeb7b6d025f5a8693104824abaa1c49

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.8.3 - IsMILOn

Full qualified VSS Path: Vehicle.OBD.DriveCycleStatus.IsMILOn
Description: Malfunction Indicator Light (MIL) - False = Off, True = On
flowchart LR Vehicle-->OBD OBD-->DriveCycleStatus DriveCycleStatus-->IsMILOn

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.DriveCycleStatus.IsMILOn
[get]  OK
Vehicle.OBD.DriveCycleStatus.IsMILOn: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.DriveCycleStatus.IsMILOn false
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.DriveCycleStatus.IsMILOn

Data Type & Unit

Path Vehicle.OBD.DriveCycleStatus.IsMILOn VSS: Addressing nodes
Data type boolean VSS: Datatypes

Note: The boolean datatype is a boolean value which technically allows values of either 0 and false; or 1 and true.

Signal Information

The vehicle signal Vehicle.OBD.DriveCycleStatus.IsMILOn is a Sensor.

The vehicle signal Vehicle.OBD.DriveCycleStatus.IsMILOn is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.DriveCycleStatus.IsMILOn is e367394c9a075eef8fd66499e3d9cf14

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.9 - EthanolPercent

Full qualified VSS Path: Vehicle.OBD.EthanolPercent
Description: PID 52 - Percentage of ethanol in the fuel
flowchart LR Vehicle-->OBD OBD-->EthanolPercent

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.EthanolPercent
[get]  OK
Vehicle.OBD.EthanolPercent: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.EthanolPercent 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.EthanolPercent

Data Type & Unit

Path Vehicle.OBD.EthanolPercent VSS: Addressing nodes
Data type float VSS: Datatypes
Unit percent VSS: Units
Label percent
Description Relation measured in percent VSS: Sensors & Actuators
Domain relation

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.EthanolPercent is a Sensor.

The vehicle signal Vehicle.OBD.EthanolPercent is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.EthanolPercent is a207e7de17e1520c894b412af6f2522c

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.10 - EVAPVaporPressureAbsolute

Full qualified VSS Path: Vehicle.OBD.EVAPVaporPressureAbsolute
Description: PID 53 - Absolute evaporative purge (EVAP) system pressure
flowchart LR Vehicle-->OBD OBD-->EVAPVaporPressureAbsolute

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.EVAPVaporPressureAbsolute
[get]  OK
Vehicle.OBD.EVAPVaporPressureAbsolute: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.EVAPVaporPressureAbsolute 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.EVAPVaporPressureAbsolute

Data Type & Unit

Path Vehicle.OBD.EVAPVaporPressureAbsolute VSS: Addressing nodes
Data type float VSS: Datatypes
Unit kPa VSS: Units
Label kilopascal
Description Pressure measured in kilopascal VSS: Sensors & Actuators
Domain pressure

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.EVAPVaporPressureAbsolute is a Sensor.

The vehicle signal Vehicle.OBD.EVAPVaporPressureAbsolute is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.EVAPVaporPressureAbsolute is ef188a1e1a1356f7bc425081e3e00805

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer -128 127
uint16 unsigned 16-bit integer 0 65535
int16 signed 16-bit integer -32768 32767
uint32 unsigned 32-bit integer 0 4294967295
int32 signed 32-bit integer -2147483648 2147483647
uint64 unsigned 64-bit integer 0 2^64 - 1
int64 signed 64-bit integer -2^63 2^63 - 1
boolean boolean value 0/false 1/true
float floating point number -3.4e -38 3.4e 38
double double precision floating point number -1.7e -300 1.7e 300
string character string n/a n/a

Min, max and default values defined in a Vehicle Signal Specification must be in the supported range of the data type.

5.1.5.11 - EVAPVaporPressureAlternate

Full qualified VSS Path: Vehicle.OBD.EVAPVaporPressureAlternate
Description: PID 54 - Alternate evaporative purge (EVAP) system pressure
flowchart LR Vehicle-->OBD OBD-->EVAPVaporPressureAlternate

Eclipse Leda: Usage Example

In Eclipse Kuksa.VAL Databroker CLI:

$ databroker-cli
sdv.databroker.v1 > connect
[connect] OK
sdv.databroker.v1 > get Vehicle.OBD.EVAPVaporPressureAlternate
[get]  OK
Vehicle.OBD.EVAPVaporPressureAlternate: ( NotAvailable )
sdv.databroker.v1 > set Vehicle.OBD.EVAPVaporPressureAlternate 0
[set]  OK

Digital Auto: Playground

playground.digital.auto provides an in-browser, rapid prototyping environment utilizing the COVESA APIs for connected vehicles.

Vehicle Model Direct link to Vehicle Signal
ACME Car (EV) v0.1 Vehicle.OBD.EVAPVaporPressureAlternate

Data Type & Unit

Path Vehicle.OBD.EVAPVaporPressureAlternate VSS: Addressing nodes
Data type float VSS: Datatypes
Unit Pa VSS: Units
Label pascal
Description Pressure measured in pascal VSS: Sensors & Actuators
Domain pressure

Note: The float datatype is a floating point number which technically allows values between -3.4e ^ -38 and 3.4e ^ 38

Signal Information

The vehicle signal Vehicle.OBD.EVAPVaporPressureAlternate is a Sensor.

The vehicle signal Vehicle.OBD.EVAPVaporPressureAlternate is a Signal.

UUID

Each vehicle signal is identified by a Universally Unique Identifier (UUID)

The UUID for Vehicle.OBD.EVAPVaporPressureAlternate is 68eaba3c79975d61bc35b92cd3e5e8d0

Feedback

Do you think this Vehicle Signal specification needs enhancement? Do you want to discuss with experts? Try the following ressources to get in touch with the VSS community:

Enhancement request Create COVESA GitHub Issue
Join COVESA www.covesa.global
Discuss VSS on Slack w3cauto.slack.com
VSS Data Experts on Google Groups covesa.global data-expert-group

About VSS

The Vehicle Signal Specification (VSS) is an initiative by COVESA to define a syntax and a catalog for vehicle signals. The source code and releases can be found in the VSS github repository.

Supported datatypes

The following is a list of VSS supported built-in datatypes:

Name Type Min Max
uint8 unsigned 8-bit integer 0 255
int8 signed 8-bit integer