Extending OpenECU Calibrator: Developers’ Guide

OpenECU Calibrator can be extended with your own code in several ways:

Extras are user-written functionality, usually taking the form of a new window in OpenECU Calibrator. They appear under the “Extras” menu. They can be saved as part of the workspace, and access OpenECU Calibrator’s facilities for interacting with hardware, seed-key security, protocols, memory and symbols.
Hardware plug-ins allow you to add support for a new hardware interface device, e.g. a previously unsupported CAN interface.
Protocol plug-ins allow you to write custom protocols to communicate with embedded systems to access their memory. They can use one of OpenECU Calibrator’s available hardware channels and are selected in the ECU window.
Scripting: it is possible to “call” OpenECU Calibrator from within another program, including a command-line program, to take care of automated tasks such as factory programming of ECUs.

All of the plug-ins take the form of .NET DLL files which OpenECU Calibrator searches its installation directory for each time it runs. OpenECU Calibrator already uses plug-ins itself to implement protocols and hardware channels; look for snoop_*.dll files in C:\Program Files\OpenECU Calibrator (or wherever it is installed).

Note: you must follow the naming convention for DLL files:
snoop_extra_*.dll for Extras
snoop_hw_*.dll for hardware channel types
snoop_protocol_*.dll for protocols

NOTE: currently all of the extensibility interfaces to OpenECU Calibrator are informal and undocumented.

Examples

Install the OpenECU Calibrator Developer package to the Developer folder of the program directory for example code.

Snoop Simple Serial Protocol (S3P)

This very simple protocol is detailed in more depth in the S3P help page. Although it can be used as-is, it is also intended as a starting-point for developers and hence source code is provided in the examples, both for the tool side and the ECU side.

Architecture

Each Extra is a c# class library project, which creates a DLL.

It has one top-level class which we get one instance of when the DLL is used by OpenECU Calibrator. This gets called by OpenECU Calibrator on various events, e.g. workspace save, menu item for Extra hit, symbols loaded, etc. Please read the commented top-level snoop_extra_???.cs code for more detail.

If your DLL produces a window of its own, it needs a Windows Form class too. For Extras, assuming the user is allowed different instances of your window, the top-level class needs to manage keeping track of those different child instances, and saving all of their settings, and passing on any events to every window of that sort.

Debug and development

The existing examples build in Visual Studio 2008 (including the free Express C# version). However, the 2010 also works fine. 2012 is untried.

Project Setup

If using Visual Studio 2010, Visual Studio changes the referenced .NET version from 3.5 to 4 when a VS2008 project is first opened and converted. Be sure to open the project properties and target the .NET framework v3.5, otherwise OpenECU Calibrator will not be able to load your DLL.
In References, the OpenECU Calibrator reference should point to C:\Program Files\OpenECU Calibrator\OpenECU Calibrator.exe. As Visual Studio remembers this as a relative path, it may be initially wrong in your copy of an example project. Also, it says it can’t find it if the OpenECU Calibrator version you have installed differs from that when the reference was made. If there is a problem, delete OpenECU Calibrator from the list of project references and browse to add it again.
Note: you may get a security warning about referencing an external executable! You need to choose ‘Open Project Normally’ (not just for browsing).
In Properties… Build… Output path, the Debug output folder should similarly be set to C:\Program Files\OpenECU Calibrator\ so that the .dll lands in the OpenECU Calibrator program folder each time you build. (But the Release target may be your own place so that the final .dll can be conveniently stored in version control and shared with others.)
If you store your release version under version control, ensure your working copy is read/write when you attempt to build, otherwise Visual Studio will not overwrite it.

Using the debugger

Debugging is possible, even though the OpenECU Calibrator source code is not provided.

Visual Studio Professional

Build the debug version of your DLL, setting the OpenECU Calibrator installation directory as the target build output location.
Set breakpoints as required in the your DLL.
Run OpenECU Calibrator as normal.
In Visual Studio, do Debug… Attach to Process and browse to the running OpenECU Calibrator.exe process.
Now the breakpoints in your code should be hit when the relevant functions in your DLL are called by OpenECU Calibrator.

Visual Studio Express 2010

This lacks some functions of the Professional version, but there are workarounds.

Firstly, to enable Debug and Release configurations to be selected:

Do Tools… Settings… Expert Settings
Open Tools… Options
… and select Show All Settings
… and in Projects and Solutions… General, select Show Advanced Build Configurations.

To debug your .DLL when it is called by OpenECU Calibrator:

Close your solution in Visual Studio.
Using another editor (e.g. Notepad), open the project.csproj file.
Add the block of XML shown below to your file and save it. (You may have to adjust the path for your installation.)
Re-open your solution.
Now when you do Debug… Go, OpenECU Calibrator will be launched and your breakpoints hit.

    <PropertyGroup>
    <StartAction>Program</StartAction>
    <StartProgram>C:\Program Files\OpenECU Calibrator\OpenECU Calibrator.exe</StartProgram>
    </PropertyGroup>

Return to Getting Started