ncReadNetMult.vi

Purpose

Read multiple frames from 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.
	RequestedDataBufSize specifies the maximum number of frames desired. To empty the read queue, call ncGetAttr.vi for the Read Entries Pending attribute to get the actual number of frames in the read queue and use that number as the RequestedDataBufSize.
	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.
	ActualDataSize (Frames) specifies the number of frames returned in Data. This number is less than or equal to RequestedDataBufSize.
	Data returns an array of clusters. Each cluster in the array uses the typedef CanFrameTimed.ctl, with the following elements. Note  Within each cluster, IsRemote indicates the frame type. The frame type determines the interpretation of the remaining fields. For a description of each frame type, refer to the Frame Types section of this function reference.
	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

Since NI-CAN handles the read queue in the background, this VI does not wait for new frames to arrive. To ensure that new frames are available before calling ncReadNetMult, first wait for the Read Available state or Read Multiple state using ncWaitForState.vi.

When you call ncReadNetMult for an empty read queue (Read Available state false), Error out returns success (status=F, code=0), and ActualDataSize (Frames) returns 0.

When a frame arrives for a full read queue, NI-CAN discards the new frame, and the next call to ncReadNetMult returns the error CanErrOverflowRead (status=T, code= BFF62028 hex). If you detect this overflow, try to read in a relatively tight loop (few milliseconds each read).

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

You can use the Network Interface and CAN Objects simultaneously. When a CAN frame arrives from the network, NI-CAN first checks the ArbitrationId for an open CAN Object. If no CAN Object applies, NI-CAN checks the comparators and masks of the Network Interface (including the Series 2 Filter Mode attributes). If the frame passes that filter, NI-CAN places the frame into the read queue of the Network Interface.

Error Active, Error Passive, and Bus Off States

When the CAN communication controller transfers into the error passive state, NI-CAN returns the warning CanCommWarning (Status=F, code=3ff6200B hex) from read VIs.

When the transmit error counter of the CAN communication controller increments above 255, the network interface transfers into the bus off state as dictated by the CAN protocol. The network interface stops communication so that you can correct the defect in the network, such as a malfunctioning cable or device. When bus off occurs, NI-CAN returns the error CanCommError (status=T, code=BFF6200B hex) from read VIs.

If no CAN devices are connected to the network interface port, and you attempt to transmit a frame, the warning CanWarnComm is returned. This warning occurs because the missing acknowledgment bit increments the transmit error counter until the network interface reaches the error passive state, but bus off state is never reached.

For more information about low-speed communication error handling, refer to the Log Comm Warnings attribute in ncSetAttr.vi.

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

IsRemote Value 1: CAN Remote Frame

IsRemote Value 2: Communication Warning or Error Frame

IsRemote Value 3: RTSI Frame

IsRemote Value 4: Start Trigger Frame

IsRemote Value 6: CAN Bus Error Frame

Field Name	Data Type	Description
IsRemote		Value 6 represents a bus error frame. Refer to the attribute description for more information on Bus Error frames.
ArbitrationId		Zero.
DataLength		Four.
Data		0—Comm State (See description below) 1—Transmit Error Counter 2—Receive Error Counter 3—ECC Register 4—X 5—X 6—X 7—X Note: X means Reserved or Don’t Care. The first data byte (Comm State) indicates the current communication state of the CAN controller. The states are: 0—Error Active 1—Error Passive 2—Bus Off
Timestamp		Time when the bus error was detected.

IsRemote Value 7: Transceiver Fault Frame

Field Name	Data Type	Description
IsRemote		Value 7 represents a transceiver fault frame. Refer to the attribute description for more information on Transceiver Fault frames.
ArbitrationId		Zero.
DataLength		One.
Data		0—Transceiver fault (0=fault cleared, 1=fault present) 1—X 2—X 3—X 4—X 5—X 6—X 7—X
Timestamp		Time when the transceiver fault was detected.

IsRemote Value 18: LIN Full Frame

Field Name	Data Type	Description
IsRemote		Value 18 represents a full frame for LIN communication. A full frame is reported when the LIN interface has received one complete LIN frame. All frames for which the LIN interface is a subscriber will be reported. Frames for which the LIN interface is a publisher will be reported only if the Self Reception attribute is set to TRUE.
ArbitrationId		Zero to sixty-three.
DataLength		One to eight.
Data		LIN frame data.
Timestamp		Time at point of reception of LIN frame checksum.

IsRemote Value 19: LIN Wakeup Received Frame

Field Name	Data Type	Description
IsRemote		Value 19 represents a wakeup received frame for LIN communication. A wakeup received frame is reported when the LIN interface is asleep, the LIN Log Wakeup attribute is set to TRUE, and a wakeup event is detected.
ArbitrationId		Zero.
DataLength		Zero.
Data		Ignored.
Timestamp		Time at point of wakeup event detection.

IsRemote Value 20: LIN Bus Inactive Frame

Field Name	Data Type	Description
IsRemote		Value 20 represents a sleep frame for LIN communication. Sleep timeout detection begins when the LIN interface senses the first activity on the bus. When bus activity ceases, a sleep frame is reported if the inactivity lasts for more than four seconds.
ArbitrationId		Zero.
DataLength		Zero.
Data		Ignored.
Timestamp		Time at point of sleep timeout detection.

IsRemote Value 21: LIN Bus Error Frame

Field Name	Data Type	Description
IsRemote		Value 21 represents a LIN bus error frame for LIN communication. A LIN bus error frame is reported when the Log Bus Errors? attribute is set to TRUE, and a bus error occurs.
ArbitrationId		Zero.
DataLength		Varies depending on the error. Refer to the LIN Bus Error Codes and Descriptions table in ncSetAttr.vi for more information.
Data		Error frame information.
Timestamp		Time at point of bus error detection.

Note  If you use Time & Date format, LabVIEW limits the Seconds Precision to 3, which shows only milliseconds. The NI-CAN timestamp provides microsecond precision. If you need to view microsecond precision, change the timestamp to decimal format, with six digits of precision.