CANoe ASAM HILAPI Support

Version 1.0 2011-03-14 Application Note AN-IND-1-014

Author(s) Restrictions Abstract Michael Stephan Public Document The ASAM AE HIL 1.0 specification defines an API for testing ECUs in Hardware-In-TheLoop simulators. This document describes CANoe support for these software interfaces.

Table of Contents 1.0 1.1 1.2 2.0 2.1 2.2 2.3 3.0 3.1 3.1.1 3.2 3.2.1 3.2.2 3.2.2.1 3.2.2.2 3.2.2.3 4.0 5.0 Overview ..........................................................................................................................................................1 Use Case / Motivation ...................................................................................................................................1 CANoe as a HIL Platform ..............................................................................................................................2 HILAPI Support in CANoe ...............................................................................................................................4 Supported APIs .............................................................................................................................................4 Interface Concept ..........................................................................................................................................4 Interface Configuration ..................................................................................................................................4 HILAPI Implementation ....................................................................................................................................7 HILAPI ...........................................................................................................................................................7 CANoe-Specific Interface ...........................................................................................................................7 Model Access Port ........................................................................................................................................9 CANoe-Specific Interfaces..........................................................................................................................9 Model Access Port ......................................................................................................................................9 Variable Access .......................................................................................................................................9 Signal Generators ..................................................................................................................................10 Capturing................................................................................................................................................10 Additional Resources .....................................................................................................................................10 Contacts.........................................................................................................................................................11

1.0 Overview
CANoe provides open programming interfaces for use with test automation systems, including CANoe COM Server, the FDX protocol and CANoe MATLAB/Simulink. From version 7.5, CANoe also supports parts of the ASAM AE HIL 1.0 specification. It is based on version 1.0.0 of the specification, which was the current release at the time of development.

1.1 Use Case / Motivation

HIL simulators typically consist of various hardware components, sometimes from different manufacturers, which are usually integrated into the overall test system via proprietary software inter-faces. In the ASAM AE HIL API specification, these interfaces are designated as drivers.

1 Copyright 2011 - Vector Informatik GmbH Contact Information: www.vector.com or +49-711-80 670-0

CANoe ASAM HILAPI Support

Figure 1: HIL testbench architecture (source: ASAM AE HIL API specification) Having different driver APIs complicates the modification, extension and maintenance of the test system in a number of ways: There is a tight linkage between the test automation software and the hardware used. This makes changing one of these components almost impossible. Test cases can't be swapped across different test systems because the hardware is controlled via different drivers. It is time-consuming to combine test automation software from one manufacturer with another manufacturer's test hardware. Experience with using and programming a test system for one manufacturer does not easily translate to other manufacturers' systems. This results in additional staff training costs. Migration to newer, more up-to-date test systems is hampered by compatibility issues and proprietary data formats. It is therefore not possible to meet the requirement that test scripts can be swapped by manufacturers and suppliers.

The ASAM AE HIL specification addresses these problems by defining a uniform software inter-face for test hardware. The software interface is divided into different application domains such as model access, diagnostics, electrical error simulation, measurement and calibration.

1.2 CANoe as a HIL Platform

CANoe can be used in a wide range of HIL applications, which may have different requirements. In the case of small and mid-sized HIL systems with moderate realtime requirements and moderate levels of complexity, CANoe in combination with the Vector VT system provides everything needed to implement a HIL system: Test script control and execution platform Realtime-capable execution platform for simple environment models Signal conditioning
2 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

Sensor/actuator simulation as interface to the SUT (system under test) Network communication with the SUT, including RBS (remaining bus simulation) Automatic and/or autonomous execution (standalone mode) if needed

Figure 2: CANoe and VT system as a mid-sized HIL system Combining the VT system, which is tailored to the electrical requirements of automotive ECUs, with cost-effective, PC-based HIL computers makes using these standard products an attractive option for both component and integration tests. Large HIL systems, on the other hand, meet the highest requirements in terms of realtime-capability and model complexity. Such systems are often based on hardware components from several manufacturers. CANoe can also be successfully integrated into such systems, where it is typically responsible for the network interface to the SUT as well as the remaining bus simulation.

Figure 3: CANoe as a component in a larger HIL assembly

3 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

2.0 HILAPI Support in CANoe

2.1 Supported APIs
In CANoe, all important values can be mapped to internal variables, i.e. so-called environment and system variables. System variables in CANoe can be accessed via the ASAM HIL API. Variables are read and written in the ASAM HIL API via the Model Port. The ASAM HIL API implementation for CANoe therefore supports the reading and writing of model variables via the Model Port.

2.2 Interface Concept

