Variables

<< Click to Display Table of Contents >>

Navigation:  »No topics above this level«

Variables

The main approach followed in the program is to create pages and the navigation between them which is a more static definition.

The dynamics come in with variables changing their values. Other tools use the term "signal" instead of "variable" to describe the same thing. A CANopen "object" also describes what we call a "variable" here. The same is true for J1939 "Suspect Parameter Numbers (SPNs)".

This page provides an overview of the general concept behind the variables.

There are follow-up pages explaining the menus and dialogs to create and manage variables owners and variables.

hmtoggle_plus1Owner Concept

Every variable in the GUI designer has to have an owner assigned. The owner is the only one controlling the value of the variable.

If somebody else tries to write the value of the variable this is considered a write request which is forwarded to the owner of the variable.

Only if the owner confirms the new value by providing an update of the variable it is considered changed.

If the variable is expected to be frequently updated by the owner e.g. via CAN bus message then they can also be considered invalid if the update does not arrive in time.

Generally there are two different types of owners:

•Remote ECUs connected via CAN bus

•Other programs/processes running on the display.

Examples of the second type are "Hardware Daemon" providing all of the hardware related predefined variables and "UD4" used for updates of the GUI definition on the display.

If considering to add your own process to communicate with PClient please contact our support team and expect to include some C++ libraries for the communication between the two in your program.

If PClient itself is the owner of a variable generally the same rules apply as for other owners. PClient has no built-in knowledge about which values of a variable are acceptable and which are not - except for the absolute minimum and maximum values.

Therefore PClient basically accepts and confirms all write requests to its variables.

Since PClient is active as long as the GUI is shown, PClient variables are valid if they ever got a valid value.

Generally the idea is to assign the variable to the owner knowing the system's limits and measuring its state. This means that e.g. engine coolant temperature should be owned by engine ECU.

On the other hand there may be some setpoints and GUI internal variables which should be owned by PClient.

A decision has to be made if a variable has to be considered a measured value as well as a setpoint.

Assume engine speed is a measured value coming from engine ECU but at the same time the operator can set a new desired engine speed by applying a new value to the engine speed variable.

Then there are (at least) two different sources for new values of the same variable.

If engine ECU is the owner of engine speed in this example, then the following will happen:

Engine as variable owner

One can see three effects here:

1.Typically the value is invalid until the owner provides the first value - there is an option though to avoid that.

2.After providing the new setpoint the value shown will switch back to the last value provided by the owner.

3.Since the owner is in control it may limit the value provided in the write request to something reasonable in current conditions.

If the display should e.g. forward the engine speed to another bus than the one where engine ECU is connected then it will only forward values confirmed by the owner.

If flickering back to last known value is not acceptable and the GUI can make sure that all settings made are valid then PClient could become the owner which would mean that any value of the variable is valid and variable will stay valid at any point of time.

If display should forward the value owned by PClient to different busses it will forward each and every value modification made by anyone - because it considers all modifications valid.
hmtoggle_plus1Remanent Variables

Remanent variables keep their values over power cycles. They get re-initialized whenever a new PClient is installed on the display.

Remanent variables are intended for operator settings and other values which will change but whose last value should be remembered when PClient is started again.
hmtoggle_plus1Predefined Variables

On the display there is a variety of predefined variables you can directly use in your GUI.

They provide e.g. hardware states such as I/O values for digital and analog ports or CAN bus status as well as display specific properties e.g. the part number and serial number.

Predefined variables are also used to e.g. configure camera interfaces, display backlight or beeper activity and obtain and set current time as provided by real time clock (RTC).

Other predefined variables provide information specific to your GUI, e.g. dealing with virtual keyboards and alarms and visibility. There are also variables showing the recent pages visited and the time a page was active.
hmtoggle_plus1ISO-VT Variables

There is a range of indices reserved for ISO-VT. These variables are not existing by default but you can create them as they are defined in the variable table.

