:html
:revision=16
<<
128.160
CAN-Object|CAN
$NoSort
--
The IP-Object CAN ...
>>

<<
128.160.1
Coding of a CAN Frame|CAN Frame
--
<h4>Normal frame</h4>
(not a RTR frame)
<!STBL>
<!+>Index<!+>Content / Value<!>
<!c>1<!>Frame-ID   (0..2<sup>29</sup>-1)<!>
<!c>2<!>Type 0=normal frame<!>
<!c>3<br>..<br>10<!>0 to 8 data bytes<br>if existing<br>(0..255)<!>
<!ETBL>

Length of the vector : 2..10, depending on the number of data bytes (0..8).

The <!SW>DLC (DataLengthCode) of the CAN frame results from the number of data bytes and is calculated by the interpreter.

If the frame should use a 29 bit identifier, the ID has to be ored with <!CW>$80000000. This will happen automatically when the identifier is bigger than 2047.

<h4>RTR-Frame</h4>
<!STBL>
<!+>Index<!+>Content / Value<!>
<!c>1<!>Frame-ID   (0..2<sup>29</sup>-1)<!>
<!c>2<!>Type 1=RTR-Frame<!>
<!c>3<!>DLC (0..8)<!>
<!ETBL>

The content of the <!SW>DLC (DataLengthCode) of the CAN frame is given directly, since a RTR-Frame does not contain any data bytes.

If the frame should use a 29 bit identifier, the ID has to be ored with <!CW>$80000000. This will happen automatically when the identifier is bigger than 2047.

<h4>Error-Frame</h4>
<!STBL>
<!+>Index<!+>Content / Value<!>
<!c>1<!>Frame-ID   (0..2<sup>29</sup>-1)<!>
<!c>2<!>Type 2=ErrorFrame<!>
<!c>3<!>Flags<!>
<!c>4<br>..<br>11<!>0 to 8 data bytes<br>if existing<br>(0..255)<!>
<!ETBL>

Known Error-Flags, taken from Vector documentation:
<!STBL>
<!>$01<!>Msg is a bus error<!>
<!>$02<!>Msgs following this has been lost<!>
<!>$04<!>NERR active during this msg<!>
<!>$08<!>Msg rcv'd in wakeup mode<!>
<!>$10<!>Msg is a remote frame<br><!REM>will not result in an error frame but in a RTR frame<!TXT><!>
<!>$20<!>Reserved for future usage<!>
<!>$40<!>TX acknowledge<!>
<!>$80<!>TX request<!>
<!ETBL>

An error frame can only be received, but not transmitted.
>>