The CANoe HILAPI is implemented as a .NET component, which implements the ASAM HIL API. Data is exchanged via CANoe's FDX protocol (read/write model variables). The CANoe FDX protocol is a UDP/IP-based software interface that enables the rapid exchange of CANoe system and environment variables as well as bus signals.

Figure 4: CANoe HILAPI interface concept

2.3 Interface Configuration

CANoe FDX description files are used to configure the CANoe HILAPI for accessing variables. The variables to be exchanged via FDX are arranged into data groups. The usual procedure is to define at least one group of read variables and one group of write variables in the description file. The actual settings that determine which group is read and which group is written are specified when the CANoe HILAPI is initialized. For this reason, the FDX description files need both to be included in the CANoe configuration (Options|Configuration Settings|FDX Protocol) and to be available in the test automation system, the HILAPI application.

4 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

Example: The aim is to read in two model variables (ModelOutput1 and ModelOutput2) and write two model variables (ModelInput1 and ModelInput2) via the CANoe HILAPI.

Control PC HILAPI

ModelInputs

ModelOutputs

Figure 5: Input and output of model variables Please take the following steps in order to configure the CANoe HILAPI: 1. Configure the required system variables in CANoe.

Figure 6: Configuring the system variables 2. Create an FDX description file with one group each for the read and write variables. Please take special care to specify the memory layout of the data groups correctly (group size, data types, data values and offsets). For more information about the FDX protocol, please see chapter 4.0. <?xml version="1.0" encoding="ISO-8859-1"?> <canoefdxdescription version="1.0"> <datagroup groupID="1" size="16">
5 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

<identifier>ModelInputs</identifier> <item type="double" size="8" offset="0"> <sysvar namespace="HILAPI" name="ModelInput1"/> </item> <item type="double" size="8" offset="8"> <sysvar namespace="HILAPI" name="ModelInput2"/> </item> </datagroup> <datagroup groupID="2" size="16"> <identifier>ModelOutputs</identifier> <item type="double" size="8" offset="0"> <sysvar namespace="HILAPI" name="ModelOutput1"/> </item> <item type="double" size="8" offset="8"> <sysvar namespace="HILAPI" name="ModelOutput2"/> </item> </datagroup> </canoefdxdescription> 3. Configure the FDX description file in CANoe.

Create your test program in a Microsoft .NET language. For more information about the CANoe HILAPI implementation, please see chapter 3.0. A test script could, for example, look like this:
6 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

static public bool RunTest(IMAPort maPort, ITestEnvironment environment) { environment.Output("Starting test..."); IFloatValue value1 = new FloatValue(); IFloatValue value2 = new FloatValue(); for (int i = 0; i < 100; ++i) { IFloatValue value3 = (FloatValue)maPort.Read("HILAPI/ModelOutput1"); IFloatValue value4 = (FloatValue)maPort.Read("HILAPI/ModelOutput2"); value1.Value = value3.Value + value4.Value; value2.Value = value3.Value * value4.Value; maPort.Write("HILAPI/ModelInput1", value1.Value); maPort.Write("HILAPI/ModelInput2", value2.Value); environment.Wait(TimeSpan.FromMilliseconds(50)); } environment.Output("Test completed"); return true; }

3.0 HILAPI Implementation

3.1 HILAPI 3.1.1 CANoe-Specific Interface

The ASAM AE HIL API specification requires manufacturer-specific APIs in order to initialize and control an actual HIL system. In the case of CANoe, there are very few functions for the HILAPI itself. They take on the following tasks: Generating and initializing the HILAPI, including FDX communication Starting the HILAPI Stopping the HILAPI

