Main Content

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

expand all

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

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

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

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

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

expand all

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

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

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

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

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

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

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

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

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

expand all

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

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

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

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

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

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

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

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

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

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

Arbitration bus speed for the selected device, in bits per second. The default speed is assigned by the selected device.

Data bus speed for the selected device, in bits per second. The default speed is assigned by the selected device.

(PEAK-System only.) Specify the prescaler for arbitration bit rates.

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.

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.

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.

(PEAK-System only.) Specify the prescaler for data bit rates.

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.

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.

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.

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

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

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

expand all

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

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 ModeVendorsInitial 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