The OTX-Runtime API (short OTX-Runtime) is a programming interface for the easy, fast and reliable execution of OTX procedures in own applications. It works independently even without the OTX Development Environment and is available for Windows and Linux. The API is available for C++, DotNet and Java. It can communication to ECUs with an standardized diagnostic runtime system (MVCI) via the DiagManager and it has extensive possibilities for seamless integration into existing systems and infrastructures. The test logic is standardized in ISO 13209 (OTX) and is available inside standardized PTX files.

Overview

The OTX-Runtime can be integrated into own applications via the OTX-Runtime API. The application integrates the OTX-Runtime API within its own process. For each started OTX procedure, the API starts a new OTX-Runner. Depending on the transport layer, the OTX-Runner is executed in a new process (transport layers SOCKETS and PIPES) or as a thread in the process of the application (transport layer RAW, C++ OTX-Runtime API only), see creating of RuntimeManager.

The diagnostic communication is based on the OTX-DiagManager. The DiagManager is a software component between the OTX-Runtime API and various, interchangeable diagnostic runtime systems, e.g. standardized MVCI-Server or proprietary diagnostic runtime systems. The OTX-DiagManager can also be used stand-alone. Depending on the transport layer, the DiagManager can be in another process or in the process of the application, see creating of DiagManager.

The configuration of the diagnostic runtime system is handled via the OTX-DiagManager, see IDiagConfiguration. The same applies to DoIP. The DoIP handling is manged in IComInterface.

The OTX runtime allows the user to use their own implementations for OTX extensions with access to external systems at runtime. The user can use own implementations for the following OTX extensions:

CommonDialogs
ExternalServiceProvider
HMI
i18n
Logging
Measure
SQL
StateVariable (ContextVariable)
TestResultHandling

To do this, the user must implement an interface available on the API, see CustomImplementation. For example iHMI for the OTX HMI extension, see ICustomScreenImplementation. As shown in the picture this custom implementation will handle the real screens (e.g. WPF or HTML) inside its own process.

Main User Cases

The main use cases are loading of OTX projects (PTX files), browsing the OTX data structure, executing of procedures and integration of external systems, like HMI.

Browsing of OTX data structureExecution of OTX proceduresIntegration into arbitrary target systems

Note: For the development of OTX projects please see OTX Development Environment.

Main Features

Implementation in native C++
- 32- and 64 bit systems
- Windows and Linux
Functions for browsing and execution of OTX
Access to external systems (OTX-Mapping)
- Interface interface for integrating own implementations
  - iHMI, iCommonDialogs
  - iExternalServiceProvider
  - iI18n, iMeasure, iLogging, iSQL
  - iStateVariable, iContextVariable
- EMOTIVE delivers default implementations
  - For iHMI -> AssemblyScreen, HtmlScreen
  - For iMeasure -> AssemblyDeviceService
  - For iExternalServiceProvider, iStateVariable and iContextVariable -> DotNetAssembly via reflection
  - For iLogging -> DefaultLogging
  - All implementations relevant to OTX mapping run in their own process
  - No fall-back implementation in OTX runtime, i.e. if there is no implementation of an interface, a NotImplementedException is thrown
- The user can use his own implementations (custom)
  - To do this, he must implement the appropriate interfaces (e.g. iHMI)
Entire diagnostic configuration + DoIP handling takes place via OTX-DiagManager
Synchronous and asynchronous behavior of Procedure execution.
Thread safe execution
Multi-Instance and Multi-Threading capable
Long time running stable
High runtime performance

First Steps

When using the OTX-Runtime API for the first time, the following steps are recommended.

Install the OTX-Runtime API, see Installation
If diagnostic communication is needed, install the OTX-DiagManager API, see Installation

Note: A Diagnostic Runtime System must be installed, configured and accessible. It is not part of the OTX-Runtime API.
Create a simple "Hello World" PTX file in OTX Development Environment without diagnostic communication

Note: The PTX file must contain the executable binary format.
Test the created "Hello World" PTX inside Runtime API Sample Program

Note: The PTX should be executed right, otherwise repeat previous steps
If diagnostic communication is needed, create a simple "Hello World" PTX file in OTX Development Environment with diagnostic communication and execute it inside Runtime API Sample Program
Fulfill the General Preconditions
Write a very simple application using the Code Example
Write a more complex application using the ApiSampleProgramCode of the Runtime API Sample Program

General Preconditions

Before usage of the OTX-Runtime API the following general preconditions must be met:

A valid license key must be entered, see LicenseManager
If diagnostic communication is needed, the DiagManager must be started

