ncConfigCANObj.vi

NI-CAN

previous page next page

ncConfigCANObj.vi

Purpose

Configure a CAN Object before using it.

Format

Input

ObjName is the name of the CAN Object to configure. This name uses the syntax "CANx::STDy" or "CANx::XTDy". CANx is the name of the CAN network interface that you used for the preceding ncConfigCANNet VI. STD indicates that the CAN Object uses a standard (11-bit) arbitration ID. XTD indicates that the CAN Object uses an extended (29-bit) arbitration ID. The number y specifies the actual arbitration ID of the CAN Object. The number y is decimal by default, but you also can use hexadecimal by adding "0x" to the beginning of the number. For example, "CAN0::STD25" indicates standard ID 25 decimal on CAN0, and "CAN1::XTD0x0000F652" indicates extended ID F652 hexadecimal on CAN1.

The special virtual interface names "CAN256" and "CAN257" are not supported for CAN Objects.

The 847x and 847x with Sync series CAN and LIN interfaces do not support ncConfigCANobj.vi.

CAN Object Config provides the core configuration attributes of the CAN Object. This cluster uses the typedef ncObjAttr.ctl. You can wire in the cluster by first placing it on the front panel from the NI-CAN Controls palette, or you can right-click the VI input and select Create Constant or Create Control.

	Period specifies the rate of periodic behavior in milliseconds. The behavior depends on the Communication Type as follows: Transmit Data Periodically, Transmit Periodic Waveform, Receive Periodic Using Remote Period specifies the time between subsequent transmissions, and must be set greater than zero. Receive Unsolicited, Transmit by Response Only Period specifies a watchdog timeout. If a frame is not received at least once every period, a timeout error is returned. Setting Period to zero disables the watchdog timer. Transmit Data by Call, Receive by Call Using Remote Period specifies a minimum interval between subsequent transmissions. Even if ncWriteObj is called very frequently, frames are transmitted on the network at a rate no more than Period. Setting Period to zero disables the minimum interval timer.
	Read Queue Length is the maximum number of unread frames for the read queue of the CAN Object. For more information, refer to ncReadObj. If Communication Type is set to receive data, a typical value is 10. If Communication Type is set to transmit data, a typical value is 0.
	Write Queue Length is the maximum number of frames for the write queue of the CAN Object awaiting transmission. For more information, refer to ncWriteObj. If Communication Type is set to receive data, a typical value is 0. If Communication Type is set to transmit data, a typical value is 10.
	Receive Changes Only applies only to Communication Type selections in which the CAN Object receives data frames (ignored for other types). For those configurations, Receive Changes Only specifies whether duplicated data should be placed in the read queue. When set to False (default), all data frames for the CAN Object ID are placed in the read queue. When set to True, data frames are placed into the read queue only if the data bytes differ from the previously received data bytes in the read queue. This attribute has no effect on the usage of a watchdog timeout for the CAN Object. For example, if this attribute is True and you also specify a watchdog timeout, NI-CAN restarts the watchdog timer every time it receives a data frame for the ID of the CAN Object, regardless of whether the data differs from the previous frame.
	Communication Type specifies the behavior of the CAN Object with respect to its ID, including the direction of data transfer: Receive Unsolicited Receive data frames for a specific ID. This type is useful for receiving a few IDs (1-10) into dedicated read queues. For high performance applications (more IDs, fast frame rates), the Network Interface is recommended to receive all IDs. Period specifies a watchdog timeout, and Receive Changes Only specifies whether to place duplicate data frames into the read queue. Transmit by Response is ignored. Receive Periodic Using Remote Periodically transmit remote frame for a specific ID in order to receive the associated data frame. Every Period, the CAN Object transmits a remote frame, and then places the resulting data frame response in the read queue. If the data frame is not received in response to the transmit remote frame, the periodic transmission is put on hold. Period specifies the periodic rate, and Receive Changes Only specifies whether to place duplicate data frames into the read queue. Transmit by Response is ignored. Receive by Call Using Remote Transmit remote frame for a specific ID by calling ncWriteObj. The CAN Object places the resulting data frame response in the read queue. Period specifies a minimum interval, and Receive Changes Only specifies whether to place duplicate data frames into the read queue. Transmit by Response is ignored. Transmit Data Periodically Periodically transmit data frame for a specific ID. When the CAN Object transmits the last entry from the write queue, that entry is used every period until you provide a new data frame using ncWriteObj. If you keep the write queue filled with unique data, this behavior allows you to ensure that each period transmits a unique data frame. If the write queue is empty when communication starts, the first periodic transmit does not occur until you provide the first data frame with ncWriteObj. Period specifies the periodic rate, and Transmit by Response specifies whether to transmit the data of the previous period in response to a remote frame. If Transmit by Response is true, the data from the previous (periodic) transmit will be retransmitted in case a remote frame is received, even if there are frames pending in the write buffer. Receive Changes Only is ignored. Transmit by Response Only Transmit data frame for a specific ID only in response to a received remote frame. When you call ncWriteObj, the data is placed in the write queue, and remains there until a remote frame is received. The number of objects for the communication type usable at the same time is limited to 12. Period specifies a watchdog timeout. Transmit by Response is assumed as True regardless of the attribute setting. Receive Changes Only is ignored. Transmit Data by Call Transmit data frame when ncWriteObj is called. When ncWriteObj is called quickly, data frames are placed in the write queue for back to back transmit. Period specifies a minimum interval, and Transmit by Response specifies whether to transmit the previous data frame in response to a remote frame. Receive Changes Only is ignored. Transmit Periodic Waveform Transmit a fixed sequence of data frames over and over, one data frame every Period. The following steps describe typical usage of this type. Configure CAN Network Interface Object with Start On Open False, then open the Network Interface. Configure the CAN Object as Transmit Periodic Waveform and a nonzero Write Queue Length, then open the CAN Object. Call ncWriteObj for the CAN Object, once for every entry specified for the Write Queue Length. Use ncAction to start the Network Interface (not the CAN Object). The CAN Object transmits the first frame in the write queue, then waits the specified period, then transmits the second frame, and so on. After the last frame is transmitted, the CAN Objects waits the specified period, then transmits the first frame again. If you need to change the waveform contents at runtime, or if you need to transmit very large waveforms (more than 100 frames), we recommend using the Transmit Data Periodically type. Using that type, you can write frames to the Write Queue until full (overflow error), then wait some time for a few frames to transmit, then continue writing new frames. This communication type has the following limitations: Write Queue Length must be greater than zero. You must write exactly Write Queue Length values before starting communication (no less). Once communication is started, you cannot write additional values. Period specifies the periodic rate. Transmit by Response and Receive Changes Only are ignored.
	Transmit By Response applies only to Communication Type of Transmit Data by Call and Transmit Data Periodically (ignored for other types). For those configurations, Transmit By Response specifies whether the CAN Object should automatically respond with the previously transmitted data frame when it receives a remote frame. When set to False (default), the CAN Object transmits data frames only as configured, and ignores all remote frames for its ID. When set to True, the CAN Object responds to incoming remote frames.
	Data Length specifies the number of bytes in the data frames for the ID of the CAN Object. This number is placed in the Data Length Code (DLC) of all transmitted data frames and remote frames for the CAN Object. This is also the number of data bytes returned from ncReadObj when the communication type indicates receive.

