Basic Open API V2.12 User s Guide

Transcription

1 Basic Open API V2.12 User s Guide

2 Copyright The data in this document may not be altered or amended without special notification from ETAS GmbH. ETAS GmbH undertakes no further obligation in relation to this document. The software described in it can only be used if the customer is in possession of a general license agreement or single license. Using and copying is only allowed in concurrence with the specifications stipulated in the contract. Under no circumstances may any part of this document be copied, reproduced, transmitted, stored in a retrieval system or translated into another language without the express written permission of ETAS GmbH. Copyright 2016 ETAS GmbH, Stuttgart The names and designations used in this document are trademarks or brands belonging to the respective owners. Document V2.0 R01 EN

3 Contents Contents 1 Introduction Safety Notice Conventions Getting started BOA packages and their contents Package: BOA Runtime Framework Package: ECU and Bus Interfaces Integration Package (EBI-IP) Package: Open Controller Driver Development Kit (OCD-DK) Package: ETAS Drivers ECU and Bus Interfaces (ED-EBI) Prerequisites How this manual is organized Getting more information Overview of BOA The purpose of BOA The structure of BOA Open Controller Drivers and the OCD Proxy The Connection Services Library OCI (Open Controller Interface) Using the OCI APIs programmatically A note on syntax General Structure and Components Controllers Concept of a controller Capabilities of a controller Configuration of a controller Status of a controller State transitions for virtual controllers The Open Session Manager Queues Self Reception Receiving bus data frames Messages Using filters Reading messages from a queue Receiving messages via a callback Receiving events Transmitting bus data frames Timers What is a timer? Controller qualities associated with timers Timer events Bus-specific OCI implementation OCI CAN specifics OCI FlexRay specifics OCI LIN specifics

4 Contents 5 CSL (Connection Service Library) Important concepts used in the CSL Trees and nodes URIs Protocol stacks How the tree of nodes is built Identifying an OCI API type: UUIDs and versions CSI API functions CSI_CreateProtocolTree() CSI_GetUriForUuid() CSI_CreateInterfaceStack() Choosing when to search for hardware Device information and licensing Authentication Backwards compatibility and API versioning API versioning Backwards compatibility Backwards compatibility from a BOA client s perspective Backwards compatibility from an OCD s perspective Troubleshooting BOA-specific problems General problems while working with BOA When compiling your software, the compiler cannot find the file OCI\oci.h You cannot find any hardware when searching using CSI Integrating ETAS Hardware into 3rd Party Software When compiling your software, the linker cannot find symbols for the OCI and/or CSI APIs When running the application, a message pops up saying: "This application has failed to start because <name>.dll was not found. Re-installing the application may fix this problem."46 10 Troubleshooting ETAS Ethernet problems Problems and Solutions BOA fails to access Hardware connected via Ethernet Network Adapter cannot be selected via Network Manager Search for Ethernet Hardware fails Glossary Appendix: Further reading Appendix: Versions of BOA APIs OCI_CAN v v1.1, added in BOA v1.2, added in BOA v1.3, added in BOA v1.4, added in BOA OCI_LIN v v1.1, added in BOA OCI_FLX v v1.1, added in BOA LIC / DEV v v1.1, added in BOA ETAS Contact Addresses

5 Figures Figures Figure 3-1: The structure of BOA, showing OCDs and the OcdProxy Figure 3-2: The structure of BOA, showing the CSL Figure 4-1: General OCI structure Figure 4-2: State chart for the virtual controller object Figure 4-3: The structure of BOA, showing the OSM Figure 4-4: Some timer events caused by connecting and disconnecting a measuring device Figure 5-1: The tree representing a connected ETAS ES910 device Figure 5-2: Binding OCI_CAN on the ES Figure 5-3: Binding OCI_CAN on the ES Figure 10-1: The ETAS Network Settings Tool

6 Introduction 1 Introduction BOA (Basic Open API) is a framework that provides a standard interface between automotive measurement / calibration (MC) hardware and software. The interface works in both ways: BOA can be used to integrate ETAS hardware products into diverse software products (both ETAS and 3rd-party 1 products). BOA can be used to integrate diverse hardware (both ETAS and 3rd-party products) into ETAS MC software. The BOA framework provides a comprehensive package of functions for reading, sending and manipulating data on a vehicle s communications bus system. BOA currently supports the CAN, LIN and FlexRay bus standards. The BOA interface is designed to be bus-independent as far as possible, providing consistent APIs across these different bus types. 1.1 Safety Notice DANGER! Sending out CAN, LIN or FlexRay messages influences the behavior of the bus network and the systems connected to it. This may result in unexpected behavior of the vehicle and thus can have potentially dangerous consequences. Only well trained personnel should be allowed to perform CAN, LIN or FlexRay message sending activities. 1.2 Conventions The following typographical conventions are used in this document: OCI_CANTxMessage msg0 = Select the file setup.exe A distribution is always a onedimensional table of sample points. Code snippets are presented on a gray background and in the Courier font. The meaning and usage of each command are explained by means of comments. The comments are enclosed by the usual syntax for comments. Text in drop-down lists on the screen, program code, as well as path- and file names are shown in the Courier font. General emphasis and new terms are set in italics. 1 3 rd -party = Non ETAS (see Glossary) 6

7 Getting started 2 Getting started 2.1 BOA packages and their contents There are various classes of BOA user: users of ETAS software, such as INCA, which contains BOA; 3rd-party hardware developers who want to integrate their hardware into ETAS software, via BOA; developers of a 3rd-party MC 2 tool who want to integrate ETAS hardware into that tool, via BOA; users of a 3rd-party MC tool which accesses ETAS hardware via BOA. To support these different types of user, BOA is divided into several packages: BOA Runtime Framework. This package contains the binaries that implement the device-independent BOA framework. It is usually included as part of the installation of a product that uses BOA. ECU and Bus Interfaces Integration Package (EBI-IP). This package contains all the headers, libraries and documentation that are required to allow a 3rd-party software developer to use BOA to access ETAS hardware. Please see the tutorial document within this package for details on how to create/configure a project to use BOA. Open Controller Driver Development Kit (OCD-DK). This package contains all the headers, libraries and documentation required to allow a 3rd-party hardware developer to use BOA to integrate their own hardware into ETAS software. ETAS Drivers ECU and Bus Interfaces (ED-EBI). This package contains all the BOA drivers that are needed to support various specific types of ETAS hardware. Each package is assigned a 4-digit version number d1.d2.d3.d4. d1 is the major version and is used to indicate an incompatible change in the package. For example, a client application which is built against version 2.x.y.z of the BOA framework will require modifications in order to operate with version 3.a.b.c. d1 is the minor version and is used to indicate a compatible change which introduces new functionality. For example, a client application which is built against version 2.0.x.y of the BOA framework will require no modifications in order to operate with version 2.1.a.b. However, the client application will not be able to take advantage of any new functionality which was added in version 2.1.a.b. d3 is the maintenance version and is used to indicate a compatible change which introduces no new functionality. d4 is used internally by ETAS to track individual builds. The currently-installed packages and their versions can be discovered via the Windows Control Panel s Programs and Features applet. The installed version of the EBI-IP can also be discovered from the header file <BOA root>\include\common\boaversion.h. ETAS always releases these three packages together: the BOA Runtime Framework; the EBI-IP; the OCD-DK. In other words, the versions of these packages proceed in lock-step and when using these packages care must be taken that they all have the same version. Unlike these three packages the ED-EBI package is released separately, and is only related to the first three packages by this statement: Each major version of the BOA runtime framework requires a specific major version of the ED-EBI. 2 MC = Measurement and Calibration 7

8 Getting started The specific major version of the ED-EBI which is required by the BOA runtime framework is defined by the pre-processor symbol ED_EBI_REQUIRED_VERSION_DIGIT1 in the file <BOA root>\include\common\boaversion.h. NOTE: (ProgramFiles) is used below as a general reference to the specific Program Files folder on 32bit and 64bit Windows PCs (ProgramFiles) = C:\Program Files on a 32bit Windows PC (ProgramFiles) = C:\Program Files (x86) on a 64bit Windows PC Each of the four BOA packages provides various files which are installed underneath (ProgramFiles)\ETAS. The first three packages place their files under BOA_V2\, whereas the ED-EBI places its files under ED-EBI_V2\. More details are given in the following subsections: Package: BOA Runtime Framework Package component Device-independent framework binaries ETAS-specific RPC 3 drivers Files under BOA_V2\ Bin\Win32\Dll\Framework, Bin\Win32\Dll\Localization ETAS network settings manager Start menu: ETAS \ IP-Configurator Package: ECU and Bus Interfaces Integration Package (EBI-IP) Package component BOA Runtime Framework package BOA Framework Development Add-on: Libraries to allow programmatic access to the BOA framework BOA Framework Development Add-on: Header files to allow programmatic access to the BOA framework BOA Framework Development Add-on: Reference Guide for all public BOA APIs BOA Framework Development Add-on: This document Documentation specific to the EBI-IP Zipped example applications contained in one zip file Files under BOA_V2\ See above Bin\Win32\Lib Include Documentation\Reference Guide Documentation\Users Guide Bin\Win32\Dll\OCDs\*2ser.dll, Bin\Win32\Dll\OCDs\dllser2*.dll, Bin\Win32\Dll\OCDs\dllcsiEss* Documentation\Tutorials\EBI- IP Examples 3 RPC = Remote Procedure Call (see Glossary) 8

9 Getting started Package: Open Controller Driver Development Kit (OCD-DK) Package component Documentation specific to the OCD-DK Zipped example applications contained in several zip files Files under BOA_V2\ OCD.DK\Documentation OCD.DK\Examples Package: ETAS Drivers ECU and Bus Interfaces (ED-EBI) Package component Device-specific drivers for ETAS hardware: DLLs that are not part of the BOA Runtime Framework Files under ED-EBI_V2\ Bin\Win32\Dll\OCDs Note The various DLLs in the directory bin\win32\dll\framework must not be copied to any other location, otherwise they will not operate correctly. When writing a client application which uses these DLLs, the client application must access the DLLs in-place by ensuring that the PATH environment variable points to bin\win32\dll\framework. Similarly, the contents of the directory bin\win32\dll\ocds must not be moved elsewhere. However, there is no need to add this directory to the PATH. 2.2 Prerequisites This manual addresses developers of both hardware and software tools in the fields of automobile control unit development and calibration. Basic knowledge of the automotive buses used and of automotive bus controllers is required, as is understanding of the C language. In order for BOA to communicate to a device over an Ethernet connection, the ETAS Network Manager must have been installed and configured. See Network Settings Tool later in this document under section (BOA fails to access Hardware connected via Ethernet) However, specialized knowledge of the ETAS hardware devices and their connection to the PC is not required. 2.3 How this manual is organized This manual consists of the following chapters: Chapter 1: Introduction This chapter outlines the possible uses of BOA. Furthermore, it contains general information such as safety and user information. Chapter 2: Getting started (this section) This chapter provides an overview of the various ways in which BOA can be installed, and describes the layout of the BOA installation on disk. Chapter 3: Overview of BOA This chapter describes the purpose of BOA, and gives a high-level description of its various components. Chapter 4: OCI (Open Controller Interface) This chapter gives details of the Open Controller Interface, the principle set of APIs defined by BOA. Chapter 5: CSL (Connection Service Library) 9

