How it Works
Danfoss
Loading...
Scripting Toolbox API
Design guide
52 pgs3.46 Mb0
Table of contents
Loading...

Danfoss Scripting Toolbox API Design guide

Design Manual
PLUS+1® Service Tool
Scripting Toolbox API
www.danfoss.com
Design Manual
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

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
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
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

Introduction

Overview

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
C
Design Manual

Script design in Service Tool

Important advisory

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.

Creating a script

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
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.

Managing script files

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.

Registration of JavaScript functions in the P1J file

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
Script design in Service Tool

Hyperlink to a script in Advanced Pages

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
Script design in Service Tool

Adding resource files to a P1D file

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.

Accessing P1D resource files in scripts

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
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
Script design in Service Tool

Creating Service Tool signals for use in scripts

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
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
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

General API Information

Supported Internet media types (MIME) in HTML dialogs

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.

PLUS+1 return codes

ECU Address Parameter

Index Parameter

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
General API Information

Ranges

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]
•

Access rights

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.

PLUS+ 1 parameter Ranges

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
Loading...
+ 36 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use