<<
128.160.2
Functions of the CAN-Object|Functions
--
>>
<<
128.160.2.1
CAN.Error|Error
!128.160.4
--
<!DEF>
function <!TW>CAN.Error (sName : string) : real;
<!TXT>
Returns the result of the last action on the CAN channel <!PW>sName. (0=ok)
>>
<<
128.160.2.2
CAN.Received|Received
--
<!DEF>
function <!TW>CAN.Received (sName : string [; rID : real [; var rTimeStamp : real]) : vector;
<!TXT>
Gets the next frame from the receive buffer of the CAN channel <!PW>sName.

If <!PW>rID is specified, then it gets the next frame with this ID but the other frames remain in the buffer.

If there is no (matching) frame available, then the returned vector is empty.

If <!PW>rTimeStamp is specified, this variable will receive the time stamp of the frame.
>>
<<
128.160.2.3
CAN.IsActive|IsActive
--
<!DEF>
function <!TW>CAN.IsActive : real;
<!TXT>
Returns <!RW>TRUE, if the CAN system is activated globally.

<!DEF>
function <!TW>CAN.IsActive (sName : string) : real;
<!TXT>
Returns <!RW>TRUE, if CAN is activated globally and the CAN channel <!PW>sName is also active.
>>
<<
128.160.2.4
CAN.IsOpen|IsOpen
--
<!DEF>
function <!TW>CAN.IsOpen (sName : string) : real;
<!TXT>
Returns <!RW>TRUE, if the CAN channel <!PW>sName is open.
>>
<<
128.160.2.5
CAN.Check|Check
!128.160.1
--
<!DEF>
function <!TW>CAN.Check (vFrame, vTest : vector [; rMode : real]) : real;
<!TXT>
Compares the frame in the vector <!PW>vFrame with the frame in the vector <!PW>vTest.

 <!PW>vFrame may contain only values 0..255 (the bytes of the frame); the ID is an exception - it may contain values 0..2<sup>29</sup>-1.

 <!PW>vTest may contain values in the range -1..255; the ID is an exception - it may contain values -1..2<sup>29</sup>-1. -1=Don't care

 <!PW>rMode determines the behaviour in case of different lengths,
<!STBL>
<!+>lMode<!+>Result<!>
<!c>0<!>Length must be identical (default)<!>
<!c>1<!><!PW>vFrame may be shorter than vTest <!>
<!c>2<!><!PW>vFrame may be longer than <!PW>vTest, no test of the 'protruding' bytes<!>
<!c>3<!><!PW>vFrame may be longer or shorter<!>
<!ETBL>

Return value: 0 = everything OK, otherwise the position in <!PW>vFrame which is different.
>>
<<
128.160.2.6
CAN.FrameAvailable|FrameAvailable
--
<!DEF>
function <!TW>CAN.FrameAvailable (sName : string [; rID : real]) : real;
<!TXT>
Returns the number of frames which are in the receive buffer of the CAN channel <!PW>sName. 

If <!PW>rID is specified, then only those frames are counted which have this identifier.
>>
<<
128.160.2.7
CAN.HexToFrame|HexToFrame
!128.160.2.9
--
<!DEF>
function <!TW>CAN.HexToFrame (sHexFrame : string) : vector;
<!TXT>
Converts the CAN frame coded in the <!PW>sHexFrame String into a vector, which can be e.g. sent with <!RW>CAN.Send. 

 <!RW>CAN.HexToFrame is similar to the system function <!RW>HexToBVect. But  <!RW>CAN.HexToFrame allows the first element to be 4 byte long, this is necessary, because the identifier can be 29 bit long. I.e. if the first 8 characters in sHexFrame are valid Hex-figures, then they will be entirely converted into one value (the future identifier). If the identifier is represented with less characters, a separator (' ', ',' ...)  must be set between the identifier and the RTR-Flag.

Example:
<!CODE>
sHexFrame        results in vFrame
'1FFFFFFF 0 0A 0B 0C' ->    [536870912, 0, 10, 11, 12]
'1FF 0 0A0B0C'        ->    [511, 0, 10, 11, 12]
'01FF 00 0A 0B 0C'    ->    [511, 0, 10, 11, 12]
'01FF000A0B0C'        ->    [511, 0, 10, 11, 12]
'1FF00A0B0C'          ->    [535824907, 12]     !! Error in RTR and no data !!
<!TXT>

Application example:
<!CODE>
PARAMETER  
  psTriggerFrame : (10, string, 'CAN-Triggerframe (HEX)', '');
:
STEP
:
  Can.Send ('CAN-B', Can.HexToFrame (psTriggerFrame));
:
END.
<!TXT>

Suggestion for the notation of a CAN frame in the parameter field of the data base:
<!CODE>
'III R 1122334455667788'
 ||| | ||            ++-Datenbyte 8
 ||| | ++-Datenbyte 1
 ||| +-RTR-Bit
 +++-Identifier
<!TXT>

Thus a frame with maximum length (8 data byte) fits into 23 characters and can be converted with <!RW>CAN.HexToFrame.
>>

<<
128.160.2.8
CAN.Cyclic.Get|Cyclic.Get
--
<!DEF>
function <!TW>CAN.Cyclic.Get (sName : string; rID :real [; var rIntervall : real]) : vector;
<!TXT>

Looks up a frame from the cyclic send table of the CAN channel <!PW>sName. If a frame with the identifier <!PW>rID exists in the cyclic list, it will be returned as result. If no such frame exists, the function will return [].

If <!PW>rIntervall is specified, this variable will receive the intervall value of the cyclic sending. If no frame with the identifier exists, the variable will not be cahznged.
>>

<<
128.160.2.9
CAN.FrameToHex|FrameToHex
!128.160.2.7
--
<!DEF>
function <!TW>CAN.FrameToHex (vVectorDecimalFrame : vector) : string;
<!TXT>
Converts the CAN frame coded (number vector) <!PW>vVectorDecimalFrame into a String. An empty String or a '!' in a String shows a failure.
<!TXT>
Look after function <!PW>HexToFrame.
>>

<<
128.160.3
Procedures of the CAN-Object|Procedures
--
>>
<<
128.160.3.1
CAN.Open|Open
--
<!DEF>
procedure <!TW>CAN.Open (sName : string);
<!TXT>
Opens the CAN channel <!PW>sName.
>>
<<
128.160.3.2
CAN.Close|Close
--
<!DEF>
procedure <!TW>CAN.Close (sName : string);
<!TXT>
Closes the CAN channel <!PW>sName.
>>
<<
128.160.3.3
CAN.Filter|Filter
--
<!DEF>
procedure <!TW>CAN.Filter (sName : string; rCode, rMask : real [; rAs29Bit : real]);
<!TXT>
Sets the receive filter of the CAN channel <!PW>sName to the Acceptance-Code <!PW>rCode and the Acceptance-Mask <!PW>rMask. (both 0..2<sup>29</sup>-1)

If <!PW>rAs29Bit is not given or <!RW>FALSE, the length of the Mask and the Codes will be used to decide, wether the filter for 11Bit or 29Bit messages will be set.

If <!PW>rAs29Bit is given with <!RW>TRUE, the filter for the 29Bit messages will be set.

>>
<<
128.160.3.4
CAN.Send|Send
!128.160.1
--
<!DEF>
procedure <!TW>CAN.Send (sName : string; vFrame : vector);
<!TXT>
Sends the frame in the <!PW>vFrame vector on the CAN channel <!PW>sName.
>>
<<
128.160.3.5
CAN.Cyclic.Send|Cyclic.Send
--
<!DEF>
procedure <!TW>CAN.Cyclic.Send (sName : string; vFrame : vector; rInterval : real);
<!TXT>
Adds the frame in the <!PW>vFrame vector to the list of cyclic sent frames on the CAN channel <!PW>sName.

Only one frame per identifier is stored in the list. A new frame with the same identifier will replace an existing one.
>>
<<
128.160.3.6
CAN.Cyclic.Off|Cyclic.Off
--
<!DEF>
procedure <!TW>CAN.Cyclic.Off;
<!TXT>
Removes all the cyclic sent frames from the lists of all CAN channels.

<!DEF>
procedure <!TW>CAN.Cyclic.Off (sName : string);
<!TXT>
Removes all the cyclic sent frames from the list of the CAN channel <!PW>sName.

<!DEF>
procedure <!TW>CAN.Cyclic.Off (sName : string; rID : real);
<!TXT>
Removes the frame with the identifier <!PW>rID from the list of cyclic sent Frames of the CAN channel <!PW>sName.
>>
<<
128.160.3.7
CAN.ClearInBuffer|ClearInBuffer
--
<!DEF>
procedure <!TW>CAN.ClearInBuffer (sName : string);
<!TXT>
Deletes all the frames from the receive buffer of the CAN channel <!PW>sName.
>>
<<
128.160.3.8
CAN.Reset|Reset
--
<!DEF>
procedure <!TW>CAN.Reset [(rUnloadDLL : real)];
<!TXT>
Has the same effect to the CAN-System as the pressing of the <!SW>Reset button in the main window.

Not only the CAN-Controller(s) are reset; all the internal data structures, which are linked to the CAN-interface, will be broken down, deleted and reinitialized with the data from the basic setup.

Particularly:
<ol indent=18>
<li>All CAN channels are closed</li>
<li>Send-/receive buffers are deleted</li>
<li>Lists of cyclic frames are deleted</li>
<li>Values of the basic setup are set</li>
</ol>

If <!PW>rUnloadDLL is <!RW>TRUE, the DLL driver is also unloaded and reloaded.

<!RW>CAN.Reset without parameters has the same effect as <!PW>rUnloadDLL = <!RW>FALSE.
>>

<<
128.160.3.9
CAN.Transceiver|Transceiver
--
<!DEF>
procedure <!TW>CAN.Transceiver (sName : string; rTransceiver, rLineMode, rResNet : real);
<!TXT>
Selects the transceiver and the mode for the CAN channel <!PW>sName.

The following information is taken from the driver library of the CANCardX.

<!STBL>
<tr bgcolor=#e0e0e0><td colspan=3><b>rTransceiver : Transceivertyp</b><!>
<tr bgcolor=#e0e0e0 align=center><td><b>Value</b><!><b>Transceiver</b><!><b>Anmerkung</b><!>
<!c>0<!>TRANSCEIVER_TYPE_NONE</td><td rowspan=5><pre> </pre><!>
<!c>1<!>TRANSCEIVER_TYPE_251<!>
<!c>2<!>TRANSCEIVER_TYPE_252<!>
<!c>3<!>TRANSCEIVER_TYPE_DNOPTO<!>
<!c>4<!>TRANSCEIVER_TYPE_W210<!>
<!c>5<!>TRANSCEIVER_TYPE_SWC_PROTO<!>Prototype. Driver may latch-up.<!>
<!c>6<!>TRANSCEIVER_TYPE_SWC</td><td rowspan=5><pre> </pre><!>
<!c>7<!>TRANSCEIVER_TYPE_EVA<!>
<!c>8<!>TRANSCEIVER_TYPE_FIBER<!>
<!c>9<!>TRANSCEIVER_TYPE_K251<!>
<!c>10<!>TRANSCEIVER_TYPE_K<!>
<!c>11<!>TRANSCEIVER_TYPE_1054_OPTO<!>1054 with optical isolation<!>
<!c>12<!>TRANSCEIVER_TYPE_SWC_OPTO<!>SWC with optical isolation<!>
<!c>13<!>TRANSCEIVER_TYPE_B10011S<!>B10011S truck-and-trailer<!>
<!c>14<!>TRANSCEIVER_TYPE_1050<!>1050<!>
<!c>15<!>TRANSCEIVER_TYPE_1050_OPTO<!>1050 with optical isolation<!>
<!ETBL>

<!STBL>
<tr bgcolor=#e0e0e0><td colspan=3><b>rLineMode</b><!>
<tr bgcolor=#e0e0e0 align=center><td><b>Value</b><!><b>Line-Mode</b><!><b>Anmerkung</b><!>
<!c>0<!>TRANSCEIVER_TYPE_NONE</td><td rowspan=5><pre> </pre><!>
<!c>0<!>TRANSCEIVER_LINEMODE_NA<!>
<!c>1<!>TRANSCEIVER_LINEMODE_TWO_LINE<!>
<!c>2<!>TRANSCEIVER_LINEMODE_CAN_H<!>
<!c>3<!>TRANSCEIVER_LINEMODE_CAN_L<!>
<!c>4<!>TRANSCEIVER_LINEMODE_SWC_SLEEP<!>SWC Sleep Mode.<!>
<!c>5<!>TRANSCEIVER_LINEMODE_SWC_NORMAL<!>SWC Normal Mode.<!>
<!c>6<!>TRANSCEIVER_LINEMODE_SWC_FAST<!>SWC High-Speed Mode.<!>
<!c>7<!>TRANSCEIVER_LINEMODE_SWC_WAKEUP<!>SWC Wakeup Mode.<!>
<!c>8<!>TRANSCEIVER_LINEMODE_SLEEP</td><td rowspan=2><pre> </pre><!>
<!c>9<!>TRANSCEIVER_LINEMODE_NORMAL<!>
<!c>10<!>TRANSCEIVER_LINEMODE_STDBY<!>Standby for those who support it<!>
<!c>11<!>TRANSCEIVER_LINEMODE_TT_CAN_H<!>truck & trailer: operating mode single wire using CAN high<!>
<!c>12<!>TRANSCEIVER_LINEMODE_TT_CAN_L<!>truck & trailer: operating mode single wire using CAN low<!>
<!ETBL>


<!STBL>
<tr bgcolor=#e0e0e0><td colspan=3><b>rResNet</b><!>
<tr bgcolor=#e0e0e0 align=center><td><b>Value</b><!><b>?</b><!>
<!c>0<!>TRANSCEIVER_RESNET_NA<!>
<!c>1<!>TRANSCEIVER_RESNET_MASTER<!>
<!c>2<!>TRANSCEIVER_RESNET_MASTER_STBY<!>
<!c>3<!>TRANSCEIVER_RESNET_SLAVE<!>
<!ETBL>

The value for the <!PW>rTransceiver should be in accordance with the installed transceiver cab!

Not all combinatiuons of <!PW>rTransceiver, <!PW>rLineMode and <!PW>rResNet  are valid!
>>

<<
128.160.3.10
CAN.Setup|Setup
--
<!DEF>
procedure <!TW>CAN.Setup (sName : string; rBaudRate, rSJW, rTSeg1, rTSeg2, rSam : real);
<!TXT>
Sets the parameter of the CAN connection

 <!PW>rBaudRate : Baudrate (1..1000000 Bd)

 <!PW>rSJW : Synchronisation Jump Width (1..4)

 <!PW>rTSeg1 : Length of Timing Segment 1 (1..16)

 <!PW>rTSeg2 : Length of Timing Segment 2 (1..8)

 <!PW>rSAM : Number of Sampling Points (1 or 3)

The following special values may be specified for any parameter:
-1 : leaves the value at its current status
-2 : takes the value from the basic setup

<!REM>
Attention: 
not all combinations of baudrate and timing can be realized.
Use the CAN Bit Calculator in the basic setup to be sure.

<!CODE>
// modify only Baudrate
CAN.Setup (sName, 83333, -1, -1, -1, -1);

// reactivate basic setup
CAN.Setup (sName, -2, -2, -2, -2, -2);
<!TXT>
>>

<<
128.160.4
Error codes of the CAN-Object|Error codes
--
<!STBL>
<!+>Code<!+>Meaning<!>
<!c>0<!>Okay, no error<!>
<!c>1<!>Channel is not open<!>
<!c>2<!>exceptional error<!>
<!c>3<!>Timeout<!>
<!c>4<!>Event cannot be generated<!>
<!c>5<!>Event cannot be set<!>
<!c>6<!>Thread cannot be generated<!>
<!c>7<!>Channel cannot be opened<!>
<!c>8<!>Channel cannot be activated<!>
<!c>9<!>Parameters cannot be set<!>
<!c>10<!>Filter cannot be set<!>
<!c>11<!>Mode acnnot be set<!>
<!c>12<!>Send error<!>
<!c>13<!>Receive buffer empty<!>
<!c>14<!>Port cannot be opened<!>
<!c>15<!>Port is not open<!>
<!c>16<!>DLL loading error<!>
<!c>17<!>DLL not loaded (CAN inactive?)<!>
<!ETBL>
>>