10 Getting started This chapter describes the design and operation of the Connection Services Library, which is used to discover and connect to hardware devices. Chapter 6: Device information and licensing This chapter describes the way in which the BOA framework allows a client application to discover properties of a connected device, and specifically any licence information which may be associated with the device. Chapter 7: Authentication This chapter discusses the mechanism which the BOA framework provides to allow a client application to authenticate the BOA framework s DLLs, thereby ensuring that licence information provided via these DLLs can be trusted. Chapter 8: Backwards compatibility and API versioning This chapter discusses how the BOA framework allows ETAS to extend BOA APIs to offer new functionality, while still ensuring backwards compatibility with older BOA clients or BOA hardware devices. Chapter 9: Troubleshooting BOA-specific problems This troubleshooting chapter gives some information of what you can do when problems arise during your work with BOA. Chapter 10: Troubleshooting ETAS Ethernet problems This troubleshooting chapter gives some information of what you can do when problems arise when connecting to ETAS Ethernet-connected hardware devices. Chapter 11: Glossary The chapter titled Glossary explains all the technical terms used in the manual. The terms are listed in alphabetical order. Chapter 12: Appendix: Further reading This appendix lists all additional documentation that is provided together with BOA or can be received from ETAS and indicates where you can find further information. Chapter 13: Appendix: Versions of BOA APIs This appendix lists the various versions of BOA APIs which have been defined by ETAS. 2.4 Getting more information The BOA Reference Guide is installed along with this document and can be accessed from the Windows Start menu option: Start->All Programs->ETAS->BOA v2->reference Guide For a list of documents providing more information, please see Appendix: Further reading on page

11 Overview of BOA 3 Overview of BOA 3.1 The purpose of BOA BOA was created to fulfil two aims: to enable easy integration of ETAS hardware devices into 3rd-party measurement and calibration software; to enable easy integration of 3rd-party bus-access hardware devices into ETAS measurement and calibration software. BOA achieves this by defining a standard called the Open Controller Interface (OCI), which describes low-level access to vehicle busses. This standard consists of a set of three APIs, one for each of the types of vehicle bus currently supported: OCI_CAN for CAN and CAN-FD; OCI_LIN for LIN; OCI_FLX for FlexRay. The syntax of these three APIs is similar, and they deal in similar concepts, but they differ slightly due to differences between the three underlying busses. The standardisation provided by the OCI APIs brings these benefits: A client of BOA can access all BOA-compliant devices in the same way, via the OCI APIs. The client needs no device-specific knowledge. The owner of a device can write a single driver, which allows his device to be used by any BOA client. The OCI APIs are described in detail in chapter The structure of BOA BOA provides a framework of core components residing on the PC. A 3rd-party can create other components that plug into this framework, to provide device-specific functionality. The following sections describe this structure Open Controller Drivers and the OCD Proxy Section 3.1 described how BOA defines three OCI APIs, each providing low-level access to a particular type of vehicle bus. A component that implements one or more of these OCI APIs is called an Open Controller Driver (OCD). Its role is identical to that of a driver in an operating system: it must map an OCI API to a particular device-specific API, defined by the creator of a hardware device. This private device-specific API allows the OCD to communicate with the hardware device via whichever PC host interface is used by the device (e.g. USB or PCMCIA). An OCD can support one or more OCI APIs and one or more types of device. For example, if the Acme company makes a range of similar hardware devices for CAN and LIN access, the Acme company might decide to write a single OCD which implements OCI_CAN and OCI_LIN and which can access any Acme device. Many OCDs are implemented by DLLs which reside on the PC, but a powerful bus-access device may contain its own OCD implementation which executes in the device s firmware; this is the case with ETAS s Ethernet-connected hardware devices. The BOA framework provides an RPC mechanism to communicate with such devices, though this mechanism is specific to ETAS devices and is therefore not described in detail in this document. Clearly, a PC application wishing to use the OCI APIs to communicate with a BOA-compliant device must link against a DLL that implements the OCI APIs. However, many OCD DLLs may be present on the PC, each exposing one or more OCI APIs. How can an application choose the correct OCD DLL, and what happens if the application needs to use more than one OCD DLL simultaneously? The BOA framework provides a solution in the form of the OcdProxy component. This is a DLL which implements all OCI APIs, and which collaborates with rest of the BOA framework 11

12 hardware / firmware ETAS Overview of BOA to route each function call made by a BOA client to the required OCD DLL. Thus, a BOA client can link against the OcdProxy DLL and rely on the BOA framework to ensure that all OCI API calls are routed to the correct destination. This arrangement can be seen in Figure 3-1. Figure 3-1: The structure of BOA, showing OCDs and the OcdProxy BOA compliant application BOA Framework OCI OCD proxy OCI OCI OCD ETAS RPC RPC on TCP/IP on Ethernet OCI OCD for 3 rd -party Hardware 3 rd -party proprietary on any PC-interface PC-based software RPC 2 OCI OCI LIN CAN FLX OCD ESxxx ETAS genuine ESxxx 3 rd -party Driver 3 rd -party Bus Access Hardware 3 rd -party 3 rd -party Bus Node Hardware The Connection Services Library Bus-access hardware devices can use a variety of host interfaces to connect to a PC: PCMCIA USB Ethernet PCIe Each bus-access device can contain several bus controllers, possible for different bus types. As a result, a PC can be connected to a network of bus controllers on different hardware devices, connected to the PC via different host interfaces. 12

13 Overview of BOA Each bus controller can be accessed via an OCI API: OCI_CAN for a CAN controller, OCI_LIN for a LIN controller and so on. Using object-oriented terminology, it can be said that a bus controller offers an OCI API. Nevertheless, in physical terms, a controller s OCI API is implemented by an OCD, as described in section Typically, the OCD is not in 1-to-1 correspondence with the bus controller: a typical OCD manages all controllers on a certain type of hardware device, or perhaps all controllers on a range of hardware device types. Section has described how a BOA client application links against the OcdProxy DLL and relies on it to route OCI API calls to the appropriate OCD. However, some questions are still unanswered: How does a BOA client discover the physical layout of the network of connected hardware devices, and the OCI API implementations that are offered by each bus controller in the network? How does the OcdProxy component establish a communication path that allows it to make function calls to the OCD responsible for a particular OCI API implementation? For example, if the client wants to call the OCI_CAN API on CAN controller #1 of the Acme CANbox device with serial number 12345, how does the OcdProxy route this function call to the correct OCD? In some trivial cases, establishing such a communication path is just a matter of loading the appropriate OCD DLL that is installed on the PC, then making a function call into the DLL. However, if the required OCD is located within the firmware of a connected hardware device, then establishing a communication path can be much more complicated. These functions are provided by a BOA framework component known as the Connection Services Library (CSL). The CSL is able to build a tree whose nodes represent the connected hardware devices, their controllers, and the OCI APIs which are offered by each controller. The CSL is able to use this tree to identify a communication path from a BOA client on the PC to any implementation of an OCI API within the tree. The CSL s contribution to the structure of BOA is shown in Figure 3-2. As can be seen from this figure, the CSL introduces several new APIs which are collectively referred to as the Connection Services Interface (CSI) APIs: The CSI Search for Services (CSI_SFS) API is implemented by the CSL and is used by the BOA client to discover the connected hardware devices, their controllers, and the OCI API implementations they offer. The CSI Connect to Service (CSI_CTS) API is implemented by the CSL and is used by the OcdProxy (or, occasionally, by the BOA client) to establish a communication path to a particular OCI API implementation. The CSI Enumerate Sub-Services (CSI_ESS) API is implemented by each OCD and is used by the CSL to discover the hardware devices, controllers and OCI API implementations that are supported by the OCD. The CSL is described in detail in chapter 5. 13

14 Overview of BOA Figure 3-2: The structure of BOA, showing the CSL BOA compliant application BOA Framework CSL CSI (SFS) CSI (CTS) CSI (ESS) OCI OCD proxy OCI CSI (ESS) CSI (ESS) ESS 2 RPC OCI OCD ETAS RPC RPC CSI (ESS) OCI OCD for 3 rd -party Hardware 3 rd -party proprietary PC-based software on TCP/IP on Ethernet on any PC-interface RPC 2ESS RPC 2 OCI OCI hardware / firmware CSI (ESS) 3 rd -party Driver OCD ESxxx ESxxx 3 rd -party Bus Access Hardware LIN CAN FLX 3 rd -party Bus Node Hardware ETAS genuine 3 rd -party 14

15 OCI (Open Controller Interface) 4 OCI (Open Controller Interface) Section 3.1 introduced the concept of the Open Controller Interface (OCI), which defines a set of three APIs, one for each of the types of vehicle bus supported: OCI_CAN for CAN and CAN-FD; OCI_LIN for LIN; OCI_FLX for FlexRay. The OCI APIs can be used by low-level application software for the following tasks: configuring a bus controller; transmitting, receiving, and filtering frame-based data. The OCI APIs are composed of some common and some bus-specific parts for CAN, LIN and FlexRay, but the general concepts are identical for each bus. 4.1 Using the OCI APIs programmatically Section described how the Open Controller Driver (OCD) associated with a particular type of hardware implements one or more of the OCI APIs, in order to provide access to the hardware device. Clearly, a BOA client application can link directly to an OCD DLL and use its implementation of the OCI APIs to access a hardware device. However, this is only possible if the BOA client knows which OCD DLL it needs to use to access a given device. Furthermore, if the BOA client needs to use two different OCD DLLs simultaneously, then it becomes difficult to prevent collisions between the names of the two OCD DLL s exported functions. Therefore, in general, the software developer of a BOA client should not link directly to an OCD DLL. Instead, a BOA client should link to the OcdProxy DLL dll-ocdproxy.dll, which is part of the BOA framework. The OcdProxy DLL implements all OCI APIs and is able to collaborate with the BOA Connection Service Library (CSL) to route each OCI API function call to the correct OCD. The declarations of the OCI APIs are available in the header file Include\OCI\oci.h. 4.2 A note on syntax The OCI APIs for CAN, LIN and FlexRay share the same concepts and, in some cases, they even share the same functions, i.e. some functions are members of all three APIs. Other functions, although they share the same semantics, have slightly different syntax from one API to the next. To reflect this, such functions have names that differ only according to the name of the associated bus, for example: OCI_CreateCANControllerVersion() OCI_CreateLINControllerVersion() OCI_CreateFLXControllerVersion() For convenience, within this document such triples of function names are referred to using the string XXX, for example OCI_CreateXXXControllerVersion(). 4.3 General Structure and Components Figure 4-1 shows the general OCI structure. The individual objects are described in further detail in the following sections. 15

16 OCI (Open Controller Interface) Figure 4-1: General OCI structure 4.4 Controllers Concept of a controller The central element of the OCI is an object known as a controller, an instance of which is represented in the OCI APIs by a controller handle. A controller handle is the anchor for any access to an OCI API, in that any communication session using an OCI API must begin by obtaining a controller handle. The lifetime of the controller handle defines the duration of the communication session. A controller is virtual, in the sense that the OCI permits several controller instances (i.e. several controller handles) to be associated with a single physical bus controller. However, a resource-limited OCD may be unable to support many virtual controller instances for each physical controller. To remove this restriction and allow a large number of virtual controller instances to be associated with any physical bus controller, the BOA framework incorporates a component known as the Open Session Manager (OSM). The OSM automatically places itself between a BOA client application and an OCD, and aggregates the virtual controller instances created by the BOA client application into a single controller instance at the interface to the OCD. No matter how many virtual controller instances are created by the BOA client application, only a single controller instance (managed by the OSM) is created in the OCD. The OSM is discussed further in section A controller instance can be created by using the OCI API function OCI_CreateXXXControllerVersion(). In order to identify a controller when calling this function, the BOA client must provide a URI which describes the physical location of the controller. For example: ETAS://ETH/ES910:abcd/CAN:1 identifies the first CAN controller of the ETAS ES910 device with serial number abcd which is connected to the PC s Ethernet port. 16

