UPT Programming Tool : CAN-Simulator

Contents

1. CAN Message Generator / Bus-Simulator
   
   1. Introduction
   2. Extracting CAN signal definitions from UPT variables
      1. Treatment of UPT variables flagged as 'TX' (Transmit from the simulated device's point of view)
   3. The option 'Inject values into simulation'
   4. The option 'Send on real CAN bus'
   5. CAN signal definition table
      
      1. Signal stimulus (expression to 'feed' into the current value)
      2. Transmit cycle (interval for periodically transmitted signals)
      3. Parameters to map a signal into its container (e.g. CAN message)
   6. The CAN Simulator's "Update Interval"
   7. Automation / Programmable test sequences
      
      1. Conditional Action table (with columns "IF.." and "THEN..")
         
         1. 'select'..'case'..'endselect'-blocks in the Conditional Action table
      2. Special interpreter functions for the CAN Simulator
         1. Check for CAN reception via can_rx(<ID> <data field>)
      3. Special interpreter commands for the CAN Simulator
         
         1. Access CAN signals / internal variables / timers
            
         2. Details about command-driven signal transmission
         3. Command-driven signal transmit timing
         4. Transmission of multiplexed messages
         5. Direct transmission / "injection" of CAN messages via can_tx(<ID> <data field>)
      4. Breakpoints and single-stepping through the Conditional Actions
      5. Programmable Buttons (on the 'Automation' tab)
      6. Text Console (text screen showing output from 'csim.print')
      7. Options to synchronize display application and CAN Simulator
   
   
2. Hints about the CAN Message Generator usage (for advanced users)

CAN Message Generator / Bus-Simulator

Introduction

'CAN-Simulator' screenshot (part of the UPT programming tool)
with tabsheet for the CAN signal definition table and 'value slider'.

The CAN message generator can do the opposite: Using the information that you have imported from a CAN database, it can assemble CAN messages that it can play "into the display simulator".
If the PC is connected to a suitable CAN bus interface, it can even send those messages to a real hardware.

Extracting CAN signal definitions from UPT variables

1. Open the CAN Simulator window: From the tool's main menu, select Tools .. CAN Message Generator / Bus-Simulator
2. There: Add signal .. Copy ALL signals from UPT display variables
3. Check option Inject values into simulation, and if you promise to be careful, Send on 'real' CAN bus
   
4. Click into the table on the signal you want to 'simulate' (or send), to select the row
5. Use the vertical slider (that is now connected to the selected signal) to modify the value

Treatment of UPT variables flagged as 'TX' (Transmit from the simulated device's point of view)

• Only CAN-signals that will be RECEIVED by the UPT (through a UPT display variable connected to a CAN-"Receive"-message)
  will be flagged for TRANSMISSION in the CAN message generator / bus simulator;
  
• CAN-signals that will be TRANSMITTED by the UPT (through a UPT display variable connected to a CAN-"Transmit"-message)
  will be flagged for RECEIVE-ONLY in the CAN message generator / bus simulator,
  and will be marked as "RX" (short for 'Receive-Only') in colum "TX cyle".

(*) If two CAN nodes simultaneously try to send a message with the same ID, the result is an 'identifier collision' aka 'priority collision' during the bus arbitration phase.
Both nodes "think" the bus is free for their transmission, because both nodes successfully send the same ID during the arbitration phase (by chance, simultaneously).
But after the arbitration phase, the data fields (with different content) collide, causing checksum errors, error frames, and thus no acknowledge from any node in the entire network.
Due to the automatic CAN retransmission, the collisions may repeat multiple times.

The option 'Inject values into simulation'

By default, the option Inject values into simulation is set. This causes the signal values modified via slider or stimulus (numeric expression) will enter the simulation within the programming tool, as a replacement for CAN messages received from the CAN-Bus.
In many cases, this option is already sufficient to test and develop an application on the PC ("run it inside the PC"). Unlike option 'Send on real CAN bus', it doesn't affect any external devices connected to the PC. Furthermore, it can be used without a CAN-bus interface on the PC.

The option 'Send on real CAN bus'

The option Send on real CAN bus should only be used if the PC (with the programming tool) is directly conntected to the MKT View (or similar DUT, 'device under test') with a suitable CAN-bus interface, and no other active CAN nodes are connected to the same network. In this case, the programming tool sends those messages, which the DUT expects to receive from a vehicle's control unit or similar. If both (CAN-simulator and vehicle) were connected simulaneously, this would cause severe collisions on the bus which must be avoided under any circumstance. If multiple nodes send CAN frames with the same message identifiers, there will be unresolvable conflicts during the bus arbitration phase, which sooner or later may cause one of the sending nodes to enter 'Bus-Off' state, i.e. it stops sending. You don't want to experience this in a vehicle while driving !
The 'Send on real CAN' option also controls the behaviour of the simulator command can_tx() as explained here (footnote for can_tx).

See also: Recording and playing back messages via 'CAN-Snooper',
        Playing back recorded CAN-traffic in the simulator,
        The PC's CAN bus interface.

CAN signal definition table

As mentioned in the introduction, signal definitions for the CAN simulator are usually extracted from the application's variable definitions, or from the CAN database (if still available).
Alternatively, signal definitions can also be entered manually in a definition table.

Signal definitions table for the CAN simulator. As usual,
column widths can be adjusted via mouse in the table header.
When selecting a cell, its full text is shown below the table.

Name

Usually copied from the variable definitions table as explained here.

Hint about signal names:

You can launch a global search for all display variables in the currently loaded application through the signal definition table's context menu. Right-click on the name in the grid to open the context menu, then select 'Global search for XYZ' (where XYZ is the clicked name). This does not only search the name in the CAN simulation, but also on all display pages, event definitions, etc, of the loaded application.

Expression (Stimulus)

Optional 'generator function'. If present (non-empty string), this numeric expression will be periodically evaluated by the display-interpreter (interval adjustable on the right side). The result will be copied into the Current Value, from where it can be mapped into a CAN message.
A double click into an empty cell in this column generates an expression for a low-frequency sinewave. Each signal will have a slightly different frequency, and the amplitude will be scaled for the signal's MinValue and MaxValue. To repeat this for all signals defined in the table, select 'More..' (button), and menu item 'Generate Stimuli for ALL signals'. Thus, with very little effort, the simulator can generate ever-changing "dummy values" for the CAN signals. Example:
isin(tsim_ms) / 4   creates a sine wave
                with amplitude 32767/4 = ca. 8191,
                period = 1024 milliseconds, i.e. frequency about 1 Hz,
                with the first rising zero-crossing
                at the start of the CAN-simulation.
(Explanation: The interpreter function tsim_ms delivers the elapsed time, in milliseconds, since the start of the CAN signal simulation ("Run"-button) as an integer value. The older function ti_ms (which, unlike tsim_ms, is also available in the device firmware) delivers the number of milliseconds elapsed since the display application was launched, or a "simulated target reset" was issued through the tool's main menu. The isin function expects an argument range of 0..1023 for a full 360° sine wave cycle, and delivers an output value range of -32767 to +32767.)

Note:

A stimulus may be disabled via command. In that case, the definition cell will be marked as 'temporarily disabled' with a transparent cross as explained in chapter 'Automation'.

Current Value

The signal's current physical value. Can be modified via vertical slider on the right side, or by entering a suitable stimulus under 'Expression'.
Even without a stimulus, the Current Value may be generated via command (csim.<SigName>) on the Automation tab.
See also: Signal value stimulus vs. signal value set via command.

TX cycle (ms)

Transmit cycle for this signal in milliseconds.
Without a cycle (0 ms), a signal will be transmitted immediately after being modified via slider, stimulus, or command (csim.<SigName>), i.e. "event-driven". This can cause a huge bus load if many values are modified at the same time (in a single update cycle) !
Via menu item More ... / Set transmit intervals for all signals, you can activate the periodic transmission of all signals contained in the table with just two mouse-clicks. For all signals that don't have a transmit-cycle yet, the time (in milliseconds) will be copied from the edit field in the right half of the window.
CAN signals that have been imported from "to-be-TRANSMITTED" UPT variables will be marked for RECEPTION ("(RX)") in this column, to avoid CAN message ID collisions as explained here.

Message ID

Hexadecimal CAN message identifier with prefix '0x'. Three digits for "standard-IDs" (11 Bit), eight digits for "extended IDs" (29 bit).

Bus

Only for systems with two or even more physical CAN interfaces.
So far, only tested with multi-channel Kvaser interfaces like 'Kvaser Hybrid 2xCAN/LIN'.
Bus 1 transmits into the first CAN interface ("CAN1" on the MKT cable, "Ch.1" on the Kvaser interface), etc.

LSB pos

Position of the signal's least significant bit within the CAN data field (0..63 for "classic" CAN).

Num bits

Number of data bits occupied by the 'raw' CAN signal (within the CAN data field, max. 64 bits for "classic" CAN).

Byte order

For historic reasons, 'M'="Motorola" (most significant byte first) or 'I'="Intel" (least significant byte first) ... the annoyance known as 'endianness'.

Data Type

U=unsigned integer, S=signed integer, F=single precision float, D=double precision float.
Type of the 'raw' value, inside the CAN data field (usually integer; float or double as 'raw signal type' is quite rare).

Factor

Multiplier for converting the 'raw' CAN value into the physical 'display' value.

Offset

Will be added when converting the 'raw' CAN value into the physical 'display' value:
  Physical value (e.g. Oil Pressure in Bar) = raw_value * Factor + Offset

MinValue, MaxValue

Possible range for the physical value. In the CAN-simulator, used to scale the 'vertical slider' position into a new physical value: Top = maximum, bottom = minimum.

Multiplexer

Definition of an optional signal multiplexer, used to squeze more signals into a CAN message than permitted by the 64-bit data field (for 'classic' CAN).
Details and format (syntax) as explained here.
Since 02/2021, the CAN simulator may indicate a problem ("red cross") if there is a stimulus (expression) defined for a MULTIPLEXER SIGNAL (not just a multiPLEXED signal):

Illegally defined stimulus ("Expression") for a Multiplexer Signal.

In this case, the error indicator (red cross) would disappear by clearing the stimulus.
See also: Peculiarities with the transmission of multiplexed CAN messages.

Steps to quickly fill the 'signal definition table' from a loaded UPT display application

The CAN Simulator's "Update Interval"

Automation / Programmable test sequences

In many cases, the cyclic transmission / simulation of CAN signals is sufficient to replace signals from a real network (CAN, etc).
In a few advanced test cases, the CAN simulator additionally has a kind of 'programmable' control itself, quite similar to the programmable 'Event-Definitions' in the UPT display application.
The basic principle is:

• You define certain "events" (conditions) in a table, and tell the program what to do if such an event occurs (actions).
  (this is quite similar to the "IF"..."THEN"-statement which you may know from some programming language).
• The table with these IF's and THEN's is periodically evaluated, for example every 100 milliseconds (adjustable via the "Update Interval" in the non-tabbed part of the CAN simulator window).
  
• The IF-column (event,condition) in the table of conditional actions can be any numeric expression, or the call of an interpreter function which returns a numeric or boolean value. Any non-zero value is treated like the boolean value TRUE. They are evaluated by the built-in interpreter.
   Example: tsim > 10
  (the result of this expression is TRUE if the CAN-simulation has been running for 10 seconds or more)
  
• The THEN-column (action) in the table can be one or more interpreter commands, separated by colons.
  Example: timer0.start(5) : capture : REM capture the screen as a file when the 1750 Hz tone is detected

Conditional Action table

The "Conditional Actions" are displayed in a table (string grid) on the 'Automation' tab.
The function is similar to display application's event definitions. Inspired by PLCs (programmable logic controllers), all lines of this simplistic 'program' are executed once per update cycle.
The definition table for Conditional Actions may look like this:

'Conditional Actions' for the CAN simulator (loaded from programs/CANSim_for_SignalMultiplexerTest.csv)

If a cell in the "IF.." column (condition) delivers a nonzero value (logical "TRUE") when being evaluated by the interpreter, then the cell in the same row under the "THEN.." (action) is executed as a command line.
Both conditions and actions are evaluated/executed by the same interpreter that is also used for the programmable display application. To use this interpreter for the CAN simulator without interfering with the display application, it has been extended with a few simulator-specific functions and commandss that will be presented later in this document. For example, the CAN simulator's "interpreter stub" (invoked on module prefix csim) allows accessing the simulator's timebase (tsim), extra timers (csim.t0 .. t9), extra variables (csim.var.<VarName>), and so on.

All conditions that are momentarily TRUE will be marked with a green background in the corresponding cells (in the "IF"-column). If an error occurrs when evaluating a condition or action, the cell will have a red background, and the status line (below the table) will show details about the error. A yellow background in the first column (with the line numbers) means 'a breakpoint in this line has fired, and paused the execution' or 'this line is the next, waiting for execution in single-step mode'.
More about breakpoints and single-stepping follows in a later chapter.
The entire Conditional Actions ("CA") table is evaluated / executed in a single over (unless debugging in 'single step' mode).
The CA table is used to implement state machines. It is not a replacement for a full-grown scripting language. Typical use cases are:

• Generate 'special' signal values that would be too difficult for a single-line stimulus
  (use csim.<SigName> for that purpose)
• Implement a test schedule ('Fahrplan'), using tsim, tsim_sec, or one of the CAN simulator's extra timers to control transmitted values

'select'..'case'..'endselect'-blocks in the Conditional Action table

• select( <selectValue> )
  Stores the value in an internal buffer, from where it will be compared with all 'case' values in all lines until the matching endselect.
  
• case <caseValue> :
  Lets the "program" execute the current line, and lines with an empty condition that follow immediately, if the case-value equals the value stored internally by select ('<selectValue>').
  The colon after the case-value is optional.
  
• case <fromValue> to <toValue> :
  Almost the same as the 'simple case', but compares the value stored by select against an entire range of values. As a condition, evaluates to TRUE if selectValue (the value stored by select) is larger or equal to fromValue, and less or equal toValue.
  
• default :
  Lets the "program" execute the current line, and lines with an empty condition that follow immediately, if the select-Value (the value stored by select) matches none of the case-values or case..to-ranges between the lines with the 'select' and the 'default:'. Like the colon after 'case' values, the colon after the 'default'-label is optional.
  
• endselect
  Ends a block with 'select', 'case', and optional 'default' labels. After a matching 'case' or executing the instructions after a 'default', of if the select-value doesn't match any 'case' and there's no 'default' at all, the program jumps into the line after the 'endselect'.
  

Special interpreter functions for the CAN Simulator

In many cases, the 'Conditions' (events) will be simple comparisons as shown in the previous chapter (e.g. tsim > 10).
The following special interpreter functions have been implemented especially for the IF-column (condition, event) in the CA table:

• initialising
  This flag is TRUE (one) once when initialising the program, or after loading a new configuration from a *.csv file. It is typically used to set variables to their initial values.
  
• always
  is simply ALWAYS true. The action (command line) in this row will be executed in every update cycle.
  
• never
  is the counterpart to the 'always'-event - it is just 'never' true (boolean 'false', or numeric value zero). You may as well enter a zero in the IF'-column of the conditional actions, but 'never' is a bit more descriptive. As strange as it seems, the 'never'-event is not completely useless: It can be used to add comments in the table, to describe (in a single line) what the following part of the program is supposed to do. The action for such a line typically begins with the interpreter command REM (remark) or (C++ style) with a double forward slash.
  
• else
  Returns TRUE if the condition in the previous line was FALSE; and FALSE if the condition in the previous line was TRUE. Use this to do "something" in a certain line #N, and do "something else" in line #N+1 if the condition in line N is not true. See the examples at the end of this chapter.
  Note: If there is no condition in a certain line of the CA table (empty "IF.."-cell), the 'empty' condition cell evaluates to TRUE if the condition in the previous line was TRUE; and FALSE if the condition in the previous line was also FALSE.
  
• sometimes
  Congratulations, you read the documentation carefully enough to spot this easter egg. Guess how often this function returns TRUE when used as a condition.
  
• csim.tsim,   tsim
  Returns the current 'CAN simulation time' as a floating point value in seconds.
  For read-access, the module prefix "csim." can be omitted.
  This timer starts at zero when clicking the 'Run'-buttons, and is often used to compute 'running' signal values, e.g.
  csim.sig.DrivenPath_km := tsim * (50.0/3.6) // driving at 50 km/h
  For special cases (e.g. to simulate a 'time warp'), csim.tsim can be set to any value via assignment.
  
• csim.t0 .. t9
  Checks if one of the CAN simulator's ten user timers is expired or has reached the end of a period, after being started via csim.ts ("timer start"). A full example showing how to start and poll these timers can be found here.
  There are similar timers in the interpreter 'outside' the CAN simulator (t0 .. t3), but to avoid interference with the display application, only use the CAN simulator's timers in the CA table.
  
• csim.tv0 .. tv9
  Reads the current timer value of a CAN-simulator timer. The time starts at zero [seconds] when a timer was started (e.g. csim.ts0(12.3)), and runs up to the timer's period (in this example, 12.3 seconds). At that time, a single-shot timer would stop, and a periodic timer would wrap around from the period time to zero. Thus, for periodic timers, csim.tv generates a sawtooth function.
  
• select, case, default, endselect : Explained in another chapter.
  

Reminder: A function returns a value to the caller, and thus can be used as part of a numeric expression or, in this context, a condition. A command (or procedure) as listed in the next chapter does not, and thus cannot be used as part of an expression. But a command may be part of ..err.. a command line or, in this context, an action.

Check for CAN reception via can_rx(<ID> <data field>)

can_rx( 0x123 00 11 22 33 44 55 66 77 )
   checks if since the last call from the same line in the 'conditional actions',
   a CAN message with hexadecimal message identifier 0x123,
   and an eight-byte data field 00 11 22 33 44 55 66 77 
   has been received.

can_rx( 0x123 FF xx xx )
   checks if since the last call (.. see above ..), a CAN message
   with a three-byte datafield, with the first data byte containing 0xFF,
   has been received (with xx = "don't care" for the 2nd and 3rd byte).

Special interpreter commands for the CAN Simulator

• csim.stop
  Stops the periodic evaluation of the 'Conditional Actions' and the transmission of CAN messages assembled from signals defined on the CAN simulator's signal definition table.
  
  
• csim.<SigName>   or   csim.sig.<SigName>
  Allows read- and write access to the Current Value with a matching (signal- or variable-)name in the signal definition table.
  Example (where "ThreeSines1" is the name of a signal or variable):
  

  Nr	IF.. (Condition)	THEN.. (Action)
  1	tsim < 10	csim.ThreeSines1 := tsim

  Even if there was a stimulus for signal "ThreeSines1" delivering a sinewave, the example generates a rising 'ramp' for the signal during the first 10 seconds. As long as the Current Value is set via interpreter command, it will not be taken from the stimulus in the same update cycle. As soon as a signal is not set via command in the CA table anymore, its 'value' will be taken from the stimulus again (unless the stimulus was disabled via command).
  
  If the signal name collides with one of the keywords or components after "csim.", the collision can be resolved by using csim.sig.<Signal-Name>.value instead of just csim.<Signal-Name> .
  

  Note:

  In many cases, the simulator's CAN signal table has been extracted from a display variables (details here). Since the simulator uses the same interpreter as the display application itself, the interpreter (invoked from the 'Conditional Actions' to evaluate conditions or execute actions) can access both
  - the display variable fed from the 'decoded' received signal,
  and the CAN simulator signal from which the value was sent.
  Thus, the CA table can also compare the 'transmitted' signal value with the 'received' signal on the other end (mapped into a UPT display variable).

  See also: Details about command-driven signal transmission, csim.sig.<SigName>.tx_flag ("forced" transmission even if the value didn't change and there's no periodic transmission).
  
  
• csim.<VarName>   or   csim.var.<VarName>
  Allows read- and write access to a user-defined variable within the CAN simulator. In contrast to signals, these variables are not mapped into CAN messages, PDUs, etc, so they don't "communicate" directly with a network. These variables simply begin to exist by assigning a value to them (no extra declaration required). The first assignment usually happens in the CAN simulator's Conditional Actions table in one or multiple lines with condition = initialising, which is where all simulator-internal variables (not CAN signals) should be initialized. See the 'timer'-example further below.
  If the variable name (<VarName>) doesn't clash with signal names or other 'csim.'-commands/functions, you can use the short form (csim.<VarName> instead of csim.var.<VarName>).
  
  
• csim.btn[N].caption   (with N = 0..2 for three buttons)
  Reads or writes the 'Caption' (text) shown on one of the three programmable buttons.
  As usual (in "C"), the array index in squared brackets is zero-based.
  
  
• csim.ts0(<interval in seconds>) .. csim.ts9(..)
  Starts one of the ten CAN simulator timers for a given time in seconds in single shot mode (not periodic).
  After the interval expires, the matching function csim.t0 .. t9 will return TRUE, until your CAN simulator script resets the 'expired'-flag via csim.tr0 .. tr9.
  If an already running single-shot timer is restarted (same start command issued twice) before it expired, the full interval starts again (note the difference to periodic timers which won't restart). That way, a single-shot timer can be used as a watchdog: As long as it is re-started frequently, it's timer event (e.g. csim.t0) will not fire.
  
  
• csim.ts0(period,pulse-time) .. csim.ts9(..)
  Starts one of the ten CAN simulator timers for a given time in seconds in periodic mode (aka 'pulse generator').
  Every period begins with the 'pulse low time', and ends with the 'pulse high time'. The timer-event polling function, csim.t0 .. t9 will return TRUE only ONCE in a period, approximately <pulse-time> seconds before the end of a full period (at the pulse's low-to-high transition).
  If an already running periodic timer is restarted with the same parameters (same start-command issued twice), it simply keeps running without causing a phase glitch (note the difference to single-shot timers which really would restart).
  Example demonstrating the use of timers, signals, and variables:

  Nr	IF.. (Condition)	THEN.. (Action)
  1	initialising	csim.var.MyCounter := 0
  2	tsim > 10	csim.ts0( 1.5, 0.5 )
  3	csim.t0	csim.var.MyCounter++ : REM increment
  4	csim.t0.running	csim.sig.EngineRPM.value := csim.t0.value

  Line 2 starts the CAN-simulator's first user-timer in periodic mode, with a period of 1.5 seconds, and a pulse-high-time of 0.5 seconds during each period, beginning 10 seconds after starting the CAN simulation.
  

  Line 3 polls (and "consumes") events from the first timer, and increments a self-defined simulator variable ("MyCounter") in each timer period.
  

  Line 4 copies the "value" of a timer itself (counting up in seconds) into one of the signals (defined on the tab), but only if that timer is currently running.
  This generates a ramp function beginning at zero when the timer was started, regardless of the stimulus for that signal.
  

  Notes:

  If period- or pulse times are shorter than the CAN simulator's adjustable update interval, you may miss events from that timer in the CA table, and the counter used in the above example ("MyCounter") won't increment as fast as it should.
  
  The post-increment (++) and post-decrement (--) operators may appear familiar from "C", but here they are only available for variables and signals inside the CAN simulator. They only work in command lines (where values are writeable), but not in numeric expressions (where everything is read-only).
  

• csim.tr0 .. tr9
  Resets the specified timer's 'expired' flags. Typically invoked from the Conditional Actions after a certain timer has expired, possibly and-combined with other conditions, e.g.

  Nr	IF.. (Condition)	THEN.. (Action)
  1	initialising	csim.var.IgnitionKeyTurned := 0
  2	csim.var.IgnitionKeyTurned	csim.ts3( 20.0 ) : ... // try to start engine
  3	csim.t3 && (csim.sig.EngineRPM>500)	csim.tr3 // engine running for at least 20 seconds ?
  4	csim.t3 && (csim.sig.EngineRPM<500)	csim.tr3 // engine refused to start within 20 seconds ?

• csim.print(value1,value2,...)
  Prints a list of values into the 'text log' on the simulator's "Automation" tab (above the conditional action table).
  Values may be integer, floating point, strings, or expressions generating any of these types. Numeric values are printed as decimal strings.
  If values are separated by comma, a space character is emitted as a separator instead.
  If values are separated by semicolon, no space character is emitted.
  Example:
  csim.print("Peak brake pressure:",csim.var.MaxPressure,"bar")
  The 'print' command can optionally modify the colours used on the text console. If the first function argument is a colour, it's the text colour (aka foreground colour). If the second argument is also one of the colour names listed here, then the 2nd argument defines the background colour. Examples:
  
  csim.print(clRed, "No response from device under test !")
csim.print(clWhite, clGreen, "Test finished, no errors.")
  Per default (with no colours specified), text is printed 'black on white' into the console window.
  Like 'writeln' (write line) in Pascal, csim.print appends a Carriage Return and New Line character after the text, to enter the next line for the next call.
• csim.write(value1,value2,...)
  Almost identical to csim.print, but 'write' does not automatically wrap to the next line after the 'printed' text. Thus, subsequent calls of csim.write can write into a single line.
• csim.tscreen.xyz
  Special commands to control the 'text screen' / Text Console.
  

Accessing CAN signals, internal variables, and 'programmable' timers

Details about command-driven signal transmission

Command-driven signal transmit timing

• In your Conditional Actions, set the signal value itself, e.g.:
    csim.sig.EngineRPM.value := 2300
  
• In your Conditional Actions, also set the signal's "transmit flag" via command, e.g.:
    csim.sig.EngineRPM.tx_flag := 1
  

Transmission of multiplexed messages

• If the CAN message (aka CAN frame with a certain message-ID) contains non-multiplexed ("normal") signals besides multiplexed signals, those non-multiplexed signals may be sent more often than intended. For example, assume "NonMuxedSignal" is a non-multiplexed signal that you want to send only once per second, and "MuxedSignal1" and "MuxedSignal2" are multiplexed signal (mapped into the same CAN message), periodically sent every 100 milliseconds. It is technically impossible to send a message without the non-multiplexed signal. Thus, whenever sending a message with "MuxedSignal1" or "MuxedSignal2", the current value of "NonMuxedSignal" will also be contained in the message frame. The actual transmit period of "NonMuxedSignal" will be 100 instead of the intended (configured) 1000 milliseconds.
  
• If a CAN message contains multiplexed signals (plural) with different multiplexer values, and more than one of these signals are "waiting for transmission" (tx_flag set via command or automatically), the CAN simulator will send multiple CAN messages with the same message-ID but different multiplexer value within fractions of a millisecond (if CAN bitrate and CAN driver permits).
  This may cause a problem in certain receivers, most noteably in small microcontrollers without a sufficiently large hardware- or interrupt-driven receive buffer.
  

Direct transmission / "injection" of CAN messages via can_tx(<ID> <data field>)

can_tx( 0x123 00 11 22 33 44 55 66 77 )
    "Sends"(*) a CAN message with the hexadecimal 11-bit ID 0x123,
    and the hexadecimal 8-byte data field 00 11 22 33 44 55 66 77,
    or (if the option 'Send on reak CAN bus' isn't set)
    only injects this message into the device simulation that currently runs in the programming tool
    (to replace a message transmitted from an ECU or similar external device).

can_tx( 0xABCDEF.x 01 02 03 04 05 06 )
    "Sends"(*) a CAN message with 29-Bit message ID 0x00ABCDEF (.x = "Extended"),
    and the specified data field (also hexadecimal per default).

Breakpoints and single-stepping through the Conditional Actions

Programmable Buttons (on the CAN simulator's "Automation" tab)

Screenshot of the CAN simulator's "Programmable Button" context menu

Text Console (text screen showing output from 'csim.print')

Screenshot of the CAN simulator's 'Text Console'
with deliberately exaggerated use of colours.

• "\r" : Carriage Return (ASCII #13). Sets the text output cursor to the begin of the current line, e.g. does not enter a new line.
  This control character can be used to update text in the current line, without adding new lines on the console. Example to overwrite the text in the current line (may be invoked multiple times):
  
    csim.write("\rWaiting for transfer..",csim.var.ProgressPercent,"%")
• "\n" : New Line (ASCII #10). Sets the text output cursor into the begin of the next line. For historic reasons, sometimes appended after the Carriage Return character.
  
  
• "<b>Bold Text</b>",
  
• "<i>Italic Text</i>",
  
• "<u>Unterlined Text</u>":
  HTML-like start- and end-tags to emit bold, italic, and/or underlined text. Similar as in the display interpreter's format string (and in contrast to 'real' HTML), these sequences may be used in any combination or sequence (HTML requires carefully balanced start- and end-tags; we don't).
  

Options to synchronize display application and CAN Simulator

• RUN-button not only starts/resumes the CAN simulator, but also the display application:
  This option also applies to applies to resuming the display application, after e.g. being paused when hitting a breakpoint in the script. In this case, 'RUN' doesn't perform a restart/reset, but continues execution of both (display application and CAN simulation) exactly at the points where they had been paused before.
  
• STOP-button not only pauses the CAN simulator, but also the display application:
  Allows temporarily pausing both, the CAN simulator as well as the display application (running in the programming tool's device simulator), almost simultaneously.
• Breakpoints in the display application also stop the CAN simulator:
  If this option is set (checked in the menu), the CAN simulation (including the periodic evaluation of Conditional Actions) will pause immediately when the user application (running in the programming tool's device simulator) hits a breakpoint. For example, when debugging a script, you may have set a breakpoint in a CAN-Receive-Handler in a script. If the CAN simulator wouldn't stop when hitting that breakpoint, it would keep sending CAN frames 'into the blue', and the CAN RX handler wouldn't have a chance to process them.
  

Hints about the CAN Message Generator usage (for advanced users)