You are currently viewing 应用笔记 | TSMaster如何使用同星标定模块

Application Notes | TSMaster How to Use TOSUN Calibration Module

Previously we came out on the TSMaster application notes series of several articles, partners feedback are very practical, but also engineers in the use of TSMaster software in the practical problems that will be encountered, today continue to bring you the application notes series of articles - how to code automatically send LIN messages.
Table of Contents for this article

I. Calibration input file preparation

The TSMaster Calibration module relies on two types of files and ECUs running the XCP or CCP stack.
(A2L files and Seed&Key files on which TSMaster depends)

1|A2L Document

A2L file is a file written in a set of descriptive XML-like language specified by ASAP2 (using open tags and close tags to describe the information), which contains the software and system information of a specific ECU, and also contains the protocol of the communication between the host computer and the ECU, which is used to guide the communication and interaction process between the host computer and the ECU, so that they can have a consistent understanding of the information of the interaction. It is used to guide the communication process between the host computer and the ECU so that they have a consistent understanding of the information they are interacting with.

Currently, TOSUN XCP and CCP modules only support loading A2L files with the highest version of 1.6x, and newer A2L files (with version number greater than or equal to 1.7) are only partially loaded. If you only have the newer A2L files, please save the 1.6x version with the relevant tools before loading them with TSMaster.

2|Seed & Key Algorithm File

For security reasons, access to certain data or requests in the ECU is restricted. Incorrect execution of routines by the controller (e.g., key learning, tire pressure calibration, etc.) or data downloads (controller program refresh, etc.) can damage the current controller or other vehicle components, which may result in the vehicle not being able to drive properly, failing vehicle inspections, decreasing the safety of the vehicle, and so on. The main measure of such access restrictions lies in the implementation of algorithms (similar to keys), i.e., seeds and keys.

The host computer (cell phone, computer, etc.) requests a seed seed from the controller, which generates a random number to be used as the seed (e.g., 1122334455667788-variable length, variable content). The controller returns this seed to the host computer. The host computer generates a key using the algorithm given by the controller (different algorithms may exist for different controllers) and the seed, and sends the key to the controller. The controller compares the key generated by the controller (with the same algorithm) with the key sent by the host computer, if it is the same, then the access restriction of the host computer will be turned on, otherwise, the host computer still can't carry out restricted access (e.g., refreshing, learning from calibration, etc.).

Since the seed is randomly generated, i.e., the controller generates a different one each time, the host computer must implement the algorithm specified by the controller. Therefore, the host computer must implement the controller's specified algorithm, otherwise the access restriction will not be lifted.

If the ECU supports the seed and Key algorithms, TSMaster relies on a DLL file that implements the corresponding unlocking algorithm. Please refer to AN0002 for details on how to create this file.

3|Calibration-enabled ECU

For demonstration purposes, this example uses the XCPSim virtual ECU that comes with the Vector installation package as an example to show how to calibrate this ECU using TSMaster. In the real application, the ECU should be switched to the user's real ECU.

XCPSim runs on hardware channel 2 of Vector Virtual 1 by default, so the application only needs to connect to hardware channel 1 of Vector Virtual 1 to communicate with it.

After installing Vector CANoe Demo version or Vector CANape, use everything to search for "XCPSim.exe" and launch it:

(Vector's XCPSim is pictured above)

II. TOSUN calibration License authorization

TOSUN calibration module is one of the few modules in the TSMaster freeware that needs to be registered in order to use the full functionality. If you do not register TOSUN calibration module, there will be the following limitations in the actual calibration.

1|Restriction of non-calibrated License

serial number functionality limitation
1 Supported Hardware All supported hardware of TSMaster (TOSUN, Vector, PEAK, Intex, Kvaser, Zhou Ligong) can be linked, but only variables can be monitored, not modified!
2 Number of monitored variables Each ECU can monitor up to 8 variables simultaneously
3 Download, modify variables unsupported

2|Calibration License Features

Calibration License depends on the hardware and can only be installed in the hardware of TOSUN, so other brands of tools can not be registered calibration License. after the registration of TOSUN calibration License, the use of the following characteristics need to pay attention to:
serial numberfunctionalitylimitation
1Supported HardwareHardware produced by TOSUN
2Number of monitored variablesinfinitely
3Download, modify variablesSupport, unlimited number
4Supported channelsAll CAN channels that come with the hardware on which the License is installed. Note that the channels of other tools emulated in a TSMaster application do not support the calibration of the License.

3|TOSUN Calibration License Authorization

Please contact TOSUN Technology Ltd. for information about calibration License authorization. The contact information is listed below.

Address: Room 904, Jiading Branch Park, National University Science Park of Tongji University, No. 4801, Cao'an Highway, Jiading District, Shanghai, China.
Tel: +86-021-59560506

After obtaining the authorization for TOSUN Calibration License and getting the hardware with the License, plugging in the hardware and using TSMaster to connect to the hardware once, the authorization information will appear in the About page of TSMaster:

(Authorization information will be displayed in the About window of TSMaster)

III. Basic configuration of TSMaster calibration module

1|TSMaster Calibration Module User Interface

Create a new project according to the following steps and use the calibration module:
1) New construction
Clicking New Project will bring up the Template Selection dialog box:

(Click on the toolbar - Project - New button)

2) Select the calibration engineering module

3) Create a calibrated empty project

4) In the calibration window, select the "Device" node, right click on it and select "New ECU".

(5) Enter the name of the ECU and click OK, the system will automatically add and select the newly created ECU.

(6) Driver selection, users need to select XCP or CCP protocol in the first line of the parameter, after selecting the protocol, then load the database file. If you need to adjust the protocol after loading the A2L file, you need to load the A2L file again after changing the protocol.

7) Load the A2L file, first select the "Database" line, click the "Open" button on the right side, select the A2L file of this ECU, the loading process is related to the file size, if the file is very large, you need to be patient and wait for a while.

8)After the loading is completed, the system will automatically copy the source A2L file to the project directory and name the A2L automatically, the naming format is: ECU name as a prefix + source A2L file name.

(After loading the A2L file, the interface will display the A2L file name)

Once the A2L file is loaded, you can view the "Database" and "Protocols" expanded below the ECU node.


(9) The database page shows information such as measured quantities and characteristics inside the A2L.

(10) The database supports search, you can enter any keyword to filter variables
(11) Protocol page displays the calibration protocol attributes of the ECU.

12) Click the "Open" button on the right side of "Seed and Key Algorithm DLL File" to load the ECU unlocking algorithm DLL file, if the ECU does not need to be unlocked, this step can be skipped.


13) After loading the DLL file of Seed and Key, the system will copy the DLL into the project folder and name it automatically, the naming rule is: ECU name as prefix + algorithm DLL file name.

14) Add the variables to be observed to the measurement list

15) Recording engine
The logging engine is not activated by default, you need to check the Activate checkbox at the bottom to enable the logging engine to automatically log the required variable values during the measurement run.

16) Check Record Engine and Edit Engine Comments, this comment information will be automatically recorded to the target mat file

2|Basic Measurement Function Configuration

1) Adding Measurement Objects
(After selecting the variable to be observed, right-click and select Add to list)

2) Cut to the "Measurement List" page, you will see the measurement object you just added.

(3) The measurement list defines the measurement mode used for each variable, if you need to collectively modify the measurement mode, you can hold down shift to multi-select the measurement object, and in the right-hand side of any one of the selected measurement mode column, select another measurement mode, you can complete the selected part of all the switching

4) This example sets the first three observations to 10ms DAQ and the last observation to 100ms DAQ

3|Configure calibration hardware channel and start calibration

1) Setting up hardware channels
In this example, hardware channel 1 of Vector Virtual 1 is used; in practice, select the channel where the ECU is located

After connecting to TSMaster successfully, click "Connect" in the upper left corner of the toolbar of calibration interface, the ECU under test will be connected and unlocked automatically; after connecting successfully, click "Run" button again, the DAQ will be activated, and then the ECU will send DAQ messages to the tool terminal automatically. After successful connection, click "Run" button again, the DAQ will be started, then the ECU will automatically send DAQ message to the tool terminal.

(2) At the beginning of the calibration measurement, you can observe the XCP message from the message information window.

3) Setting up automatic operation of the calibration module
The calibration module can also be launched automatically with the start of the TSMaster application, eliminating the need to manually click the Connect and Launch buttons!

4|Basic Calibration Function

After the DAQ starts, TSMaster automatically maps each variable inside the ECU to its corresponding system variable, i.e., the changes of the variables inside the ECU will be directly affected by the system variables, so the variables inside the ECU can be observed by observing these system variables. For scalar quantities, the corresponding system variables are writable, and writing these system variables means modifying the scalar quantities inside the ECU.