17 OCI (Open Controller Interface) ETAS://PCMCIA/CANCARDX:defg/CAN:2 identifies the second CAN controller of the CanCardX device with serial number defg which is connected to the PC s PCMCIA port. URI syntax is described further in section 5.1.2, and the whole of chapter 5 discusses how a BOA client can discover the connected hardware devices and build URIs which can be used to identify them. As well as identifying the physical location of the controller, a caller using OCI_CreateXXXControllerVersion() must also specify the version of the OCI_XXX API which he requires. The concept of the version of an API is discussed further in section A controller instance can be destroyed by calling OCI_DestroyXXXController(). Doing so will also destroy all other objects associated with the controller, such as queues, filters, etc. On the other hand, if a controller instance is not explicitly destroyed then the controller and all its resources will remain in existence; they will never be tidied up automatically Capabilities of a controller Capabilities are static and describe the abilities of a controller; they list specific functions or features of the controller. The capabilities are closely related to hardware. An example of a controller capability might be the physical layer supported by the underlying hardware device, or, for CAN devices, whether the extended frame format is supported. A controller s capabilities can be read via the function OCI_GetXXXControllerCapabilities() Configuration of a controller A controller s configuration is defined as those controller parameters that can be modified by a BOA client at runtime. The baudrate of a CAN controller, or the key-slot ID of a FlexRay controller, are examples of configuration parameters. A controller s configuration is set when the BOA client calls OCI_OpenXXXController(), and can be read by calling OCI_GetXXXConfiguration(). Recall that several virtual controller instances (i.e. several controller handles) can be associated with a single physical controller. The controller configuration is associated with the physical controller and is shared among all associated virtual controller instances. Therefore, the first BOA client which configures the physical controller can choose any configuration it pleases. A subsequent client which attempts to configure the physical controller while the original client s controller handle is still in one of the open states (see section 4.4.5) must choose a compatible configuration, otherwise OCI_OpenXXXController() will return OCI_ERR_INCOMPATIBLE_CONFIG. It is meaningful for a BOA client to call OCI_GetXXXConfiguration() before calling OCI_OpenXXXController(); doing so retrieves any controller configuration which has already been set by another client. If no such configuration is available (i.e. no other client has configured the controller already) then OCI_GetXXXConfiguration() returns OCI_ERR_NO_CONFIG Status of a controller A controller s status is defined as those controller properties which are modified by external events, not by a BOA client. The number of remaining cold-start attempts for a FlexRay controller, or the sleep mode state of a LIN controller are examples of status fields. The current status of a controller can be read by calling OCI_GetXXXControllerStatus(). 17

18 OCI (Open Controller Interface) State transitions for virtual controllers A virtual controller instance can exist in different states; the state chart in Figure 4-2 gives an overview of the different transitions between states, and the OCI functions that cause state transitions to occur. Note that the different virtual controllers associated with the same physical controller can occupy different states. Note also that a controller s State is not the same as its Status as detailed in the section above ( Status of a controller ). Terminology associated with controller states: A controller state is sometimes referred to as a mode. The current state of a controller can be obtained via the function OCI_GetXXXControllerProperties(). The function OCI_SetXXXControllerProperties() can only be used to execute state transitions between the suspended and running states. Open/close will transition to/from the created state. Figure 4-2: State chart for the virtual controller object The controller states have the following meanings: Created A virtual controller enters the created state when it is created (see section 4.4.1). While in the created state, the configuration, status and capabilities of the controller can be examined, but no modifications can be made to the controller. The controller leaves the created state when the function OCI_OpenXXXController() is called, at which point the physical controller configuration is specified, as described in section Upon leaving the created state, the controller can move to either the suspended state or the running state, according to the arguments supplied to OCI_OpenXXXController(). Both these states are referred to as open states. Suspended 18

19 OCI (Open Controller Interface) In the suspended state the virtual controller will not interact with the vehicle bus, yet the BOA client can perform all other operations which are possible in the running state. The client can create transmission and reception queues, manipulate their associated filters, and enqueue frames to be sent on the bus (though no frames will actually be sent). After completion of these steps the controller can be switched to the running state by the function OCI_SetXXXControllerProperties(). Running The running state is identical to the suspended state, except that now the controller interacts with the vehicle bus. Upon entering the running state, any frames that were queued for transmission during the suspended state will be transmitted, and the controller will start to receive data using any receive queues and filters that have been configured. Changes can still be made to queues, filters, etc., and these will take effect immediately. At any point, the controller can be returned to the created state by calling OCI_CloseXXXController(), or destroyed completely by calling OCI_DestroyXXXController(). Note that since each virtual controller has its own state, the physical controller will still send/receive data while any associated virtual controller instance is in the "running" state The Open Session Manager An OCD may have limitations associated with its hardware: The OCD may support only a limited number of virtual controller instances per physical controller. The OCD may support only a limited number of white filters 4 when receiving frames from the vehicle bus. The OCD may only be able to buffer a limited number of frames received from the vehicle bus. The Open Session Manager (OSM) is a BOA framework component that is hidden from the client application. It exists to remove these limitations and is in operation by default. The OSM allows a client application to create many virtual controller instances, each referring to the same physical controller, and all sharing a single OCI controller instance at the OCD. Recalling that a controller instance is equivalent to an API session, it can be seen that the OSM s function is to aggregate many client API sessions into a single API session at the OCD. Hence it does not matter if an OCD supports only a single concurrent controller instance; only one such instance will be created, and the OSM will use it to support as many virtual controller instances as the client application requires. Ideally, each virtual controller instance shares the physical hardware and the OCD without adversely affecting the operation of other virtual controllers or even being aware of their existence. However, although the OSM appears mostly transparent to a BOA client application, it is not completely so. The OSM has two principal restrictions: Section discusses the need for two clients who are sharing a physical controller to agree on a single configuration for the controller. The OSM will transparently adjust the two clients controller configurations to increase the chances that they will be compatible with each other, but in many cases the clients will still need to collaborate with each other to agree on a single configuration. For example, clearly there must be an agreement on a single baudrate to be used for the CAN bus. The OSM does not operate to perform session aggregation between different client processes which access the same physical bus controller. In this use case, each client process will have its own instance of the BOA framework and its own instance of the OSM. Thus two connections will be created to the physical bus controller, one from each client process. It is entirely dependent on the hardware device as to whether this is supported. 4 White filter = A filter that defines what is let through (see Glossary) 19

20 OCI (Open Controller Interface) The OSM s contribution to the structure of BOA is shown in Figure 4-3 below. Figure 4-3: The structure of BOA, showing the OSM BOA compliant application session BOA Framework session CSL CSI (SFS) CSI (CTS) CSI (ESS) OCI OCD proxy OCI OSM OCI virtual controller physical controller virtual controller OCI OCI OCI OSM CSI (ESS) CSI (ESS) ESS 2 RPC OCI OCD ETAS RPC RPC CSI (ESS) OCI OCD for 3 rd -party Hardware 3 rd -party proprietary PC-based software on TCP/IP on Ethernet on any PC-interface RPC 2ESS RPC 2 OCI OCI hardware / firmware CSI (ESS) 3 rd -party Driver OCD ESxxx ESxxx 3 rd -party Bus Access Hardware LIN CAN FLX 3 rd -party Bus Node Hardware ETAS genuine 3 rd -party 4.5 Queues A BOA client must use the OCI APIs to create queues in order to transmit and receive bus frames. Each controller can be associated with at most one receive queue, while the maximum number of transmit queues varies from one bus type to another (such bus-specific details are discussed further in section 4.11). All queues are independent from each other; there is no prioritization between different queues, and the order of coexisting queues is arbitrary. Queues are described by the following qualities: Capabilities 20

21 OCI (Open Controller Interface) The capabilities of a queue contain static information about the queue, namely the guaranteed capacity of the queue and the possible maximum capacity (which will be greater than the guaranteed capacity if the queue s storage can be extended dynamically). The queue capabilities can be read using the function OCI_GetQueueCapabilities() which is present on any OCI API. Properties The properties of a queue can be modified by the BOA client. They define a low watermark and a high watermark : these values are used to generate events associated with the queue, as described in section 4.8. The queue properties can be read and set using the functions OCI_GetQueueProperties() and OCI_SetQueueProperties(). Status The queue status describes those properties of the queue which cannot be modified directly, but which vary in response to external events. These are the current number of entries in the queue and the maximum number of entries in the queue since the queue was last emptied via the function OCI_ResetQueue(). The queue status can be read using the function OCI_GetQueueStatus(). A queue can be emptied by calling the function OCI_ResetQueue(), though it should be noted that the use of this function creates complicated synchronization issues which are described further in this function s page in the BOA Reference Guide[1]. 4.6 Self Reception For CAN, LIN and Flexray, Self Reception mode is specified in Controller configuration and on creation of the Rx Queue. The table below, illustrates the combinations of the input flags and the resulting return code in OCI_CreateXXXRxQueue(). Controller (SR Flag) Rx Queue (SR Flag) Rx Queue Return Value OFF OFF OCI_SUCCESS OFF ON OCI_WARN_INCONSISTENT_SELF_RECEPTION ON OFF OCI_WARN_INCONSISTENT_SELF_RECEPTION ON ON OCI_SUCCESS 4.7 Receiving bus data frames Messages BOA refers to a bus data frame as a message. Clearly there are at least three types of message, corresponding to CAN, LIN and FlexRay data frames. However, BOA also distinguishes between transmitted and received messages, and, as is shown in section 4.8, other types of notification are also treated as messages. Where it is necessary for an OCI API function to be able to accept several different types of message as an argument, the function accepts a structure containing two fields: a union field, typed according to the various possible message types which can be accepted; an indicator field, which indicates the current type of the union. OCI_CANMessage is an example of such a structure. 21

22 OCI (Open Controller Interface) A data message encapsulates a bus data frame and therefore contains bus-specific items such as a payload and a frame ID. Depending on the specific type of the message, the BOA framework may also add other fields, such as a timestamp (for received messages) or various flags. For more detailed information on OCI messages, see the BOA EBI-IP tutorial [2] Using filters In order to receive messages, a BOA client must create a receive queue, and then add filter(s) to the queue. To do this, the BOA client must use a controller that is in one of the open states (see section 4.4.5). Each filter defines a pass condition, i.e. it acts as a white filter. A received message is compared in turn against each filter, and a copy of the message is added to the receive queue when a filter match occurs. This means that by default, a received message will be ignored and not stored in the queue. Only those messages that meet all conditions of a filter are accepted. Each filter possesses a property known as a tag. When a message passes a filter and is accepted by a queue, the filter s tag value is appended to the copy of the message, which is added to the queue, thereby indicating which filter caused the message to be accepted. If the message was accepted by several filters attached to the same queue, it is undefined which tag value will be appended to the message copy. The tag value is opaque to BOA; it is intended to allow the BOA client to demultiplex messages which are received by a single queue but which are destined for different components of the BOA client. Filters can be added or removed as required after a queue has been created, even while messages are actually being received. When a queue is deleted, the filters are deleted along with the queue. An RX queue can be created using the function OCI_CreateXXXRxQueue() and destroyed using OCI_DestroyXXXRxQueue(). Filters which accept bus frames can be added and removed from a queue via OCI_AddXXXFrameFilter() and OCI_RemoveXXXFrameFilter(). Note In contrast to queues, filters are not described by capabilities, properties or a status Reading messages from a queue Once a queue has been created, and filter(s) have been added to it as described in the previous section, the contents of the queue defines a stream of messages which can be read by the BOA client. The client can read messages in order from the queue by calling the function OCI_ReadXXXData() Receiving messages via a callback The previous section describes how a BOA client can read received messages from a queue. However, it is also possible for received messages to be delivered via a callback. The structure OCI_XXXRxQueueConfiguration which the BOA client supplies when a queue is created contains a function pointer called onframe. If this has a non-zero value, frames which are received by the queue will not in fact be added to the queue at all; instead they will be passed to the callback function specified by onframe. This mechanism allows a received message to reach the BOA client with as little latency as possible and is therefore more flexible than using OCI_ReadXXXData(). 4.8 Receiving events Section 4.7 described how the OCI APIs can be used to receive bus frames in the form of data messages. The same mechanism can be used to receive events. An event is an 22

