ods-exd-api-box

A Python helper package to build ASAM ODS EXD-API gRPC plugins/services.

What is ASAM ODS EXD-API?

The ASAM ODS standard defines how measurement and test data is stored and managed. The EXD-API (External Data API) is a gRPC interface that allows ODS servers to read data from external file formats (TDMS, CSV, HDF5, …) without importing the raw data.

An EXD-API plugin acts as a bridge: the ODS server calls the plugin to inspect a file’s structure (groups, channels, data types) and to retrieve channel values on demand.

How this library helps

ods-exd-api-box provides the gRPC server scaffolding, protobuf wiring, file registry, and configuration handling so you can focus on the file-reading logic. It offers two interfaces at different abstraction levels:

Interface	Best for	Protobuf knowledge required?
`ExdFileInterface`	Full control over structure and value mapping	Yes
`FileSimpleInterface`	Quick plugins using pandas DataFrames	No

See Choosing an Interface for a detailed comparison.

Installation

# Core (ExdFileInterface only)
pip install ods-exd-api-box

# With pandas support (FileSimpleInterface)
pip install 'ods-exd-api-box[simple]'

Architecture Overview

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

Quick Start

Using `ExdFileInterface` (full control)

from ods_exd_api_box import ExdFileInterface, serve_plugin

class MyFileHandler(ExdFileInterface):
    # Implement create, close, fill_structure, get_values
    ...

if __name__ == "__main__":
    serve_plugin(
        file_type_name="my-format",
        file_type_factory=MyFileHandler.create,
        file_type_file_patterns=["*.myext"],
    )

Using `FileSimpleInterface` (pandas-based)

from ods_exd_api_box.simple import FileSimpleInterface, serve_plugin_simple

class MySimpleHandler(FileSimpleInterface):
    # Implement create, close, data (returns pd.DataFrame)
    ...

if __name__ == "__main__":
    serve_plugin_simple(
        file_type_name="my-format",
        file_type_factory=MySimpleHandler.create,
        file_type_file_patterns=["*.myext"],
    )

Documentation

Page	Description
Architecture	Internal wiring, call flow, how the two interfaces relate
Choosing an Interface	Side-by-side comparison of both approaches
ExdFileInterface Guide	Full-control interface with protobuf
FileSimpleInterface Guide	Pandas-based simple interface
Server Options	CLI arguments, env vars, TLS configuration
Docker Deployment	Containerizing your plugin
Real-World Plugins	Production plugins using this library