Danfoss Scripting Toolbox API Design guide

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

AJ00000002en-000601 | 5

Design Manual

PLUS+1® Service Tool Scripting Toolbox API

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

Design Manual

PLUS+1® Service Tool Scripting Toolbox API

Script design in Service Tool

Important advisory

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.

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.

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.

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

PLUS+1® Service Tool Scripting Toolbox API

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.

AJ00000002en-000601 | 9

Design Manual

PLUS+1® Service Tool Scripting Toolbox API

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>

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

<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

AJ00000002en-000601 | 11

Design Manual

PLUS+1® Service Tool Scripting Toolbox API

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

</SignalList>

</ServiceNetwork>

</System>

Select from the popup menu: System Navigator > Diagnostic Data > Add Diagnostic Data File

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.

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

AJ00000002en-000601

Design Manual

PLUS+1® Service Tool Scripting Toolbox API

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

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.

ECU Address Parameter

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.

Index Parameter

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.

AJ00000002en-000601 | 15

Design Manual

PLUS+1® Service Tool Scripting Toolbox API

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

AJ00000002en-000601

+ 36 hidden pages

Danfoss Scripting Toolbox API Design guide

Contents

Introduction

Overview

Script design in Service Tool

Important advisory

Creating a script

Managing script files

Registration of JavaScript functions in the P1J file

Hyperlink to a script in Advanced Pages

Adding resource files to a P1D file

Accessing P1D resource files in scripts

Creating Service Tool signals for use in scripts

General API Information

Supported Internet media types (MIME) in HTML dialogs

PLUS+1 return codes

ECU Address Parameter

Index Parameter

Ranges

Access rights

PLUS+ 1 parameter Ranges