This approach allows to save the resources if you don't use ISO-VT on your display while still providing the information in a standardized manner not interfering with your user defined variables.
hmtoggle_plus1Data Types

Every variable has to have a type. By default character strings and numeric types are supported.

Numeric types are either signed or unsigned and have a length in bits.

In order to support the minimum requirements of CANopen there are a few predefined data types which can not be deleted or modified.

Additionally both two bit types are provided which are used for some predefined variables representing booleans with an additional "undefined / unknown / don't care" state required e.g. for J1939 protocol.

Note: String variables are intended to carry readable strings. Therefore their value is considered to end where a "\0" character occurs.

Note: If string values should be shown on display they are interpreted as UTF-8 format which is the same as ASCII for the first 127 characters only.
hmtoggle_plus1Organizing principles

The program provides two separate means of variable organization:

•Variable groups are supposed to support the designer in keeping variables where he will find them again. These groups are not relevant for the device.

•Index and subindex are used to identify a variable even on display side. This concept was mainly introduced for CANopen support but is used for all variables.

It is suggested to create variable groups for all variables belonging together in one way or the other. One option would be to create one variable group per ECU. Another would be to find variables belonging to a certain subject and create a group for them.

Anyways each variable has to belong to exactly one variable group and if you don't create your own groups all your variables will end up in "common" group.

Note: In main screen variables can be handled and searched using variable view but when choosing a variable in a dialog it can really be helpful to have them ordered in meaningful groups.

CANopen organizes all variables as "objects" in its "object dictionary". From this object dictionary definition we "borrowed" the index and subindex approach. And since the display does not follow any of the predefined CANopen "device profiles" we had to move them all into the CANopen index range of 0x2000 ... 0x5FFF where proprietary objects have to reside.

Within this range we reserved index 0x2000 ... 0x2FFF for our predefined variables whereas user defined variables are located in the 0x3000 ... 0x5FFF range.

CANopen (and our program) allow two approaches to handle subindices: Either the subindex 0 is the only variable defined for an index or subindex 0 defines the highest subindex existing for an index.

It is recommended to use the latter approach and create subindices starting from 1. If you really want to use CANopen, the program will calculate the correct value of subindex 0 in this case.

Similar to variable groups you can use index as a grouping mechanism for many sub-indices. It would probably be a good idea to store all variables with the same index in the same variable group.

For the predefined variables every variable group contains exactly one index with all its sub-indices.
hmtoggle_plus1Variable import

It is possible to import variables from another project or via a .csv file with parameters for variables. This way large amounts of variables can be created quickly. The .csv file has to look like this:

Variable;Index;Sub-Index;Owner;Group;Property_Description;Data-Type;Length;Access Type;Min Val;Max Value;Default Value;Initialize Value As Invalid;Remanant;Force writing

test1;0x3011;0x01;;;;INTEGER;8;;;;;TRUE;FALSE;FALSE

test2;0x3011;0x02;;;;INTEGER;16;;;;;TRUE;FALSE;FALSE

test3;0x3011;0x03;;;;INTEGER;8;;;;;TRUE;FALSE;FALSE

test4;0x3011;0x04;;;;INTEGER;16;;;;;TRUE;FALSE;FALSE

To import variables, click in the menu Communication -> Import Export Variables -> Import Variables

variable import file dialog

 

In the file dialog, choose the according file type (project xml or CSV) and the file from which you want to import the variables and click Open.

 

variable_import_attribute_mapping

In this dialog you can choose the appropriate delimiter, the row where the program should start reading the variable data, and a table where you can tell the program which column contains which property for the variables. If you have used the format shown above you can use the default values and click Next...

If you haven't given all properties for all variables, the program will show dialoges and suggest default values for these properties. After confirming these a last dialog will be shown where you can choose which variables you actually want to import.

variable_import_imported_variables

You can select single variables or all variables. Click on the button >> to choose variables for import. Click import to create all the chosen variables in your project.