This is a page describing variable creation and maintenance.
It is based on the concepts described in general variable approach and also uses settings explained in variable owner configuration.
Data types can be created and maintained in the "Data type definitions" dialog.
Open Data Types Definitions Dialog
1.Open menu "Communication".
2.Select "Options"
3.Choose
Use Data Type Definitions Dialog
1.Check "Signed" if you need an additional signed data type.
2.Type the length of the new data type in bits.
3.Press "Add" button to add your new data type to the GUI definition.
4.New type will appear in this list (for our example it would be "INTEGER27").
5.Press "Close" button once you're finished adding and deleting variable data types.
As stated in general description it is good practice to organize variables in groups to support maintenance once there are more than a few of them.
There are two ways to open the "Variable Groups Configuration" dialog.
Open Variable Groups Configuration from Menu
1.Open "Communication" menu.
2.Select "Variable Group Configuration..."
Open Variable Groups Configuration from Variable Manager
1.Open Menu "Communication".
2.Select "Variable Manager..."
3.Press button "Groups..."
Variable Group Configuration
Initially the dialog only shows the predefined variable groups which can not be modified or deleted.
In order to add your group(s)
1.Press "Add Group" button
2.Type the name of your group in the box that appears and press "Enter".
The new group will be moved where it belongs alphabetically in the list of variable groups. Like that it could move out of the visible part of the list.
You can create more groups by repeating the steps above.
In order to modify the name of one of your groups, follow the instruction on the bottom of the dialog.
Press the "Remove..." button in order to delete one of your groups. If it should already contain variables they will be moved to "Common" group.
The variable manager dialog is the main place to create and maintain variables.
Open Variable Manager Dialog
1.Open "Communication" menu.
2.Select "Variable Manager..."
Create New Variable
In order to add a new variable to the GUI definition
1.Press button "Create a new Variable..." in Variable Manager dialog. This opens the "Add New Variable" dialog.
2.Type a valid name that you will recognize when you want to attach this variable to DDOs later or when you want to use it in a script.
3.Define the index for the variable. If you should use CANopen this will be the index published in EDS file.
4.Define subindex for the new variable. See dedicated section of variable concept for recommendations on index and subindex.
5.Choose data type for your variable only for CANopen you can not reduce the size in CAN messages. Otherwise main criteria is to make the variable big enough for all values it should transport.
6.Select owner of the variable. See section owner concept in base document for criteria about which owner a variable should get.
7.Select a group for the new variable. See section organizing principles in base document for some recommendations on group definitions.
8.Press "Add" button to add the new variable to GUI definition. Every press on "Add" will create a new variable - as long as name and index/subindex combination are unique.
9.If you want to create more than one variable you can either directly modify your settings OR press "Reset" first to get the dialog cleaned up first.
10.When you are finished creating variables, press "Close" button to leave the dialog and return to "Variable Manager".
Maintain and Modify Variables
Variable manager provides all the properties of all variables so that you can check the predefined ones and modify or delete your own variables.
Before actually deleting a variable it is recommended to make sure that it isn't used anymore in the variable view.
The Variable manager provides the following options and properties to maintain variables.
Manage Variables
In this section some other dialogs can be opened:
Groups opens the Variable Group configuration dialog
Processes opens the Process Configuration dialog
ECU(s) opens the Terminal and Owner ECU(s) Configuration dialog
Create a new Variable openes the Create new Variable dialog
Select Variable
In this section variables can be filtered by
- Groups
- Owner
- and Variable name
Note that only one variable can be selected at any time.
Properties
Name
The name of a variable is used to identify the variable within the OPUS Projektor mainly. In order to find a variable in this dialog, attach it to an object or use it in a script this name is required.
Therefore it is recommended to use a logic naming convention that will support working with variable. This will not only help you in your work but also others using it in the future - think of maintenance and maybe even our support team helping you with this GUI definition at some point of time.
Index
On the display side index and subindex are the main criteria to identify a variable - so it has to be unique within the GUI definition.
If you should use CANopen this value is directly exposed in the EDS file describing the object dictionary. Therefore the value range for index is limited to the proprietary range of CANopen indices. Range 0x2000 ... 0x2FFF is reserved for predefined variables so that your own variables can occupy the range 0x3000 ... 0x5FFF.
Like using variable groups proper selection of index and subindex can help to keep the GUI definition maintainable. See dedicated section of variable concept for recommendations on index and subindex.
Warning: Although one can change index and subindex here they render all references to this variable useless. I.e. if you have to modify index or subindex after assigning the variable anywhere (DDO, mapping, action ...) you have to re-visit all these assignments and assign them again.
SubIndex
Subindex is directly tied to index - every subindex can only occur for one variable per index.
If you set subindex to 0 then this is the only variable for this index. If you skip subindex 0 you can define up to 254 (0x01 ... 0xFE) subindices per variable thus using the index like a group definition containing subindices that also belong together logically.
See property "index" above and dedicated section of variable concept for recommendations on index and subindex.
Owner
Every variable needs an owner and only the owner is allowed to actually change the value of the variable. Here you can assign either one of the predefined or your self defined owners.
There is an extra page for creation and maintenance of owners. Recommendations about owner assignment can be found on general variable page.
Description
This property exists for documentation and maintenance - please take the time to provide a short comment about the purpose and specific use of this variable.
Like that this property can make it easier to understand the GUI definition - especially for persons not involved in its development, e.g. maintainers or our support team.
Data Type
For CANopen this is how the variable will be maintained in object dictionary, mapped to PDOs and published in EDS. For other protocols or internal use you should choose a format covering the variable's purpose while avoiding to waste space in CAN messages.
Internally all numeric variables are stored as 32 bit anyways - so if in doubt and not using CANopen "INTEGER32" or "UNSIGNED32" should work for most applications. When adding the variable to mappings you may have to reduce its mapped size because default is to reserve the amount of bits defined here.
Custom data type creation is explained at the top of this page.
Maximum Length (in bits/bytes)
For numeric data types the length in bits is part of the data type and just shown here - i.e. this property is not editable for numeric types.
For strings this property defines the maximum length in bytes. This length is only enforced for user input in the program as well as on the device. Otherwise longer strings can be written to and read from string variables.
Please note that the display internally uses UTF-8 encoding which uses up to four bytes for special characters e.g. used in Russian or Asian language. So if you want the string to contain such characters you should make sure there is enough room. If you stick to basic ASCII encoding (values 0 ... 127) then UTF-8 is the same as ASCII and every character takes exactly one byte.
Access Type
This property allows some optimization and is required for CANopen support.
Generally the owner of a variable has full access and can modify its value whenever he needs to. Access type describes what others can do with the variable: If you e.g. set the variable as "ReadOnly" then a write request will not even be sent to the owner but the attempt to write will directly fail.
Full access to the variable is provided with access type "ReadWrite" - so if the variable should not need limitations this is the value to choose.
Default Value
The variable is initialized with this value - depending on "Initialize Value As Invalid" below you may never actually see this value on screen.
Initialize Value as Invalid
Set this property to consider the variable value invalid until a first value is provided by the owner. DDOs typically appear disabled (grey mask on top) while the value is invalid.
If you want to consider the "Default Value" above a valid value of the variable even though it was not set by the owner you should uncheck this property.
Remanent
Set this property if variable value should persist over power cycles. This property only actually modifies user defined variables owned by PClient. For predefined variables it's an information about what the owner does.
Force Writing
Normally there is some optimization in place which only forwards "new" variable values if the value was modified. I.e. PClient only forwards write requests to the variable owner if the value is different from the current one. The other way around it only forwards the "new" value sent by the owner if the value differs from the last one received.
This is helpful in most cases where e.g. the value is periodically transferred in a CAN message.
There are use cases though where every update or write request has to be forwarded i.e. the write itself is more meaningful than the value it transports. An example from the predefined variables is "@BeeperRepetitions" which should start a beeper sequence which could have the same amount as repetitions as the last one. For these cases "Force Writing" should be checked.
Preview Value Specific
These properties do not change the value of the variable. The properties will help showing the variable value as it should be displayed.
This can be configured manually or by a definition in a DBC file.
The properties have the same functionality as those for Numeric Fields.
Unit Suffix
Here a text can be written that will be shown after the number of the variable, i.e. to include the unit, like 3 kg.
Note that for this property the property Use Variable Preview Value Settings of the Numeric Field has to be checked.
Protocol Specific
Based on the CAN protocol use to communicate with variable owner there could be additional properties required. These properties would appear here.
One example for these additional properties is index/subindex of the variable in the owner's object dictionary. This is currently only used if the owner is a CANopen ECU.
Protocol specific properties are explained on the pages of the protocols, see CAN Freestyle, CANopen and J1939.
Events
The "Events" tab allows to assign actions to specific events. By default no actions are assigned.
OnValueChangeByOwner
This event is triggered whenever the owner of the variable changes its value i.e. really sends a different value or "Force Writing" is true.
If you should see any "Event Options" for this event - ignore them like PClient does.
Possible actions that can be assigned are
•"No Action" which is the default
•"Set Value" to assign a constant value to another variable, e.g. to reset a counter or trigger something attached to a variable where "Force Writing" is true.
•"Scale Value" allows modifying the new variable value before it is distributed within the display. The following calculation will be applied using integer arithmetics:
variable_value = ((( received_value + offset1 ) * multiplier ) / divisor ) + offset2
•"Execute Script" allows to execute a script and provides additional parameter "Execute on every Xth Event" so that it is possible to execute the script only for e.g. every third variable update. This action should only be used for variables which are rarely updated since otherwise it could slow down PClient.
OnValueChangeRequest
This event is triggered whenever an entity that is NOT the owner of the variable tries to write a value to the variable. The event is only triggered if the value differs from the one the variable currently has or "Force Writing" is true for the variable.
If you should see any "Event Options" for this event - ignore them like PClient does.
Possible actions that can be assigned are
•"No Action" which is the default
•"Set Value" to assign a constant value to another variable, e.g. to reset a counter or trigger something attached to a variable where "Force Writing" is true.
•"Scale Value" allows modifying the value to be written before it is forwarded to the owner. The following calculation will be applied using integer arithmetics:
value_to_forward_to_owner = ((( requested_value + offset1 ) * multiplier ) / divisor ) + offset2
•"Execute Script" allows to execute a script and provides additional parameter "Execute on every Xth Event" so that it is possible to execute the script only for e.g. every sixth write request to the variable. This action should only be used for variables where write requests are applied rarely since otherwise it could slow down PClient.