Examples of Different Communication Types

The following figures demonstrate how you can use the Communication Type attribute for actual network data transfer. Each figure shows two separate NI-CAN applications that are physically connected across a CAN network.

The following figure shows a CAN Object that periodically transmits data to another CAN Object. The receiving CAN Object can queue up to five data values.

Example of Periodic Transmission

The following figure shows a CAN Object that polls data from another CAN Object. NI-CAN transmits the CAN remote frame when you call ncWriteObj.vi.

Example of Polling Remote Data Using ncWriteObj.vi

The following figure shows a CAN Object that polls data from another CAN Object. NI-CAN transmits the remote frame periodically and places only changed data into the read queue.

Example of Periodic Polling of Remote Data

Error in describes error conditions occurring before the VI executes. If an error has already occurred, the VI returns the value of the Error in cluster in Error out.

	status is True if an error occurred. If status is True, the VI does not perform any operations.
	code is the error code number identifying an error. A value of 0 means success. A negative value means error: VI did not execute the intended operation. A positive value means warning: VI executed intended operation, but an informational warning is returned. For a description of the code, wire the error cluster to a LabVIEW error-handling VI, such as the Simple Error Handler.
	source identifies the VI where the error occurred.

Output

Error out describes error conditions. If the Error in cluster indicated an error, the Error out cluster contains the same information. Otherwise, Error out describes the error status of this VI.

	status is True if an error occurred.
	code is the error code number identifying an error. A value of 0 means success. A negative value means error: VI did not execute the intended operation. A positive value means warning: VI executed intended operation, but an informational warning is returned. For a description of the code, wire the error cluster to a LabVIEW error-handling VI, such as the Simple Error Handler.
	source identifies the VI where the error occurred.

Description

The CAN Object provides read/write access to a specific ID on the network.

You normally call ncConfigCANNet before this VI in order to configure the Network Interface attributes, then call ncConfigCANObj for each CAN Object desired.

If you intend to use RTSI features to synchronize the CAN Object with other National Instruments cards, refer to the ncConfigCANObjRTSI VI.

When a network frame is transmitted on a CAN-based network, it always begins with the arbitration ID. This arbitration ID is primarily used for collision resolution when more than one frame is transmitted simultaneously, but often is also used as a simple mechanism to identify data. The CAN arbitration ID, along with its associated data, is referred to as a CAN Object.

The NI-CAN implementation of CAN provides high-level access to CAN Objects on an individual basis. You can configure each CAN Object for different forms of communication (such as periodic polling, receiving unsolicited CAN data frames, and so on). After you configure a CAN Object and open it for communication, use the ncReadObj and ncWriteObj VIs to access the data of the CAN Object. The NI-CAN driver performs all other details regarding the object.

previous page start next page