23 OCI (Open Controller Interface) asynchronous notification of an occurrence either within the BOA framework or on a vehicle bus: Queue events A queue event occurs when, for example, a OCD s queue becomes full, or reaches its high-water mark. The structure OCI_QueueEvent lists all the queue events which can occur. Timer event Timer events are discussed further in section The structure OCI_TimerEvent lists all the timer events which can occur. Internal error event When an error occurs asynchronously within the BOA framework the BOA client is notified via an internal error event. The most common internal error event occurs when a hardware device is disconnected while a BOA communication session is still in progress. The structure OCI_InternalErrorEvent lists all the internal error events which can occur. Bus-specific events Many bus-specific events are defined, such as CAN error frames, FlexRay data loss, etc. These are described further in section 4.11 and are documented fully in the BOA Reference Guide[1] for each OCI API. Each event is classified as a type of BOA message, and therefore can be received by using filters and queues in the manner described in sections 4.7.2, and Although dedicated functions such as OCI_AddQueueEventFilter() exist to specify event filters, event messages are processed by the same RX queue as data messages: events do not have their own dedicated queue type. Thus a BOA client can receive event messages by calling OCI_CreateXXXRxQueue() then applying some event filters to the queue. The only difference between the mechanism for receiving event messages and that for receiving data messages is the way in which event messages are delivered to the BOA client: when an event message matches a filter on a queue, the configuration of the filter combines with the configuration of the queue to determine whether the event message is delivered to the BOA client via a dedicated callback function or whether the event message is delivered in-band by adding it to the stream of received data messages. When an event is received which matches one of the event filters associated with a queue, there are two possibilities: Delivery via a dedicated callback If the onevent function pointer in the queue s OCI_XXXRxQueueConfiguration structure is non-zero, and if the destination member of the matched filter s configuration structure specifies OCI_EVENT_DESTINATION_CALLBACK, then the event message is passed to the callback onevent. Delivery in-band If the onevent function pointer in the queue s OCI_XXXRxQueueConfiguration structure is zero, or if the destination member of the matched filter s configuration structure specifies OCI_EVENT_DESTINATION_INBAND, then the event message is delivered to the application in the same way as a data message. (This can mean delivery either via OCI_ReadXXXData() or via a callback - see sections and 4.7.4). Note that these two possibilities are not mutually exclusive. OCI_EVENT_DESTINATION_INBAND and OCI_EVENT_DESTINATION_CALLBACK are single-bit flags and can be binary OR ed together. On this case, the event message will be duplicated and delivered in both ways. 23

24 OCI (Open Controller Interface) 4.9 Transmitting bus data frames 4.10 Timers Transmitted bus frames are also treated as messages, and are processed via queues in a similar manner to received bus frames. Transmit queues are manipulated using the OCI API functions OCI_CreateXXXTxQueue(), OCI_WriteXXXData() and OCI_DestroyXXXTxQueue(). The maximum number of transmit queues varies from one bus type to another; such busspecific details are discussed further in section Transmit queues cannot have filters applied to them What is a timer? Each message that is received via an OCI API has a timestamp; this is necessary to know the message s alignment on a timescale. These timestamps are provided by a timer. Each physical controller uses exactly one timer. This may be a timer which is located within the same hardware device as the controller, or it may be an external timer which is able to synchronize several hardware devices. The identity of the timer which is currently used by a controller can change at any point; this may occur, for example, when an external timer is connected to the hardware network and becomes available for synchronization. The identity of a timer is expressed as a clock ID. If two controllers use a timer with the same clock ID, then the timestamps from these controllers are located on the same timescale, and there is no drift and no jitter. However, if two controllers use timers with different clock IDs, there may be drift and jitter, even if the two timers have properties (frequency, origin, etc.) which are nominally the same. Note: a description of drift and jitter can be found in chapter 11 (Glossary) Controller qualities associated with timers A controller has qualities which relate to its timer: Capabilities The timer capabilities provide static information on the controller s local timer. This may, or may not, be the timer currently used by the controller: recall that the identity of the timer which is currently used by a controller can change at any point. The timer capabilities include the clock ID of the timer, its tick resolution and accuracy, the point of origin of the local timescale, and the reference scale used by the timer. Full details of the timer capabilities are provided in the structure OCI_TimerCapabilities obtained by the function OCI_GetTimerCapabilities(). Status Timer events The timer status provides information about the timer which the controller is actually using at the current point. This information includes the current time and the current clock ID that is used for timestamping. If different timers are synchronized, this is the clock ID of the synchronization master. Full details of the timer capabilities are provided in the structure OCI_TimerStatus obtained by the function OCI_GetTimerStatus(). Section 4.8 mentioned that timers can generate events, which can be filtered and received via a queue in the same manner as any other OCI message. Timer events occur to indicate: the connection of a device to an external reference (SYNC_LOCK); the loss of connection to an external reference (SYNC_LOSS); 24

25 OCI (Open Controller Interface) the occurrence of a leap second which is required to compensate for the differences in the TAI and UTC reference time systems (LEAP_SECOND). All these events lead to jumps in the timestamp value, e.g. because different reference systems are used. The OCI APIs simply provide the raw timestamps from the controller s timer without any modification or correction. Modifications or corrections which are required as a result of a timer event, or simply in order to map messages from different controllers onto the same timescale, must be done by the BOA client. To make sure that the timestamps which stem from different timers can be correctly mapped, the BOA client should query the timer status whenever a timer event occurs. For that purpose it is recommended to filter for timer events and define callbacks as explained in section 4.8. Figure 4-4 illustrates some timer events caused by connecting and disconnecting a measuring device. The sample topology contains two devices which can be synchronized with each other; device A contains timer A, and device B contains timer B. Phase 1 unsynchronized devices: The measuring devices are not yet synchronized. The frames from each device get their timestamps from the corresponding timer. Phase 2 synchronized devices: A SYNC_LOCK event is caused, e.g. by connecting the devices physically with each other. Timer A is the master, and timer B gets synchronized to timer A. This can lead to discontinuous timer values. After the SYNC_LOCK event, frames from device A and device B get timestamps from synchronized timers. Phase 3 unsynchronized devices: A SYNC_LOSS is caused, e.g. because the physical connection between the devices gets lost. Both timers start from the timer value reached at the moment of the SYNC_LOSS. Each device uses its own timer again and consequently the individual timer s slope, which will result in a drift between the timers. 25

26 OCI (Open Controller Interface) Figure 4-4: Some timer events caused by connecting and disconnecting a measuring device 26

27 4.11 Bus-specific OCI implementation OCI CAN specifics In OCI CAN, there is at most one transmit queue and one receive queue per virtual controller instance, reflecting the fact that a CAN controller performs transmission and reception in a FIFO manner. There is no prioritization between queues of different virtual controller instances on the same physical controller. All CAN frames are queued and transmitted in the same order as they are delivered to the transmit queue via OCI_WriteCANData(). In addition to receiving data messages, a CAN queue can receive the following CAN-specific event messages which are generated by the associated CAN controller: Error frame messages An error frame message encapsulates an error frame, as received from the CAN bus. Despite its name, this message is classified as an event message, not a data message by the BOA framework. For more information about error frame messages, see the description of the structure OCI_CANErrorFrameMessage in the BOA Reference Guide[1]. Controller event message A controller event message announces a change in the controller s state, such as becoming active, or reaching its error limit. For more information about controller event messages, see the description of the structure OCI_CANEventMessage in the BOA Reference Guide[1]. Starting from v1.3 of OCI_CAN, the OCI_CAN API also supports CAN-FD. An OCI_CAN controller s capabilities describe its support (or lack of support) for CAN-FD. If CAN-FD is supported, an OCI_CAN client provides CAN-FD configuration when he opens the OCI_CAN controller. The OCI_CAN client uses the dedicated message types OCI_CANFDRxMessage and OCI_CANFDTxMessage to transmit and receive CAN-FD messages via the OCI_CAN controller (using OCI_WriteCANDataEx() and OCI_ReadCANDataEx()). CAN-FD support is described in detail in the BOA Reference Guide[1]. Self Reception can also be configured at a frame filter level. The table below illustrates all the combinations available when using OCI_AddCANFrameFilterEx(), also taking into account Controller and Rx Queue configuration values for Self Reception (See section 4.6 for more details). Controller (SR Flag) AND Rx Queue (SR Flag) Both ON All other combinations Filter Mask (SR Flag) Filter Value (SR Flag) Filter Return Value Should SR Messages reach client? OFF OFF OCI_SUCCESS YES OFF ON OCI_SUCCESS YES ON OFF OCI_SUCCESS NO ON ON OCI_SUCCESS YES OFF OFF OCI_WARN_INCONSIST ENT_SELF_RECEPTION OFF ON OCI_WARN_INCONSIST ENT_SELF_RECEPTION ON OFF OCI_SUCCESS NO ON ON OCI_WARN_INCONSIST ENT_SELF_RECEPTION NO NO NO 27

28 OCI FlexRay specifics Like CAN, a FlexRay controller receives data in a FIFO manner and therefore can support at most one receive queue per virtual controller instance. Again like CAN, this queue can receive FlexRay-specific event messages which are generated by the controller, as well as data messages containing frames received from the bus. FlexRay event messages are represented by the structure OCI_FlexRayEventMessage and announce occurrences such as a change of the controller s state or the loss of data on the bus. Full details are contained in the Reference Guide entry for OCI_FlexRayEventMessage. However, unlike CAN, a FlexRay controller does not transmit data frames in a FIFO manner. Instead, the controller maintains an array of buffers, and the contents of each buffer is transmitted at a fixed point in the transmission schedule. In OCI FlexRay, the array of TX 5 buffers is configured when a virtual controller instance is moved from the created state to one of the open states, as described in section This is the purpose of the field txbuffer in the OCI_FlexRayConfiguration structure which is passed to OCI_OpenFlexRayController(). OCI FlexRay permits many transmit queues to be created for each controller instance. Each transmit queue is associated with a subset of the array of TX buffers. A frame which is written to the transmit queue is copied to one of the buffer in the subset, and is placed on the FlexRay bus when transmission of that buffer is scheduled. The subset of buffers which is associated with a transmit queue is configured by the parameter bufferindexes in the structure OCI_FlexRayTxQueueConfiguration which is passed to OCI_CreateFlexRayTxQueue(). Two different transmit queues cannot share the same buffer if they are associated with the same physical controller, even if they are associated with different virtual controller instances. The fact that OCI FlexRay requires the controller s array of buffers to be configured when the controller is opened causes difficulties for some use cases, such as XCP-on-FlexRay, which require that the controller s buffers are re-configured while communication is taking place. Therefore, OCI FlexRay also supports the dynamic re-configuration of the controller s buffers. To allow proper synchronization with the transmit queue contents, buffer reconfiguration is triggered by pseudo-messages which the BOA client places in the transmit queue. These messages are never actually transmitted; instead they modify the configuration of the buffers associated with the transmit queue. Switch message This message, represented by the OCI_FlexRaySwitchMessage structure, enables or disables a TX buffer associated with the transmit queue. Disabling a TX buffer is usually done with the intention of enabling reception on the {slot, cycle, channel} tuple associated with the TX buffer, since many FlexRay controllers do not permit simultaneous TX and RX on the same {slot, cycle, channel} tuple. Reconfiguration message OCI LIN specifics This message, represented by the OCI_FlexRayReconfigurationMessage structure, causes a buffer associated with the transmit queue to be reconfigured. A LIN network contains two types of node: master nodes, which control the schedule of the bus by transmitting request headers; slave nodes, which transmit frames in response to the requests generated by the master. Slave nodes can also receive frames sent by other slaves. Correspondingly, an OCI LIN controller can be either a master controller or a slave controller. The controller s capabilities (obtained via OCI_GetLINControllerCapabilities()) indicate whether the controller is able to act as a master, a slave, or either. When the controller is moved to one of the open states, as 5 TX = Transmit (see Glossary) 28

