ASAM ODS EXD-API MDF4 plugin

This repository contains a ASAM ODS EXD-API plugin that uses asammdf to read the ASAM MDF4 files.

It is built on the ods-exd-api-box helper library which provides the gRPC server infrastructure and proto stubs.

Find more tools supporting your digital transformation in the Peak Solution Git Repo.

Content

Implementation

• src/asam_ods_exd_api_mdf4/external_data_file.py
  Implements the ExdFileInterface from ods-exd-api-box to access MDF4 files using asammdf. Also contains the entry point to run the gRPC service.

Tests

• test_exd_api.py
  Some basic tests on example files in data folder.
• example_access_exd_api_mdf4.ipynb
  jupyter notebook the shows communication done by ASAM ODS server or Importer using the EXD-API plugin.

Development

Setup

Install uv and then install the project with dev dependencies:

uv sync --group dev

Run Tests

uv run python -m unittest discover tests

Run Plugin Locally

Use an explicit IPv4 bind address on Windows to avoid IPv6 bind issues:

uv run asam-ods-exd-api-mdf4 --bind-address 127.0.0.1 --port 50051

Stop the server with Ctrl+C. A non-zero exit code after interruption is expected.

Optional Parameters

The file handler accepts optional parameters in the EXD-API Identifier.parameters string. Parameters are separated with semicolons, for example:

parameters="values_raw=True;values_ignore_value2text_conversions=True"

values_raw

When set to True, the plugin reads the raw MDF samples without applying channel conversion rules. This is useful when you want the original stored values instead of the converted engineering values.

Example:

exd_api.Identifier(url=file_uri, parameters="values_raw=True")

values_ignore_value2text_conversions

When set to True, the plugin ignores value-to-text conversions and returns the underlying numeric or non-string values instead of the text labels created by the conversion tables. This is especially relevant for channels whose MDF conversion rules map numeric values to strings.

Example:

exd_api.Identifier(url=file_uri, parameters="values_ignore_value2text_conversions=True")

The behavior is covered by the conversion tests in tests/test_exd_api_string_conversion.py, where the same MDF file is read with and without these parameters to confirm the returned data types and sample values.

Run Plugin With uvx

Run the latest published package without installing it into the current project environment:

uvx asam-ods-exd-api-mdf4 --bind-address 127.0.0.1 --port 50051

Code Quality

uv sync --group dev                    # 1. Install all dependencies
uv run ruff format .                   # 2. Format code
uv run ruff check --fix .              # 3. Fix lint violations
uv run mypy src/asam_ods_exd_api_mdf4/external_data_file.py      # 4. Type check
uv run python -m unittest discover tests  # 5. Run tests

Docker

Docker Image Details

The Docker image for this project is available at:

ghcr.io/peak-solution/asam-ods-exd-api-mdf4:latest

This image is automatically built and pushed via a GitHub Actions workflow. To pull and run the image:

docker pull ghcr.io/peak-solution/asam-ods-exd-api-mdf4:latest
docker run -v /path/to/local/data:/data -p 50051:50051 ghcr.io/peak-solution/asam-ods-exd-api-mdf4:latest

Using the Docker Container

To build the Docker image locally:

docker build -t asam-ods-exd-api-mdf4 .

To start the Docker container:

docker run -v /path/to/local/data:/data -p 50051:50051 asam-ods-exd-api-mdf4

have a look at start options to figure out how to customize the behavior of the EXD-API plugin.

Architecture and Usage in ODS Server

sequenceDiagram

actor CLIENT as Client
participant PDTT as 🛠️Importer
participant PODS as 🗃️ASAM ODS server
participant PLUGIN as 📊EXD-API plugin
participant FILE as 🗂️File Storage

autonumber

opt Import phase
  FILE ->>+ PDTT: New file shows up
  PDTT ->>+ PLUGIN : Get Structure
  PLUGIN -> FILE: Extract content information
  PLUGIN ->> PLUGIN: Create Structure
  PLUGIN ->>- PDTT: Return Structure
  PDTT ->> PODS: Import ODS structure
  Note right of PDTT: Create hierarchy<br/>AoTest,AoMeasurement,...
  PDTT ->>- PODS: Add External Data info
  Note right of PDTT: Attach AoFile ... for external data<br/>AoFile,AoSubmatrix,AoLocalColumn,...
end

Note over CLIENT, FILE: Now we can work with the imported files

loop Runtime phase
  CLIENT ->> PODS: Establish ODS session
  CLIENT ->> PODS: Work with meta data imported from structure
  CLIENT ->> PODS: Access external channel in preview
  PODS ->> PLUGIN: GetValues
  PLUGIN ->> FILE: Get Channel values
  PLUGIN ->> PODS: Return values of channels
  PODS ->> CLIENT: Return values needed for plot
end