Behind the Scenes

This page explains how ECU Project Synchronization selects, compares, and merges the shared configuration.

What Publishing Does

For each contract, dvcfg-b project publish does the following:

It collects the elements selected by the contract in the active module configurations of the publishing project, see Sync Job Contracts.
It adds the parent containers and module configurations of these elements, so the elements keep their position.
It writes the result as <name>_published.arxml into the sync job data folder and adds the checksum file <name>_checksum.md5 and the file <name>_shortDef.json.

Publishing doesn’t change the configuration values of the publishing project. Existing files of the same contract in the sync job data folder are overwritten.

What Synchronizing Does

For each contract, dvcfg-b project sync does the following:

It loads the file <name>_published.arxml from the sync job data folder. Other files in the folder aren’t loaded. If the folder contains no <name>_published.arxml, but other ARXML files whose names start with the contract name, the log names these files in a warning and the contract is reported as Failed.
It creates the module configurations that exist only in the published data, see Missing Module Configurations.
It compares the module configurations that are active in both the published data and the consuming project.
It takes over the differences, following the rules below.
It marks each synchronized element in the consuming project with an annotation whose origin is DV:EcuProjectSync and whose label contains the contract name.
If the comparison found differences, it writes the sync report <name>.html into the log folder of the consuming project.

After all contracts are processed, the command saves the consuming project, even if some contracts are Incomplete.

Merge Rules

Situation in the consuming project	Result of the synchronization
An element of the published data is missing.	The element is created.
An element has a different value than in the published data.	The published value overwrites the value of the consuming project.
An element exists only in the consuming project and was never synchronized.	The element is kept.
An element was synchronized by the same contract before, but isn’t part of the published data anymore.	The element is deleted.
A module configuration of the published data is missing.	The module configuration is created, see Missing Module Configurations.
A module configuration uses a different module definition than in the published data.	The module configuration isn’t synchronized. Its elements and their annotations stay unchanged.

Situation in the consuming project

Result of the synchronization

An element of the published data is missing.

The element is created.

An element has a different value than in the published data.

The published value overwrites the value of the consuming project.

An element exists only in the consuming project and was never synchronized.

The element is kept.

An element was synchronized by the same contract before, but isn’t part of the published data anymore.

The element is deleted.

A module configuration of the published data is missing.

The module configuration is created, see Missing Module Configurations.

A module configuration uses a different module definition than in the published data.

The module configuration isn’t synchronized. Its elements and their annotations stay unchanged.

Each change is checked on its own. If a change isn’t allowed, for example because the element is pre-configured or the model validation rejects it, only this change is skipped. All other changes are still taken over, and the contract is reported as Incomplete.

If you don’t want to keep the result of a synchronization, discard the changes of the consuming project in your version control system.

Missing Module Configurations

If the published data contains a module configuration that isn’t active in the consuming project, dvcfg-b project sync creates it like a manual module activation:

The module configuration gets the short name and the module definition of the published data. It’s created in the package of the active ECU configuration, for example /ActiveEcuC.
It gets the same initial content as a manually activated module, for example mandatory containers and parameters with their recommended or default values.
The published content is then synchronized like the content of any other module configuration.

The log shows The module '<module>' of the published data has been created with the module definition '<definition>'.

Only the module definition of the published data is used. The module configuration isn’t created in the following cases:

The module definition of the published data doesn’t exist in the consuming project, even if the consuming project contains another implementation of the module, for example a VTT module instead of the real-target module.
The consuming project already contains the maximum number of module configurations that the module definition allows, for example a single-instance module with a different short name.
Another element already uses the short name, or the module activation is rejected.

In these cases, the log shows a warning with the reason, for example The module '<module>' of the published data could not be created: the module definition '<definition>' is not available in the project. The other module configurations are still synchronized, and the contract is reported as Incomplete.

If a created module configuration is later removed from the published data, it stays in the consuming project. Only its synchronized elements are deleted.

Role of the Contract on Both Sides

On the publishing side, the contract defines which elements are exported. On the consuming side, the contract only identifies the sync job: dvcfg-b project sync uses its name to find the published data. The content that is synchronized is determined entirely by the published data.

Changing only the consuming project’s copy of a contract therefore has no effect. Changes take effect when the publishing project publishes with the changed contract. The only exception is the name: if you rename the contract on the consuming side only, the published data isn’t found anymore.

It’s good practice to keep one contract file in a shared location and pass it to both commands.

Pitfalls

Renamed published data: dvcfg-b project sync only finds published data with the exact file name <name>_published.arxml. Don’t rename the files of the published data.
ARXML files from other sources: dvcfg-b project sync only accepts published data that dvcfg-b project publish created. Other ARXML files aren’t loaded, even if they’re named like the contract, for example a job contract export of DaVinci Configurator 5 (<name>.arxml).
Changed contracts: If you change a contract, for example to share more elements, publish again. Elements that were synchronized before but aren’t selected by the changed contract anymore are deleted from the consuming project at the next synchronization.
Changes in the consuming project: Elements that are part of the published data are overwritten at the next synchronization. Change shared elements in the publishing project and publish them again, instead of changing them in the consuming project.
Different BSW Packages: Synchronization needs the same module definitions in both projects. If the publishing project and a consuming project use different versions of a module, the module configuration isn’t synchronized. Update both projects to compatible BSW Packages first.
Different ECU configuration packages: Instance paths contain the package of the active ECU configuration, for example /ActiveEcuC. Use the same package in all projects.
Repeated synchronization: dvcfg-b project sync always compares the complete published data with the consuming project, even if the published data hasn’t changed since the last synchronization. If nothing has changed, the project stays unchanged and the contract is reported as Synchronized.