29 described in section 4.4.5, the controller s configuration must specify whether it is to act as a master or a slave. Both master and slave controllers support a transmit queue, but the purpose of the queue varies between the two: A LIN master controller can support at most one transmit queue, and the queue can only be used to transmit messages of type OCI_LINMasterRequestMessage, i.e. LIN master requests. A LIN slave controller can support many transmit queues, but each queue can only be used to transmit messages of type OCI_LINTxMessage which have a single frame ID. In other words, one transmit queue is needed for each frame ID which the BOA client wishes to send. Furthermore, each transmit queue can only hold a single message at a time, i.e. each queue has a capacity of 1. The message in the queue is placed on the bus when the bus master sends a request header, but this does not cause the message to be removed from the transmit queue. The message is only removed from the transmit queue when a new message is written to the queue, or when the queue is destroyed. Thus a message which is added to a slave s transmit queue may be sent once, many times, or not at all, depending on the behavior of the bus master. Both master and slave controllers support a receive queue, though only a single receive queue can be created per controller, reflecting the fact that the controller receives messages in a FIFO manner. In addition to receiving data messages, a LIN queue can receive the following LIN-specific event messages which are generated by the associated LIN controller: Wake-up event message This message is generated when the LIN controller wakes up from the sleep state due to an internal stimulus. It is represented by the structure OCI_LINWakeUpEventMessage. Sleep mode event message This message is generated when the LIN controller enters or leaves the sleep state due to a stimulus from the LIN bus. It is represented by the structure OCI_LINSleepModeEventMessage. Transmission status event message This message is generated whenever a LIN message is successfully transmitted or received by the controller. It is represented by the structure OCI_LINTransmissionStatusEventMessage. Synchronization error event message This message is generated when the controller is unable to synchronize itself with the LIN bus, for example because the controller is configured with an incorrect baudrate. It is represented by the structure OCI_LINErrSyncEventMessage. CRC detect event message When a LIN controller is moved to one of the open states, its configuration must specify the CRC (cyclic redundancy check) algorithm and DLC (data length code) which is to be used for each frame ID which may occur on the bus. If, once the controller has been opened, a frame is received whose CRC algorithm was not configured in this manner, then the controller automatically detects the CRC algorithm which is used by the frame and generates a CRC detect event message. This event is only generated once for each frame type (i.e. once for each frame ID). It is represented by the structure OCI_LINCrcDetectEventMessage. DLC detect event message A DLC detect event is generated in similar circumstances to a CRC detect event, i.e. when a frame is received whose DLC was not configured when the controller was opened. Once again, the DLC detect event is only generated once for each frame 29

30 type (i.e. once for each frame ID). It is represented by the structure OCI_LINDlcDetectEventMessage. Data lost event message This message is generated by the controller when it detects that data has been lost on the bus. (If data is lost because of a queue overflow within the controller, a queue overflow event will be generated instead, as described in section 4.8). It is represented by the structure OCI_LINErrDataLostEventMessage. 30

31 5 CSL (Connection Service Library) Section introduced the Connection Services Library (CSL), which is responsible for searching for connected hardware devices and for establishing a connection to any specific device. Recall that the CSL specifies several Connection Services Interface APIs: The CSI Search for Services (CSI_SFS) API is implemented by the CSL and is used to discover the connected hardware devices, their controllers, and the OCI API implementations they offer. The CSI Connect to Service (CSI_CTS) API is implemented by the CSL and is used to establish a communication path to a particular OCI API implementation. The CSI Enumerate Sub-Services (CSI_ESS) API and the CSI Enumerate Component Services API (CSI_ECS) are implemented by each OCD and are used by the CSL to discover the hardware devices, controllers and OCI API implementations which are supported by the OCD. A BOA client may need to call the first two of these APIs, and they are described in detail in the following chapters of this document. The third and fourth APIs (i.e. CSI_ECS and CSI_ESS) are only relevant when creating a new OCD, and are therefore not described in detail in this document. A full description of these APIs is contained in the OCD-DK [3]. A BOA client can use the CSI APIs by including the headers located in the directory Include\CSI, then linking to the CSL s import library dll-csibind.lib. 5.1 Important concepts used in the CSL The CSL uses some complex concepts, and it is useful to have an understanding of these before trying to use the CSI APIs. Therefore, these concepts are discussed in this section, before the CSI APIs are introduced in section Trees and nodes The CSL models hardware, and their connections, as a tree of nodes. A node can represent a PC host interface, such as Ethernet; a hardware device, such as ETAS s ES910; a removable board, or other component of a modular hardware device, such as the ES920 piggy board which is available for ETAS s ES910; a bus controller on a hardware device, such as one of the two CAN controllers on ETAS s ES910. This list is not exhaustive; it is possible for a node to be used to represent any physical component which is deemed significant to the BOA client. Such nodes are called physical nodes. Furthermore, the tree of nodes is not restricted to representing physical objects: a node can also represent an API implementation. For example, the node which represents a CAN controller will have a child node which represents the OCI_CAN API, indicating that an implementation of OCI_CAN is available which can access the associated CAN controller. Such a node is called a protocol node. Using object-oriented terminology, it can be said that the protocol node itself offers the OCI API. Figure 5-1 shows the tree which is used to represent a single ETAS ES910 device attached to the PC via Ethernet; the ES910 also contains an ES920 piggy board. Note how non-singleton physical nodes must include an instance identifier such as a controller number (as in CAN:1 ) or a serial number (as in ES910:abcd ). 31

32 Figure 5-1: The tree representing a connected ETAS ES910 device Root PCMCIA Ethernet USB ES910:abcd CAN:1 CAN:2 LIN:1 LIN:2 ES920 OCI_CAN OCI_CAN OCI_LIN OCI_LIN FLX:1 FLX:2 OCI_FLX OCI_FLX Key: Protocol node Physical node URIs Protocol nodes have other features which extend their role beyond simply indicating whether a certain OCI API can be used to access a certain controller: A protocol node can be located underneath any node in the tree, not just those nodes which represent bus controllers. A protocol node can indicate that, although it offers a certain OCI API, it requires an implementation of another API in order to operate. This concept allows protocol nodes to be chained together. A protocol node which depends on another protocol node in this manner is referred to as a protocol translation node. Although these features appear rather confusing at first, in fact they combine to make protocol nodes one of the most powerful concepts of the CSL. They are discussed in more detail in section The CSL uses Uniform Resource Identifiers (URIs) to identify paths through the tree of nodes, thereby also identifying particular node instances. The syntax of such a URI is as follows: ETAS://<URIname>/<URIname>/.../<URIname> where URIname is the name (using URI-compatible characters) of a node in the tree. UriName in turn has the syntax: <TypeName>[:<InstanceId>] where TypeName is an identifier for the type of the node, and InstanceId is an optional identifier for the instance of the node type. InstanceId is only required for non-singleton physical nodes. For example, using the tree shown in Figure 5-1: The URI of the first FlexRay controller is ETAS://ETH/ES910:abcd/ES920/FLX:1. 32

33 The URI of the USB bus is ETAS://USB. The CSL does not define the URI names of individual nodes; instead, these are defined by the OCDs which are used to build the tree. This process is described fully in section A consequence of this is that there is no standard for the URI names used in CSL URIs Protocol stacks The construction of a protocol stack is one of the most complicated operations performed by the CSL, and, in fact, it is not necessary to understand it in order to use the CSL effectively. Therefore the reading of this sub-section is optional and can be skipped if a detailed understanding is not sought. The tree of nodes, which is described in the previous sections, shows the hardware devices that are connected to the PC, but it also fulfils an equally important purpose: it allows the CSL to establish a communication path to any OCI API implementation, such as OCI_CAN, which is present in the tree. This process is referred to as binding an instance of the OCI API. Some examples show the problems which must be solved by the binding process: Suppose the Acme company make a USB-connected device called the CANbox, and that an OCD for this device is installed on the PC. How does the CSL route OCI_CAN function calls to this OCD, and how does the OCD know which CANbox device, and which CAN controller within that device, should be used? ETAS makes Ethernet connected hardware, and each ETAS device contains its own OCD in firmware. How does the CSL find such an OCD, and how does the CSL establish an RPC (remote procedure call) connection that allows function calls to be directed to the OCD? The result of binding an API is a data structure known as a protocol stack. This contains all the information the BOA framework needs to pass a function call from the BOA client to the target OCI API implementation. The protocol stack is opaque to the BOA client. To understand how the CSL builds a protocol stack, it is first necessary to describe a few properties of a protocol node. These properties describe various aspects of how the CSL accesses the OCD associated with the protocol node. It is necessary for the CSL to access this OCD, because it is this OCD that actually implements the OCI API represented by the protocol node. A protocol node has a property known as its binding type. This indicates the way in which the node s OCD can be called. Currently two binding types are defined: DLL binding, i.e. the OCD is a DLL and so the node s OCD can be bound via the operating system s dynamic loader; TCP binding, i.e. the OCD listens on a TCP port and can be accessed via a TCP socket. A protocol node has a property called an access parameter. This is a text string which contains the following information, encoded as a set of key-value pairs: Information required by the binding mechanism to access the node s OCD. For example, if the node uses DLL binding, the access parameter contains the name of the DLL. Information private to the OCD, describing the location of the physical node with which the protocol node is associated. For example, if the OCD manages all connected Acme CANbox devices, the access parameter will indicate which device, and which controller, is associated with the protocol node. The access parameter of a protocol node is defined by the OCD which implements the node. Most of the contents of the access parameter is private to the OCD. A protocol node has a property known as its affinity. This indicates the physical location of the node s OCD, and therefore indicates the set of callers who can reach the OCD. For example: the OCD may be a DLL which is loaded into the BOA client s process, in which case the OCD can be reached by any caller in BOA client s process; 33

34 the OCD may be a DLL which is loaded into a process executing in the firmware of a connected hardware device, in which case the OCD can be reached by any caller within that firmware process; the OCD may be a TCP service which is listening on a particular IP address, in which case the OCD can be reached from peers in the same IP subnet (ignoring the possibilities offered by IP routing). Also, recall from section that protocol nodes have other features that extend their role beyond simply indicating whether a certain OCI API can be used to access a certain controller: A protocol node can be located underneath any node in the tree, not just those nodes representing bus controllers. A protocol node can indicate that, although it offers a certain OCI API, it requires an implementation of another API in order to operate. This concept allows protocol nodes to be chained together. A protocol node that depends on another protocol node in this manner is referred to as a protocol translation node. To construct a protocol stack, the CSL requires the BOA client to provide a URI which identifies a protocol node representing the OCI API implementation which the client wishes to use. Using the example of Figure 5-1, this could be ETAS://ETH/ES910:abcd/CAN:1/OCI_CAN. The CSL follows the URI path through the tree, and builds a stack of protocol nodes: The topmost node in the stack must: implement the OCI API which is requested by the BOA client (though remember that this topmost node may require another protocol node in order to operate); use DLL binding; have an affinity which matches the BOA client s process. In other words, the topmost node in the stack must be implemented by an OCD which can be loaded directly into the BOA client s process by the CSL. A new node is added to the bottom of the stack if both of the following statements are true the OCI API (which the new node offers) matches the API which is required by the current bottom node in the stack, and the new node s binding type and affinity indicate that it can be accessed by the current bottom node in the stack. The stack is complete when a node is added which requires no other node. Some examples make this clearer: Trivial example: binding OCI_CAN on the ETAS ES580 device The ETAS ES580 is a PCMCIA card that offers two CAN ports. Figure 5-2 shows the trivial protocol stack which describes how to call OCI_CAN for the URI ETAS://PCMCIA/ES580:abcd/CAN:1/OCI_CAN. The CSL calculates this stack as follows: 1. Begin at the root and follow the URI path until a protocol node is found which implements OCI_CAN. 2. The OCI_CAN node for CAN:1 is found. 3. The OCI_CAN node fulfils the criteria for becoming the topmost node in the protocol stack: it implements OCI_CAN; it uses DLL binding; it has an affinity which matches the BOA client s process. 4. The OCI_CAN node also fulfils the criterion for being the bottom-most node in the protocol stack, i.e. it does not require any other node. Therefore, the protocol stack is complete and contains a single node. 34

