ncWriteNet.vi

NI-CAN

previous page next page

ncWriteNet.vi

Purpose

Write a single frame to a CAN or LIN Network Interface Object.

Format

Input

ObjHandle in is the object handle from the previous NI-CAN VI. The handle originates from the ncOpen VI.

Note The description of the input terminals is specified by the frame type. The value of IsRemote indicates the frame type. For a description of each frame type, refer to Frame Types.

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

ObjHandle out is the object handle for the next NI-CAN VI.

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

You use ncWriteNet to place a frame into the Network Interface write queue. Since NI-CAN handles the write queue in the background, this VI does not wait for the frame to be transmitted on the network.

To transmit a set of frames as quickly as possible, simply call ncWriteNet once per frame, without using ncWaitForState.vi after each write. This technique makes good use of the write queue to optimize frame transmission.

Once you have written frames, if you need to wait for the final ncWriteNet to be transmitted successfully, use ncWaitForState.vi with the Write Success state. The Write Success state sets when all frames of the write queue have been successfully transmitted. The Write Success state clears whenever you call ncWriteNet.

The ncWriteNet.vi and ncWriteNetMult.vi functions share a common write queue in the Network Interface. Therefore, when you set the Transmit Mode attribute to Timestamped Transmit, ncWriteNetMult.vi places timestamped frames into the queue, and ncWriteNet.vi places non-timestamped frames into the queue. If you write timestamped frames followed by a non-timestamped frame, the timestamped frames will transmit first, followed immediately by the non-timestamped frame. For example, assume you write 3 frames A, B, and C with ncWriteNetMult.vi, followed by frame D with ncWriteNet.vi, and frame E with ncWriteNetMult.vi. Frames A, B, and C will transmit in their timed sequence. Frame D immediately follows frame C. Frame E transmits with the expected time distance from frame C, because the non-timestamped frame does not affect ncWriteNetMult.vi timing.

Sporadic, recoverable errors on the network are handled automatically by the CAN protocol. As such, after ncWriteNet returns successfully, NI-CAN eventually transmits the frame on the network unless there is a serious network problem. Network problems such as missing or malfunctioning devices are often reported as the warning CanWarmComm (status=F, code=3FF6200B hex).

If the write queue is full, a call to ncWriteNet returns the error CanErrOverflowWrite (status=T, code= BFF62008 hex). In many cases, this error is recoverable, so you should not exit the application when it occurs. For example, if you want to transmit thousands of frames in succession (for example, downloading code), the application can check for the error CanErrOverflowWrite, and when detected, simply wait a few milliseconds for some of the frames to transmit, then call ncWriteNet again. If the second call to ncWriteNet returns an error, that can be treated as an unrecoverable error (no other device is ACKing the frames).

Although the Network Interface allows Write Queue Length of zero, this is not recommended, because every new frame will always overwrite the previous frame.

Frame Types

IsRemote indicates the frame type. The frame type determines the interpretation of the remaining fields. The following tables describe the fields of the cluster for each value of IsRemote.

To determine if your hardware supports one of the following frame types for this function, refer to Frame Types for CAN and LIN Hardware.

IsRemote value 0: CAN Data Frame

Field Name	Data Type	Description
IsRemote		Value 0 represents a CAN data frame. The CAN data frame contains data from the network.
ArbitrationId		Specifies the arbitration ID to transmit in the CAN data frame. A standard ID (11-bit) is specified by default. In order to specify an extended ID (29-bit), OR in the bit mask 20000000 hex.
DataLength		Indicates the number of data bytes in the Data array. If left unwired, a value of zero is assumed.
Data		Specifies the data bytes (8 maximum).

IsRemote value 1: CAN Remote Frame

Field Name	Data Type	Description
IsRemote		Value 1 represents a CAN remote frame.
ArbitrationId		Specifies the arbitration ID of the remote frame to transmit.
DataLength		Specifies the number of bytes requested. The value is transmitted in the CAN remote frame, but with no data.
Data		Ignored. No data bytes are contained in a CAN remote frame.

IsRemote value 16: LIN Response Entry Frame

