can.Channel Properties
Properties of the can.Channel
object
Use the following properties to examine or configure CAN channel settings. Use
canChannel
to create a CAN channel object. Use configBusSpeed
to set timing parameters.
Note
Not all bit timing properties are available for all vendors and protocol modes. See Bit Timing Property Initial Values.
Device Information
DeviceVendor
— Device vendor name
char vector
The DeviceVendor
property indicates the name of the device
vendor.
Values are automatically defined when you configure the channel with the canChannel
or j1939Channel
function.
Data Types: char
Device
— Channel device type
char vector
This property is read-only.
For National Instruments™ devices, the Device
property displays the device
number on the hardware.
For all other vendors, the Device
property displays information
about the device type to which the CAN or J1939 channel is connected.
Values are automatically defined when you configure the channel with the canChannel
or j1939Channel
function.
Data Types: char
DeviceChannelIndex
— Device channel index
double
This property is read-only.
The DeviceChannelIndex
property indicates the channel index on
which the specified CAN or J1939 channel is configured.
Values are automatically defined when you configure the channel with the canChannel
or j1939Channel
function.
Data Types: double
DeviceSerialNumber
— Device serial number
double | char
This property is read-only.
The DeviceSerialNumber
property displays the serial number of
the device connected to the CAN or J1939 channel.
Values are automatically defined when you configure the channel with the canChannel
or j1939Channel
function.
Data Types: double
| char
ProtocolMode
— Protocol mode of CAN channel
'CAN'
(default) | 'CAN FD'
This property is read-only.
The ProtocolMode
property indicates the communication protocol
for which the CAN channel is configured, either CAN
or CAN
FD
.
The value is defined when you configure the channel with the canChannel
function.
Data Types: char
Status Information
Running
— Indicate running status of channel
false
(0
) | true
(1
)
This property is read-only.
The Running
property indicates the state of the CAN or J1939
channel, according to the following values:
false
(default) — The channel is offline.true
— The channel is online.
Use the start
function to set your channel
online.
Data Types: logical
MessagesAvailable
— Number of messages available to be received by CAN channel
double
This property is read-only.
The MessagesAvailable
property displays the total number of
messages available to be received by a CAN channel. The value is 0
when no messages are available.
Data Types: double
MessagesReceived
— Number of messages received by CAN channel
double
This property is read-only.
The MessagesReceived
property indicates the total number of
messages received since the channel was last started. The value is 0
when no messages have been received, and increments based on the number of messages the
channel receives.
Data Types: double
MessagesTransmitted
— Number of messages transmitted by CAN channel
double
This property is read-only.
The MessagesTransmitted
property indicates the total number of
messages transmitted since the channel was last started. The default value is
0
when no messages have been sent, and increments based on the
number of messages the channel transmits.
Data Types: double
MessageReceivedFcn
— Callback function to run when messages available
function handle | char | string
Configure MessageReceivedFcn
as a callback function to run,
specified as a character vector, string, or a function handle, when a required number of
messages are available.
The MessageReceivedFcnCount
property defines the required
number of messages available before the configured
MessageReceivedFcn
runs.
For example, to specify the callback function to execute:
canch.MessageReceivedFcn = @Myfunction;
Data Types: char
| string
| function_handle
MessageReceivedFcnCount
— Specify number of messages available before callback is triggered
numeric
Configure MessageReceivedFcnCount
to the number of messages
that must be available before the MessageReceivedFcn
callback
function is triggered.
The default value is 1
. You can specify a positive integer for
your MessageReceivedFcnCount
. For example, to specify the message
count required to trigger a callback:
canch.MessageReceivedFcnCount = 55;
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
InitializationAccess
— Indicate control of device channel
true
(1
) | false
(0
)
This property is read-only.
The InitializationAccess
property indicates if the configured
CAN or J1939 channel object has full control of the device channel, according to the
following values:
true
— Has full control of the hardware channel and can change the property values.false
— Does not have full control and cannot change property values.
You can change some property values of the hardware channel only if the object has full control over the hardware channel.
Note
Only the first channel created on a device is granted initialization access.
Data Types: logical
InitialTimestamp
— Indicate when channel started
datetime
This property is read-only.
The InitialTimestamp
property indicates when the channel was
set online with the start
function or when its start trigger was
received. For National Instruments devices, the time is obtained from the device driver; for devices from
other vendors the time is obtained from the operating system where MATLAB is
running.
Data Types: datetime
FilterHistory
— Indicate settings of message acceptance filters
char
This property is read-only.
Indicate settings of message acceptance filters, returned as a character vector.
This property indicates the settings implemented by the functions filterAllowOnly
, filterAllowAll
, and filterBlockAll
.
Example: 'Standard ID Filter: Allow All | Extended ID Filter: Allow
All'
Data Types: char
Channel Information
BusStatus
— Status of bus
char
This property is read-only.
The BusStatus
property displays information about the state of
the CAN bus or the J1939 bus.
'N/A'
— Property not supported by vendor.'ErrorActive'
— Node transmits Active Error Flags when it detects errors. Note: This status does not necessarily indicate that an error actually exists, but indicates how an error is handled.'ErrorPassive'
— Node transmits Passive Error Flags when it detects errors.'BusOff'
— Node will not transmit anything on the bus.
Data Types: char
SilentMode
— Specify if channel is active or silent
false
(default) | true
Specify whether the channel operates silently, according to the following values:
false
(default) — The channel is in normal or active mode. In this mode, the channel both transmits and receives messages normally and performs other tasks on the network such as acknowledging messages and creating error frames.true
— The channel is in silent mode. You can observe all message activity on the network and perform analysis without affecting the network state or behavior. In this mode, you can only receive messages and not transmit any.
When you clear and recreate a Kvaser channel, its SilentMode
setting is retained. If you specify SilentMode
on a device that
does not support it, an error results.
Data Types: logical
TransceiverName
— Name of device transceiver
char
This property is read-only.
TransceiverName
indicates the name of the device transceiver. The
device transceiver translates the digital bit stream going to and coming from the bus
into the real electrical signals present on the bus.
Data Types: char
TransceiverState
— Specify state or mode of transceiver
numeric
If your CAN or J1939 transceiver allows you to control its mode, you can use the
TransceiverState
property to set the mode.
The numeric property value for each mode is defined by the transceiver manufacturer. Refer to your CAN transceiver documentation for the appropriate transceiver modes. Possible modes representing the numeric value specified are:
high speed
high voltage
sleep
wake up
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
ReceiveErrorCount
— Number of errors during message reception
double
This property is read-only.
The ReceiveErrorCount
property indicates the total number of
errors during message reception since the channel was last started. The default value is
0
, and increments based on the number of errors.
Data Types: double
TransmitErrorCount
— Number of errors during message transmission
double
This property is read-only.
The TransmitErrorCount
property indicates the total number of
errors during message transmission since the channel was last started. The default value
is 0
, and increments based on the number of errors.
Data Types: double
BusSpeed
— Bit rate of bus transmission
double
This property is read-only.
The BusSpeed
property indicates the speed at which messages are
transmitted in bits per second. The default value is assigned by the vendor driver.
You can set BusSpeed
to a supported bit rate using the
configBusSpeed
function, specifying the
channel name and the bit rate value as input parameters. For example, to change the bus
speed of the CAN channel object canch
to 250,000 bits per second, and
view the result, type
configBusSpeed(canch,250000); bs = canch.BusSpeed
Data Types: double
SJW
— CAN Synchronization jump width (SJW) of bit time segment
double
This property is read-only.
SJW
displays the synchronization jump width of the bit time
segment. To adjust the on-chip bus clock, the controller can shorten or prolong the
length of a bit by an integral number of time segments. The maximum value of these bit
time adjustments are termed the synchronization jump width or
SJW
.
Note
This property is not available for National Instruments CAN
devices. The channel displays NaN
for the value.
Data Types: double
TSEG1,TSEG2
— Allowed number of bit segments to lengthen and shorten CAN sample time
double
This property is read-only.
The TSEG1
and TSEG2
properties indicate
the amount in bit time segments that the channel can lengthen and shorten the sample
time, respectively, to resynchronize or compensate for delay times in the network. The
value is inherited when you configure the bus speed of your CAN channel.
Note
This property is not available for National Instruments CAN
devices. The channel displays NaN
for the value.
Data Types: double
NumOfSamples
— Number of samples per read
double
This property is read-only.
The NumOfSamples
property is a bit timing parameter that
indicates the number of bit samples performed for a single bit read on the network. The
value is a positive integer based on the driver settings for the channel.
Note
This property is not available for National Instruments CAN
devices. The channel displays NaN
for the value.
Data Types: double
ArbitrationBusSpeed
— CAN FD arbitration bit rate
numeric
Arbitration bus speed for the selected device, in bits per second. The default speed is assigned by the selected device.
DataBusSpeed
— CAN FD data bit rate
numeric
Data bus speed for the selected device, in bits per second. The default speed is assigned by the selected device.
ArbitrationPrescaler
— Bit rate prescaler
integer
(PEAK-System only.) Specify the prescaler for arbitration bit rates.
ArbitrationSJW
— Maximum allowed time adjustment
integer
Specify the maximum limit of the arbitration synchronization jump width, the bit time adjustment in the case of resynchronization. The value must be a positive integer indicating a number of bit time quanta segments. The selected bus speed setting determines the default value.
ArbitrationTSEG1
— Number of time quanta before sample
integer
Specify the number of bit time quanta before the sampling point. The value must be a
positive integer. Typically, an adjustment of this value is made with a corresponding
inverse adjustment to ArbitrationTSEG2
so that their sum remains
constant. The selected bus speed setting determines the default value.
ArbitrationTSEG2
— Number of time quanta after sample
integer
Specify the number of bit time quanta after the sampling point. The value must be a
positive integer. Typically, an adjustment of this value is made with a corresponding
inverse adjustment to ArbitrationTSEG1
so that their sum remains
constant. The selected bus speed setting determines the default value.
DataPrescaler
— Bit rate prescaler
integer
(PEAK-System only.) Specify the prescaler for data bit rates.
DataSJW
— Maximum allowed time adjustment
integer
Specify the maximum limit of the data synchronization jump width, the bit time adjustment in the case of resynchronization. The value must be a positive integer indicating a number of bit time quanta segments. The selected bus speed setting determines the default value.
DataTSEG1
— Number of time quanta before sample
integer
Specify the number of bit time quanta before the sampling point. The value must be a
positive integer. Typically, an adjustment of this value is made with a corresponding
inverse adjustment to DataTSEG2
so that their sum remains constant.
The selected bus speed setting determines the default value.
DataTSEG2
— Number of time quanta after sample
integer
Specify the number of bit time quanta after the sampling point. The value must be a
positive integer. Typically, an adjustment of this value is made with a corresponding
inverse adjustment to DataTSEG1
so that their sum remains constant.
The selected bus speed setting determines the default value.
BusLoad
— Load on CAN bus
double
This property is read-only.
The BusLoad
property provides information about the load on the
CAN network for message traffic on Kvaser devices. The current message traffic on a CAN
network is represented as a percentage ranging from 0.00%
to
100.00%
.
Data Types: double
OnboardTermination
— Configure bus termination on device
true
(1
) | false
| (0
)
The OnboardTermination
property specifies whether the NI-XNET
device uses its onboard termination of the CAN bus. For more information on the behavior
and characteristics of a specific device, refer to its vendor documentation.
Data Types: logical
StartTriggerTerminal
— Specify start trigger source terminal
char | string
The StartTriggerTerminal
property specifies a synchronization
trigger connection to start the NI-XNET channel on the connected source terminal.
To configure an NI-XNET CAN module (such as NI 9862) to start acquisition on an
external signal triggering event provided at an external chassis terminal, set the CAN
channel StartTriggerTerminal
property to the appropriate terminal
name. Form the property value character vector by combining the chassis name from the NI
MAX utility and the trigger terminal name; for example,
'/cDAQ3/PFI0'
.
Note
This property can be configured only once. After it is assigned, the property is
read-only and cannot be changed. The only way to set a different value is to clear
the channel object, recreate the channel with canChannel
, and configure its properties.
Examples
Configure an NI-XNET CAN module start trigger on terminal
/cDAQ3/PFI0
.
ch1 = canChannel('NI','CAN1') ch1.StartTriggerTerminal = '/cDAQ3/PFI0' start(ch1) % Acquisition begins on hardware trigger
With a hardware triggering configuration, the InitialTimestamp
value represents the absolute time the CAN channel acquisition was triggered. The
Timestamp
values of the received CAN messages are relative to the
trigger moment.
ch1.InitialTimestamp messages = receive(ch1,Inf); messages(1).Timestamp
Data Types: char
| string
Other Information
DataBase
— CAN database information
struct
The Database
property stores information about an attached CAN
database. If your channel message is not attached to a database, the property value is
an empty structure, []
. You can edit the CAN channel
Database
property, but cannot edit the CAN message
Database
property.
To see information about the database attached to your CAN message, type:
message.Database
To set the database information on your CAN channel to
C:\Database.dbc
, type:
channel.Database = canDatabase('C:\Database.dbc')
Tip
CAN database file names containing non-alphanumeric characters such as equal signs and ampersands are incompatible with Vehicle Network Toolbox™. You can use a period in your database name. Rename any CAN database files with non-alphanumeric characters before you use them.
Data Types: struct
UserData
— Custom data
any data
Enter custom data to be stored in your CAN message or a J1939 parameter group,
channel, or database object using the UserData
property. When you
save an object with UserData
specified, you automatically save the
custom data. When you load an object with UserData
specified, you
automatically load the custom data.
Tip
To avoid unexpected results when you save and load an object with
UserData
, specify your custom data in simple data types and
constructs.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
| char
| string
| struct
| table
| cell
| function_handle
| categorical
| datetime
| duration
| calendarDuration
| fi
Complex Number Support: Yes
Tips
Bit Timing Property Initial Values
The following table indicates the initial or default values for bus speed and bit timing properties, depending on vendor and protocol mode.
Protocol Mode | Vendors | Initial values |
---|---|---|
CAN | MathWorks PEAK-System NI-XNET |
BusSpeed: 500000 |
Vector Kvaser |
BusSpeed: 500000 SJW: 1 TSEG1: 4 TSEG2: 3 NumOfSamples: 1 | |
CAN FD | MathWorks NI-XNET Kvaser |
ArbitrationBusSpeed: 500000 DataBusSpeed: 2000000 |
Vector |
ArbitrationBusSpeed: 500000 ArbitrationSJW: 2 ArbitrationTSEG1: 6 ArbitrationTSEG2: 3 DataBusSpeed: 2000000 DataSJW: 2 DataTSEG1: 6 DataTSEG2: 3 | |
PEAK-System |
ArbitrationPrescaler: 5 ArbitrationSJW: 1 ArbitrationTSEG1: 5 ArbitrationTSEG2: 2 DataPrescaler: 2 DataSJW: 1 DataTSEG1: 3 DataTSEG2: 1 |
Version History
Introduced in R2009a
See Also
Functions
External Websites
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)