EcuX - File format suggestion by evc.de

Version 0.5, 29.12.2020. Differences to 0.4 are marked in brown. (Req. WinOLS 4.50)
Version 0.4, 29.1.2019. Differences to 0.3 are marked in green.
Version 0.3, 30.1.2014. Differences to 0.2 are marked in blue.

 

1.   Open format

EcuX is an open format. We’re inviting you to implement it in your software. To discuss extensions or get notified when we release updated specifications, please contact EVC.

2.   Wrapper

EcuX files are regular zip files where the suffix has been changed to EcuX.
Example: myfile.EcuX

3.   Content overview

4.   Contents.ini header

All files should start with a comment header to explain the file format:
; This is the Contents.ini file of an EcuX package. It's an open format, you're welcome to import/export it with your own tools. For the current version documentation check http://ecux.evc.de/

Furthermore a version number and authoring tool name are recommended:
[global]
EcuX_version = 0.3
AuthorTool = WinOLS

5.   Versions

EcuX 0.3 introduces file versions. Now one EcuX file can contain multiple versions of the same tuning data. For example an original version, a “+5%” version and a “+10%” version. If you use versions, then each function (e.g. CPU) must be included in each version. EcuX 0.3 introduces versions in such a way that old importers should be able to handle the files and just import the original version, ignoring anything else.

Example of binary files included in an EcuX archive file:

 

CPU

Eprom

EEprom

Version 1

cpu1.bin

eprom1.bin

Eeprom1.bin

Version 2

Cpu2.bin

eprom2.bin

eeprom2.bin

(It’s not mandatory to use *these* names.)

6.   Additional non-standard files

Normally all files (except the contents.ini files) included in the zip file, should be explained in the “File1, File2, …” section(s) in the “Filename, Filename_v2, …” value(s). If you want to include additional files that are not part of the standard, it’s recommended to prefix the names of these files with the text “NonStandard_”. Example “NonStandard_MyAdditionalData.txt”.

7.   Sections and Values

Sections:

[global]

Recommended. Includes data about the file itself.

[File1]

Mandatory. The [File...] section explains the program which other files it should import as binary from the zip package.

[File2], …

There can be more than 1 file. Note that [File3] may only exist if [File2] contains at least an entry for "Filename".

[Description]

Additional information about all the files in general. Note that this data is very similar to the WinOLS ini-format.

[NonStandard_AuthorName]

