Name

The name of a variable is used to identify the variable within the program mainly. In order to find a variable in this dialog, attach it to a DDO 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.

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.