4-1 Observing ECU Variables through System Variables

From any window in the TSMaster software where system variables can be observed (graphs, panels, dashboards, applets, System Variable Manager, etc.), the user can add and observe the desired system variables, including, of course, those associated with the calibrated ECU. The quickest way to add the observed signals is to filter them from the database, select one or more signals, right-click on them, and select Add to Graph or Panel in the context menu. This is shown in the figure below:

(Adding observations directly from the database to the graph window)

Another method is to add directly in the existing measurement window. For example, right-click in the signal list and select "Add System Variable" in the pop-up context menu:

The system variable selector will pop up:

This can be filtered in the selector, e.g. by typing "sine":

(Filtering of system variable selectors)

By selecting "ecu1.sineSignal" and clicking the OK button, you will be able to observe the real-time variation curve of this variable in the graph window:

(System variables corresponding to measurement objects are added to the graphic window)

Follow this method to add each of the four observations to which the DAQ has been added in the example:

Select Separate View to separate the four axes:

You can see the four variables displayed separately:

4-2 Modifying Scalar Quantities by System Variables

Modify the scalar quantity also for its associated system variables, through the applet, system variable manager, signal stimulation and other functions to modify a scalar quantity, to signal stimulation window as an example, first open the signal stimulation window

Click the "Add System Variable" button in the upper left corner to open the system variable selector. Note that the grayed-out variables are read-only variables, i.e., observation quantities, which cannot be modified, so you should select system variables that can be written (i.e., scalar quantities):

The Signal Excitation window can be used to modify not only the calibration amount, but also the value of any writable system variable other than the calibration, for example, to allow a system variable to follow a specific customized curve, and therefore has a very wide range of applications.


Select the two signals "ecu1.sineSignal" and "ecu1.sineSignalFreq" and click OK, the two new system variables will appear in the Signal Stimulus list:

(New system variables added to the signal excitation window)

You can see that the default value of these two variables inside the ECU is 1. Click on the up key of the physical value of the first signal to make it increment by 1:

(The values of system variables can be modified via buttons and text boxes)
When the amplitude is changed to 2, switch to the graph window and you can see that the amplitude of the sine wave has changed:
(Observations of measurements affected by the modified calibration)

4-3 Creating Variable Change Curves by Signal Excitation Window

By selecting the signal generator type of the amplitude signal as sine wave, you can control the scalar quantity inside the ECU to change in a sinusoidal manner.

After selecting and clicking the Configure button on the rightmost side of the Signal Generator column, the Configuration interface of the Signal Generator will be opened. You can see that in the properties of the Period Generation, the period is 100 ms, which indicates the period of the excitation, which can be increased or decreased, and the minimum period is 1 ms. Note that the smaller the period, the heavier the network load.


In addition, the values of parameters such as period, amplitude, phase and offset of the signal can be modified:

(Signal Generator Properties Configuration)

Click the OK button after the modification, you can see that the signal generator is not yet started, you need to manually click the blue start arrow to start the signal generation, of course, you can also check the lightning bolt selector box in the upper right corner of this window, so that it will start and run together with the TSMaster application when it starts!

After clicking start, you can see that the signal generator is running, at this time, the signal "ecu1.sineSignal" will be changed in a cycle of 100 ms, at this time, you can pause the signal generation or stop the signal generation.

Switching to the graph window, you can see the changes produced by the sine curve after the amplitude has been modified simultaneously:

4-4 Modifying the Measurement Mode of a Signal

In addition to the DAQ measurement mode that comes with the ECU, the system also provides a query (Polling) mode
In this example, the noiseSignal is modified to query mode and the pulseSignal is divided:

Calibration measurements are then initiated and multiple measurement modes can be seen running simultaneously.

IV. Signal Recording Function

TOSUN XCP module supports recording signals directly into mat files, which brings great convenience to the development and testing of MBD-based algorithms. Refer to the previous section for the basic signal recording function, this section describes how to record CAN signals and calibration signals in one file at the same time.

1|Associated CAN Database

Disconnect TSMaster, drag the dbc file into TSMaster, it will automatically open the database viewer and load the database. After the database is loaded, you need to configure the signal mapping function to map the CAN signals to system variables. The advantage of this is that the simulation and debugging of the system depends directly on the system variables, and if you change the database later, you only need to change the signal mapping without modifying the scripts or any elements related to the system variables.
(Drag in the dbc file, in this case "Powertrain.dbc")