35 Now the BOA framework can call the OCI_CAN API ETAS://PCMCIA/ES580:abcd/CAN:1/OCI_CAN as follows: 1. The CSL examines the topmost (and only) protocol node in the protocol stack. 2. The CSL extracts the name of the protocol node s OCD DLL from the protocol node s access parameter. 3. The CSL loads the OCD DLL which implements the API offered by the protocol node. 4. The CSL calls the OCI_CAN API on the protocol node s OCD DLL, passing the protocol stack to the OCD DLL. 5. The OCD DLL examines the access parameter of the topmost node of the protocol stack. It extracts the serial number of the ES580 device, and controller number of the CAN controller. 6. The OCD DLL applies the OCI_CAN API to the identified device and controller. Figure 5-2: Binding OCI_CAN on the ES580 Root PCMCIA Protocol stack ES580:abcd Key: Physical node Properties of provided API Protocol node Properties of required API CAN:1 API = OCI_CAN Binding = DLL Affinity = BOA client process Access param = DLL=<filename>,serial=abcd,port=1 OCI_CAN CAN:2 API = OCI_CAN Binding = DLL Affinity = BOA client process Access param = DLL=<filename>,serial=abcd,port=2 OCI_CAN Non-trivial example: binding OCI_CAN on the ETAS ES910 device The ETAS ES910 is an Ethernet-connected device which offers two CAN, two LIN ports and (with the optional ES920 piggy-back device) two FlexRay ports. Figure 5-3 shows the protocol stack which describes how to call OCI_CAN for the URI ETAS://ETH/ES910:abcd/CAN:1/OCI_CAN. All controllers apart from CAN:1 are omitted from the diagram for clarity. The CSL calculates this stack as follows: 1. Begin at the root and follow the URI path until a protocol node is found which implements OCI_CAN. 2. A protocol translation node OciCan2Serial is found. This is a node that is able to translate OCI_CAN into a generic serialized API, for transmission across a TCP connection. The node OciCan2Serial fulfils the criteria for becoming the topmost node in the protocol stack: it implements OCI_CAN; it uses DLL binding; 35

36 it has an affinity which matches the BOA client s process. Unfortunately, because this node depends on another node in order to implement OCI_CAN, the search to complete the protocol stack must continue. 3. A protocol translation node Serial2Tcp is found. This is a node that is able to transmit the generic serialized API across a TCP connection. It is added to the bottom of the protocol stack. 4. Following the URI, the CSL moves to the ES910:abcd node. 5. A protocol translation node Tcp2Serial is found. This is a node that is able to receive the generic serialized API from a TCP connection. It is added to the bottom of the protocol stack. 6. A protocol translation node Serial2OciCan is found. This is a node that is able to convert API calls from the generic serialized from back to OCI_CAN. It is added to the bottom of the protocol stack. 7. Following the URI, the CSL moves to the CAN:1 node. 8. The protocol node OCI_CAN is found. It fulfils the criterion for being the bottommost node in the protocol stack, i.e. it does not require any other node. Therefore, the protocol stack is complete. Now the BOA framework can call the OCI_CAN API ETAS://ETH/ES910:abcd/CAN:1/OCI_CAN as follows: 1. The CSL examines the topmost protocol node in the protocol stack, i.e. OciCan2Serial. 2. The CSL extracts the name of the OciCan2Serial node s OCD DLL from the node s access parameter. 3. The CSL loads the OciCan2Serial node s OCD DLL. 4. The CSL calls the OCI_CAN API on the OciCan2Serial node s OCD DLL, also passing the protocol stack to the OCD DLL. 5. The OciCan2Serial OCD DLL serializes the OCI_CAN function call and uses the protocol stack to identify and load the Serial2Tcp node s OCD DLL. 6. The OciCan2Serial OCD DLL passes the serialized OCI_CAN function call, and the protocol stack, to the Serial2Tcp node s OCD DLL. 7. The Serial2Tcp OCD DLL uses the protocol stack to identify the IP address and port number of the Tcp2Serial node s OCD DLL that is running in a process in the ES910 firmware. 8. The Serial2Tcp OCD DLL transmits the serialized OCI_CAN function call, and the protocol stack, to the Tcp2Serial OCD DLL running on the ES The Tcp2Serial OCD DLL, on the ES910, uses the protocol stack to identify and load the Serial2OciCan node s OCD DLL. 10. The Tcp2Serial OCD DLL passes the serialized OCI_CAN function call, and the protocol stack, to the Serial2OciCan OCD DLL. 11. The Serial2OciCan OCD DLL de-serializes the OCI_CAN function call and uses the protocol stack to identify and load the OCD that implements the final OCI_CAN node. 12. The OCI_CAN OCD DLL examines the access parameter of the bottom-most node of the protocol stack. It extracts the controller number of the CAN controller. 13. The OCI_CAN OCD DLL applies the OCI_CAN API to the identified controller. 36

37 Figure 5-3: Binding OCI_CAN on the ES910 Root API = OCI_CAN Binding = DLL Affinity = BOA client process Access param = DLL=<filename> OciCan2Serial API = serial Binding = DLL Affinity = BOA client process API = serial Binding = DLL Affinity = BOA client process Access param = DLL=<filename> Serial2Tcp API = serial Binding = TCP Affinity = subnet address ETH ES910:abcd Key: Physical node API = serial Binding = TCP Affinity = subnet address Access param = TCP/<address>:<port> Tcp2Serial API = serial Binding = DLL Affinity = firmware process API = serial Binding = DLL Affinity = firmware process Access param = DLL=<filename> Serial2OciCan API = OCI_CAN Binding = DLL Affinity = firmware process CAN:1 Properties of provided API Protocol node Properties of required API API = OCI_CAN Binding = DLL Affinity = firmware process Access param = DLL=<filename>,port=1 OCI_CAN Protocol stack How the tree of nodes is built The previous sections have assumed that the tree of physical and protocol nodes exists, without saying how the CSL discovers the information which is required to build the tree. In fact, the CSL discovers the structure of the tree by using two APIs: the CSI Enumerate Component Services API (CSI_ECS), which is implemented by each OCD DLL; the CSI Enumerate Sub-Services API (CSI_ESS), which is implemented by each node in the tree. The CSL begins by assuming that all OCD DLLs are located in either the BOA directory <BOA root>\bin\win32\dll\ocds or the ED-EBI directory <ED-EBI root>\bin\win32\dll\ocds. The CSL loads each DLL in these directories and tries to call the CSI_ECS API function CSI_IdentifyComponent() on the DLL. Doing this gives the OCD the opportunity to add child nodes to any parent node that already exists in the tree. However, the OCD can only add children to a single parent, and the OCD can only add a single layer of children to the parent, i.e. it cannot add any grandchildren. Typically, when the CSL calls CSI_IdentifyComponent(), the OCD will add one or more nodes representing the PC host interfaces which the OCD uses. For example: The OCD for the ETAS ES580 adds a PCMCIA node as a child of the root of the tree. The OCD for a USB-connected device would add a USB node as a child of the root of the tree. 37

38 The OCD that searches for Ethernet-connected ETAS devices adds an ETH node as a child of the root of the tree. It is permitted for two OCDs to add a node with the same URI name, i.e. the URI name of a node does not need to be unique. For example, two different manufacturers may have USBconnected devices, so each device s OCD would add a USB node to the tree. In such a case, the USB node would appear twice in the tree. Once all OCDs have contributed to the tree via CSI_IdentifyComponent(), the CSL descends the tree recursively, calling the CSI_ESS API on each node in the tree. The purpose of the CSI_ESS API is to allow the CSL to enumerate the children of a node in the tree. Thus, any node in the tree that has children must offer the CSI_ESS API. In practice, only physical nodes can have children, therefore only physical nodes can offer the CSI_ESS API. The CSI_ESS API is handled exactly like the OCI APIs: it is implemented by an OCD and can be bound in the manner described in section 5.1.3, by constructing and using a protocol stack. Therefore, any OCD that implements one or more OCI APIs must also implement CSI_ESS to allow the CSL to discover structure of the tree Identifying an OCI API type: UUIDs and versions Throughout this document, the various types of OCI APIs are identified simply by their names, e.g. OCI_CAN, OCI_FLX, etc. However, the CSL uses some more precise concepts to identify the type of an OCI API. The first such concept is that the type of an OCI API is identified by a Universally Unique Identifier (UUID). Preprocessor definitions UUID_OCICAN, UUID_OCILIN and UUID_OCIFLX are available by including the header oci.h. The BOA client should use these definitions whenever a CSI API requires a UUID to identify the type of an OCI API. Secondly, an OCI API supports the concept of a version of the API. This allows ETAS to extend or modify the definition of an OCI API in a controlled manner. The version of an interface is identified by a 4-digit version number, i.e. a number of the form v1.v2.v3.v4. Currently only the roles of v1 and v2 are defined: a change in v1 denotes a new, incompatible version of the OCI API in question; a change in v2 denotes a compatible extension to the OCI API. An API with version number 1.n.0.0 is a superset of version 1.m.0.0, when n > m. In other words, version 1.n.0.0 contains all the functionality defined in version 1.m.0.0, plus some new functionality. Currently, all OCI API interface versions which have been defined by ETAS follow this form, i.e. each new OCI API version is a superset of all older versions of the same API. The concept of API versioning is used to enable backwards compatibility between older BOA clients and newer OCDs, or vice versa. This is discussed further in section CSI API functions CSI_CreateProtocolTree() The function CSI_CreateProtocolTree() is part of the CSI Search For Services (CSI_SFS) API. It can be used by the BOA client to build a tree of nodes that represent the connected hardware and APIs, as described in section Despite its name, CSI_CreateProtocolTree() builds a complete tree containing both physical and protocol nodes. While CSI_CreateProtocolTree() can simply be used to obtain the complete tree, it also supports filtering capabilities which allow it to return a sub-tree, i.e. a portion of the complete tree: The uriname argument specifies the root of the sub-tree which is to be created by the function. For example, specifying ETAS://ETH causes the function to create a sub-tree rooted at the ETH node, i.e. representing only Ethernet-connected hardware devices. 38

39 The range argument specifies a white filter: only nodes whose type falls within the specified range are present in the returned tree. For example, it is possible to request that only physical nodes are present in the tree. If this filter causes a node to be omitted from the tree, then all children of the node will be omitted also. Each node of the returned protocol tree is represented by a structure of type CSI_SubItem. This is a complex structure, but only a few fields are significant for a BOA client: Field nodetype uriname server.id.api.uuid Description This field identifies the type of the node, i.e. whether it is a hardware device, a host interface, a protocol node, etc. This field contains the node s URI name. This can be combined with the URI names of the node s ancestors in the tree to create a URI path which identifies the node uniquely. More details are in sections and If the node is a protocol node, this field identifies the API which the node offers. The concept of using UUIDs to identify APIs is described further in section server.id.api.version If the node is a protocol node, this field identifies the version of the API which the node offers. The concept of API versions is described further in section Instances of CSI_SubItem are linked together to create the protocol tree. For example, an ETAS ES910 connected to the PC s Ethernet port may result in a tree like this: Root Ethernet (uriname = "ETH") ES910 with serial number abcd (uriname = "ES910:abcd") CAN controller 1 (uriname = "CAN:1") CAN controller 2 (uriname = "CAN:2") LIN controller 1 (uriname = "LIN:1") LIN controller 2 (uriname = "LIN:2") URIs can be built up using the information in this tree, e.g. ETAS://ETH/ES910:abcd/CAN:2. Such a URI can then be used, for example, as an argument to OCI_CreateXXXControllerVersion(). A protocol tree which is created via CSI_CreateProtocolTree() must be destroyed by calling CSI_DestroyProtocolTree() CSI_GetUriForUuid() The previous section describes how CSI_CreateProtocolTree() can be used to build a tree structure which describes the connected hardware devices, and the APIs (i.e. protocols) which are available on each hardware device. The section also mentions that the URI of a node in the tree can be constructed by considering the uriname properties of the node and its ancestors. CSI_GetUriForUuid() is a helper function which performs this activity. CSI_GetUriForUuid() searches a tree and identifies URIs paths to all nodes which implement a certain OCI API with a certain version. When calling CSI_GetUriForUuid(): The tree is represented by an instance of CSI_Tree, as constructed by CSI_CreateProtocolTree(). The OCI API required by the BOA client is represented by an instance of the structure BOA_UuidVersion, which encapsulates the UUID and the version number of the OCI API that the BOA client wishes to find. (Section gives more details about the use of UUIDs and version numbers to identify OCI API types). 39

