ncReadNet.vi

NI-CAN

previous page next page

ncReadNet.vi

Purpose

Read single frame 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.
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.
Note  The description of the output 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 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 ncReadNet VI is useful when you need to process one frame at a time, because it returns separate outputs for ArbitrationId, Timestamp, and so on. In order to read multiple frames at a time, such as for high-bandwidth networks, use the ncReadNetMult VI.

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

When you call ncReadNet for an empty read queue (Read Available state false), the frame from the previous call to ncReadNet is returned again, along with the CanWarnOldData warning (status=F, code=3FF62009 hex).

When a frame arrives for a full read queue, NI-CAN discards the new frame, and the next call to ncReadNet returns the error CanErrOverflowRead (status=T, code= BFF62028 hex). If you detect this overflow, switch to using ncReadNetMult 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 CanWarnComm warning 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, 847x CAN, or 847x with Sync CAN interfaces 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 CAN 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.
previous page start next page