Note: A DiagRuntimeSystem must be installed, configured and accessible, see Installation.
An instance of a RuntimeManager must be created

Note: A RuntimeManager instance can be created inside the main thread or inside a new thread.
All needed custom implementations should be registered at the API, see CustomImplementation
A PTX or PPX file must be loaded, see LoadPtx

Note: The PTX file must contain the executable binary format, which can be created inside the OTX Development Environment.

The settings of project, custom implementations, tracing etc. should be handled, see Configuration

General Usage Example

The following sequence diagram shows the general interaction between application, OTX-Runtime, CustomImplementation, DiagManager and ECU.

General interaction between application, OTX-Runtime, CustomImplementation, DiagManager and ECU

Code Example

The basic proceeding how the OTX-Runtime API can be used is described in the following pseudo code example. The example executes the main procedure of a PTX file.

Note: How the OTX-Runtime API can be used in detail can be seen in the source code example of the Runtime API Sample Program.

// Generally applicable Pseudo-Code example
// ========================================
// Please note that the exact syntax of C++, DotNet and Java is different!
 
void main()
{
    // Release the license manager
    // ===========================
    OpenTestSystem.Otx.Runtime.Api.License.LicenseManager.SetLicenseKey("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX");
 
    // Create the RuntimeManager and connect it to DiagManager
    // =======================================================
    // Creates the RuntimeManager at automatic selected port connected with DiagManager at port 8888
    // Please note that the DiagManager must be started, e.g. via DiagManagerSample.exe!
    OpenTestSystem.Otx.Runtime.Api.IRuntimeManager runtimeManager = null;
    runtimeManager = OpenTestSystem.Otx.Runtime.Api.RuntimeManagerFactory.CreateSocketRuntimeManager(0, 8888);
 
    // Create callbacks for RuntimeManager events
    // ==========================================
    runtimeManager.OnProcedureStarted += ProcedureStartedHandler(ProcedureStarted);
    runtimeManager.OnProcedureFinished += ProcedureFinishedHandler(ProcedureFinished);
    runtimeManager.OnProcedureStopped += ProcedureStoppedHandler(ProcedureStopped);
    runtimeManager.OnProcedureAborted += ProcedureAbortedHandler(ProcedureAborted);
 
    // Set trace folder and level
    RuntimeConfig.Instance.TraceFolder = "C://");
    RuntimeConfig.Instance.TraceLevel = TraceLevels.All;
 
    // Set CustomScreen implementations
    // ================================
    // Create custom implementation and set to the RuntimeManager
    CustomScreenImplementation customScreenImplementation = new CustomScreenImplementation();
    runtimeManager.SetCustomImplementation(customScreenImplementation);
 
    // Load PTX file and browse OTX data structure
    // ===========================================
    OpenTestSystem.Otx.Runtime.Api.Project.IProject project = runtimeManager.LoadPtx("C:\\HelloWorldSample1.ptx");
    OpenTestSystem.Otx.Runtime.Api.Otx.IProcedure procedure = project.MainProcedure;
 
    if (procedure != null)
    {
        if (procedure.Parameters.Size > 0)
        {
            // Assume the first parameter is an InParameter of data type String
            OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureParameter parameter = procedure.Parameters[0];
            if (parameter.DataType == "String" && parameter is OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter)
            {
                (OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter) parameter.Value = "Hello World";
            }
        }
 
        // Executes the procedure synchronous
        // ==================================
        OpenTestSystem.Otx.Runtime.Api.IRuntimeContext runtimeContext = runtimeManager.Execute(procedure);
 
        if (runtimeContext.IsFinished)
        {
            // Procedure finished successfully
        }
        else if (runtimeContext.IsStopped)
        {
            // Procedure was stopped by the user
        }
        else if (runtimeContext.HasRuntimeException)
        {
            // Procedure was terminated by a runtime exception
        }
        else if (runtimeContext.HasOtxException)
        {
            // Procedure was terminated by an OTX exception
        }
        else
        {
            // Procedure was finished by another reason
        }
    }
}
 
// Callback - this method is called after a Procedure was started
private void ProcedureStarted(IRuntimeContext context)
{
    // Do something ...
}
 
// Callback - this method is called after a Procedure was finished
private void ProcedureFinished(IRuntimeContext context)
{
    // Do something ...
}
 
// Callback - this method is called after a Procedure was stopped
private void ProcedureStopped(IRuntimeContext context)
{
    // Do something ...
}
 
// Callback - this method is called after a Procedure was aborted
private void ProcedureAborted(IRuntimeContext context)
{
    // Do something ...
}

Table of Contents