OTX-Runtime for Java  
OTX-Runtime API

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.

Table of Contents

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.

  1. Install the OTX-Runtime API, see Installation
  2. 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.

  3. Create a simple "Hello World" PTX file in OTX Development Environment without diagnostic communication

    Note: The PTX file must contain the executable binary format.

  4. Test the created "Hello World" PTX inside Runtime API Sample Program

    Note: The PTX should be executed right, otherwise repeat previous steps

  5. 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
  6. Fulfill the General Preconditions
  7. Write a very simple application using the Code Example
  8. Write a more complex application using the Code Example of the Runtime API Sample Program

General Preconditions

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

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

    Note: A DiagRuntimeSystem must be installed, configured and accessible, see Installation.

  3. An instance of a RuntimeManager must be created

    Note: A RuntimeManager instance can be created inside the main thread or inside a new thread.

  4. All needed custom implementations should be registered at the API, see CustomImplementation
  5. 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.

  1. 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;
// 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 ...
}

Related OTX document

OTX document (HelloWorldSampleDocument.otx) related to the examples above.

<?xml version="1.0" encoding="utf-8"?>
<otx xmlns="http://iso.org/OTX/1.0.0" xmlns:hmi="http://iso.org/OTX/1.0.0/HMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="id_0a4aa7adb9484acd80fd9b8cc0889d1c" name="HelloWorldSampleDocument" package="HelloWorldSample1Package1" version="1.0.0.0" timestamp="2020-04-30T15:12:52.8454075+02:00">
<procedures>
<procedure id="id_9fd318a128cd4945aa7ed8d5cd57c0b8" name="main" visibility="PUBLIC">
<realisation>
<parameters>
<inParam name="Message" id="InParameterDeclaration_9d68143af6864f9b89691051826e9f9a">
<realisation>
<dataType xsi:type="String" />
</realisation>
</inParam>
</parameters>
<flow>
<action name="ConfirmDialog1" id="ConfirmDialog_9f6feabe81034ffab0d6113e65df827f">
<realisation xsi:type="hmi:ConfirmDialog">
<hmi:title xsi:type="StringLiteral" value="Hello World" />
<hmi:message xsi:type="StringValue" valueOf="Message" />
</realisation>
</action>
</flow>
</realisation>
</procedure>
</procedures>
</otx>
OpenTestSystem.Otx.Runtime.Api.RuntimeManagerFactory
Factory class for creating runtime managers, see IRuntimeManager.
Definition: RuntimeManagerFactory.java:10
OpenTestSystem.Otx.Runtime.Api.License
Package containing all objects related to licensing.
Definition: IpcLicenseCheckerBase.java:1
OpenTestSystem.Otx::RuntimeConverter::Api::TraceLevels
TraceLevels
OpenTestSystem.Otx.Runtime.Api.RuntimeManagerFactory.CreateSocketRuntimeManager
static IRuntimeManager CreateSocketRuntimeManager(int otxRunnerPort)
Creates SocketRuntimeManager without DiagManager.
Definition: RuntimeManagerFactory.java:32
OpenTestSystem.Otx.Runtime.Api.Project
Package containing main entries: IProject and IPlayerProject.
Definition: IPlayerProject.java:1
OpenTestSystem.Otx.Runtime.Api.License.LicenseManager
Class to manage the OTX-Runtime API licenses.
Definition: LicenseManager.java:9
OpenTestSystem.Otx.Runtime.Api.Otx.IProcedure
Represents an OTX Procedure.
Definition: IProcedure.java:6
OpenTestSystem.Otx.Runtime.Api.Otx
Package for browsing at OTX data structure.
Definition: IContextVariable.java:1
OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureInParameter
Represents InParameter of a Procedure.
Definition: IProcedureInParameter.java:8
OpenTestSystem.Otx.Runtime.Api.Otx.IProcedureParameter
Represents base class for InParameter, OutParameter and InOutParameter of a Procedure.
Definition: IProcedureParameter.java:8
OpenTestSystem.Otx
Package containing all objects which are standardized according to ISO 13209 (OTX)
OpenTestSystem.Otx.Runtime
Package containing all objects for browsing and execution of OTX procedures.
Definition: opentestsystem.otx.runtime2.api/src/main/java/opentestsystem/otx/runtime/package-info.java:4
OpenTestSystem.Otx.Runtime.Api.IRuntimeManager
Runs a PTX/PPX file directly.
Definition: IRuntimeManager.java:17
OpenTestSystem
Package containing all objects related to testing inside automotive industry.
OpenTestSystem.Otx.Runtime.Api.Project.IProject
Contains Packages and settings.
Definition: IProject.java:15
OpenTestSystem.Otx.Runtime.Api.IRuntimeContext
Contains information of a Runner instance.
Definition: IRuntimeContext.java:14
OpenTestSystem.Otx.Runtime.Api
Package containing the programming interface for browsing and execution of OTX procedures in own appl...
Definition: ApiConstants.java:1
OpenTestSystem.Otx.Runtime.Api.License.LicenseManager.SetLicenseKey
static void SetLicenseKey(String licenseKey)
Sets a valid license key to release the API.
Definition: LicenseManager.java:24