To configure the port that shall be used for the communication select main menu tab [Communication][Port Configuration...] . A new dialog 'Port Configuration' will be opened. Depending on the Selected Port the Bus Speed should be set. Press "OK" to confirm the settings.

1.Select CANFreestyle on the CAN port configured before - in our example we configured it for CAN 1.

2.Type a valid name and description - these are mainly for your convenience and may help others to understand the GUI configuration in future.

ECUs are configured in the same "Terminal and Owner ECU(s) Configuration" dialog that was used above to activate CANFreestyle protocol and to configure the display's address. ECUs are configured in the lower part of this dialog:

1.Type a name describing the ECU

2.Press "Add"

Then the new ECU will automatically be selected and one can modify the other parameters:

3.Provide a description that could help others to understand better which ECU is meant here

4.In case the ECU is not needed anymore it can be deleted again. If it already owns any variables, the owner will be changed to the display (PClient) when you delete it.

Knowing that we could end up with a lot of variables per ECU it's a good idea to create one variable group per ECU. Of course you are free to organize variables in groups however you prefer.

1.Open Menu "Communication"

2.Select "Variable Group Configuration ..."

3.In the dialog that opens press "Add Group" to create a new variable group

4.Type a sensible name for the new group

5.Once you pressed "Enter" to confirm the new group name it will move according to alphabetical order of all groups.

6.Press "close" once you're finished creating or deleting variable groups.

Creation of CANFreestyle variables is similar to all other variables

1.Open the "Communication" menu and choose "Variable Manager ..." entry

2.Variable Manager dialog opens (which can be used as shortcut to all variable related tasks)

3.Press "Create a new Variable ..." button

4."Add new variable" dialog opens

5.Fill in a name of the variable

6.Type an index for the variable. You are free to enter the value in decimal or hexadecimal, starting with "0x". Anyways hexadecimal will be displayed. (Although the concept comes from CANopen you should use index and subindex as a means of ordering and grouping of variables)

7.Add a subindex for the new variable. Note: Combination of index and subindex has to be unique among all variables in the GUI definition.

8.Select signed or unsigned data type at least as wide as the variable will be in CAN message.

9.Change owner from default "PClient" to the newly created CANFreestyle ECU. Note: If you keep "PClient" you could handle the variable also but would not notice if the ECU is not available anymore.

10.Select the newly created variable group for the variable.

11.Press "Add" to finally create the new variable with the settings made above.

If the variables was created successfully the above message will be shown at the lower left box of the dialog.

Now you can either create more variables by editing the settings with or without "Reset" or leave the dialog with "Close".

After closing the "Add New Variable" dialog you can modify all the properties of the variable(s) just created or already existing in "Variable Manager" dialog:

For a detailed description of all the variable properties and events please refer to variable view.

There is a second option to create variables:

1.In variable view press the "Var +" button

2.A new variable with default settings appears

3.You can double click each property and edit it.

Warning: If you type a group name that was not defined yet, a new variable group will be created.

Warning: Depending on your sorting option the variable can "disappear" whenever a modification is confirmed.

More details on this option can be found in variable view.

So the recommendation is to create variables following the first option and use variable view to manage and modify existing variables.

ID

Is the object ID created internally which can not be modified.

Name

The name of the mapping as used during creation. This name can be edited here.

Type

"Receive" or "Transmit" - this property can not be modified. If this needs to be changed you have to delete and recreate the mapping.

Description

Should be a valid description of the mapping which helps understanding its purpose and context in future.

Mapping Variable Type

CANFreestyle only supports one type:

•Length based mappings find every variable (or constant) by position and length within the CAN message. If length based mappings are less than 8 bytes long, their variables or constants can be placed at any position. If they shall be longer, the variables and constants have to be byte aligned.

Receive from / Transmit to

For receive mappings: Select the ECU which will send the Mapping where the variable should be extracted.

For transmit mappings this property describes the destination address to be used (i.e. the ECU that shall receive the values).

Little Endian/Big Endian

CANFreestyle values are transferred least significant byte first (Little Endian) by default. Here you can change this to most significant byte first (Big Endian). If you have a Mapping which contains Little and Big Endian values you have to create two separate mappings.

This setting only applies to numeric values. Strings are expected to be "big endian" i.e. the first byte of the word or sentence is the first one on the bus.

Mapping Length

Enter the length of the message you want to configure. The length has to be between 0 and 8 bytes.

Object Status

With Object Status Active the mapping is working, i.e. it is processing received messages or sending them. With Object Status Inactive the mapping is not working. This property can be switched at run time with the setProperty JavaScript function to enable / disable CAN mappings.

CAN ID Type

This setting defines whether an '11 Bit Identifier' or '29 Bit Identifier' should be used for the CAN ID.

CAN ID (0x)

This defines a CAN ID for the appropriate Mapping. The ID is not unique so it is possible do define several mappings with the same ID e.g. if a multiplexer is used.

CAN ID Mask