40 CSI_GetUriForUuid() outputs an array of URI paths, one for each node in the tree which implements the specified OCI API. The BOA client can select a URI from this array and use it as an argument to, for example, OCI_CreateXXXControllerVersion() CSI_CreateInterfaceStack() The purpose of CSI_CreateInterfaceStack() is to create a protocol stack, as described in section Recall that, in summary, a protocol stack is a data structure that describes how to route OCI API function calls to a particular OCI API implementation. A protocol stack is opaque to the BOA client. Usually a BOA client does not need to call CSI_CreateInterfaceStack() explicitly, since this is done automatically by the OcdProxy when the BOA client calls OCI_CreateXXXControllerVersion(). Therefore the reading of this sub-section is optional and can be skipped if a detailed understanding is not sought. When calling CSI_CreateInterfaceStack(), the BOA client must specify the location and type of the OCI API which is the desired target of the protocol stack. This is done by supplying the following arguments: A URI identifying the location of the target OCI API, e.g. ETAS://ETH/ES910:abcd/CAN:1/OCI_CAN. Although it is permitted for the URI to contain the API type as its last element, this is not necessary and, in fact, is discouraged. Continuing the above example: ETAS://ETH/ES910:abcd/CAN:1/OCI_CAN is permitted; ETAS://ETH/ES910:abcd/CAN:1 is preferred. A Universally Unique Identifier (UUID), identifying the type of the target OCI API. This UUID, instead of the URI, is the preferred way of indicating the type of the target OCI API. Preprocessor definitions UUID_OCICAN, UUID_OCILIN and UUID_OCIFLX are available by including the header oci.h. The version of the target OCI API. (The use of UUIDs and version numbers to identify the type of an OCI API is discussed further in section 5.1.5). Typically, the BOA client will deduce the UUID and version of the target OCI API by examining the tree constructed by CSI_CreateProtocolTree() and identifying the node which offers the API which the client wishes to call. Note that, in order to construct a protocol stack, CSI_CreateInterfaceStack() tries to communicate with each hardware device which is specified in the URI. Therefore, if the specified hardware is not connected, CSI_CreateInterfaceStack() will fail. Once the BOA client has used CSI_CreateInterfaceStack() to construct a protocol stack, the client can use the stack by passing it to the function OCI_CreateXXXControllerBind(). This function is identical to its counterpart OCI_CreateXXXControllerVersion(), except that it uses a protocol stack instead of a URI to identify the target OCI API implementation. Once the BOA client has finished using a protocol stack, the stack must be destroyed by calling CSI_DestroyInterfaceStack(). 5.3 Choosing when to search for hardware Using the BOA framework to search for connected hardware devices is a relatively timeconsuming operation, so it is important to understand how to control when a search will occur. The BOA framework will search for connected hardware devices in two situations. Firstly, and most obviously, a search will occur when a client application calls the API CSI_CreateProtocolTree() to build a tree of nodes, as described in section Secondly, a search will also occur when a client application calls the API OCI_CreateXXXControllerVersion() to connect to a specific hardware device. This is 40

41 because the internal operation of OCI_CreateXXXControllerVersion() consists of two steps: 1. Search for connected hardware, to confirm that the URI provided to OCI_CreateXXXControllerVersion() corresponds to a connected device. 2. Try to connect to the device, using the information gained during the search in step 1. The fact that a search occurs as part of the operation of OCI_CreateXXXControllerVersion() can cause poor performance, particularly if it is necessary for a client application to invoke this function many times in quick succession. Therefore the BOA framework provides an additional set of helper functions called OCI_CreateXXXControllerNoSearch() which attempt to connect to a device using information gained during a previous search. This set of functions can be used as follows: 1. Call CSI_CreateProtocolTree() to search for connected hardware devices. If required, specify a URI to restrict the host interface on which the search should occur. Note that the range parameter of CSI_CreateProtocolTree() must be set so that all node types, not just physical nodes, are included in the search results. 2. Call OCI_CreateXXXControllerNoSearch(), specifying a URI and API version (as for OCI_CreateXXXControllerVersion()), and also specifying the protocol tree created in step 1. Note that OCI_CreateXXXControllerNoSearch() will fail if the specified URI was not part of the search performed in step Call OCI_CreateXXXControllerNoSearch() with other arguments, to create further BOA API sessions Destroy the protocol tree created in step 1. Obviously if the hardware device is disconnected after step 1 then all attempts to call OCI_CreateXXXControllerNoSearch() will fail. But this is no different from what would occur anyway when using OCI_CreateXXXControllerVersion(). Finally, it is worth noting that if a BOA client application makes use of CSI_CreateInterfaceStack(), there is a corresponding function CSI_CreateInterfaceStackFromTree() which, again, allows the client to re-use the results of a search performed previously via CSI_CreateProtocolTree(). 41

42 6 Device information and licensing The BOA OCI_XXX APIs are concerned with accessing automotive buses, but BOA also provides an API which can be used to access information and functionality associated with bus-access hardware devices themselves. This is the DEV API, which was previously known as the LIC API since much of its functionality concerns licensing. The functions DEV_CreateSessionVersion() (or DEV_CreateSessionNoSearch()) and DEV_DestroySession() are used to begin and end a session of the DEV API. Use cases supported by the DEV API are: Certain ETAS hardware devices contain some device-specific licence information in their firmware which determines whether the device instance is permitted to operate with an ETAS software tool. This licence information is sometimes referred to as an "ETAS bit" in the device's firmware. An ETAS software tool can use the function DEV_GetLicenceValue() to obtain this information and decide whether to allow the user to access the device instance. When a non-etas (i.e. 3rd-party) software tool is using BOA to access ETAS hardware, the 3rd-party tool may require ETAS hardware to act as a dongle for the tool. In order to support this, an ETAS hardware device must be able to encapsulate information about the licencing of various features of the 3rd-party tool. This can be achieved by using the DEV API to store an arbitrary blob of data on the ETAS hardware device. The blob is stored on the device by the 3rd-party and later queried by the 3rd-party's software tool. The details of the DEV API are described in the BOA Reference Guide [1]. 42

43 7 Authentication Some BOA client applications such as ETAS INCA will only operate with OCD DLLs written by approved authors. To support this requirement, the BOA framework provides an ETASspecific mechanism to allow a client application to authenticate the OCD DLLs which are in use by the BOA framework. (A BOA client application which does not share this requirement to authenticate OCD DLLs can ignore the rest of this section). ETAS's mechanism for authenticating a DLL relies upon "challenge response": the BOA framework issues a value called the "challenge", and the OCD DLL is expected to authenticate itself via an appropriate response. The authentication process can be seen from two points of view: The point of view of an OCD DLL: how can an OCD DLL satisfy the BOA framework that the OCD DLL is authentic? The point of view of a BOA client application: how can a client confirm that the OCD DLLs which are in use by the BOA framework are authentic? The point of view of an OCD DLL is dealt with in detail in the OCD-DK [3], so it is only necessary to consider here the point of view of a BOA client application. If a BOA client application wants to authenticate the OCD DLL(s) which will be used to communicate with a particular hardware device, the client must take these steps: 1. The client calls CSI_CreateInterfaceStack() to create a protocol stack for its chosen BOA API and URI. This is describes further in section The client passes the protocol stack to CSI_GetOcdAuthInfo(). This function authenticates each OCD DLL which is referenced by the protocol stack, and outputs an array of CSI_OcdAuthInfo structures, giving the authentication result for each OCD DLL. 3. The client iterates over the array of CSI_OcdAuthInfo structures and confirms that all the OCD DLL(s) referenced by the protocol stack were successfully authenticated. 4. If the authentication was satisfactory, the client proceeds to use the protocol stack as an input to OCI_CreateXXXControllerBind(), to create an API session using the authenticated OCD DLL(s). 43

44 8 Backwards compatibility and API versioning 8.1 API versioning As BOA APIs such as the OCI_XXX and DEV APIs evolve, new functionality may be added to an API, or existing functionality may be modified and expanded. Section has already explained that each BOA API has an associated version number, and this number is used to identify changes to the API. The version of the original API is defined as , and the version number is incremented as new BOA releases modify the definition of the API. The reference guide [1] describes in detail the changes which have occurred in each API version. So, for example, the documentation for the field slavebaudratetype of the structure OCI_LINControllerCapabilities notes that this field was introduced in version 1.1 of the OCI_LIN API. The various versions of each API are also summarised in an appendix of this document, in section 13. It is important that each BOA client clearly understands which API version he requires in order to operate. For example, a client which uses CAN-FD requires at least v1.3 of OCI_CAN. If this version is not offered by the connected hardware device, the client must consider whether he can operate without CAN-FD, or whether he must abort. This question is one aspect of backwards compatibility, which is discussed further in the next section. Similarly, it is important that each BOA OCD clearly understands which API versions it offers. Particularly, an OCD should note that when it offers version 1.x of an API, it is assumed also to offer all previous versions from 1.0 up to 1.(x-1). 8.2 Backwards compatibility When a BOA API is modified and a new version is created, it is necessary that the following use cases are correctly supported: A client which was built to use the new API definition may be used with an OCD which only implements the old API definition. The client must still be able to operate, though obviously without using any features which were introduced in the new API definition. An OCD which implements the new API definition may be used by a client which was built to use the old API definition. Such a client must still get the behaviour which he expects from the OCD. The BOA framework supports both these use cases via the same mechanism. When a BOA client creates a new session of a BOA API for a particular URI, the BOA client and the referenced OCD can each discover which versions of that BOA API are supported by the other. This is described in the following two subsections Backwards compatibility from a BOA client s perspective This is how a BOA client must proceed if it uses a new API version which may not be supported by the OCD associated with its chosen URI. OCI_CAN is used as an example: 1. The BOA client begins by trying to use its ideal version of OCI_CAN, e.g. v1.3. He uses OCI_CreateCANControllerNoSearch() (or OCI_CreateCANControllerVersion()) to try to create an OCI_CAN session which uses this API version for its chosen URI. 2. If OCI_CreateCANControllerNoSearch() fails with the error BOA_ERR_PROTOCOL_VERSION_NOT_SUPPORTED the BOA client knows that the OCD associated with its chosen URI does not support v1.3 of OCI_CAN. At this point, the BOA client must decide whether OCI_CAN v1.3 is essential for its operation or whether it could fall-back to a previous version of OCI_CAN. 3. If the BOA client decides he can use a previous version of OCI_CAN, he repeatedly calls or OCI_CreateCANControllerNoSearch() for older and older versions of OCI_CAN, until he finds a version of OCI_CAN which succeeds. This is the latest version of OCI_CAN which is supported by the OCD associated with the client's chosen URI. 44

45 Now that the BOA client has successfully established an older version of OCI_CAN which he can use, it is vital that he does not attempt to use features which are only available in newer versions of OCI_CAN. Specifically, he must not: call API functions which were added in a newer version of OCI_CAN; access structure fields which were added in a newer version of OCI_CAN. So, for example, if a BOA client ideally requires OCI_CAN v1.3 but uses OCI_CAN v1.1 as a compromise, he must not: call OCI_WriteCANDataEx() or OCI_ReadCANDataEx(); read the value of the field canfdsupport in the structure OCI_CANControllerCapabilities; set the value of the field canfdenabled in the structure OCI_CANConfiguration; Backwards compatibility from an OCD s perspective Now consider an OCD's point of view: the OCD must discover the API version which is being requested by the BOA client so that the OCD can adapt its behaviour to that expected by the client, in case the client was built to use an older version of the API. An OCD can discover the API version requested by a BOA client via the parameter protocolstack which is passed to the OCD's implementation of OCI_CreateCANControllerBind() (again using OCI_CAN as an example). The field protocolstack->server.id.api.version contains the required information. Once the OCD has discovered the API version requested by the client, the OCD can behave accordingly, either offering new behaviour if the client requested a newer API version, or offering old behaviour in order to maintain backwards compatibility with an older client. Once the OCD has deduced that the client has requested an older version of the API, it is vital that the OCD does not attempt to use features which are only available in newer versions of the API. Specifically, when the client uses the API to get or set a structure instance the OCD must not access structure fields which were added in a newer version of the API. So, for example, if a BOA client requests OCI_CAN v1.1 even though the OCD supports OCI_CAN v1.3, the OCD must not: set the value of the field canfdsupport in the structure OCI_CANControllerCapabilities; read the value of the field canfdenabled in the structure OCI_CANConfiguration; Doing so will have undefined behaviour due to possible overwriting of memory etc.. 45