If you need any file format extensions, please contact EVC. If you do not want to contact EVC or if the extensions should not be included into the standard, please put all data in a section starting with [NonStandard_...
Applications should ignore this data unless they really know how to handle it.

Section: global:

EcuX_version

The version of the standard that this file uses.

AuthorName

The name of the software that was used to create this file.

Section: File1 (, File2, …):

Filename

Mandatory. Refers to a file in the same zip package that the contents.ini file was in.

Optional in 0.5, if Length is present.

Filename_v2, Filename_v3, …

If the EcuX file contains more than 1 version, then the filenames (for the other versions of this element) are written here.

Function

Explains from which hardware part this file comes from.

Valid values: Configuration, CPU, CPU2, CPU3, CPU4, Eprom, Eprom2, Eprom3, Eprom4, EEprom

ReadOffset          

The offset if only a part of the memory is read, mostly used at OBD data area programming.

DisplayOffset

The offset where the processor sees the memory, mostly necessary at Tricore.

Length

Length of this File in hex. Only necessary when no filename (and thus no file) is given. Useful for declaring virtual elements within a file.

IsHardware

“true” or “false”. Non-Hardware elements usually overlap hardware elements and are listed as virtual elements within hardware elements.

IsValid

“true” or “false”. Rarely needed. Can be used to declare an element which should not be used because it’s not in the file.

ReadIsOnlyPartial

Valid values: "Yes" if only a partial file is read via OBD; otherwise "No"

In case of “Yes” the ReadOffset should be set.

NonStandard_AuthorName

If you need any file format extensions, please contact EVC. If you do not want to contact EVC or if the extensions should not be included into the standard, please put all file1, 2…-related extension data in a field starting with NonStandard_...
Applications should ignore this data unless they really know how to handle it.

Section: Description:

NumVersions

The number of versions in this file. If this value isn’t present, the importer should assume “1”.

VersionName, VersionName_v2, VersionName_v3, …

The name of version 1 (often the original), version 2, version 3, ...

ClientName

Customer's name

ClientLicenseplace

Customer's license plate

ClientVIN

Customer's vehicle identification number

VehicleType

The vehicle type
Valid values: Passenger car, Truck, Motor bike, Agriculture, Boat, Bus, Other

VehicleProducer

The car manufacturer                       e.g. Audi, BMW,  MB

VehicleSeries

The product line                                e.g. A8,    F25,       W221

VehicleBuild

The generation of the product line e.g. D4,    X3,         C

VehicleModel

The model, mostly engine specific e.g. 4.2L, 3.0T,      350CDI

VehicleCharacteristic

If the manufacturer has released a tuning version e.g. CSL, OPC

VehicleModelyear

The year e.g. 2011

Userdef1

These items are (for WinOLS) imported in the "Userdef" fields. The user can assign (in WinOLS) a custom field name to any of the 5 fields.

Userdef2

 

Userdef3

 

Userdef4

 

Userdef5

 

EcuUsage

Valid values: Engine, Transmission, ABS

EcuProducer

The manufacturer of the ECU e.g. Bosch

EcuBuild

The product name of the ECU by the manufacturer e.g. MED9.1

EcuProdNr

The ECU number of the vehicle manufacturer e.g. 1K0907115F

EcuStgNr

The ECU number of the ECU manufacturer e.g. 0261S02227

EcuSoftware

The software number of the ECU manufacturer e.g. 377837

EcuSoftwareversion

The software version of the EVC manufacturer e.g. 000

EngineName

The name of the engine e.g. A16LET, M50

EngineType

Valid values: Diesel, Petrol, Turbo-Diesel, Turbo-Petrol

EngineDisplacement

e.g. 2.0L

EngineTransmission

Valid values: Automatic transmission, Switch gear

OutputPS

e.g. 136

OutputKW

e.g. 100

ReadingHardware

How the file has been created.
Valid values: BDM100, CMD-Flash, Byteshooter, NewGenius, OptiCan, KESS, SPI-Wizard III

ProjectType

Contents of the files. Valid values include: Partial (map data),Partial (full length),Complete binary file, BdmToGo, BslToGo, Eprom

PleaseContact

If file [File_] is encrypted: Who can decode it.

VersionName

This version's name. E.g. "Original"

Comment1

Values in Ini files must not contain line breaks. To simulate line breaks in comments, use multiple comments with numbers.

Comment2, …

Value of second line, third line, …

ClientNumber

A customer number

ClientLicenceplace

The customer’s license plate

EcuUse

e.g. Engine

EcuSoftwareversionVersion

The lower part of the software version

EngineEmissionStandard

e.g. Euro 3

ResellerProjectDetails

For WinOLS resellers

ResellerProjectType

For WinOLS resellers

ResellerCredits

For WinOLS resellers

8.   Contents.ini - smallest valid example

; This is the Contents.ini file of an EcuX package. It's an open format, you're welcome to import/export it with your own tools. For the current version documentation check http://ecux.evc.de/

 

[File1]

Filename             = data.bin

9.   Contents.ini – all info field example

; This is the Contents.ini file of an EcuX package. It's an open format, you're welcome to import/export it with your own tools. For the current version documentation check http://ecux.evc.de/

 

[Global]

EcuX_version         = 0.3

AuthorTool           = WinOLS

 

[File1]

Filename             = data.bin

Function             = CPU

ReadOffset           = 0x00000000

DisplayOffset        = 0x00000000

ReadIsOnlyPartial    = No

 

NonStandard_AcmeLtd  = MyValue

 

 

[File2]

Filename             = more.bin

Function             = Eprom

 

NonStandard_AcmeLtd  = MyValue

 

 

[Description]

ClientName           = ...

ClientLicenceplace   = ...

ClientVIN            = ...

 

VehicleType          = Passenger car

VehicleProducer      = VW

VehicleSeries        = Golf

VehicleBuild         = 6

 

VehicleModel         = 2.0TFSI

VehicleCharacteristic =

VehicleModelyear     = 2011

 

Userdef1             = ...

Userdef2             = ...

Userdef3             = ...

Userdef4             = ...

Userdef5             = ...

 

EcuUsage             = Engine

EcuProducer          = Bosch

EcuBuild             = MED9.1

EcuProdNr            = 1K0907115F

EcuStgNr             = 0261S02227

EcuSoftware          = 377837

EcuSoftwareversion   = 000

 

EngineName           = ...

EngineType           = ...

EngineDisplacement   = ...

EngineTransmission   = ...

OutputPS             = ...

OutputKW             = ...

EngineEmissionStandard = ...

 

ReadingHardware      = BDM100

ProjectType          = Hardware

PleaseContact        = John Doe

VersionName          = Original

Comment1             = Please, modify XYZ and then ...

Comment2             = This is a second line (after a line break)

 

 

[NonStandard_AcmeLtd]

Key1                 = Value1

Key2                 = Value2

Key3                 = Value3

 

10.         Contents.ini – example with versions

; This is the Contents.ini file of an EcuX package. It's an open format, you're welcome to import/export it with your own tools. For the current version documentation check http://ecux.evc.de/

 

[Global]

EcuX_version         = 0.3

AuthorTool           = WinOLS

 

[File1]

Filename             = data1.bin

Filename_v2          = data2.bin

Filename_v3          = data3.bin

Function             = CPU

 

[File2]

Filename             = more1.bin

Filename_v2          = more2.bin

Filename_v3          = more3.bin

Function             = Eprom

 

[Description]

NumVersions          = 3

VersionName          = My original

VersionName2         = My version 2

VersionName3         = My version 3

ClientName           = ...

ClientLicenceplace   = ...

ClientVIN            = ...

 

11.         WinOLS-Specific Extensions

The following data fields are not part of the EcuX core specifications because they require WinOLS:

Section: Description:

NonStandard_Evc_ApplyScript

Once the EcuX file is successfully imported into WinOLS, this .winolsskript file is applied to the project when importing. Useful for transferring map data. See the WinOLS help file for details.

 

Example:

[Description]

NonStandard_Evc_ApplyScript = NonStandard_script.winolsskript