2|Configuring the Symbol Mapping Engine

Click on "Symbol Mapping" in the "Simulation" toolbar to open the Symbol Mapping Manager. In this example, we want to record the value of the signal "EngSpeed" in the "EngineData" message. In this example, we want to record the value of the signal "EngSpeed" in the message "EngineData", enter "speed" in the filter on the left side of the dialog box to filter out the database symbols with "speed", and in the list of system variables on the right side, enter "speed" to filter out the database symbols with "speed". In the list of system variables on the right side of the dialog box, right click to add a new system variable:

The System Variable Selector dialog box will pop up:

Since the internal variables are automatically generated by the system, any variables that the user needs to add should be in the User Variables list, so switch to the User Variables page and add a new user variable:

Enter the new user variable as "XCPSimBus.engine_speed":

The added system variables will be shown in the list:
Selecting this variable and clicking "OK" will add the newly created variable to the symbol mapping. After adding the variable, select the signal in the left column and the system variable in the right column at the same time, and then click the "Connect" button in the upper toolbar to create a symbol mapping from the CAN signal to the system variable.

A successful connection will prompt that the mapping was created successfully:

Symbol mapping engine is disabled by default, you need to check "Activate" in the upper left corner to make it work automatically when the application connects:

3|Excitation of CAN signal

In practical applications, the CAN signal changes from the received message. In this example, for demonstration purposes, a transmit message will be constructed to stimulate the signal, open the CAN / CAN FD transmit window, click on the "Add" button in the upper left corner, select the EngineData message and click on OK:

Select the "EngSpeed" signal and modify its excitation properties:

(Modification of CAN signal generator)

A sine wave is selected in this example:

(Check the lightning bolt button in the upper right corner of the send window to make it automatically motivated)
After starting the simulation, you can see that the value of this signal changes automatically for a period of 3 seconds:

4|View Mapping Variables

At this point we can map the curve of the variable "XCPSimBus.engine_speed" in the graphic window, first of all right click and select Add System Variable:
Select the system variable:
The graph will show the variation curve of the mapped system variables:

5|Logging System Variables

Open the System Variables logging page of the logging engine, which can log not only the mapped system variables, but also any other system variables. Right-click on it and select the "Add" button:
In the System Variable Selector, select the system variable to be recorded:
When selected, a system variable record is added to the Record System Variables screen:
Press F5 to start the application and you can see the measurement process with system variable logging:
After stopping the application, the mat file is automatically created under the TSMaster binary file path bin\Logging\signals\.

V. Signal playback function

1|Add Record File

Right click on the "Measurement Log" node of the ECU under test and select "Load" to load and playback the log file. The link to the loaded file will remain in the measurement log and the user can switch the playback target and playback a log file repeatedly.
Select the mat format log file output by TSMaster in the pop-up dialog box:
If the recording file is very large, the playback process dialog box will be displayed and the user can interrupt the playback process at any time:

2|Recorded file playback via TSMaster

You can right click in the log file and select the playback function:

3|Recorded file playback via Matlab

Drag a mat file directly into the Matlab interface to load the contents of the mat file in the workspace.
About TSMaster Software

TSMaster is a virtual instrument software platform launched by TOSUN, which can connect, configure and control all hardware tools and devices of TOSUN, and realize the functional requirements of automotive bus embedded code generation, monitoring, simulation, development, diagnostics, calibration, Bootloader, I/O control, test and measurement, EOL and other occasions. And the software 90% function is free.


TSMaster comes with applets that support users to customize the simulation test panel, test flow, test logic, and even test system and automation report generation. Every line of code written by users based on TSMaster is hardware-agnostic, shareable, referenceable and cross-platform.


In addition, TSMaster can support Matlab Simulink co-simulation and Carsim to complete ECU algorithm simulation test with vehicle dynamics model (soft real-time HIL). Built-in C script, Python script editor, you can execute ECU code directly in TSMaster.


TSMaster can also support Vector, Kvaser, PEAK, ICS, Zhou Ligong bus tools and mainstream instruments (oscilloscopes, waveform generators, digital multimeters) and boards (AI, DI, DO, etc.) in the market, which can realize multi-hardware and multi-channel joint simulation and testing.