If not all bits of the Identifier should be evaluated it is possible to define a CAN ID Mask which only evaluate the needed bits of the CAN ID.

NOTE: You can define your own CAN ID Mask here.

These settings define if and when the display sends a request (for receive mappings) or answers a request for a transmit mapping.

The only pre-requisite is that the ECU sending the request is "known", i.e. defined in the ECU Configuration.

Enable Request

For receive mappings this means that the display will send out a request to get the Mapping based on the following settings.

For transmit mappings this means that the request defined in the following properties will be recognized and answered with the transmit mapping.

Request message

This allows definition of a Message with fixed data section which will be sent out in order to get the receive mapping based on the following triggers.

Request Message Transmission Period

This is only enabled for receive mappings. It defines the interval in milliseconds the display will send requests for the mapping. Set to 0 if no periodic request is required.

Send Request On

•"Specific Variable Change" allows triggering the request based on the value change of any variable in the project.

•"None" means there is no trigger besides the time based one.

Select Variable (Rx)

Only enabled if this is a receive mapping, request is enabled and "Send Request On" is set to "Specific Variable Change". This allows setting the variable whose value change should trigger sending the request.

Receive Timeout

This is intended for receive mappings which are expected to arrive periodically - either by default or by periodic request. If the mapping is not received in as many milliseconds as defined here all variable values of the mapping are considered invalid and hence all DDOs showing them will also be disabled (i.e. numeric fields shown with dashes, meters and such grayed out).

Use as Write Request

If checked this means that the transmit mapping will be sent out once if there is a write request to one of the variables contained in the mapping. Usually the display only sends values provided by the owners of the respective variables in transmit mappings.

This means that e.g. engine speed will only be sent out as provided by engine ECU. If in your system modifying the measured engine speed value is used to set a new desired engine speed then you can check this property and writing on the engine speed variable will send out the transmit mapping containing the new setpoint of the engine speed value.

Please note that all other values in the mapping will be the ones provided by their respective owners and even the new setpoint will in the next message be replaced by the last measured value provided by the owner.

If you should want to write to the same variable from many sites you should consider "PClient" as the variable owner which will accept all write requests but whose variables will never become invalid again once they have a value.

Send Value On

•None: Mapping is only sent time based (if configured) and on request.

•Any Variable Change: Whenever one of the mapped variables changes its value the mapping is sent out.

•Specific Variable Change: The mapping is sent out if the variable specified in the following property changes its value.

Select Variable (Tx)

Choose the variable whose value change should trigger sending out the mapping. This variable can be part of the mapping but doesn't have to be.

Transmission Period (in ms)

Defines the interval between messages for this transmit mapping. Set to 0 if time based sending is not desired.

After setting all the general properties of the mapping now the data part has to be defined.

Some general rules apply:

•All variable's and constant's positions define the position of the least significant bit (for little and big endian)

•Transmit mappings have to be defined completely - we can not send "gaps" on the bus.

•Receive mappings can have gaps - as long as the length can be determined.

•Receive mappings are recognized if all the following conditions are true:

   if (  ( (CAN-ID received AND configured CAN-ID Mask) == (configured CAN-ID AND configured CAN-ID Mask) )

      &&  ( (message length) == (message length configured) )

      &&  ( (constants received AND configured mask) == (constants configured AND configured mask) ) )

Note: It is allowed to leave gaps in the data section of receive mappings. However, the message length has to be configured correctly in the Mapping Length property

Note: The last condition allows covering multiplexed Mappings by defining a separate mapping for each value of the multiplexer

To do this, use a constant value from the "Constants" group and adjust it to the length of the multiplexer region in your system.

Then map this constant to the appropriate byte/bit position. Fill the rest with the variables needed.

Create the mapping multiple times with different constant values. Each mapping will only react if its constant value equals the incoming message. The variables should match the message structure for the according multiplexer value.

1.Press "Add" button to add a line to the mapping.

2.Select the group of the variable to map.

3.Select the variable itself.

After doing this the properties in the line adjust to the variable definitions made earlier e.g. the length is set to 16 bits and the mask is set to 0xffff meaning all the bits will be taken.

This tab allows adding actions to mapping related events. It only appears for receive mappings.

The configured actions for the events are executed directly in the CAN thread when the event happens.

The CAN stacks will wait until the actions are executed.

OnReceiveTimeOut

This event is triggered if a receive mapping is not received within the period defined as "Transmission Period". If this happens all the variables mapped to the PGN are automatically considered invalid and additionally the action is executed.

If you should see any "Event Options" for this event - ignore them like the PClient does.

Possible actions that can be assigned are

•"No Action" which is the default

•"Set Value" to assign a constant value to a variable, e.g. to reset a counter, raise an alarm or trigger something attached to a variable where "Force Writing" is true.

•"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 timeout.

OnReceiveTimeOutResolved

This event is triggered if a receive mapping which time out before is received again. If this happens all the variables mapped to the PGN are automatically considered valid again (assuming the PGN received really contained a value for them) and additionally the action is executed.