Field Name	Data Type	Description
IsRemote		Value 16 represents a response entry frame for LIN communication. The behavior resulting from writing a response type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the LIN Sleep attribute is set to FALSE: A response entry frame is issued when it is desired to configure the LIN interface slave task to subscribe to or publish data, in response to a particular header ID received from a master task. Each response entry frame indicates the ID of the header for which it is to respond, whether the response is to publish data or subscribe to data, and if it is to publish data, the data length code (DLC) and data values. The DLC determines whether the response will be to subscribe (DLC = 0), or publish (DLC = data length), in response to a header containing the ID of the response frame. Sixty-four response entry frames (one for each of the sixty-four LIN IDs) may be written to the response queue in the LIN interface. When the Network Interface is created or reset, the interface is reset to act as a slave and to respond as subscriber to data for all LIN IDs. If the LIN Sleep attribute is set to TRUE: A response entry frame is issued when the LIN interface has been acting as a slave (processing master headers), has been put asleep, and is desired to be used to wake the bus and initiate the transmission of headers by the master. When the response entry type is written to the LIN interface, two things occur. First, the response queue is loaded with the ID, DLC, and data (if DLC is non-zero meaning the response is to publish), of the response entry frame. Next the interface transmits a wakeup break on the bus. Per the LIN specification, it either waits until the master acknowledges the wakeup break by writing a header within the specified time, or re-transmits the wakeup break if it does not. When the master responds with a header, the LIN interface sets the LIN Sleep attribute to FALSE, and responds to the ID contained in the header in the manner (publish or subscribe) specified for that ID in the response queue.
ArbitrationId		Zero to sixty-three.
DataLength		Zero if the response is to subscribe to data. Actual length of Data if the response is to publish data.
Data		Ignored if DataLength is zero. Data to publish if DataLength is non-zero.
Timestamp		Ignored.

IsRemote value 17: LIN Header Frame

Field Name	Data Type	Description
IsRemote		Value 17 represents a header frame for LIN communication. The behavior resulting from writing a header type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the LIN Sleep attribute is set to FALSE: A header frame is issued when it is desired to use the LIN interface as a master, querying a slave task to publish data. Issuing a header frame causes the LIN interface to write a break-sync-id sequence to the LIN bus, with the expectation that an external slave will publish data. Once a header frame is issued, the LIN interface will behave as a master until the next time it is started. If the LIN Sleep attribute is set to TRUE: A header frame is issued when the LIN interface has been acting as a master (transmitting header and full IsResponse types), has been put asleep, and is desired to be used to wake the LIN bus and query a slave task to publish data. Issuing a header frame causes the LIN interface to write a wakeup break followed by break-sync-id sequence to the LIN bus, with the expectation that all slaves will wake up and a slave task will publish data in response. The LIN interface also sets the LIN Sleep attribute to FALSE.
ArbitrationId		Zero to sixty-three.
DataLength		One to eight if the Enable DLC Check attribute is set to 1 (TRUE). If the Enable DLC Check attribute is set to 0 (FALSE), the data length is ignored.
Data		Ignored.
Timestamp		Ignored.

IsRemote value 18: LIN Full Frame

Field Name	Data Type	Description
IsRemote		Value 18 represents a full frame for LIN communication. The behavior resulting from writing a full type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the LIN Sleep attribute is set to FALSE: A full frame is issued when it is desired to use the LIN interface as a master, publishing data to an external slave. Issuing a full frame causes the LIN interface slave task response queue to be updated, the master task to write a header to the LIN bus, then the LIN interface slave task to publish a response, with the expectation that one or more external slaves will subscribe to the data. Once a full frame is issued, the LIN interface will behave as a master until the next time it is started. If the LIN Sleep attribute is set to TRUE: A full frame is issued when the LIN interface has been acting as a master (transmitting header and full IsResponse types), has been put asleep, and is desired to be used to wake the LIN bus and publish data to one or more external slaves. Issuing a full frame causes the LIN interface slave task response queue to be updated, the master task to write a wakeup break followed by a header to the LIN bus, then the LIN interface slave task to publish a response, with the expectation that all slaves will wake up and one or more external slaves will subscribe to the published data. The LIN interface also sets the LIN Sleep attribute to FALSE.
ArbitrationId		Zero to sixty-three.
DataLength		One to eight.
Data		Data to publish.
Timestamp		Ignored.

previous page start next page