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

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.
DataLength		Indicates the number of data bytes in the Data array.
Data		The received data bytes (8 maximum).

IsRemote Value 1: CAN Remote Frame

Field Name	Data Type	Description
IsRemote		Value 1 represents a CAN remote frame. Only Series 2 or later can receive remote frames using the Network Interface. For Series 1 hardware, you must handle incoming remote frames with CAN Object only.
ArbitrationId		Specifies the arbitration ID to transmit in the CAN data frame.
DataLength		Returns the Data Length Code in the remote frame, but with no data.
Data		Ignored. No data bytes are contained in a CAN remote frame.

IsRemote Value 2: Communication Warning or Error Frame

Field Name	Data Type	Description
IsRemote		Value 2 represents a communication warning or error frame. This indicates a communication problem reported by the CAN controller or the low-speed CAN transceiver. This frame type occurs only when you set the Log Comm Warnings attribute to TRUE and the CAN controller is in the error passive state. For more information on communication problems, refer to the Description section of this function reference.
ArbitrationId		8000000B hex—Comm. error: General 4000000B hex—Comm. warning: General 8001000B hex—Comm. error: Stuffing 4001000B hex—Comm. warning: Stuffing 8002000B hex—Comm. error: Format 4002000B hex—Comm. warning: Format 8003000B hex—Comm. error: No Ack 4003000B hex—Comm. warning: No Ack 8004000B hex—Comm. error: Tx 1 Rx 0 4004000B hex—Comm. warning: Tx 1 Rx 0 8005000B hex—Comm. error: Tx 0 Rx 1 4005000B hex—Comm. warning: Tx 0 Rx 1 8006000B hex—Comm. error: Bad CRC 4006000B hex—Comm. warning: Bad CRC 0000000B hex—Comm. Error/warnings cleared 8000000C hex—Transceiver fault warning 0000000C hex—Transceiver fault cleared
DataLength		Ignored.
Data		Ignored.

IsRemote Value 3: RTSI Frame

Field Name	Data Type	Description
IsRemote		Value 3 represents a RTSI frame. This indicates when a RTSI input pulse occurred relative to incoming frames. This frame type occurs only when you set the RTSI Mode attribute to On RTSI Input–Timestamp event (refer to ncConfigCANNetRTSI.vi for details).
ArbitrationId		Is the special value 40000001 hex.
DataLength		The RTSI signal detected.
Data		Ignored.

IsRemote Value 4: Start Trigger Frame

Field Name	Data Type	Description
IsRemote		Value 4 represents the start trigger frame. When the Log Start Trigger attribute is enabled, this frame indicates the time when the start trigger occurs. For example, if you use ncConnectTerminals.vi to connect a RTSI input to the start trigger, this frame occurs when the RTSI input pulses for the first time. Another use case for logging the start trigger would be for logging the received CAN frames in a file. This ensures that the first frame in a logfile is a start trigger frame, which specifies the absolute time (date/time) at which CAN communication started.
ArbitrationId		Zero.
DataLength		One.
Data		The Data array contains a single byte that specifies the timestamp format used for all the subsequent CAN frames. The value is 0 for absolute timestamps, and 1 for relative timestamps.
Timestamp		This indicates the time of the start trigger in the absolute format. Within a logfile, this timestamp indicates the date and time at which communication started. The timestamp is a LabVIEW numeric double with Format and Precision of Absolute time (date/time). The format of this timestamp is always absolute, even when Data byte 0 specifies relative timestamp format. This absolute timestamp provides date/time information even when the CAN frames use the relative format.

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.