D 2018-09-11T04:36:32.548
L tclcan
P 8100903a444594fdb921452a09534f149cdaa05c
U chw
W 14007
<h2>Name</h2>
<b>can</b> - Tcl interface to Linux SocketCAN
<h2>Synopsis</h2>
<tt>package require Tcl 8.6</tt><br>
<tt>package require tclcan</tt><br>
<tt>can bcmopen <i>ifname</i></tt><br>
<tt>can bitrate <i>ifname ?rate? ?sample_point?</i></tt><br>
<tt>can bittiming <i>ifname</i></tt><br>
<tt>can bitttiming_const <i>ifname</i></tt><br>
<tt>can berr <i>ifname</i></tt><br>
<tt>can clock <i>ifname</i></tt><br>
<tt>can close <i>chan</i></tt><br>
<tt>can ctrlmode <i>ifname ?mode ...?</i></tt><br>
<tt>can devstat <i>ifname</i></tt><br>
<tt>can dump <i>chan</i></tt><br>
<tt>can interfaces</i></tt><br>
<tt>can open <i>ifname</i></tt><br>
<tt>can read <i>chan</i></tt><br>
<tt>can restart <i>ifname</i></tt><br>
<tt>can restart_ms <i>ifname ?ms?</i></tt><br>
<tt>can start <i>ifname</i></tt><br>
<tt>can state <i>ifname</i></tt><br>
<tt>can stop <i>ifname</i></tt><br>
<tt>can write <i>chan canid data ?ifindex?</i></tt><br>
<tt>can write <i>chan opcode flags count time1 time2 canid ?ifindex ...?</i></tt>
<h2>Description</h2>
This package provides Tcl support for Linux SocketCAN <b>CAN_RAW</b> and <b>CAN_BCM</b> socket types. The package implements a new channel type and a Tcl command to perform operations on these channels. The standard <tt>gets</tt>, <tt>puts</tt>, and <tt>read</tt> Tcl commands are not supported, but <tt>close</tt>, <tt>fconfigure</tt>, and <tt>fileevent</tt> are available as for normal channels, e.g. sockets. When the <b>libsocketcan</b> shared library is available, various subcommands can be used to manage CAN interfaces, too.
<h2>Commands</h2>
<tt>can bcmopen <i>ifname</i></tt>
Opens a channel by creating a broadcast manager socket (type <b>CAN_BCM</b> ) on the given CAN interface <tt><i>ifname</i></tt>. If <tt><i>ifname</i></tt> is specified as an empty string, the channel is bound to all CAN interfaces. The command returns an identifier for the channel which is to be used in subsequent <tt>can read</tt> and <tt>can write</tt> commands.
<tt>can bitrate <i>ifname ?rate? ?sample_point?</i></tt>
Gets or sets the bitrate <tt><i>rate</i></tt> (and sets optional sample point to <tt><i>sample_point</i></tt>) on the CAN interface <tt><i>ifname</i></tt>.
<tt>can bittiming <i>ifname</i></tt>
Retrieves the current bit timing of the CAN interface <tt><i>ifname</i></tt>. For details refer to <b>/usr/include/can_netlink.h</b>.
<tt>can bittiming_const <i>ifname</i></tt>
Retrieves configuration on bit timing of the CAN interface <tt><i>ifname</i></tt>. For details refer to <b>/usr/include/can_netlink.h</b>.
<tt>can berr <i>ifname</i></tt>
Retrieves error counters of the CAN interface <tt><i>ifname</i></tt>. The result is a dictionary made up of the keys <tt>txerr</tt> and <tt>rxerr</tt> with respective integer error counters.
<tt>can clock <i>ifname</i></tt>
Retrieves the clock frequency of the CAN interface <tt><i>ifname</i></tt>. For details refer to <b>/usr/include/can_netlink.h</b>.
<tt>can close <i>chan</i></tt>
Closes the channel <tt><i>chan</i></tt> which was formerly obtained by <tt>can open</tt>. This is equivalent to invoking the <tt>close</tt> command with <tt><i>chan</i></tt> as parameter.
<tt>can ctrlmode <i>ifname ?mode ...?</i></tt>
Gets or sets modes on the CAN interface <tt><i>ifname</i></tt>. If no <tt><i>mode</i></tt> is specified, the current active modes are returned as a list. Otherwise, <tt><i>mode</i></tt> must be one or more words of <tt>loopback</tt>, <tt>listenonly</tt>, <tt>3_samples</tt>, <tt>one_shot</tt>, <tt>berr_reporting</tt>, <tt>fd</tt>, and <tt>presume_ack</tt>. In order to turn a mode off, prefix the word with a minus sign. Likewise, to turn it on, a plus sign may be optionally used as prefix.
<tt>can devstats <i>ifname</i></tt>
Retrieves device statistics as a dictionary. For details refer to <b>/usr/include/libsocketcan.h</b> and <b>/usr/include/can_netlink.h</b>.
<tt>can dump <i>chan</i></tt>
Reads a <b>CAN_RAW</b> or <b>CAN_BCM</b> message off <tt><i>chan</i></tt> and returns a formatted representation of it as a list. The list is empty if no CAN message was pending on <tt><i>chan</i></tt>.
Otherwise, for <b>CAN_RAW</b> channels the list has five or six elements which are: 1. an integer time stamp equivalent to <tt>clock microseconds</tt>, 2. the interface index (see <tt>can interfaces</tt>), 3. the CAN identifier as a hexadecimal string with 0x prefix, 4. a frame format tag of the CAN message as <tt>EFF</tt> (extended frame format) or <tt>SFF</tt> (standard frame format) optionally followed by <tt>|RTR</tt> (remote transmission request) or <tt>|ERR</tt> (error frame), 5. the data length as a decimal number, and optionally 6. the data portion of the CAN message as hexadecimal dump without blanks and prefix.
For <b>CAN_BCM</b> channels the list is made up of: 1. an integer time stamp equivalent to <tt>clock microseconds</tt>, 2. the interface index (see <tt>can interfaces</tt>), 3. the major CAN identifier as a hexadecimal string with 0x prefix, 4. a frame format tag as described above, 5. the <tt>BCM</tt> opcode as one of <tt>TX_STATUS</tt>, <tt>TX_EXPIRED</tt>, <tt>RX_STATUS</tt>, <tt>RX_TIMEOUT</tt>, or <tt>RX_CHANGED</tt>, 6. the <tt>BCM</tt> flags separated by vertical bars (<tt>SETTIMER</tt>, <tt>STARTTIMER</tt>, <tt>TX_COUNTEVT</tt>, <tt>TX_ANNOUNCE</tt>, <tt>TX_CP_CAN_ID</tt>, <tt>RX_FILTER_ID</tt>, <tt>RX_CHECK_DLC</tt>, <tt>RX_NO_AUTOTIMER</tt>, <tt>TX_RESET_MULTI_IDX</tt>, and <tt>RX_RTR_FRAME</tt>), 7. the <tt>BCM</tt> count field, 8. the first <tt>BCM</tt> interval field as floating point number, 9. the second <tt>BCM</tt> interval field as floating point number, optionally 10. to 13. describing the first CAN frame as CAN identifier (hexadecimal string), the frame format tag (<tt>EFF</tt>, <tt>SFF</tt>, etc.), the data length, and the payload as hexadecimal dump. Fields 10. to 13. repeat for the respective number of CAN frames contained in the <tt>BCM</tt> message.
<tt>can interfaces</tt>
Returns a list of CAN network interface names and indices suitable for <tt>can open</tt>, <tt>can read</tt>, <tt>can write</tt> and link management subcommands.
<tt>can open <i>ifname</i></tt>
Opens a channel (raw <b>AF_CAN</b> socket) on the given CAN interface <tt><i>ifname</i></tt>. If <tt><i>ifname</i></tt> is specified as an empty string, the channel is bound to all CAN interfaces. The command returns an identifier for the channel which is to be used in subsequent <tt>can read</tt> and <tt>can write</tt> commands.
<tt>can read <i>chan</i></tt>
Reads a <b>CAN_RAW</b> or <b>CAN_BCM</b> message off <tt><i>chan</i></tt> as a list. The list is empty if no CAN message was pending on <tt><i>chan</i></tt>.
Otherwise, for <b>CAN_RAW</b> channels it is made up of four elements, 1. the CAN identifier as an integer number including flags as explained below, 2. the data portion of the CAN message as a byte array, 3. the interface index of the CAN interface the CAN message was received from, and 4. a boolean value indicating if more CAN messages can be read using <tt>can read</tt>.
For <b>CAN_BCM</b> channels it is made up of at least seven elements: 1. the interface index, 2. the major CAN identifier (see above), 3. the <tt>BCM</tt> operation as one of <tt>TX_STATUS</tt>, <tt>TX_EXPIRED</tt>, <tt>RX_STATUS</tt>, <tt>RX_TIMEOUT</tt>, or <tt>RX_CHANGED</tt>, 4. the <tt>BCM</tt> flags as an integer number, 5. the <tt>BCM</tt> count field as an integer number, 6. the first <tt>BCM</tt> interval field as a floating point number, and 7. the second <tt>BCM</tt> interval field as a floating point number. When CAN frames are part of the <tt>BCM</tt> message, each frame is a pair of CAN identifier as integer number and the payload as byte array of length 0 to 8 for normal frames or an integer number for RTR frames.
<tt>can restart <i>ifname</i></tt>
Performs a link restart on the CAN interface <tt><i>ifname</i></tt>.
<tt>can restart_ms <i>ifname ?ms?</i></tt>
Gets or sets the restart timer of the CAN interface <tt><i>ifname</i></tt>. <tt><i>ms</i></tt> must be specified as positive integer number of milliseconds.
<tt>can start <i>ifname</i></tt>
Performs a link startup on the CAN interface <tt><i>ifname</i></tt>.
<tt>can state <i>ifname</i></tt>
Retrieves the linmk state of the CAN interface <tt><i>ifname</i></tt>. The result is one of <tt>error_active</tt>, <tt> error_warning</tt>, <tt>error_passive</tt>, <tt>bus_off</tt>, <tt>stopped</tt>, <tt>sleeping</tt>, or <tt>unknown</tt>.
<tt>can stop <i>ifname</i></tt>
Performs a link stop on the CAN interface <tt><i>ifname</i></tt>.
<tt>can write <i>chan canid data ?ifindex?</i></tt>
Writes a <b>CAN_RAW</b> message to <tt><i>chan</i></tt>. <tt><i>canid</i></tt> is the CAN identifier as integer number, <tt><i>data</i></tt> a byte array of the data to be sent. The optional <tt><i>ifindex</i></tt> is the CAN interface index (see <tt>can interfaces</tt>) on which the message is to be sent. It is mandatory to specify <tt><i>ifindex</i></tt> when <tt><i>chan</i></tt> is bound to all interfaces, i.e. the interface name on <tt>can open</tt> was an empty string.
<tt>can write <i>chan opcode flags count time1 time2 canid ?ifindex ...?</i></tt>
Writes a <b>CAN_BCM</b> message to <tt><i>chan</i></tt>. <tt><i>opcode</i></tt> must be a <tt>BCM</tt> operation out of the set <tt>TX_SETUP</tt>, <tt>TX_DELETE</tt>, <tt>TX_READ</tt>, <tt>TX_SEND</tt>, <tt>RX_SETUP</tt>, <tt>RX_DELETE</tt>, and <tt>RX_READ</tt>. <tt><i>flags</i></tt> must be a list with zero or more elements of the set <tt>SETTIMER</tt>, <tt>STARTTIMER</tt>, <tt>TX_COUNTEVT</tt>, <tt>TX_ANNOUNCE</tt>, <tt>TX_CP_CAN_ID</tt>, <tt>RX_FILTER_ID</tt>, <tt>RX_CHECK_DLC</tt>, <tt>RX_NO_AUTOTIMER</tt>, <tt>RX_ANNOUNCE_RESUME</tt>, <tt>TX_RESET_MULTI_IDX</tt>, and <tt>RX_RTR_FRAME</tt>. <tt><i>count</i></tt> is the counter for the first interval <tt><i>time1</i></tt>. The intervals <tt><i>time1</i></tt> and <tt><i>time2</i></tt> must be given as floating point numbers of seconds. <tt><i>canid</i></tt> is the major CAN identifier for the <tt>BCM</tt> message. <tt><i>ifindex</i></tt> is the interface index which is required, if the <b>CAN_BCM</b> channel was bound to all interfaces. All following optional arguments make up CAN frames and must be pairs of a CAN identifier and a byte array of 0 up to 8 bytes for normal frames, or an integer as data length for RTR frames.
<h2>CAN Identifiers</h2>
The Linux SocketCAN interface defines special bits in CAN identifiers which are made up of the three most significant bits in a 32 bit integer: 0x80000000 for extended frame format (<tt>EFF</tt>), 0x40000000 for remote transmission request (<tt>RTR</tt>), and 0x20000000 for error frames (<tt>ERR</tt>). The lower 29 (for <tt>EFF</tt>) or 11 (for <tt>SFF</tt>) bits make up the CAN identifier. In order to retrieve the real CAN identifier of a received CAN message from <tt>can read</tt> a binary and with the masks 0x1FFFFFFF or 0x7FF must be carried out. In order to send an <tt>RTR</tt> message, the CAN identifier must be binary or-ed with 0x40000000 for <tt>can write</tt>. In order to send a 29 bit CAN identifier it must be or-ed with 0x80000000.
<h2>Channel Options</h2>
The following list describes the additional channel options of CAN channels.
<tt>-error</tt>
The last system error message on the channel. This is a read-only option.
<tt>-filter <i>?list?</i></tt>
Message filters applied on reception. <tt><i>list</i></tt> must be made up of an even number of integers specifying CAN identifiers and masks. The default is no filtering, expressed as two zero values. Up to 16 filters can be specified. For details refer to <b>/usr/include/linux/can.h</b>.
<tt>-loopback <i>?bool?</i></tt>
Messages sent are looped back on the local system when enabled (on by default).
<tt>-ownmsgs <i>?bool?</i></tt>
Messages sent are received on the same channel when enabled (off by default).
<h2>Link Management</h2>
The link management subcommands <tt>bitrate</tt>, <tt>bittiming</tt>, <tt>bittiming_const</tt>, <tt>berr</tt>, <tt>clock</tt>, <tt>ctlrmode</tt>, <tt>devstat</tt>, <tt>restart</tt>, <tt>restart_ms</tt>, <tt>start</tt>, <tt>state</tt>, and <tt>stop</tt> depend on an installed <b>libsocketcan</b> shared library for proper operation. Otherwise they report "function not implemented". All changes of link state by these commands usually require administrative rights. Either the calling process must have super user privileges or the <b>CAP_NET_ADMIN</b> capability must be effective. The latter can be achieved by a command similar to:
<verbatim>
setcap cap_net_admin+eip binary-package-requiring-tclcan
</verbatim>
Furthermore, retrieving link information depends on CAN driver support. Usually, the virtual CAN driver <b>vcan</b> and drivers attached through a serial line discipline (using the <b>slcan_attach</b> or <b>slcand</b> programs) only provide rudimentary link state information.
<h2>Broadcast Manager Examples</h2>
Open <tt>BCM</tt> channel:
<verbatim>
set chan [can bcmopen can0]
</verbatim>
Schedule sending the pattern 0x41424344 on CAN identifier 0x123 once per second:
<verbatim>
can write $chan TX_SETUP \
{SETTIMER STARTTIMER} \
0 0.0 1.0 0x123 0x123 ABCD
</verbatim>
Dispatch receiving CAN identifier 0x123 with update rate limited to two seconds:
<verbatim>
can write $chan RX_SETUP \
{SETTIMER RX_FILTER_ID RX_ANNOUNCE_RESUME} \
0 0.0 2.0 0x123
</verbatim>
Dump all received <tt>BCM</tt> messages on standard output:
<verbatim>
proc dump chan {puts [can dump $chan]}
fileevent $chan readable [list dump $chan]
</verbatim>
Z 1f40654a77005b51521494a7503369e5