Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Artifact ID:	a9464f6d7b70bade5629f1266b74033807888b54
Page Name:	tclcan
Date:	2018-05-22 22:26:54
Original User:	chw
Parent:	1abff35962e7a5b209d8a4b016eab7a1e7052b63 (diff)
Next	6fba5bfd0d9b22b6edd0d6eb7fefa3aa93c37ae7

Name

can - Tcl interface to Linux SocketCAN

Synopsis

package require Tcl 8.6
package require tclcan
can bitrate ifname ?rate? ?sample_point?
can bittiming ifname
can bitttiming_const ifname
can berr ifname
can clock ifname
can close chan
can ctrlmode ifname ?mode ...?
can devstat ifname
can dump chan
can interfaces
can open ifname
can read chan
can restart ifname
can restart_ms ifname ?ms?
can start ifname
can state ifname
can stop ifname
can write chan canid data ?ifindex?

Description

This package provides Tcl support for Linux SocketCAN raw AF_CAN sockets. The package implements a new channel type and a Tcl command to perform operations on these channels. The standard gets, puts, and read Tcl commands are not supported, but close, fconfigure, and fileevent are available as for normal channels, e.g. sockets. When the libsocketcan shared library is available, various subcommands can be used to manage CAN interfaces, too.

Commands

can bitrate ifname ?rate? ?sample_point?

Gets or sets the bitrate rate (and sets optional sample point to sample_point) on the CAN interface ifname.

can bittiming ifname

Retrieves the current bit timing of the CAN interface ifname. For details refer to /usr/include/can_netlink.h.

can bittiming_const ifname

Retrieves configuration on bit timing of the CAN interface ifname. For details refer to /usr/include/can_netlink.h.

can berr ifname

Retrieves error counters of the CAN interface ifname. The result is a dictionary made up of the keys txerr and rxerr with respective integer error counters.

can clock ifname

Retrieves the clock frequency of the CAN interface ifname. For details refer to /usr/include/can_netlink.h.

can close chan

Closes the channel chan which was formerly obtained by can open. This is equivalent to invoking the close command with chan as parameter.

can ctrlmode ifname ?mode ...?

Gets or sets modes on the CAN interface ifname. If no mode is specified, the current active modes are returned as a list. Otherwise, mode must be one or more words of loopback, listenonly, 3_samples, one_shot, berr_reporting, fd, and presume_ack. 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.

can devstats ifname

Retrieves device statistics as a dictionary. For details refer to /usr/include/libsocketcan.h and /usr/include/can_netlink.h.

can dump chan

Reads a CAN message off chan and returns a formatted representation of it as a list. The list is empty if no CAN message was pending on chan. Otherwise the list has five or six elements which are: 1. an integer time stamp equivalent to clock microseconds, 2. the interface index (see can interfaces), 3. the CAN identifier as a hexadecimal string with 0x prefix, 4. a frame format tag of the CAN message as EFF (extended frame format) or SFF (standard frame format) optionally followed by |RTR (remote transmission request) or |ERR (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.

can interfaces

Returns a list of CAN network interface names and indices suitable for can open, can read, can write and link management subcommands.

can open ifname

Opens a channel (raw AF_CAN socket) on the given CAN interface ifname. If ifname 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 can read and can write commands.

can read chan

Reads a CAN message off chan as a list. The list is empty if no CAN message was pending on chan. Otherwise 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 can read.

can restart ifname

Performs a link restart on the CAN interface ifname.

can restart_ms ifname ?ms?

Gets or sets the restart timer of the CAN interface ifname. ms must be specified as positive integer number of milliseconds.

can start ifname

Performs a link startup on the CAN interface ifname.

can state ifname

Retrieves the linmk state of the CAN interface ifname. The result is one of error_active, error_warning, error_passive, bus_off, stopped, sleeping, or unknown.

can stop ifname

Performs a link stop on the CAN interface ifname.

can write chan canid data ?ifindex?

Writes a CAN message to chan. canid is the CAN identifier as integer number, data a byte array of the data to be sent. The optional ifindex is the CAN interface index (see can interfaces) on which the message is to be sent. It is mandatory to specify ifindex when chan is bound to all interfaces, i.e. the interface name on can open was an empty string.

CAN Identifiers

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 (EFF), 0x40000000 for remote transmission request (RTR), and 0x20000000 for error frames (ERR). The lower 29 (for EFF) or 11 (for SFF) bits make up the CAN identifier. In order to retrieve the real CAN identifier of a received CAN message from can read a binary and with the masks 0x1FFFFFFF or 0x7FF must be carried out. In order to send an RTR message, the CAN identifier must be binary or-ed with 0x40000000 for can write. In order to send a 29 bit CAN identifier it must be or-ed with 0x80000000.

Channel Options

The following list describes the additional channel options of CAN channels.

-error

The last system error message on the channel. This is a read-only option.

-filter ?list?

Message filters applied on reception. list 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 /usr/include/linux/can.h.

-loopback ?bool?

Messages sent are looped back on the local system when enabled (on by default).

-ownmsgs ?bool?

Messages sent are received on the same channel when enabled (off by default).

Link Management

The link management subcommands bitrate, bittiming, bittiming_const, berr, clock, ctlrmode, devstat, restart, restart_ms, start, state, and stop depend on an installed libsocketcan 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 CAP_NET_ADMIN capability must be effective. Furthermore, retrieving link information depends on CAN driver support. Usually, the virtual CAN driver vcan and drivers attached through a serial line discipline (using the slcan_attach or slcand programs) only provide rudimentary link state information, YMMV.