canctl
QNX SDP8.0Utilities ReferenceUtilities
Control a CAN (Controller Area Network) device
Syntax:
canctl -uunit[,mailbox] [-bdeFhiMnPrsT] [-c freq[kKmM],bprm,ts1,ts2,sjw]
[-f 0x########] [-m 0x########] [-p 0x########] [-R delay_ms]
[-t 0x########] [-w 0xmid,mid_type,data_str]
[-y 0xmid,mid_type,data_str]
Runs on:
QNX OS
Options:
- -b
- Use blocking mode.
- -c freq[kKmM],bprm,ts1,ts2,sjw
- Set the reference clock frequency in Hz and bit timings.
The arguments are as follows:
- freq[kKmM] — the clock rate in Hz, optionally followed by a multiplier of k or K for 1000, and m or M for 1000000
- bprm — the baud rate prescaler
- ts1 — the number of time quantas for time segment 1
- ts2 — the number of time quantas for time segment 2
- sjw — the number of time quantas for the syncronization jump width
- -d
- Print debugging information. If you specify a receive or transmit mailbox in the -u option, you get information for that mailbox; otherwise, you get information for all of them. The information depends on the driver, but could include the values of the driver's registers and mailboxes.
- -e
- Print error information.
- -F
- Get the current message filter. The -u option must specify a receive mailbox.
- -f 0x########
- Set the message filter. The -u option must specify a receive mailbox.
- -h
- Print the usage message.
- -i
- Get device information.
- -M
- Get the message ID. The -u option must specify a receive mailbox.
- -m 0x########
- Set the message ID.
The -u option must specify a receive mailbox.
The form of the ID depends on whether or not the driver is using extended MIDs:
- In standard 11-bit MIDs, bits 18–28 define the MID.
- In extended 29-bit MIDs, bits 0–28 define the MID.
- -n
- Use nonblocking mode.
- -P
- Get the tx message priority. The -u option must specify a transmit mailbox.
- -p 0x########
- Set the tx message priority. The -u option must specify a transmit mailbox, and the priority must not exceed the maximum for the device (usually defined as a constant whose name is in the form board_CANMCF_TPL_MAXVAL).
- -R delay_ms
- Read extended CAN messages continuously, with the given delay in milliseconds between each read.
- -r
- Read an extended CAN message.
- -s
- Get device statistics.
- -T
- Get the device's timestamp.
- -t 0x########
- Set the device's timestamp.
- -uunit[,mailbox]
- Specify the CAN device to operate on. The mailbox name consists of rx or tx followed by the mailbox number. The default is /dev/can1/rx0.
- -w 0xmid,mid_type,data_str
- Write a CAN message (in string format for test purposes). A mid_type of 0 indicates a standard message ID; a value of 1 indicates an extended message ID.
- -y 0xmid,mid_type,data_str
- Write a CAN message in raw mode (in string format for test purposes). A mid_type of 0 indicates a standard message ID; a value of 1 indicates an extended message ID.
Description:
The canctl utility lets you control a Controller Area Network (CAN) device
through its driver, whose name is in the form dev-can-board.
This utility provides a command-line interface to the following devctl() commands,
which are described in the Devctl and Ioctl Commands reference:
| canctl option | devctl() command(s) |
|---|---|
| -c | CAN_DEVCTL_SET_TIMING |
| -d | CAN_DEVCTL_DEBUG_INFO, CAN_DEVCTL_DEBUG_INFO2 |
| -e | CAN_DEVCTL_ERROR |
| -F | CAN_DEVCTL_GET_MFILTER |
| -f | CAN_DEVCTL_SET_MFILTER |
| -i | CAN_DEVCTL_GET_INFO |
| -M | CAN_DEVCTL_GET_MID |
| -m | CAN_DEVCTL_SET_MID |
| -P | CAN_DEVCTL_GET_PRIO |
| -p | CAN_DEVCTL_SET_PRIO |
| -R | CAN_DEVCTL_READ_CANMSG_EXT |
| -r | CAN_DEVCTL_READ_CANMSG_EXT |
| -s | CAN_DEVCTL_GET_STATS |
| -T | CAN_DEVCTL_GET_TIMESTAMP |
| -t | CAN_DEVCTL_SET_TIMESTAMP |
| -w | CAN_DEVCTL_WRITE_CANMSG_EXT |
The -u option becomes the file descriptor that's passed to devctl().
The information that's displayed depends on the hardware.
Here are some abbreviations that you might see in the output:
- LAM
- Local area mask
- MB
- Mailbox name
- MCF
- Message control field
- MDH
- Message data high word
- MDL
- Message data low word
- MID
- Message ID
- MOTS
- Message object timestamp
Let's use examples to illustrate what you can use canctl for.
In these examples, we'll use a fictitious board, the Exempli Gratia 123, or EG123.
First, let's start the CAN driver in self-test mode:
# dev-can-eg123 -t eg123can1
# ls /dev/can1
rx0 rx1 rx2 rx3 rx4 tx5 tx6 tx7 tx8 tx9
In this mode, the transmitter and receiver of the CAN device are looped back.
Let's assume that the message IDs (MIDs) of the transmit and receive mailboxes are
configured by default as follows:
| Mailbox | MID |
|---|---|
| RX0, TX5 | 0x100C0000 |
| RX1, TX6 | 0x101C0000 |
| RX2, TX7 | 0x102C0000 |
| RX3, TX8 | 0x103C0000 |
| RX4, TX9 | 0x104C0000 |
All messages transmitted with MID 0x101C0000 (TX6) are received by any receivers with a filter for MID 0x101C0000, which is RX1 in this case. The CAN drivers let you configure the number of RX and TX devices, as well as the MIDs.
You can use cat to read CAN messages from a receive mailbox:
# cat /dev/can1/rx0 &
You can use echo, directed at a transmit mailbox,
to transmit a CAN message.
The receive mailbox that uses the same message ID receives the message;
in this case, RX0 gets the message, and the cat utility displays it:
# echo testing > /dev/can1/tx16
testing
Now, let's examine how you can use canctl to send devctl() commands to the CAN driver to take advantage of various driver features.
Getting and setting the message ID
You can use the -M option or the
CAN_DEVCTL_GET_MID
devctl() command to obtain the message ID (MID) for a given device:
# canctl -u1,rx0 -M
GET_MID = 0x100C0000
You can use the -m option or the
CAN_DEVCTL_SET_MID
devctl() command to specify a new MID.
Here we set this for a TX device and the corresponding RX device:
# canctl -u1,rx1 -m0x11CC0000
# canctl -u1,tx6 -m0x11CC0000
You can also specify the starting MID value when you start the driver.
The form of the message ID depends on whether or not the driver is using extended MIDs:
- In standard 11-bit MIDs, bits 18–28 define the MID.
- In extended 29-bit MIDs, bits 0–28 define the MID.
Extended CAN message data
You can get additional information with each received CAN message, but
this feature must be enabled in the driver:
# dev-can-eg123 -t -M can1
Then, if you transmit a CAN message:
# echo tstdat1 > /dev/can1/tx5
# canctl -u1,rx0 -r
READ_CANMSG_EXT:
mid = 0x100C0000
timestamp = 0xE74
dat len = 8
dat = tstdat1
You can also use the CAN_DEVCTL_READ_CANMSG_EXT devctl() command to get the extended information.
Normal reads still work, but the extended information is discarded.
Device timestamps
You can specify the timestamp when you start the driver:
# dev-can-eg123 -t -m0x123456 -M can1
(We've also enabled extended messaging in this case.)
You can use canctl or the
CAN_DEVCTL_GET_TIMESTAMP
and
CAN_DEVCTL_SET_TIMESTAMP
devctl() commands to get or set the timestamp:
# canctl -u1 -T
GET_TIMESTAMP = 0x1BD9FC
# canctl -u1 -t0xAAAAAA
# canctl -u1 -T
GET_TIMESTAMP = 0xAAEBEC
If extended message information is enabled, the information includes the timestamp:
# echo testing > /dev/can1/tx5
# canctl -u1,rx0 -r
READ_CANMSG_EXT:
mid = 0x100C0000
timestamp = 0xAED57A
dat len = 8
dat = testing
Message priorities
Priorities can be associated with CAN transmit messages. The hardware uses these priorities to determine which CAN message to transmit first if there are multiple messages waiting to be transmitted. The default priorities depend on the driver.
To read the current priorities, use the -P or the
CAN_DEVCTL_GET_PRIO
devctl() command:
# canctl -u1,tx1 -P
GET_PRIO = 16
To set a new device priority, use the -p or the
CAN_DEVCTL_SET_PRIO
devctl() command:
# canctl -u1,tx1 -p5
Message filtering
You can use masks on the receive mailboxes to further modify the filtering provided by the message IDs (MID).
The mask specifies which bits in the MID are to be ignored.
By default, the mask is disabled, but you can enable and modify it by using the
-f option or the
CAN_DEVCTL_SET_MFILTER
devctl() command:
- Start the driver with extended MIDs enabled:
# slay dev-can-eg123 # dev-can-eg123 -t -x can1 - Get the initial mask values:
# canctl -u1,rx0 -F MFILTER = 0x0 # canctl -u1,rx1 -F MFILTER = 0x0 # canctl -u1,tx5 -F MFILTER = 0x0 - Get the initial MID values:
# canctl -u1,rx0 -M GET_MID = 0x100C0000 # canctl -u1,rx1 -M GET_MID = 0x101C0000 # canctl -u1,tx5 -M GET_MID = 0x100C0000 - Set new MID values for rx0, rx1, and tx5
# canctl -u1,rx0 -m0x100C0001 # canctl -u1,rx1 -m0x100C0002 # canctl -u1,tx5 -m0x100C0002 # canctl -u1,rx0 -M GET_MID = 0x100C0001 # canctl -u1,rx1 -M GET_MID = 0x100C0002 # canctl -u1,tx5 -M GET_MID = 0x100C0002 - Transmit a CAN message from tx5:
# echo testing > /dev/can1/tx5 - Determine which RX device received that message:
# cat /dev/can1/rx0 [Ctrl+C] # cat /dev/can1/rx1 testing [Ctrl+C]RX1 received the message because its MID exactly matched that of TX5.
- Use the -f option (or the
CAN_DEVCTL_SET_MFILTER
devctl() command) to set the local area mask (LAM) filter on RX0 and RX1:
# canctl -u1,rx0 -f0xFFFFFFF0 # canctl -u1,rx1 -f0xFFFFFFF0 - Transmit a CAN message from tx5:
echo testing > /dev/can1/tx5 - Determine which RX device received that message:
# cat /dev/can1/rx1 [Ctrl+C] # cat /dev/can1/rx0 testingRX0 and RX1 now appear to have the same MID since the last nibble is now ignored for both devices because they have the last nibble of the LAM filter cleared. Therefore, RX0 received the message because it is the first message buffer with the most matching MID bits.
Page updated: