Design Manual
PLUS+1® Service Tool
Scripting Toolbox API
www.danfoss.com
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Revision history |
Table of revisions |
|
|
|
|
|
|
|
Date |
Changed |
Rev |
|
|
|
|
|
November 2019 |
Updated to support 12.0 and later |
0601 |
|
|
|
|
|
March 2019 |
Updated to support 11.1.x. and later |
0502 |
|
|
|
|
|
November 2018 |
Updated to support 11.0.x. and later |
0501 |
|
|
|
|
|
November 2017 |
Updated to support 10.0.x. and later |
0401 |
|
|
|
|
|
May 2017 |
Updated to support 9.1.x. and later |
0301 |
|
|
|
|
|
January 2016 |
Converted to DITA CMS and Danfoss layout. Supports 8.0.x and later. |
0201 |
|
|
|
|
|
September 2013 |
New edition |
0101 |
|
|
|
|
2 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual |
|
PLUS+1® Service Tool Scripting Toolbox API |
|
Contents |
|
Introduction |
|
Overview.............................................................................................................................................................................................. |
6 |
Script design in Service Tool |
|
Important advisory........................................................................................................................................................................... |
7 |
Creating a script................................................................................................................................................................................ |
7 |
Managing script files....................................................................................................................................................................... |
8 |
Registration of JavaScript functions in the P1J file............................................................................................................... |
8 |
Hyperlink to a script in Advanced Pages.................................................................................................................................. |
9 |
Adding resource files to a P1D file........................................................................................................................................... |
10 |
Accessing P1D resource files in scripts................................................................................................................................... |
10 |
Creating Service Tool signals for use in scripts................................................................................................................... |
12 |
General API Information |
|
Supported Internet media types (MIME) in HTML dialogs.............................................................................................. |
15 |
PLUS+1 return codes.................................................................................................................................................................... |
15 |
ECU Address Parameter............................................................................................................................................................... |
15 |
Index Parameter............................................................................................................................................................................. |
15 |
Ranges................................................................................................................................................................................................ |
16 |
Access rights.................................................................................................................................................................................... |
16 |
PLUS+ 1 parameter Ranges........................................................................................................................................................ |
16 |
Node Address.................................................................................................................................................................................. |
17 |
Online mode requirements........................................................................................................................................................ |
17 |
Script error handling..................................................................................................................................................................... |
18 |
Miscellaneous API functions |
|
St_MessageBox............................................................................................................................................................................... |
19 |
St_Delay............................................................................................................................................................................................. |
19 |
St_CurrentErrorCode.................................................................................................................................................................... |
19 |
St_CurrentErrorString................................................................................................................................................................... |
19 |
St_ConsoleLog................................................................................................................................................................................ |
19 |
St_ConsoleError.............................................................................................................................................................................. |
20 |
St_SetExitCode................................................................................................................................................................................ |
20 |
St_FileDialog.................................................................................................................................................................................... |
20 |
Gateway API functions |
|
St_GetActiveGateway................................................................................................................................................................... |
21 |
St_GetActiveGatewayDevice..................................................................................................................................................... |
21 |
St_GetGatewayCount................................................................................................................................................................... |
21 |
St_GetGatewayInfo....................................................................................................................................................................... |
21 |
St_GetGatewayDeviceCount..................................................................................................................................................... |
21 |
St_GetGatewayDeviceInfo.......................................................................................................................................................... |
22 |
St_SetGatewayBaudrate.............................................................................................................................................................. |
22 |
ECU API functions |
|
St_ScanSystem................................................................................................................................................................................ |
23 |
St_GetNodeCount......................................................................................................................................................................... |
23 |
St_GetNodeAddress...................................................................................................................................................................... |
23 |
St_LoadNodeData.......................................................................................................................................................................... |
23 |
St_GetNodeInfo.............................................................................................................................................................................. |
24 |
St_GetParameterCount................................................................................................................................................................ |
25 |
St_GetParameterData................................................................................................................................................................... |
25 |
St_ControlNode.............................................................................................................................................................................. |
26 |
St_RecoverEcu................................................................................................................................................................................. |
26 |
Read Parameter API functions |
|
St_ReadParameter......................................................................................................................................................................... |
27 |
St_ClearReadParameterList........................................................................................................................................................ |
27 |
St_AddReadParameterList.......................................................................................................................................................... |
27 |
St_ReadParameterList.................................................................................................................................................................. |
27 |
St_GetReadParameterListValue................................................................................................................................................ |
27 |
St_ClearExpectedSignalValueList............................................................................................................................................ |
28 |
© Danfoss | November 2019 |
AJ00000002en-000601 | 3 |
Design Manual |
|
PLUS+1® Service Tool Scripting Toolbox API |
|
Contents |
|
St_AddExpectedSignalValueList.............................................................................................................................................. |
28 |
St_WaitForExpectedSignalValues............................................................................................................................................ |
28 |
St_ClearCanXplorerSignalError................................................................................................................................................. |
28 |
Write Parameter API functions |
|
St_WriteParameter........................................................................................................................................................................ |
29 |
St_ClearWriteParameterList....................................................................................................................................................... |
29 |
St_AddWriteParameterList......................................................................................................................................................... |
29 |
St_WriteParameterList................................................................................................................................................................. |
29 |
Parameter files API functions |
|
St_CreateP1tFromFile................................................................................................................................................................... |
30 |
St_CreateP1tFromString............................................................................................................................................................. |
30 |
St_OpenP1tFile............................................................................................................................................................................... |
30 |
St_GetP1tFileEcuData.................................................................................................................................................................. |
31 |
St_GetP1tFileParameterCount.................................................................................................................................................. |
31 |
St_GetP1tFileParameterData..................................................................................................................................................... |
31 |
CAN message API functions |
|
St_SendCan...................................................................................................................................................................................... |
32 |
File download API functions |
|
St_OpenApplication...................................................................................................................................................................... |
33 |
St_GetDownloadData.................................................................................................................................................................. |
33 |
St_SetDownloadParameterValue............................................................................................................................................. |
34 |
St_DownloadFile............................................................................................................................................................................ |
34 |
St_DownloadPackage.................................................................................................................................................................. |
34 |
Service application API functions |
|
St_GetScreenNodeCount............................................................................................................................................................ |
35 |
St_GetScreenNodeAddress ....................................................................................................................................................... |
35 |
St_GetScreenParameterCount.................................................................................................................................................. |
35 |
St_GetScreenParameterData..................................................................................................................................................... |
35 |
St_SetScreenParameterData...................................................................................................................................................... |
36 |
St_ReloadScreen............................................................................................................................................................................ |
36 |
St_UpdateScreenLogValues....................................................................................................................................................... |
36 |
St_IsLogging.................................................................................................................................................................................... |
36 |
St_ActivateDocument.................................................................................................................................................................. |
36 |
St_GetResourceFileCount........................................................................................................................................................... |
36 |
St_GetResourceFileData.............................................................................................................................................................. |
37 |
St_SelectResourceFileDialog..................................................................................................................................................... |
37 |
St_GetGenericEcuDefinitionCount.......................................................................................................................................... |
37 |
St_GetGenericEcuDefinitionData............................................................................................................................................. |
37 |
St_GetGenericEcuCount.............................................................................................................................................................. |
38 |
St_GetGenericEcuData................................................................................................................................................................. |
38 |
Report API functions |
|
St_EnableAutoReport................................................................................................................................................................... |
39 |
St_AddReportLine......................................................................................................................................................................... |
39 |
St_SaveScriptReport..................................................................................................................................................................... |
39 |
St_ClearScriptReport..................................................................................................................................................................... |
39 |
Hyperlink API functions |
|
Hyp_ScanSystem............................................................................................................................................................................ |
40 |
Hyp_UnitHistory............................................................................................................................................................................. |
40 |
Hyp_ViewNavigator...................................................................................................................................................................... |
40 |
Hyp_StartLog................................................................................................................................................................................... |
40 |
Hyp_StopLog................................................................................................................................................................................... |
40 |
Hyp_ParamUpload........................................................................................................................................................................ |
40 |
Hyp_ParamDownload.................................................................................................................................................................. |
40 |
Hyp_ReplaceMissingEcu............................................................................................................................................................. |
40 |
Hyp_ReplaceExistingEcu............................................................................................................................................................. |
41 |
4 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual |
|
PLUS+1® Service Tool Scripting Toolbox API |
|
Contents |
|
Hyp_Close......................................................................................................................................................................................... |
41 |
Progress API functions |
|
Ui_ClearModalProgressList........................................................................................................................................................ |
42 |
Ui_AddModalProgressItem........................................................................................................................................................ |
42 |
Ui_UpdateModalProgressItem................................................................................................................................................. |
42 |
Ui_ModalProgressStepIt.............................................................................................................................................................. |
42 |
Ui_ModalSetProgressText........................................................................................................................................................... |
42 |
Ui_InitModalSequence................................................................................................................................................................. |
43 |
Ui_EndModalSequence............................................................................................................................................................... |
43 |
User interface API functions |
|
Ui_ShowUI........................................................................................................................................................................................ |
44 |
Service Tool events |
|
_ServiceTool_BeforeScanSystem............................................................................................................................................. |
45 |
_ServiceTool_AfterScanSystem................................................................................................................................................ |
45 |
_ServiceTool_BeforeParameterUpload.................................................................................................................................. |
45 |
_ServiceTool_AfterParameterUpload..................................................................................................................................... |
45 |
_ServiceTool_BeforeParameterDownload........................................................................................................................... |
45 |
_ServiceTool_AfterParameterDownload............................................................................................................................... |
45 |
_ServiceTool_AfterStartLog....................................................................................................................................................... |
46 |
_ServiceTool_AfterStopLog....................................................................................................................................................... |
46 |
_ServiceTool_BeforeLoadScreen.............................................................................................................................................. |
46 |
_ServiceTool_AfterLoadScreen................................................................................................................................................. |
46 |
_ServiceTool_AfterFileOpen...................................................................................................................................................... |
46 |
Appendix A: Return codes |
|
© Danfoss | November 2019 |
AJ00000002en-000601 | 5 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Use the Scripting Toolbox to develop script sequences written in JavaScript/HTML. Scripts are started using Advanced Page hyperlinks or triggered on a range of service tool events.
This is a PLUS+1® Service Tool upgrade feature. A Service Tool Professional Add-on License (Danfoss part 11179527) enables the design functionality of this feature. Using service application files containing scripts does not require any additional license and can be used with the built-in license supplied with the PLUS+1® Service Tool installation.
Features and benefits:
•Develop calibration sequences and troubleshooting wizards
•Read and write access to tuning parameters
•Download of application files to microcontrollers
•Access to any ECU supported by PLUS+1® Service Tool
6 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
C Caution
It is not possible to cancel execution of a service tool script function.
It is recommended to save your service application file before running scripts.
A Service Tool script contain of Script Interface file and a Script file. The Script Interface File is stored in a .P1U file and uses HTML format and the Script file is stored in a .P1J file and uses JavaScript format.
1.Right-click on the Scripts node under Design in the System Navigator and select New Script to create template script files.
This will create a ScriptInterface and ScriptFunctions node under Scripts.
2.Double-click on ScriptFunctions to open file ScriptFunctions.P1J in the associated editor.
There is no file association for P1U and P1J files by default when installing the PLUS+1 Service Tool. Use the select default program dialog that appears to associate the text files with your favorite text editor.
© Danfoss | November 2019 |
AJ00000002en-000601 | 7 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
3.Save the changes in the editor and select Reload after right-clicking on the ScriptFunctions node to reload the file with the changes.
Changes in the P1U and P1J file will be automatically saved when saving the P1D file.
Before you release your service application, you must test the service application file following your usual test procedures to verify that it works as intended.
The menu items Add Script Interface file and Add Script file accessible by right-clicking on the Scripts node can be used to add P1U and P1J files from disk.
It is only possible to add a single P1U and P1J file.
It is also possible to save or delete exiting script files from the Scripts popup menu.
The JavaScript functions in the P1J file that shall be accessible in the Service Tool needs to be registered in the top of the P1J file.
Add a line with the text //PLUS+1-reg: followed by the name of the JavaScript function.
//PLUS+1-reg: MyFunction
function MyFunction()
{
//JavaScript code
}
JavaScript is case sensitive. Watch your capitalization closely when you write JavaScript statements.
8 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
Each registered JavaScript function will be accessible using Advanced Page hyperlink. The following Advanced Page components support hyperlinks:
•Button
•Text
•Image
•Input Value
The tooltip of the component will indicate the P1J and JavaScript function that will be started when clicking the component.
© Danfoss | November 2019 |
AJ00000002en-000601 | 9 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
It is possible to include resource files and access these files from scripts, i.e. PLUS+ 1 downloadable file (.hex/.lhx), images and JavaScript libraries.
1. Select in the System Navigator > Resources > Add Resource File.
2. Browse to the file.
The example how to include a JavaScript library in a script: P1D Design
P1U file
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script type="text/javascript" src="plus1://core.js"></script>
<script type="text/javascript" src="p1d://ScriptFunctions.P1J"></script> <script type="text/javascript" src="p1d://jquery-1.6.4.js"></script>
</head>
</html>
10 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
The example how to display an image resource file in a HTML dialog: P1D Design
P1U file
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script type="text/javascript" src="plus1://core.js"></script>
<script type="text/javascript" src="p1d://ScriptFunctions.P1J"></script> </head>
<body>
<img src="p1d://DanfossLogo.png" width="200" height="100"> </body>
</html>
P1J file
//PLUS+1-reg: AccessResourceFileFromP1D
function AccessResourceFileFromP1D()
{
Ui_ShowUI("HTML Dialog Test", 0, 0, 400, 200);
}
HTML Dialog Test displayed when running the script
© Danfoss | November 2019 |
AJ00000002en-000601 | 11 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
The Service Signal protocol included the Service Tool can be used to create Service Tool defined signals. These signals can be read and written from scripts and Service pages and can be used to save configuration and states in different pages or scripts in the P1D file.
Changed signal values will be restored to default values if the P1D file is closed or if the DLL protocols are reloaded (occurs during Reset Gateway, Manage Protocols menu and when changing Online/Offline mode).
The Service Tool signals are defined in a XML file with the following format:
XML file example
<?xml version="1.0" encoding="UTF-8"?>
<System xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ServiceSignals.xsd">
<FileFormat>001A</FileFormat>
<ServiceNetwork>
<Node Name="Service1" Address="1"/>
<Node Name="Service2" Address="0x01F1"/>
<SignalList Node="Service1">
<Signal Name="ServiceToolParameter1" Type="U8" Value="9"/> <Signal Name="ServiceToolParameter2" Type="U32" Value="123"/> <Signal Name="ServiceToolParameter3" Type="BOOL" Value="1"/>
</SignalList>
<SignalList Node="Service2">
<Signal Name="TestSignal1" Type="S32" Value="-100"/> </SignalList>
</ServiceNetwork>
</System>
Select from the popup menu: System Navigator > Diagnostic Data > Add Diagnostic Data File
12 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
Select the Service Signals XML file from the popup menu: Add Diagnostic Data > Service Signals >
Browse:
The Service Signals ECUs defined in the selected XML file will be displayed in the: System Navigator > ECU list after the System Scan.
© Danfoss | November 2019 |
AJ00000002en-000601 | 13 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Script design in Service Tool
The Signal names defined in the selected XML file are now accessible from Service pages and from script API functions.
Service pages with Service Signals in Run mode
14 | © Danfoss | November 2019 |
AJ00000002en-000601 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
Scheme |
File extension |
MIME type |
|
|
|
plus1 |
.html |
text/html |
|
|
|
plus1 |
.js |
text/javascript |
|
|
|
plus1 |
.css |
text/css |
|
|
|
p1d |
.html, .p1u |
text/html |
|
|
|
p1d |
.js, .p1j |
text/javascript |
|
|
|
p1d |
.css |
text/css |
|
|
|
p1d |
.txt |
text/plain |
|
|
|
p1d |
.xml |
text/xml |
|
|
|
p1d |
.jpg, .jpeg |
image/jpeg |
|
|
|
p1d |
.png |
image/png |
|
|
|
p1d |
.gif |
image/gif |
|
|
|
|
|
|
MIME type text/plain will be used for unlisted file types.
Functions that return a PLUS+ 1 result code returns the value –1 on success and a positive number on error; see Appendix A: Return codes on page 47.
Parameters named ‘Address’ refers to a node (ECU) address. This information is returned by the St_GetNodeAddress function but is also available in the:
System Navigator > ECU list > Application > Diagnostic ID.
Parameters named Index refers to a zero-based index of the data to target. The value of 0 identifies the first item in the list.
© Danfoss | November 2019 |
AJ00000002en-000601 | 15 |
Design Manual
PLUS+1® Service Tool Scripting Toolbox API
General API Information
A range is a set of accessible indexes in an array. Indices in a range are specified either as a comma separated list containing single values or a range separated by a dash ‘-‘.
Example – given an array: int test[30]; //(c-syntax) The following examples are valid:
•[1,2,3,23]
•[3-17]
•[0-5,9,11,12-22]
•[29]
The following examples are not allowed:
•[-1]
•[30]
In order to control the level of information shown to the user in the service tool, some API functions provide Access Level information. If the access level in the service tool is equal or higher than the level reported by the protocol, the information should be shown in the service tool. Access Level is provided as information by the protocol DLL and is never enforced. The Service tool is responsible for interpreting and enforcing access levels reported by the protocol.
Read and Write access rights are defined as a single character in the range of [D0-9]. 0-9 indicates the access level and D signifies that the functionality is not supported or not used.
Numerical value strings should be presented in decimal form unless stated otherwise and the protocol is responsible for removing leading and trailing white space when converting value strings.
The following numerical ranges are supported:
Type |
Min |
Max |
|
|
|
BOOL |
0 |
1 |
|
|
|
U8 |
0 |
255 |
|
|
|
U16 |
0 |
65535 |
|
|
|
U32 |
0 |
4294967295 |
|
|
|
S8 |
-128 |
127 |
|
|
|
S16 |
-32768 |
32767 |
|
|
|
S32 |
-2147483648 |
2147483647 |
|
|
|
16 | © Danfoss | November 2019 |
AJ00000002en-000601 |