Revision History
1.0 Installation
1.1 Introduction
2. Workspaces
2.2 Development
2.3 Dashboard Configurator
2.3.01 Dashboard Configuration UDS Project View
2.3.02 Dashboard Configuration J1939 Project View
2.3.03 PIDs Library View
2.3.04 Gauges Library View
2.4 Compiler
2.5 CAN Log Parser
2.6 Settings
3. General usage
A. LUA Scripting presentation
B. Dashboard Configuration Examples
B1 Example: Your first dashboard configuration
B2 Example: Your second dashboard configuration
B3. Example: Definition of really Composite PID
C. Gauge Filters
Copyright: TomElectronics SRL
Installation
Installing StartDiag Suite is very simple and straightforward:
Download the install package from StartDiag website
Start the installation process by double clicking on the downloaded file
Installation should proceed automatically.
The installation process then automatically registers the following extensions to be used with StartDiag Suite:
sds will be opened with the Development workspace
udp will be opened with the Dashboard Configuration UDS Project View workspace
jdp will be opened with the Dashboard Configuration J1939 Project View workspace
uplib will be opened with PIDs Library View workspace
jplib will be opened with PIDs Library View workspace (in this case the PID request table will be the same shown in Dashboard Configuration J1939 Project View)
glib will be opened with Gauges Library View workspace
NOTE: if any of these extensions are already associated with other application at the moment of the installation, the association is NOT changed.
Installed Files
The installation copies the files required to run the application C:\Program Files(x86)\StartDiagSuite.
Even if the installation path is common to for all the users, each user that needs to use StartDiag Suite needs to install it. This does not mean that there will be a copy of the execution files, in fact to simplify the management, only one copy of the Suite will be installed, but each user will have his own set of example files to work with. In fact each user that installs the Suite will have a set of example files installed in the personal Documents\StartDiagSuite folder organized by workspace.
Uninstall
A note of attention has to be done here: for how the installation works, if more than one user has installed the StartDiag Suite and one user uninstalls the tool, the tool will not be available anymore for any of the users. On the other hand, in such a case the example folders will NOT be automatically deleted for any other user apart from the one that performs the uninstall operation.
This means that if the StartDiag Suite has to be uninstalled for all the users, after the first user has performed the uninstall process, the example folders in each of the users' Documents folder have to be manually deleted afterwards.
StartDiag Suite is the PC companion application to the StartDiag System.
It is a tool developed specifically to simplify the operation that you have to do in order to take full advantage of the customizability that StartDiag offers.
Suite is specifically designed to be the editing tool for your StartDiag files and configurations.
The main concept behind the StartDiag Suite is to offer a set of simple workspaces that helps you in developing a single aspect of the StartDiag System (each workspace does one thing and does it in the most simple way possible).
2. Workspaces
Many functions of the StartDiag System require from the user a certain level of interaction, while others make use of files provided by the user to offer an extended set of features that better suit your need.
StarDiag Suite provides you a set of tools specific for each of these use-cases and in order to keep them well separated and organized, the working environment of the Suite has been divided into four main workspaces, each responsible for handling a specific aspect of the StartDiag work.
Help is your main information hub. Here you can find links to the installed documentation for all the supported products: the StartDiag System, the LUA script development and for the StartDiag Suite itself.
Development allows you to develop LUA script with the help of the syntax highlighting customized to support our specific StartDiag APIs.
Dashboard Configurator allows you to develop in a very simple way your personalized dashboard scripts using tables instead of writing LUA code.
Compiler is more of an advanced tool to be applied to LUA script after they have been fully developed and you are satisfied with the result.
CAN Log Parser is the interface with the CAN Logger feature of the StartDiag System.
Settings allows you to configure some settings of the bhaviour os the StartDiag Suite.
A fifth tab is available (Help) to offer you easy access to all the documentation that you may need about the full StartDiag ecosystem.
This is your main information hub.
From here you can easily open the documentation about the StartDiag Suite itself (Guide) ,but also the one for LUA scripting development (Developer Guide) and the StartDiag System (StartDiag Device Guide).
You can also go directly to the online LUA reference documentation (LUA Reference Manual)
Our StartDiag Suite (Disclaimer) is also available from here
The most powerful tool that StartDiag offers you is the LUA scripting engine.
To put it simple, StartDiag reads a script file from the SD and executes the instructions inside.
You are the creator of those scripts, and as such you can decide what they do, and how they do it. This is the real power behind the tool: it gives you the freedom to interact with the CAN bus without having to worry about the lower details of it, you can talk to the electronics modules of the vehicle.
In order to harness that power we have developed StartDiag Suite Development workspace.
In essence, it is a text editor to write your own scripts, but in comparison to other applications that you may use to write a simple note, it offers full syntax highlight with the support for our customized LUA commands to interact specifically with the CAN bus.
NOTE: by default the Development workspace works on files with extensions sds, which is the one used by StartDiag display. You can open manually files with lua or txt extension by changing the filter in the bottom right corner of the "Development - Open" window. After this you will be able to select files with the selected extension that were not visible before.
This is where you can develop your fully customized Dashboard Configuration scripts and manage your collections of parameters and gauges definitions.
Let's start explaining briefly the relevance of the concept of Dashboard in the StartDiag System.
DASHBOARD CONFIGURATION ON STARTDIAG:
It is very useful to describe here a little of what is going on about the Dashboards on the StartDiag System before proceeding.
StartDiag Display unit offers 4 different dashboards, where each dashboard is a container for variable number of gauges.
Gauges, at their basic, are display elements that present on the StartDiag Display screen one value.
(1)
The displayed values, generally data read from the StartDiag Controller unit, can be of 3 main types:
- data read from the Controller sensors, which are battery voltage or Controller temperature.
- date read from external sensors connected to the Controller, which currently is the EGT sensor.
- data read form the connected vehicle using the OBD CAN bus.
The generic name used to reference these possible values is PIDs so the dashboards are pages that shows PIDs.
(2)
Sometimes you want to use not a single PID, but a composition of PIDs, or perhaps you need to see a single PID but with a different measurement unit than the one provided by the ECM. This is where the concept of "Composite PID" plays a big role.
Composite PIDs are just the combination of one or more PIDs and some mathematical operations in between them.
In the StartDiag System, each single PID is by itself a Composite PID, just a very simple one.
(3)
After you have decided which Composite PID you want to see, probably you want the gauge to display a bit more information other than the bare number, so you have to provide a Gauge Definition that defines the units to be assigned to the gauge, a short description and other options that will be discussed later.
At this point you have:
- a Composite PID Definition
- a Gauge Definition
(4)
You have up to 6 Gauges in a Dashboard, so one last step is needed to fully define a Dashboard: connect your Composite PIDs Definitions with the Gauges Definitions (you do not have to worry about how many Gauges you define, even if the Dashboard selected on the StartDiag Display has less than defined Gauges, or more, all will work correctly, meaning that only the defined Gauges, or at most the used Gauges, will be shown).
With all these information provided StartDiag Display can show you whatever you want, where you want, inside the Dashboard you want.
Now that we have a better understanding of how the Dashboards are handled on the StartDiag System, we can pass to see how to customize them.
The relevant Workbench for that operation is the Dashboard Configurator.
It offers the possibility to manage three types of documents:
- Dashboard Configuration Project is the direct editing document that will be used to customize the StartDiag Display Dashboard
- PIDs Library is a document that allows you to manage specifically PIDs and Composite PIDs definitions without worrying about any other aspect of the configuration
- Gauge Library is a document that focus on the definition of the Gauges that will later be used in the Dashboard Configuration Project document
In order to allow you to focus on each of these type of documents, the Dashboard Configurator Workbench have a different layout for each document type. Each of these layout is called a VIEW.
VIEWS:
Dashboard configurator workspace allows you to operate on various types of projects.
Dashboard Configuration UDS Project View is the View that allows you to prepare the configuration file to be used with StartDiag Display. It is comprised of 4 tables mirroring the description given in DASHBOARD CONFIGURATION ON STARTDIAG above.
PIDs Library View is the View allowing the design of the parameters that will be shown in the Dashboards. It shows only 2 tables: one for the basic PID and one for the Composite PIDs
Gauges Library View is the View designed to define the Gauges configuration. It is only one table allowing to see better all the fields related to the Gauges definitions.
WORKING WITH VIEWS:
Views have been designed to improve the management of "libraries" of predefined definitions, be them PIDs or Gauges, offering a more clear separation based on what you are working on.
Library is a core concept here. A Library is a group of uniform data represented in a table.
While a Dashboard Configuration Project is the union of the 4 groups (PID Reuqests, Composite PIDs, Gauges and Dashboard) reflecting the organization underneath the StartDiag Display customization, the Libraries allows you to focus only on the single aspects of the definitions that you are working on in a specific moment.
All the definition will be later easy to import into a single Dashboard Configuration Project for the final compilation, using the Edit commands.
More than one file can be opened at the same time in the Dashboard Configurator Workspace, and this is an instrumental mechanic in the workflow in this environment.
You can easily have a Dashboard Configuration Project View open, alongside a PIDs Library View and a Gauges Library View.
With this setup, it is straightforward to edit or add PID Requests and Composite PIDs definitions in the PIDs Library, add one or more Gauges definitions in the Gauge Library View, and then send only the required ones from the Libraries to the Configuration Project to be exported for the StartDiag Display.
This last step of passing definitions between Libraries and Configuration Project can be done using some of the Edit commands offered:
- you can simply select the relevant rows in the tables and do Copy/Paste operations. This is straightforward and allows even to copy single cells, but care must be taken when copying definitions that rely on other tables rows to be effective. Ex: if you want to copy a Composite PID definition (table 2) from a PID Library, you should beforehand copy the rows of the PID Requests (table 1) used.
- another option is to use the "Send To" command: this allows you to select the required rows from the Composite PIDs table and when the command is issued, the Dashboard Configurator Workbench will automatically select the needed rows from PID Requests and copy over those too. this command works even between compatible Libraries and between Dashboard Configuration Projects
Truth to be told, "Send To" command is way more flexible than that, in fact it allows you to send data from whichever table you may have done a selection, to another file. What makes this command very powerful is that it automatically copy all the "dependencies" that your selection has.
Let's make an example: Suppose we have a PID Request defined, a Composite PID referring the PID Request, a Gauge Configuration, and a Dashboard using the Gauge configuration and the Composite PID. If we select just the entry in the Dashboard configuration and we use the "Send To" command, it will copy to the destination file the Dashboard configuration and the Gauge configuration and the Composite PID and the PID Request! All at once!
If instead we select juts the Composite PID, "Send To" will copy for us the Composite PID and the PID Request.
Dashboard definition is provided as a LUA script specialized for this purpose.
As such, you can freely develop it in the Development workspace, but a graphical way is easier to work with and that is what Dashboard Configurator workspace provides.
It is designed as four separate tables, where each is associated with a step in the Dashboard Definition described above (each table has also a number next to the name which correspond to the respective position in the previous section).
The first 3 tables in the Dashboard Configurator workspace have the first row called "Key". This is already set so you do not have to worry about it. You can use this field when it is needed to link an element of a table inside the relevant fields of the consecutive tables.
Another self explanatory column available in all the tables is the "Note". This will be also written inside the generate Dashboard Script file for future reference.
PID REQUESTS (1):
PID Request table represents the definitions of the PIDs.
Here you can define the source of the data:
- left empty means that this row will not be considered
- {ECU} means that the source of the data is the CAN bus, and will required the other columns of the row to be compiled according to the CAN bus requirements to be correct.
- Temp is the temperature sensor on the StartDiag Controller unit
- Volt is the voltage read from the StartDiag Controller unit (this may be slightly different that the equivalent value provided by the ECUs)
- EGTE is the StartDiag EGT external probe value
- EGTI is the StartDiag EGT internal value (this value is read inside the Sensor box)
- Constant means that you are defining a meta-pid used only to define constant values used for Composite PID definitions
If you select whichever source apart from {ECU}, all the unused columns will be deactivated.
- "RemoteID" is the CAN ID used to request the data from
- "Local ID" is the CAN ID used to wait for the response on
- "SID" is the Service ID to be used for the request
- "DID" is the Data ID for the request
- "Start" is the position of the value inside the received data
- "Length" is the length in bytes of the value in the received data
- "Offset" is a constant that will be added to the received value (this is always added, so if you want to subtract instead, declare it as a negative number)
-"Scale" is a multiplication factor that is applied to the value (before the Offset is applied)
NOTE: for a deeper understanding of these columns you may want to refer to the StartDiag Developer Guide in the uds.xmit section
A row in this table is considered valid the moment it is marked as not Disabled.
COMPOSITE PIDS (2):
This table allows you to combine one or more PID Configurations defined in PID REQUESTS.
First you should select the PID REQUESTS element you want to combine in the given Composite PID row, then you can enable it without errors.
Only the Composite PIDs enabled will be valid to be used in the successive tables.
GAUGES (3)
In this table you can define all the aspects of the Gauges in the Dashboard.
Let's inspect the various fields available and what they mean:
- "Enable" allows to mark as usable the definition on this row
- "Desc" is the short description of the value. This will be shown inside the Gauge and have to be at most 12 characters long
- "Units" is the measurement unit for the value. Like Desc this is shown inside the Gauge and have to be at most 12 characters long
- "Digit Val" is a flag (can be only ON or OFF) and is used with an analog gauge to change its behavior, passing from a normal uniform value change to a Gauge that moves only inside a set of discrete values (Ex: is the Gauge can display the values [1, 2, 3] and this flag is ON, the needle will be only on the values 1, 2, or 3 and not in between them)
- "ValMin" is the lowest value represented by the Gauge (this has no effect on digital gauges)
- "ValMax" is the highest value represented by the Gauge (this has no effect on digital gauges)
- "DecNumb" is the number of decimal digit shown in a gauge
- "ZoneAColorID" is the color to be used for the lowest colored section of the Gauge range (default: None)
- "ZoneBColorID" is the color to be used for the middle colored section of the Gauge range (default: None)
- "ZoneCColorID" is the color to be used for the highest colored section of the Gauge range (default: None)
- "ZoneBStart" is the value from which the middle section starts (default: 33% of ValMax)
- "ZoneCStart" is the value from which the last section starts (default: 66% of ValMax)
- "AlarmMin" is the value under which the AlarmMinis triggered (default: 33% of ValMax)
- "AlarmMinOn" is a flag to turn ON or OFF the AlarmMin
- "AlarmMax" is the value over which the AlarmMax is triggered (default: 66% of ValMax)
- "AlarmMaxOn" is a flag to turn ON or OFF the AlarmMax
- "Weight" is the Weight of the filter to be used on the received data (default = 1). For more information please see Gauge Filters
DASHBORAD (4)
This is the last step in the Dashboard configuration: here you will connect the Composite PIDs you defined in table (1) and (2) with Gauge Configurations defined in (3).
This table has only two columns:
- "GaugeConfigurationKey" which indicates which Gauge Configuration from table (3) to use
- "PIDCompositeKey" which indicates which Composite PID from table (2) to use
Here only rows marked as enabled in the previous tables can be used.
OPTIONS:
In the Option table you can setup some configuration that have an effect on the full Dashboard setup:
- "Request Delay": this time (in hundredths of second) is a fixed time applied between PID Requests. This is needed on some vehicles since they may have trouble in answering to a request done too quickly.
NOTE: if you have Composite PID with 2 PID Requests in it, this time will be applied 3 times to get the full Composite PID value!
DASHBORAD SCRIPT GENERATION:
After the DASHBORAD (4) table has been completed you can prepare the output file to be copied on the StartDiag System SD card.
To do so, you just have to select from the menu "File"->"Export.." (or use the shortcut Ctrl+E).
The output file can be saved on the local hard disk or directly on the SD card if it is already inserted in the computer.
This Dashboard Project View allows you to configure dashboards that handle data for J1939 standard.
The general behavior is exactly the same as for Dashboard Configuration UDS Project View but the table (1) [PID Requests J1939] is structured with the fields necessary to define J1939 standard requests.
PID REQUESTS (1):
PID Request table represents the definitions of the PIDs.
Here you can define the source of the data:
- left empty means that this row will not be considered
- {ECU} means that the source of the data is the CAN bus, and will require the other columns of the row to be compiled according to the CAN bus requirements to be correct.
- Constant means that you are defining a meta-pid used only to define constant values used for Composite PID definitions
If you select whichever source apart from {ECU}, all the unused columns will be deactivated.
- "PGN" is the PGN field in J1939 standard
- "Remote Address" is the J1939 Address of the remote unit that the request is for
- "Start" is the position of the value inside the received data
- "Length" is the length in bytes of the value in the received data
- "Mask" is the bitmask to be applied on the received data prior to extracting numerical values
- "Time Validity" is the time between active requests or after which data will be considered "old" in the Gauge. (NOTE: this is hundredths of seconds)
- "Offset" is a constant that will be added to the received value (this is always added, so if you want to subtract instead, declare it as a negative number)
-"Scale" is a multiplication factor that is applied to the value (before the Offset is applied)
-"Is Active" is a flag that indicates if the definition applies to an active PID. In J1939 protocol data can be actively requested by an ECU/Tester or they are simply broadcasted on the bust on regular time intervals. If this flags is set, then the defined PID will be actively requested, otherwise StartDiag Controller will just wait for it to be passed on the bus.
Table(2), Table(3) and Table(4) works exactly as in Dashboard Configuration UDS Project View.
OPTIONS:
In The Option table you can setup some configuration that have an effect on the full Dashboard setup:
- "StartDiag Address" is the address you want to use as source of our requests in J1939 Bus
- "StartDiag Name" is the J1939 Name you want to use for the Address Arbitration.
NOTE: StartDiag Controller doesn't really conform completely to the address arbitration procedure. If an address is acquired by StartDiag and some other module arrives after and request the same address, we do not try to negotiate to keep it, we just disconnect from the bus for safety reasons.
This view, comprised of only 2 tables allows you to define the PID Requests to be done and the Composite PIDs to combine them and apply mathematical transformations to the result.
The maximum number of entries for each of the tables is of 4096 rows.
This View is comprised of only one table to maximize the viewing area, since the Gauges offer many configurable parameters.
The maximum number of rows that can be stored in a Gauge Library is 4096.
The compiler is a component that works on plain text scripts (like the ones that you can develop in the Development) environment and produces an output file in a different format (binary) that StartDiag can still recognize and utilize perfectly but consumes less space or encrypts it so that only you know how it works internally but can still give it to others to use.
Currently the Compiler allows you to:
Generate a "LUA Binary" file (useful to reduce the space occupied by the script)
Generate a "Controller SN Locked" file (this is an encrypted format that requires the Controller unit to have the exact serial number you provided at compilation time in order for the script to start; basically, with this option you are locking the script to work only on the one StartDiag controller you specified).
NOTE: The Controller SN provided is preserved between executions of the StartDiag Suite application. Make sure you update it accordingly to the unit that you are preparing the file for!
Since the Controller SN is long and can be difficult to read and input correctly (it must be written exactly as it is seen on the StartDiag Display unit, even the dashes), from Firmware v.0000.00.05 there is a button to export to a file on the SD Card the StartDiag Information. That file can then be loaded automatically in the StartDiag Suite Compiler section using the button "Get From File...".
One of the most useful features of the StartDiag System is the possibility to log the activity on the connected CAN bus to be later used on your PC for deeper analysis.
To be as quickly as possible, the StartDiag devices use a binary format that is quite hard to read by a human.
This complexity is overcome by the use of this workspace, which allows you to open a log file generated by a StartDiag unit and to export the content in a human readable format, picking between some possible output options:
- "Plain Text" generates a text file that you can easily open with whichever text editor you prefer (potentially even the Development workspace, even though it will offer no special help for such a file format).
Each line contains the following fields:
#- Packet index (this is a consecutive number indicating the order of arrival of the packet)
#- Time: this is a high speed time indication for the arrival time. Please take note that this number is not an absolute time indication; it just rolls over periodically
#- CAN ID of the packet
#- CAN packet type (D for Data, R for Remote)
#- CAN Data Len for the [packet]
#- CAN Data contained in the packet
- "CSV Without Padding" generates a CSV file where each field is separated from the other by a ";" and is very commonly used by spreadsheet applications. This version does not add the padding, reducing the output size of the generated file.
- "CSV With Padding" generates a CSV file where each field is separated from the other by a ";" and is very commonly used by spreadsheet applications.
CAN packets are structured according to the CAN protocol, but here it is enough to say that each packet has from 0 to 8 bytes in it. "With Padding" in this case indicates that even if the packet capture contains less than 8 bytes, the representation exported will have 8 bytes indicated, and the empty spaces will be filled by a fixed value.
This is useful to simplify parsing of the file using external scripting tool, like Python or .Net.
- "ASC Without Padding" (ALPHA) generates an ASC file from the given CAN Log adding only the data received in the CAN packet.
- "ASC With Padding" (ALPHA) generates an ASC file from the given CAN Log adding bytes to reach 8 bytes to each CAN packet that is not full. This is useful to simplify parsing of the file using external scripting tool, like Python or .Net.
This Wrokspace allows you to configure some of the inetrnal behaviour of StartDiag Suite.
- "MAXIMUM LENGTH OF SEARCH TEXT" is the maximum length allowed for the text to be searched in the currently active document. This applies to both Development and Dashboard Configurator.
- "MINIMUM SELECTION LENGTH FOR APPBUSY" indicates how long have to be a selection for the copy and paste oeprations for showing the "Application Busy" dialog. When the selection is as big as this value, or bigger, the "Applciation Busy" dialog will be shown. This applies to both Development and Dashboard Configurator.
- "BUSY WINDOW DELAY MS" is the time (in milliseconds) after which, during an operation, the "Application Busy" dialog is shown. This applies to both Development and Dashboard Configurator.
- "Zoom Percentage" is the starting zoom level set for the Development workspace.
NOTE: you can always revers back to all the original values by pressing Set Defaults...'.'
StartDiag Suite implements some helpful features to help you to be quicker in doing your job, and this section will discuss exactly those.
A common point to all the workspaces is that, in one way or another, they need to access files. The logic behind the file selection is to preserve the last used path in that context. This means that, the first time you use a file path it will be very generic, but from that moment on, the last explored path in that context, or the last used one in a similar context, will be used.
Since the workspaces are so specialized, it can happen to have to switch between them very often. This can easily be done by clicking on their tab, or in a more quick way pressing Control (Ctrl for short) and the indicated shortcut key (for example you can reach directly the Development workspace by pressing Ctrl and while keeping it pressed, press F1).
This section is not meant to be a LUA tutorial, instead it is thought to be like a brief presentation about the possibilities that LUA Scripting offers in respect to the StartDiag ecosystem.
For the full documentation of the LUA language, please refer to the main LUA website, and for more specific information about LUA in the StartDiag System, refer to the StartDiag Developer Guide.
WHAT IS SCRIPTING
Scripting is a form of programming, just with less problems.
Programming is the activity of developing programs and normally it refers to using a rather complicated set of tools to generate a final program that can be executed.
Scripting instead is more like writing a set of instructions (in this, it is very similar to programming), but the instructions are passed to a program that reads them, executes them in order, provides the result to the user. No need for complicated set of tools, for scripting you just need a text editor to write the script (this is the role of StartDiag Suite Development workspace) and the interpreter (in our case it is the LUA Interpreter embedded in the StartDiag System).
WHAT CAN LUA SCRIPTING DO FOR YOU
StartDiag ecosystem is based on freedom.
The freedom to talk to your vehicle and do what you want with the connected electronic modules and the freedom to customize your experience with the StartDiag System itself.
All this freedom arrives from the simple fact that you can write your own scripts and StartDiag will execute them and report you back with the results.
And here comes the other important point: in your script you can take actions based on those results!
This can lead to some pretty interesting scripts.
GENRAL SCRIPTING
Without entering into too technical details, here will do a brief explanation of the constructs that can be used by every scripting context.
The main ingredients that compose a script (or a program) are:
- data
- conditional instructions
- loops
Clearly more commands are available , but they are mostly to simplify the development.
Data is basically a way to define, store and access information. Normally these are called "variables" if they can change during the execution, or "constant" if they are fixed for all the life of the execution.
Conditional instructions are very useful to handle decisions. They are commands that do something if a certain situation happens, for example:
if A is equal to 23 then print "odd"
Loops are useful to repeat other commands a given amount of times. It would be quite uncomfortable to write 100 identical instructions to write 100 variables. Using a construct in the form:
repeat 100 times [ print counter ]
is way more easy to read and write.
These are the kind of constructs that make development of scripts powerful!
LUA SCRIPTING
And here we will see how LUA implements those very useful constructs.
Let's start by seeing an example of how to define a variable in LUA:
a = 42
Here we have just defined a variable called "a" and assigned to it the value 42. Quite simple.
For constants, LUA uses variables, just remember to not change their value!
For conditional instruction, the most common is the "IF" instruction:
IF a == 42 THEN
PRINT('A is equal to 42!')
END
LUA uses the "IF" command, followed by the condition that is checked, and after the "THEN" keyword.
The block of instructions is terminated by the "END".
All the instructions put between "THEN" and "END" will be executed only if the condition is true.
And now, the loop instructions. Again, the most common is presented, which is "FOR".
FOR works on a numerical counter it repeats as long as the counter variable has a value between the initial and the final value.
FOR idx = 1, 100 DO
PRINT('Current index =' .. idx)
END
This will print "Current index = 1", then "Current index = 2" and so on until "Current index = 100" and then will stop.
As for the IF, the instructions between "DO" and "END" will be executed the requested amount of times.
LET'S WRAP IT UP
This was not a course in programming. This was just an introduction to explain what is the real power behind the concept of allowing you to develop your own LUA Scripts for the StartDiag ecosystem.
By accessing the communication channel of your vehicle, and extracting information, you can get data.
Leveraging the loops and conditional instructions you can do what you want if the vehicle gives certain responses to your requests.
You can decide to ask the vehicle some functional parameters, like the current speed and if it is higher than a given threshold (IF .... THEN .... END ) you can beep as a warning.
This is the freedom the StartDiag System gives you.
Here we are, ready to prepare your first Dashboard Configuration file to be used on your StartDiag System!
Let's start with a quick review of the sections Dashboard Configurator and Dashboard Configuration Project View.
To prepare the Dashboard Project you need to specify the requests to be done on the CAN. After you will be able to export the file to Dashboard Configuration script (which is a LUA script that you can put on the SD card in the Config folder with a proper name) and then you will be able to see the specified data on your StartDiag System Dashboard of choice.
We will start with a simple SAE PID request, the Engine Coolant Temperature and we will prepare the full Dashboard Configuration following the steps suggested in Dashboard Configurator.
B1. Example: Your first dashboard configuration
B2. Example: Your second dashboard configuration
B3. Example: Definition of really Composite PID
Here we are, ready to prepare your first Dashboard Configuration file to be used on your StartDiag System!
Let's start with a quick review of the sections Dashboard Configurator and Dashboard Configuration UDS Project View.
To prepare the Dashboard Project you need to specify the requests to be done on the CAN.
After, you will be able to export the file to Dashboard Configuration script (which is a LUA script that you can put on the SD card in the Config folder with a proper name in the form of "Dshbrd_X.sds" where X is A, B, C or D depending on which dashboard you want to associate it to) and then you will be able to see the specified data on your StartDiag System Dashboard of choice.
We will start with a simple SAE PID request, the Engine Coolant Temperature and we will prepare the full Dashboard Configuration following the steps suggested in Dashboard Configurator.
1. PID Request (1) configuration
It is requested as:
- Service: 0x01
- PID: 0x05
- Data bytes returned: 1
- Description: Engine coolant temperature
- Minimum: -40
- Maximum: 215
- Units: °C
- Formula: A − 40
This is all we need to know to setup the readings in Dashboard Configurator.
All the fields are self explanatory enough, with the exception of Formula (a deeper description can be found in the document "StartDiag Developer Guide" in the section "C. PID definition examples").
Formula is presented as A - 40, but what is A? A is the first received byte. (if in the formula you find B, C and so on those are the second, third and consecutive bytes).
OK, back to work.
We know that we have to ask to an ECU the data. So in the dropdown "Source" field we select ECU.
Now comes the trickiest part: "RemoteID" and "LocalID". The issue here is that there is no fixed or standard way to know this number. This is an information you have to find or look for yourself.
"RemoteID" is the address that the ECU accept requests on, while "LocalID" is the address that the ECU uses to send the response to.
In this example we will assume the most standard couple: "RemoteID" = 0x7E0, "LocalID" = 0x7E8.
"SID" is the abbreviation of ServiceID and form the data above we know it is 0x01.
"DID" is the abbreviation of DataID. It is handled as 2 bytes value, but a single byte is accepted. From the data above we see 0x05, so we can use both 0x05 or 0x0005 and both will be ok and correct.
"Start" is the offset of the byte where the data to be read starts. This is important because writing the wrong start implies reading wrong data. From the data above we know we are expecting a single byte so we can set "Start" = 0 (first byte).
"Length" tells how many bytes compose the data. The accepted values are 1,2,4, and since we know from above that we have a single byte, length must be 1.
"Little Endian" is a parameter telling StartDiag if it has to interprete the data as Little Endian instead of the default configuration of Big Endian. For a deeper explanation check "B. Data and Endianness" "StartDiag Developer Guide". For now, since it is one single byte this configuration doesn't change anything, so leave it off.
"Offset" field tells how much the result read from the data have to be changed. This number will be added, so if you want to subtract a value (like in this case) you must write it as negative number). The Formula says -40, so we define "Offset" = -40.
"Scale" is the final value to set and is the multiplication factor applied to the read data. This can be negative. In our case the formula says A - 40 and we can read as (A * 1) so we set "Scale" = 1 (which basically means no scale).
"Note" is a text field that you can freely use to put your own comments and reminder.
2.Composite PIDs (2) configuration
This table is useful to define more complicated PIDs that require more than one value to be read from an ECU.
In this example we are just using the single PID defined above, so here just set "First Field" to the key that was automatically assigned to the PID Request defined before (in this example we have PR_0001).
"Note" is a text field that you can freely use to put your own comments and reminder.
3.Gauges (3) configuration
Gauges configuration setup the graphical representation of the data on the StartDiag System Dashboard (for more, read "5 Dashboards" in "StartDiag Device Guide").
Each dashboard is composed of 1 or more Gauges, and this configuration will be applied to the Gauge indicated in the Table "Dashboard (4)" (more on that later).
Some of the fields of this table are related to the data definition provided above, but even for those, it is up to you to decide how much you really want to stick to them. In fact the definitions of the generic PIDs are... generic. If you have special configuration, nothing prevents you from doing so.
Let's proceed with order.
(If you want to understand more about these fields, please refer to "StartDiag Developer Guide" section "8.5.8 gauge configuration table")
Please note that many of the fields are indeed optional, but in this example we will setup all of them for clarity.
"Description" is a short description shown in the Gauge. You can put whatever you want here, in this example we will use "Description" = "ECT".
"Measurement Units" is a short string providing the measurement units to be shown. Here we set "Measurement Unit" = "°C"
"Digital Value" is a flag that, when activated, forces an Analog Gauge to only move on the values marks, leave it deactivated.
"Min. Value" is the minimum value shown by the Gauge. The data description above says that the minimum is -40°C, we can set it to -40, or to see values a bit more in the middle we set "Min. Value" = -50.
"Max. Value" is the maximum value shown by the Gauge. The data description above says that the maximum is 215°C, we can set it to 215, or to see values a bit more in the middle we set "Max. Value" = 225.
"Decimal Places" is how many decimal digits you want to see. This is an integer value, so we set it as "Decimal Places" = 0.
"First Zone Color" is the color to use for the first zone (for more information see Dashboard Configuration Project View). Since low numbers are cold, we will set "First Zone Color" = "Azure".
"Second Zone Color" is the color to use for the second zone (for more information see Dashboard Configuration Project View). Since middle numbers are ok, we will set "Second Zone Color" = "Green".
"Third Zone Color" is the color to use for the third zone (for more information see Dashboard Configuration Project View). Since high numbers are hot, we will set "Third Zone Color" = "Red".
"Second Zone Start" is the value where the second zone starts (the first zone automatically starts at the value "Min. Value"). In this example we will set "Second Zone Start" = 80.
"Third Zone Start" is the value where the third zone starts. In this example we will set "Third Zone Start" = 100.
"Alarm Min." is the value below which an alarm on the gauge will be triggered. For example we set "Alarm Min." = 10.
"Alarm Min. On" is a flag that enable the alarm min in the Gauge. In this case we do not want the min alarm to be active, so we leave "Alarm Min. On" deactivated.
"Alarm Max." is the value above which an alarm on the gauge will be triggered. For example we set "Alarm Max." = 120.
"Alarm Max. On" is a flag that enable the alarm max in the Gauge. In this case we do want the max alarm to be active, so we set "Alarm Max. On" to activate it.
"Weight" value is set to 1 since we do not really want to apply any filter to these data (temperatures tend to change slowly enough that no filter is needed).
"Note" is a text field that you can freely use to put your own comments and reminder.
4. Dashboard (4) configuration
Dashboard table is where the Composite PIDs are coupled with their defined graphical representation as a Gauge.
The number of the row where the definition is done defines which gauge in the dashboard will show the data read.
In this example we will define in the first gauge (first row in the table) so it will use the first Gauge definition and the first Composite PID defined.
"Gauge Configuration Key" is the Gauge configuration from table Gauges (3) to use. We will set "Gauge Configuration Key" = "GC_0001".
"Composite PID Key" is the Composite PID definition to use to get the data. In this example we set "Composite PID Key" = "CP_0001".
"Note" is a text field that you can freely use to put your own comments and reminder.
5. Options configuration
This table allows you to configure some option that will be applied by StartDiag System Controller when reading the PIDs.
For UDS PIDs, it may happen that some PIDs give reading errors at times, maybe you enter in the Dashboard on StartDiag Device and some are working fine, you exit, you enter later on and some of the ones working before now are giving you errors, or the other way around.
In this case you can setup a delay here that will be applied after each PID request done by the StartDiag System Controller.
In this case we leave the default value unchanged.
NOTE: each PID is retrieved as a standalone data request. This delay is applied after each request.
Dashboard Script Export
Done, the definition of the Dashboard is done.
Don't worry if we have defined only one Gauge in the Dashboard, all the others will be handled correctly showing them as not configured on the Device.
Now it is time for the last step: the generation of the file to be put on the Device SD card.
This is simply done by clicking on "File" -> "Export Dashboard Project.." (or using the key combination "Ctrl + E").
Select the output file and click "Save".
Up to this section whichever name you selected is fine, but if you want to use this new file on the SatrtDiag Device, the filename must be put in a specific folder and must have a specific name.
For the dashboard configuration to be accepted by StartDiag Device, the Dashboard configuration file (extensions .sds) must be put in "Config" folder on the SD card, and the name must be in the format of "Dshbrd_X.sds" where X is A, B, C or D and select to which Dashboard this configuration apply.
This can be done on the PC and the already renamed file put on the SD card, or the file can be copied on the SD card and then renamed properly.
By default the SD card already contains 4 dashboard configuration files, one for each dashboard. You may have to replace the currently set configuration file with the new one you just generated.
Generally speaking it is always a good idea also to make a backup of the files before you replace them, so in case it will be easier to get back to the previous situation.
When you are ready, you can put the SD card in your StartDiag Device and launch the Dashboard!
Before proceeding, check B1. Example: Your first dashboard configuration if you have not done it yet.
This section will build heavily on the subjects introduced there.
Here we will discuss a bit more about how to handle data that is more than one byte long.
In reality the only part of the workflow introduced into B1. Example: Your first dashboard configuration that changes is the "Length" defined, but that takes a bit of discussion.
For a deeper explanation of the topic, please refer to "StartDiag Developer Guide" section "B. Data and Endianness" and "C. PID definition examples".
Here we will define the requests for SAE Standard, service 0x01, "Engine Speed" PID.
It is requested as:
- Service: 0x01
- PID: 0x0C
- Data bytes returned: 2
- Description: Engine speed
- Minimum: 0
- Maximum: 16,383.75
- Units: rpm
- Formula: (A*256 + B) / 4
1. PID Request (1) configuration
"DID" from the data above we see 0x0C, so we can use "DID" = 0x000C (we used 0x000C instead of 0x0C just to show that it works the same).
"Start" from the data above we know we are expecting two bytes starting at index 0, so "Start" = 0 (first byte is byte number 0 !).
"Length" this is clearly stated in the above description as 2, so we set "Length" = 2.
Note: for the formulas that use A, B, C and so on we can count the number of letters and that will be matching the length defined.
"Little Endian" is left unchecked. This is because looking at the Formula we see that byte A is multiplied by 256, while B is not. This is equivalent to moving the byte A to the left of 1 full byte. So A is the Most Significant Byte, and since A comes before B in the data, this is what is called a Big Endian notation.
"Offset" is set to 0. Looking at the Formula we do not see any constant added or subtracted, hence we set "Offset" = 0.
"Scale" is identified from the Formula. There we see that the data is divided by 4, so we set "Scale" = 0.25 (equivalent to 1/4).
2.Composite PIDs (2) configuration
In this example we are just adding the second PID defined above, so here just set "First Field" to the key that was automatically assigned to the PID Request defined before (in this example we have PR_0002).
"Note" is a text field that you can freely use to put your own comments and reminder.
2.Composite PIDs (2) configuration
Nothing different respect to the previous example B1. Example: Your first dashboard configuration has been done here.
3.Gauges (3) configuration
Here we are showing a couple of different things with respect to B1. Example: Your first dashboard configuration.
Most notably we set the "Max. Value" less than the value specified by the PID definition. This is fine, we are considering that for our vehicle the maximum RPM speed will be around 9000 rpm, and so we have a better view of the real data.
Moreover we set the "Max. Alarm" to 7.000 rmp, same value where the Second Zone starts.
Speaking about Zones, this time we do not use the Third Zone, so we leave the fields empty.
"Weight" value is set to 0.5. RPM change very quickly and an intermediate filter can prove useful to have a better representation of the data.
4. Dashboard (4) configuration
Here we add on the second row:
"Gauge Configuration Key" will be set "Gauge Configuration Key" = "GC_0002".
"Composite PID Key" is set as "Composite PID Key" = "CP_0002".
Before proceeding, check B1. Example: Your first dashboard configuration if you have not done it yet.
This section will build heavily on the subjects introduced there.
Here we will discuss a bit more about Composite PIDs.
These are a concept that gives you the flexibility to perform operation and composition with data received by an ECU or with constants defined by you.
In this example we suppose that we are interested in the ratio between Engine Coolant Temperature (ECT) and Intake Air Temperature (IAT). Both are standard SAE PIDs defined by service 0x01, respectively with data ID of 0x05 for ECT and 0x0F for IAT.
Standard SAE doesn't provide a single PID with the information that we need, but using Composite PIDs we can extract that on our own!
ECT requested is defined as:
- Service: 0x01
- PID: 0x05
- Data bytes returned: 1
- Description: Engine Coolant Temperature
- Minimum: -40
- Maximum: 215
- Units: °C
- Formula: A − 40
IAT requested is defined as:
- Service: 0x01
- PID: 0x0F
- Data bytes returned: 1
- Description: Engine Coolant Temperature
- Minimum: -40
- Maximum: 215
- Units: °C
- Formula: A − 40
1. PID Request (1) configuration
Give the above definition, and the information explained in B1. Example: Your first dashboard configuration we can easily compile the PID Request (1) table rows.
Keep in mind that we need to define both before we can use them, and for sake of order in this example, let's define in PR_0001 ECT, and in PR_0002 IAT.
2.Composite PIDs (2) configuration
This is where the big changes happen.
What we want now is to define a "combination" of ECT and IAT, specifically we want to implement a formula like "ECT" / "IAT".
The table Composite PIDs (2) has a set of columns named "Fields" and "Operator".
We can set ECT (PR_0001) as the "First Field". If we stop here we just said that we want to see ECT in the First Composite PID (CP_0001).
This time instead we select "First Operator" as "/" which is the division operator, and after we set "Second Field" to IAT (PR_0002).
This is all we have to do to define a Composite PID calculating the requested value!
Given this definition, StartDiag System Controller will request both the SAE PID (one by one) and then perform the division. The result of the operation will be displayed in the Dashboard on StartDiag System Display.
3.Gauges (3) configuration
Gauge configuration for the Composite PID defined above is exactly the same as above. We set the requested value, leaving the unused ones empty.
4. Dashboard (4) configuration
Also for this table the configuration follows exactly what was done in the previous example.
Filter: an introduction
Values incoming form StartDiag Controller are directly read from the connected CAN BUS.
The frequency of the readings depends on the BUS conditions, the current work load of the Controller itself and the other connected device that is providing
the data to be displayed.
After being received, the data is displayed to you in the StartDiag Display inside one of the available Dashboard.
Here you can see the value changing in real time as the new values come in.
Sometimes the data may arrive quickly enough that the representation inside the single Gauges seem to be even too reactive, almost flickering in values, and at times this graphical behavior does not really help you in reading the value that is being presented.
To mitigate this behavior we introduced a filter on the data that is displayed in the Dashboards.
The filter applied is called Exponential Moving Average Filter, you can look it up online, but it is not as complicated as the name may suggest.
Let's take a look at it together.
The main formula is:
Value = (ImmediateValue * Weight) + (OldValue * (1 - Weight))
The idea behind this filter is quite simple, we take the current instantaneous value and we multiply it by a parameter called Weight, then we sum it with the previous value shown multiplied by (1 - Weight) [NOTE: it is important that the sum of the two coefficients add up to 1!].
Basically we are taking a part of the current received value and we add it to a scaled value of the previous one. This gives us the current value that will be shown, which later is going to be used as the old value the next time that we receive data to be presented in the Gauge. It is similar to an average, but instead of giving all the values in the formula the same importance they are scaled giving more relevance to one than the other by tweaking the value of Weight.
A Weigth of 0.9 will give a lot of importance to the new value arrived respecting the old one, a Weight of 0.1 will give more relevance to the previous value than the one just arrived.
In the screenshot below you can see the effect in the Chart View on StartDiag System Display of three different filter configurations:
- The white graph is the data arrived with no filter applied
- The pink graph is the result of applying the filter with Weight = 0.5
- The yellow graph is the result of applying the filter with Weight = 0.1
This kind of filter allows to remove the components that changes very quickly from the incoming data, slowing down the changes of the value displayed and so reducing the flickering effect and slowing down the sudden changes in value represented in a Gauge.
Looking at the formula it is possible to nice a couple of interesting facts:
- Setting Weight = 1 will result in applying no filter at all! In fact in such a case the only relevant component remaining is Value = ImmediateValue
- Setting Weight = 0 will result in a filter that NEVER update the result. (Not a very useful filter indeed)
To avoid the problem of a useless filter, StartDiag Suite doesn't allow weight to be set to 0.
Obviously the application of such a filter has some effect on the number that you see in the Dashboard:
- the values change slower (if a value changes quickly from, let's say 0 to 100, using the filter it will pass from intermediate values that are not really part of the received data but result of the filter action)
- if data reaches a maximum values just for a brief period of time, the value presented may not represent that number (we may say the filter tends to smooth the peaks and valleys in the incoming data)
- if the data presents a medium value, the stronger the filtering action, the more the data will tend to be flattened toward such value
Finding the right value of the Weight can be tricky, since that depends specifically on the nature of the data that
Filter: Display override
StartDiag Display shows the instantaneous values of the requested PIDs in the Dashboards configured.
To allow for a more stable reading of the given values, a filter can be applied and set in the two places:
- when the Dashboard file is defined using StartDiagSuite, the filter Weight can be set in the column of the same name in the Gauge Configuration table
(This value is assigned also in the output Dashboard configuration file used on the StartDiag System SD card)
- as for other settings, this can be overwritten on the StartDiag Display unit from the sub-menu of the Dashboard
Clearly the customization applied on the StartDiag Display will be active only the specific StartDiag Display unit (they are saved on the SD card) and are applied only if the configuration of the Gauge to which they apply is not changed in the Dashboard script since when the overridden settings have been done.
Finding the right value of the Weight can be tricky, since that depends specifically on the nature of the data that is analyzed.
Filter: Filter Configuration
As a general suggested approach, the following steps allow for the quickest configuration:
- prepare the full Dashboard configuration in StartDiag Suite Dashboard Configurator workspace with no filter active
- save it on the SD Card and start using it on StartDiag System
- here you can use the "Change configuration" option on the various Gauges (see StartDiag Device Guide) to set a different value for the Weight of the filter
- when you find the value working for the specific Gauge, open up the Dashboard Configurator and set the Weight there
- export again the configuration and give it a test
REMEMBER: if you make use of the StartDiag Gauge override settings without updating the source Configurator Project, what you see on your device is not what is seen by someone else using your Dashboard Configurator Project file!