If you should see any "Event Options" for this event - ignore them like the PClient does.

Possible actions that can be assigned are

•"No Action" which is the default

•"Set Value" to assign a constant value to a variable, e.g. to reset a counter, raise an alarm or trigger something attached to a variable where "Force Writing" is true.

•"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 timeout.

OnMappingReceived

The action for this event is executed EVERY TIME the mapping is received (regardles of value changes).

When a script action is executed, the variables used in the mapping will already have been updated with the values from the CAN message.

Do NOT execute complex scripts at this event if the mapping is received very often!

Monitor the performance on the device with a realistic cycle time of all CAN messages.

Monitor the cycle time of transmit messages (the CAN stack has to wait until the received action is over before taking care of other tasks like sending out transmit mappings).

If you should see any "Event Options" for this event - ignore them like the PClient does.

Possible actions that can be assigned are

•"No Action" which is the default

•"Set Value" to assign a constant value to a variable, e.g. to reset a counter, raise an alarm or trigger something attached to a variable where "Force Writing" is true.

•"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 timeout.

The following settings can be made for each variable added to the mapping:

Byte Bit Position

Position is shown as byte#:bit# where byte 1 is the byte closest to the CAN identifier and bit 1 is the least significant bit of a byte. I.e. full CAN message starts with byte 1 directly behind the CAN ID and ends with byte 8. In a byte with value 1 bit 1 is set, in a byte with value 128 bit 8 is set.

These enumeration scheme matches the one used in J1939 standard documents so that you can directly copy the position. Engine coolant temperature is defined as the first byte - so set start position to 1:1.

Alternatively one can type the bit position directly: 1 refers to the bit closest to the CAN identifier and 64 is the bit at the end of the CAN message.

Warning: This input does not always behave as expected when typing position by hand. Finally the displayed "byte:bit" value is relevant.

The mapping is filled correctly if there are no gaps i.e. the whole message gets filled with values.

Please refer to the following image for byte and bit enumeration within a CAN message. This enumeration is valid for little and big endian variables since it only refers to the CAN message itself.

Length

Defines the size of the mapped numeric variable or constant in bits. If a string is mapped this defines the length of the string in bytes.

Mapped length can be shorter than the length defined for the variable but not longer. By default the variable length is used.

Is Constant

Enable this checkbox to define a constant. Depending on the mask constants can be used to fill gaps or recognize multiplexers in receive mappings. In transmit mappings constants are required for every part of the message not filled with a variable.

Uncheck this property to map a variable.

Constant Value

Although appearance does not change this property is only valid and editable for constants i.e. lines where "Is Constant" property is set.

If valid this defines the numeric value of the constant. Please note that constants are always expected to be numeric - there is no option to define string constants.

Group

Variable group containing the variable to be mapped. Does not apply to constants.

Variable

The variable to be mapped.

Mask

Variable or constant are bitwise ANDed with mask before they are applied.

See receive condition on how this can be used to receive multiplexed mappings.

See section mapping calculations for details about how this property applies to receive and transmit mappings.

Mask is not used for String variables.

Offset1

Offset1 is a floating point value applied to the received value after mask and shift factor but before scale and offset 2.

See section mapping calculations for details about how this property applies to receive and transmit mappings.

Offset 1 is not used for String variables.

Values can be entered in decimal form or in scientific notation / floating-point representation.

Shift X Bits

Shift received value to the right by as many bits as defined here. Negative values shift to the left.

This value is applied after the mask but before offset and scale.

See section mapping calculations for details about how this property applies to receive and transmit mappings.

Shift is not used for String variables.

Scale

Floating point value to scale the received value before applying it to the mapped variable. Is applied after mask, shift and offset 1 but before offset 2.

Scale is not used for String variables.

Values can be entered in decimal form or in scientific notation / floating-point representation.

Offset2

Floating point value applied after all the other calculations are done.

See section mapping calculations for details about how this property applies to receive and transmit mappings.

Offset2 is not used for String variables.

Values can be entered in decimal form or in scientific notation / floating-point representation.

Empty Field

This a simple information field. It shows a "Warning" icon if e.g  a variable is not completely mapped.

In the example(4) a 16 bit variable is mapped only with 8 bits, so the warning is shown.

The calculations applied to a mapping are defined mainly for receive mappings

For transmit mappings all calculations are inverted so that the same values can be applied to receive and transmit mappings.

The formula converting a mapped area of a CAN message into the variable value is as follows:

     variable_value = (((( CAN_value >> shift ) & mask ) + offset1 ) * scale ) + offset2

Consequently the calculation applied to transmit mappings inverts the above:

   CAN_value = (((( variable_value - offset2 ) / scale ) - offset1 ) & mask ) << shift

Note: For constants only "shift" and "mask" are applied.

Note: Currently signed/unsigned calculation is performed based on variable definition. If variable is signed this means the CAN_value is considered negative if the most significant bit of the mapped area is set.