46 9 Troubleshooting BOA-specific problems This chapter gives some information of what you can do if problems arise during your work with BOA. 9.1 General problems while working with BOA When compiling your software, the compiler cannot find the file OCI\oci.h Check for the following possible causes: Make sure you have the EBI-IP (or OCD-DK) installed. Make sure you have set the compiler s include path to refer to (ProgramFiles)\ETAS\BOA_V2\Include You cannot find any hardware when searching using CSI Check for the following possible causes: Check whether there is a general hardware access problem. See section (Search for Ethernet Hardware fails). Make sure the hardware's OCD DLL is present in the directory (ProgramFiles)\ETAS\ED-EBI_V2\Bin\Win32\Dll\OCDs. Make sure that your application is linking to the LIB dll-csibind.lib which is located in folder (ProgramFiles)\ETAS\BOA_V2\Bin\Win32\Lib. Do not move the DLL (ProgramFiles)\ETAS\BOA_V2\Bin\Win32\Dll\Framework\dllcsiBind.dll to another location. 9.2 Integrating ETAS Hardware into 3rd Party Software When compiling your software, the linker cannot find symbols for the OCI and/or CSI APIs Check for the following possible causes: Make sure you added dll-csibind.lib and dll-ocdproxy.lib to the linker's input. Make sure you installed the EBI-IP correctly and that the required lib files are present in (ProgramFiles)\ETAS\BOA_V2\Bin\Win32\Lib When running the application, a message pops up saying: "This application has failed to start because <name>.dll was not found. Re-installing the application may fix this problem." Check for the following possible causes: Make sure that you have modified the Windows PATH environment variable to point to the location (ProgramFiles)\ETAS\BOA_V2\Bin\Win32\Dll\Framework. Make sure you have installed the BOA Runtime Framework correctly (do not copy DLLs to your project folders etc.). 46

47 10 Troubleshooting ETAS Ethernet problems This chapter gives some information of what you can do if problems arise that are not specific to an individual software or hardware product Problems and Solutions BOA fails to access Hardware connected via Ethernet Network Settings tool (Network Manager) For BOA to be able to access hardware connected via an Ethernet connection, the user must run the ETAS Network Settings tool (i.e. Network Manager) at least once. This is usually available from the ETAS shortcut. Once the Network Settings tool is running and visible you should see a dialog window similar to that in Figure 7-1 below Figure 10-1: The ETAS Network Settings Tool Press the <F1> key to display the help screen. Network Settings overview ETAS software supports different configurations for hardware access via Ethernet: Using multiple network adapters: One network adapter for the company network the ETAS hardware Using one network adapter: Automatic toggling between the company network and the vehicle application. You do not need a separate network adapter to connect the ETAS hardware to your PC. You can use the same network adapter for the corporate network and for the ETAS network. The Network Manager assists you in configuring the network environment for the ETAS hardware. The Network Manager gives you an overview of the available network adapters of your PC and the type of IP address assignment. Here, you select the network adapter with which you 47

48 want to connect the ETAS hardware to your PC. Additionally, you can define the address pool for the IP assignment of the ETAS hardware. To select the network adapter and configure the network environment for the ETAS hardware, you do not need administrator rights, and you can switch between the ETAS network and the corporate network without rebooting your PC Network Adapter cannot be selected via Network Manager Cause: APIPA is disabled The alternative mechanism for IP addressing (APIPA) is usually enabled on all Windows XP and Vista systems. Network security policies, however, may request the APIPA mechanism to be disabled. In this case, you cannot use a network adapter which is configured for DHCP to access ETAS hardware. The ETAS Network Manager displays a warning message. The APIPA mechanism can be enabled by editing the Windows registry. This is permitted only to users who have administrator privileges. It should be done only in coordination with your network administrator. To enable the APIPA mechanism: Open the Registry Editor: Windows XP: Click Start and then click Run. Enter regedit and click OK. Windows Vista or Windows 7: Click Start, enter regedit in the entry field, and push <ENTER>. The registry editor is displayed. Open the folder HKEY_LOCAL_MACHINE\SYSTEM\ CurrentControlSet\Services\ Tcpic\Parameters\ Click Edit Find to search for the key IPAutoconfigurationEnabled. If you cannot find any instances of the registry key mentioned, the APIPA mechanism has not been disabled on your system, i.e. there is no need to enable it. Otherwise proceed with the following steps Search for Ethernet Hardware fails Set the value of the key IPAutoconfigurationEnabled to 1 to enable the APIPA mechanism. You may find several instances of this key in the Windows registry which either apply to the TCP/IP service in general or to a specific network adapter. You only need to change the value for the corresponding network adapter. Close the registry editor. Restart your workstation in order to make your changes take effect. Cause: The versions of the Hardware and the ETAS MC Software are not compatible If you are using ETAS hardware with ETAS MC software, you can use the ETAS HSP Update Tool to check the firmware version of your hardware: Make sure you use the ETAS HSP Update Tool with the latest HSP (Hardware Service Pack) version. Also use the HSP Update Tool to check whether the hardware is compatible with the MC software used. Make sure any additional drivers for that hardware are installed correctly. 48

49 You can get the required HSP from the ETAS internet pages at If you still cannot find the hardware using the HSP Update Tool, check whether the hardware offers a Web interface and whether you can find using this interface. Otherwise, check whether one of the following causes and solutions might apply. Cause: Personal Firewall blocks Communication For a detailed description on problems caused by personal firewalls and possible solutions see Cause: Permissions given through the firewall block ETAS hardware later in this section. Cause: Client Software for Remote Access blocks Communication PCs or notebooks which are used outside the ETAS hardware network sometimes use a client software for remote access which might block communication to the ETAS hardware. This can have the following causes: A firewall which is blocking Ethernet messages is being used (see Cause: Personal Firewall blocks Communication on page 49). By mistake, the VPN client software used for tunnelling filters messages. As an example, Cisco VPN clients with versions before V4.0.x in some cases erroneously filtered certain UDP broadcasts. If this might be the case, please update the software of your VPN client. Cause: ETAS Hardware hangs Occasionally the ETAS hardware might hang. In this case switch the hardware off, then switch it on again to re-initialize it. Cause: ETAS Hardware went into Sleep Mode In order to save power, some ETAS devices will go to sleep mode if they do not see that they are connected to another device/computer. To solve that, connect your Ethernet cable from your computer to the "HOST"/"Sync In" port on the device. After the device turns on, connect to the device using the web interface and change the settings so that the device always stays on. Consult the device's manual for details on how to do that. Cause: Network Adapter temporarily has no IP Address Whenever you switch from a DHCP company LAN to the ETAS hardware network, it takes at least 60 seconds until ETAS hardware can be found. This is caused by the operating system s switching from the DHCP protocol to APIPA, which is being used by the ETAS hardware. Cause: ETAS Hardware had been connected to another Logical Network If you use more than one PC or notebook for accessing the same ETAS hardware, the network adapters used must be configured to use the same logical network. If this is not possible, it is necessary to switch the ETAS hardware off and on again between different sessions (repowering). Cause: Device driver for network card not in operation It is possible that the device driver of a network card is not running. In this case you will have to deactivate and then reactivate the network card. To deactivate and reactivate the network card: To deactivate the network card first select in the Windows start menu the following item: Windows XP: Control Panel Network Connections 49

50 Windows Vista or Windows 7: Control Panel Network and Internet Network and Sharing Center Right click on the used network adapter and select Disable in the context menu. In order to reactivate the network adapter right click on it again and select Enable. Cause: Laptop power management deactivates the network card The power management of a laptop computer can deactivate the network card. Therefore, you should turn off power monitoring on the laptop. To switch off power monitoring on the laptop: From the Windows Start Menu, select Windows XP: Control Panel System. Then select the Hardware tab and click on Device Manager. Windows Vista or Windows 7: Control Panel System and Maintenance Device Manager. In the Device Manager open the tree structure of the entry Network Adapters. Right click on the used network adapter and select Properties in the context menu. Select the Power Management tab and deactivate the Allow the computer to turn off this device to save power option. Select the Advanced tab. If the property Autosense is included, deactivate it also. Click OK to apply the settings. Cause: Automatic disruption of network connection It is possible, after a certain period without data traffic, that the network card automatically interrupts the Ethernet connection. This can be prevented by setting the registry key autodisconnect. To set the registry key autodisconnect: Open the Registry Editor. Select under HKEY_LOCAL_MACHINE\SYSTEM\ ControlSet001\Services\lanmanserver\parameters the Registry Key autodisconnect and change its value to 0xffffffff. Cause: Permissions given through the firewall block ETAS hardware Personal firewalls may interfere with access to ETAS Ethernet hardware. The automatic search for hardware typically cannot find any Ethernet hardware at all, although the configuration parameters are correct. Certain actions in ETAS products may lead to some trouble if the firewall is not properly parameterized, e.g. upon opening an experiment in ASCET or searching for hardware from within INCA or HSP. If a firewall is blocking communication to ETAS hardware, you must either disable the firewall software while working with ETAS software, or the firewall must be configured to give the following permissions: Outgoing limited IP broadcasts via UDP (destination address ) for destination ports or

51 Incoming limited IP broadcasts via UDP (destination IP , originating from source IP ) for destination port Directed IP broadcasts via UDP to the network configured for the ETAS application, destination ports or Outgoing IP unicasts via UDP to any IP in network configured for the ETAS application, destination ports through Incoming IP unicasts via UDP originating from any IP in the network configured for the ETAS application, source ports through 18020, destination ports through Outgoing TCP/IP connections to the network configured for the ETAS application, destination ports through Note The ports that have to be used in concrete use cases depend on the hardware used. For more precise information on the port numbers that can be used please refer to your hardware documentation. Windows XP, Windows Vista and Windows 7 come with a built-in personal firewall. On many other systems it is very common to have personal firewall software from third party vendors, such as Symantec, McAfee or BlackIce installed. The proceedings in configuring the ports might differ for each personal firewall software used. Therefore please refer to the user documentation of your personal firewall software for further details. As an example for a firewall configuration, you will find below a description on how to configure the widely used Windows XP firewall if the hardware access is prohibited under Windows XP with Service Pack 2. Solution for Windows XP Firewall, Users with Administrator Privileges If you have administrator privileges on your PC, the following dialog window opens if the firewall blocks an ETAS product. To unblock a product: In the "Windows Security Alert" dialog window, click on Unblock. The firewall no longer blocks the ETAS product in question (in the example: ASCET). This decision survives a restart of the program, or even the PC. 51

52 Instead of waiting for the "Windows Security Alert" dialog window, you can unblock ETAS products in advance. To unblock ETAS products in the firewall control: From the Windows Start Menu, select Settings Control Panel. In the control panel, double-click the Windows Firewall icon to open the "Windows Firewall" dialog window. In the "Windows Firewall" dialog window, open the "Exceptions" tab. This tab lists the exceptions not blocked by the firewall. Use Add Program or Edit to add new programs, or edit existing ones. 52

53 Make sure that the ETAS products and services you want to use are properly configured exceptions. Open the "Change Setup" window. To ensure proper ETAS hardware access, make sure that at least the IP addresses xxx are unblocked. Close the "Change Setup" window with OK. Close the "Windows Firewall" dialog window with OK. The firewall no longer blocks the ETAS product in question. This decision survives a restart of the PC. Solution for Windows XP Firewall, Users without Administrator Privileges This section addresses users with restricted privileges, e.g., no system changes, write restrictions, local login. Working with an ETAS software product requires "Write" and "Modify" privileges within the ETAS, ETASData, and ETAS temporary directories. Otherwise, an error message opens if the product is started, and a database is opened. In that case, no correct operation of the ETAS product is possible because the database file and some *.ini files are modified during operation. The ETAS software has to be installed by an administrator anyway. It is recommended that the administrator assures that the ETAS program/processes are added to the list of the Windows XP firewall exceptions, and selected in that list, after the installation. If this is omitted, the following will happen: The "Window Security Alert" window opens when one of the actions conflicting with a restrictive firewall configuration is executed. To unblock a program (no Admin privileges): In the "Windows Security Alert" dialog window, activate the option For this program, don t show this message again. Click OK to close the window. An administrator has to select the respective ETAS software in the "Exceptions" tab of the "Windows Firewall" dialog window to 53