public class HILAPI : IHILAPI, IDisposable { public HILAPI(); public void Initialize(string address, int port, List<FDXDescription> descriptions);
7 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

public bool Start(int timeout); public void Stop(bool stopTarget); // .. } To initialize the HILAPI, you need to specify the host address of the UPD port for FDX communication (default: 2809). The last parameter contains a list of FDX description objects: public class FDXDescription { public FDXDescription(); public FDXDescription(string filename); public string FileName; public Dictionary<ushort, FDXGroup> ReadGroups; public Dictionary<ushort, FDXGroup> WriteGroups; public void AddReadGroup(FDXGroup group); public void AddWriteGroup(FDXGroup group); } An FDX description object contains the path to an FDX description file, which in turn contains the variables to be transmitted, organized in groups. You use the FDX description object to specify which FDX variable groups are read (i.e. received, AddReadGroup) and which are written (i.e. sent, AddWriteGroup) by the HILAPI. The group description structure is defined in the following way: public struct FDXGroup { public FDXGroup(ushort id); public FDXGroup(ushort id, uint cycleTime); public ushort Id; public uint CycleTime; } The identifier (Id) specifies the FDX group within the FDX description file. You use the cycle time (CycleTime) to specify how often the respective group is transmitted. Future versions of CANoe will support evaluation of the cycle time specified in this structure.

8 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

3.2 Model Access Port 3.2.1 CANoe-Specific Interfaces

The CANoe HILAPI has a CreateMAPort method that is used to instantiate Model Access Port objects: public class HILAPI : IHILAPI , IDisposable { public IMAPort CreateMAPort(); // .. } The IMAPort interface enables access to model variables, signal generators and recordings (capturing).

3.2.2

Model Access Port

The IMAPort interface is defined in the following way: public interface IMAPort : IPort { IList<string> TaskNames { get; } IList<string> VariableNames { get; } ICapture CreateCapture(string task); ISignalGenerator CreateSignalGenerator(); DataType GetDataType(string variableName); bool IsReadable(string variableName); bool IsWritable(string variableName); IBaseValue Read(string variableName); void Write(string variableName, IBaseValue value); } The CANoe simulation does not have a task concept. This means that the TaskNames property returns an empty list.

3.2.2.1

Variable Access

The VariableNames property returns a list of the variable names in use. This corresponds to the variable names contained in the configured FDX description. You can use the GetDataType, IsReadable and IsWritable methods to query details about the variables in use. The Read and Write methods enable read and write access to the variables. Please note that variables need to be configured for the required access type via the CANoe HILAPI. If you want to read and write to a variable, you need to include it in two FDX groups (the read group and the write group). The Seat Test HILAPI Demo Configuration CANoe sample configuration illustrates variable access.

9 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

3.2.2.2

Signal Generators

The CreateSignalGenerator method is used to create signal generators. This API will be supported in future CANoe versions.

3.2.2.3

Capturing

The CreateCapture method is used to create capture objects. This API will be supported in future CANoe versions.

4.0 Additional Resources

ASAM AE HIL SPECIFICATION
http://www.asam.net/

VECTOR MANUAL
CANoe_FDX_Protocol_EN.pdf CANoe FDX Protocol

CANOE DEMO
Seat Test HILAPI Demo Configuration

10 Application Note AN-IND-1-014

CANoe ASAM HILAPI Support

5.0 Contacts
Germany and all countries not named below: Vector Informatik GmbH Ingersheimer Str. 24 70499 Stuttgart GERMANY Phone: +49 711-80670-0 Fax: +49 711-80670-111 E-mail: info@de.vector.com United Kingdom, Ireland: Vector GB Ltd. Rhodium, Central Boulevard Blythe Valley Park Solihull, Birmingham West Midlands B90 8AS UNITED KINGDOM Phone: +44 121 50681-50 Fax: +44 121 50681-69 E-mail: info@uk.vector.com USA, Canada, Mexico: Vector CANtech, Inc. 39500 Orchard Hill Place, Suite 550 Novi, MI 48375 USA Phone: +1 248 449 9290 Fax: +1 248 449 9704 E-mail: info@us.vector.com France, Belgium, Luxemburg: Vector France SAS 168 Boulevard Camlinat 92240 Malakoff FRANCE Phone: +33 1 42 31 40 00 Fax: +33 1 42 31 40 09 E-mail: information@fr.vector.com China: Vector Informatik GmbH Shanghai Representative Office Room 1701, No.398 Jiangsu Road Changning District Shanghai 200050 P.R. CHINA Phone: +86 21 6432 53530 Fax: +86 21 6432 5308 E-mail: info@cn.vector.com Japan: Vector Japan Co. Ltd. Seafort Square Center Bld. 18F 2-3-12, Higashi-shinagawa, Shinagawa-ku Tokyo 140-0002 JAPAN Phone: +81 3 5769 7800 Fax: +81 3 5769 6975 E-mail: info@jp.vector.com Sweden, Denmark, Norway, Finland, Iceland: VecScan AB Theres Svenssons Gata 9 41755 Gteborg SWEDEN Phone: +46 31 764 76 00 Fax: +46 31 764 76 19 E-mail: info@se.vector.com India: Vector Informatik India Pvt. Ltd. 4/1/1/1, Sutar Icon, Sus Road, Pashan, Pune - 411 021 INDIA Phone: +91 9673 336575 Fax: +91 20 2587 2025 E-mail: info@in.vector.com Korea: Vector Korea IT Inc. #1406, Mario Tower, 222-12 Guro-dong, Guro-gu Seoul, 152-848 REPUBLIC OF KOREA Phone: +82 2 807 0600 Fax: +82 2 807 0601 E-mail: info@kr.vector.com

11 Application Note AN-IND-1-014