ncGetAttr.vi

NI-CAN

ncGetAttr.vi

Purpose

Get the value of an object attribute.

Format

Input

ObjHandle in is the object handle from the previous NI-CAN VI. The handle originates from the ncOpen VI.
AttrId specifies the attribute to get.

Baud Rate

Returns the value of the Baud Rate as configured with ncSetAttr.vi.

Form Factor

Returns the form factor of the card on which the Network Interface or CAN Object is located.

The returned Form Factor is an enumeration.

0 PCI

1 PXI

2 PCMCIA

3 AT

4 USB

Interface Number

Returns the Interface Number of the port on which the Network Interface or CAN Object is located.

This is the same number that you used in the ObjName string of the previous Config and Open VIs.

LIN Checksum Type

Returns the value of the LIN Checksum Type attribute as configured with ncSetAttr.vi.

LIN Enable DLC Check

Returns the value of the LIN Enable DLC Check attribute as configured with ncSetAttr.vi.

LIN Log Wakeup

Returns the value of the LIN Log Wakeup attribute as configured with ncSetAttr.vi.

0 FALSE (default)

1 TRUE

LIN Response Timeout

Returns the value of the LIN Response Timeout attribute as configured with ncSetAttr.vi.

LIN Sleep

Returns the value of the LIN Sleep attribute. This attribute may be updated by the user with ncSetAttr.vi or by the reception of a wakeup signal on the LIN bus.

Listen Only?

Returns the Listen Only? attribute as configured with ncSetAttr.vi.

Log Bus Errors?

Returns the value of the Log Bus Errors? attribute as configured with ncSetAttr.vi.

Log Comm Warnings

Returns TRUE or FALSE depending on whether communication warnings (including transceiver faults) were logged to the Network Interface read queue. For more information, refer to this attribute in ncSetAttr.vi.

Log Start Trigger?

Returns the value of the Log Start Trigger? attribute as configured with ncSetAttr.vi.

Log Transceiver Faults?

Returns the value of the Log Transceiver Faults? attribute as configured with ncSetAttr.vi.

Master Timebase Rate

Returns the present Master Timebase Rate in MHz, programmed into the CAN Series 1 or Series 2 hardware. For PCMCIA, this attribute will always return 10 MHz.

For the 847x series CAN and LIN interfaces, this attribute returns the value that was automatically detected.

Object State

Returns the current state bit mask of the object. Polling with ncGetAttr provides an alternative method of state detection than ncWaitForState or ncCreateOccur. For more information on the states returned from this attribute, refer to the DesiredState input of ncWaitForState.

Protocol Version

For NI-CAN, this returns 02000200 hex, which corresponds to version 2.0B of the Bosch CAN specification and 2.0 of the LIN specification. For more information on the encoding of the version, refer to Software Version.

This attribute is available only from the Network Interface, not CAN Objects.

Read Entries Pending

Returns the number of frames available in the read queue. Polling the available frames with this attribute can be used as an alternative to the ncWaitForState and ncCreateOccur VIs.

ReadMult Size for Notification

Returns the number of frames used as a threshold for the Read Multiple state. For more information, refer to this attribute in ncSetAttr.

Receive Error Counter

Returns the Receive Error Counter from the SJA1000 CAN controller. This Receive Error Counter is specified in the Bosch CAN standard as well as ISO CAN standards.

This attribute is unsupported for Series 1 hardware (returns error). This attribute is available only from the Network Interface, not CAN Objects.

Self Reception?

Returns the Self Reception attribute as configured with ncSetAttr.vi.

Serial Number

Returns the Serial Number of the card on which the Network Interface or CAN Object is located.

Series

Returns the Series of the card on which the Network Interface or CAN Object is located.

Series 1 hardware products use the Intel 82527 CAN controller.

Series 2 hardware products use the Philips SJA1000 CAN controller, plus improved RTSI synchronization features.

The 847x and 847x with Sync series CAN hardware products use the Philips SJA1000 CAN controller. The 847x and 847x with Sync series LIN hardware products use the AMTEL ATA6620 LIN controller.

The 847x with Sync series hardware products add synchronization features to the 847x hardware products.

The returned Series is an enumeration.

0

Series 1

1

Series 2

2

847x

3

847x with Sync

Series 2 Comparator

Returns the Series 2 Comparator attribute as configured with ncSetAttr.

This attribute is available only from the Network Interface, not CAN Objects.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

Series 2 Error/Arb Capture

Returns the current values of the Error Code Capture register and Arbitration Lost Capture register from the Philips SJA1000 CAN controller chip.

The Error Code Capture register provides information on bus errors that occur according to the CAN standard. A bus error increments either the Transmit Error Counter or the Receive Error Counter. When communication starts on the interface, the first bus error is captured into the Error Code Capture register, and retained until you get this attribute. After you get this attribute, the Error Code Capture register is again enabled to capture information for the next bus error.

The Arbitration Lost Capture register provides information on a loss of arbitration during transmits. Loss of arbitration is not considered an error. When communication starts on the interface, the first arbitration loss is captured into the Arbitration Lost Capture register, and retained until you get this attribute. After you get this attribute, the Arbitration Lost Capture register is again enabled to capture information for the next arbitration loss.

For each of the capture registers, a single-bit New flag indicates whether a new error has occurred since the last Get. If the New flag of a register is set, the associated fields contain new information. If the New flag of a register is clear, the associated fields are the same as the previous Get.

This attribute is commonly used with the Single Shot Transmit? attribute. When a Write function is used to transmit the single frame, you can get this attribute to determine if the transmit was successful. If the single shot transmit was not successful, this attribute provides detailed information for the failure.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error). Since the information and bit format is very specific to the Philips SJA1000 CAN controller on Series 2 and 847x CAN hardware, National Instruments cannot guarantee compatibility for this attribute on future hardware series. When using this attribute in the application, it is best to get the Series to verify that the hardware is Series 2, 847x, or 847x with Sync.

The following figure and the associated tables describe the format of bit fields in this attribute. The lowest byte (bits 0–7) corresponds to the Error Code Capture register. The next byte (bits 8–15) corresponds to the Arbitration Lost Capture register. Bit 16 (00010000 hex) is the New flag for the Error Code Capture fields. Bit 17 (00020000 hex) is the New flag for the Arbitration Lost Capture field. Bits marked as "X" are reserved, and should be ignored by the application.

Series 2 Error/Arb Capture Format

SEG Field of the Error Code Capture Register

Value in SEG Field Meaning
0 No error (ignore DIR and ERRC as well)
2 ID.28 to ID.21 (most significant bits of identifier)
3 Start of frame
4 Bit SRTR (RTR for standard frames)
5 Bit IDE
6 ID.20 to ID.18
7 ID.17 to ID.13
8 CRC sequence
9 Reserved bit 0
10 Data field
11 Data length code
12 Bit RTR (RTR for extended frames)
13 Reserved bit 1
14 ID.4 to ID.0
15 ID.12 to ID.5
17 Active error flag
18 Intermission
19 Tolerate dominant bits
22 Passive error flag
23 Error delimiter
24 CRC delimiter
25 Acknowledge slot
26 End of frame
27 Acknowledge delimiter
28 Overload flag

DIR Field of the Error Code Capture Register

Value in DIR Field Meaning
0 TX; error occurred during transmission
1 RX; error occurred during reception

ERRC Field of the Error Code Capture Register

Value in ERRC Field Meaning
0 Bit error
1 Form error
2 Stuff error
3 Other type of error

ALC Field Contains the Arbitration Lost Capture Register

Value in ALC Field Meaning
0 ID.28 (most significant bit of identifier; first ID bit in frame)
1 ID.27
2 ID.26
3 ID.25
4 ID.24
5 ID.23
6 ID.22
7 ID.21
8 ID.20
9 ID.19
10 ID.18
11 SRTR (RTR for standard frames)
12 IDE
13 ID.17 (extended frames only)
14 ID.16 (extended frames only)
15 ID.15 (extended frames only)
16 ID.14 (extended frames only)
17 ID.13 (extended frames only)
18 ID.12 (extended frames only)
19 ID.11 (extended frames only)
20 ID.10 (extended frames only)
21 ID.9 (extended frames only)
22 ID.8 (extended frames only)
23 ID.7 (extended frames only)
24 ID.6 (extended frames only)
25 ID.5 (extended frames only)
26 ID.4 (extended frames only)
27 ID.3 (extended frames only)
28 ID.2 (extended frames only)
29 ID.1 (extended frames only)
30 ID.0 (extended frames only)
31 SRTR (RTR for extended frames)

NEWECC Field is the New Flag for the Error Code Capture Register

Value in NEWECC Field Meaning
0 SEG, DIR, and ERRC fields contain the same value as the last Get of this attribute. If no error has occurred since the start of communication, all fields are zero.
1 SEG, DIR, and ERRC fields contain information for a new bus error.

NEWALC Field is the New Flag for the Arbitration Lost Capture Register

Value in NEWALC Field Meaning
0 ALC field contains the same value as the last Get of this attribute.
1 ALC field contains information for a new arbitration loss.

Series 2 Filter Mode

Returns the Series 2 Filter Mode attribute as configured with ncSetAttr.

This attribute is available only from the Network Interface, not CAN Objects.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

Series 2 Mask

Returns the Series 2 Mask attribute as configured with ncSetAttr.

This attribute is available only from the Network Interface, not CAN Objects.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

Single Shot Transmit?

Returns the Single Shot Transmit attribute as configured with ncSetAttr.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

Software Version

Version of the NI-CAN software, with major, minor, update, and beta build numbers encoded in the U32 from high to low bytes. For example, 2.0.1 would be 02000100 hex, and 2.1beta5 would be 02010005 hex.

This attribute is provided for backward compatibility. ncGetHardwareInfo.vi provides more complete version information.

Termination

Returns the value of the Termination attribute as configured with ncSetAttr.vi.

Timeline Recovery

Returns the Timeline Recovery attribute for the CAN Network Interface Object.

Timestamp Format

Returns the present Timestamp Format programmed into the CAN or LIN hardware. This attribute applies to the entire card.

Transceiver External Inputs

Returns the Transceiver External Inputs for the Network Interface.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

Series 2 XS cards enable connection of an external transceiver. For an external transceiver, this attribute allows you to determine the input voltage on the STATUS pin of the CAN port.

For many models of CAN transceiver, an NERR pin is provided for detection of faults and other status. For such transceivers, you can wire the NERR pin to the STATUS pin of the CAN port.

This attribute is supported for Series 2 XS cards only (returns error for non-XS cards).

This attribute uses a bit mask. When using the attribute, use bitwise AND operations to check for values, not equality checks (equal, greater than, and so on).

00000001 hex STATUS

This bit is set when 5 V exists on the STATUS pin.

This bit is clear when 0 V exists on the STATUS pin.

Transceiver External Outputs

Returns the Transceiver External Outputs for the Network Interface.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

Series 2 XS cards enable connection of an external transceiver. For an external transceiver, this attribute allows you to determine the output voltage on the MODE0 and MODE1 pins of the CAN port, and it allows you to determine if the CAN controller chip is sleeping.

For more information on the format of the value returned in this attribute, refer to the description of Transceiver External Outputs in ncSetAttr.vi.

This attribute is supported for Series 2 XS cards only (returns error for non-XS cards).

Transceiver Mode

Returns the Transceiver Mode for the Network Interface.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

This attribute is not supported for Series 1 CAN, 847x LIN, or 847x with Sync LIN interfaces (returns error).

For Series 2 cards for the PCMCIA form factor, this property requires a corresponding Series 2 cable (dongle). For information on how to identify the series of the PCMCIA cable, refer to Series 2 Vs. Series 1.

The Transceiver Mode changes when you set the mode within the application, or when a remote wakeup transitions the interface from Sleep to Normal mode. For more information, refer to ncSetAttr.vi.

This attribute uses the following values:

0 (Normal)

Transceiver is awake in normal communication mode.

1 (Sleep)

Transceiver and the CAN controller chip are both in sleep mode.

2 (Single Wire Wakeup)

Single Wire transceiver is in Wakeup Transmission mode.

3 (Single Wire High-Speed)

Single Wire transceiver is in High-Speed Transmission mode.

Transceiver Type

Returns the type of transceiver for the Network Interface. For hardware other than Series 2 XS cards, the Transceiver Type is fixed. For Series 2 XS cards, the Transceiver Type reflects the most recent value specified by MAX or ncSetAttr.vi.

This attribute is available only for the Network Interface, not CAN Objects. Nevertheless, the attribute applies to communication by CAN Objects as well as the associated Network Interface.

This attribute is not supported on the PCMCIA form factor.

This attribute uses the following values:

0 (High-Speed)

Transceiver type is High-Speed (HS).

1 (Low-Speed/Fault-Tolerant)

Transceiver type is Low-Speed/Fault-Tolerant (LS).

2 (Single Wire)

Transceiver type is Single Wire (SW).

3 (External)

Transceiver type is External. This transceiver type is available on Series 2 XS cards only. For more information, refer to ncSetAttr.vi.

4 (Disconnect)

Transceiver type is Disconnect. This transceiver type is available on Series 2 XS cards only. For more information, refer to ncSetAttr.vi.

5 LIN

Transceiver type is LIN.

Transmit Error Counter

Returns the Transmit Error Counter from the Philips SJA1000 CAN controller. This Transmit Error Counter is specified in the Bosch CAN standard as well as ISO CAN standards.

This attribute is unsupported for Series 1 hardware (returns error). This attribute is available only from the Network Interface, not CAN Objects.

Transmit Mode

Returns the Transmit Mode the CAN Network Interface Object is presently configured for.

The returned Transmit Mode is an enumeration.

0 Immediate Transmit

1 Timestamped Transmit

User RTSI Frame

Returns the User RTSI Frame attribute as configured with ncSetAttr.vi.

Virtual Bus Timing

Returns a Boolean value of True or False to indicate whether Virtual Bus Timing has been set or not for the specified virtual interface. This attribute is applicable to all CAN Objects opened on the virtual interface.

Write Entries Free

Returns the number of frames that can be accepted for a CAN or LIN Network Interface Object or CAN Object to write without causing overflow error.

Write Entries Pending

Returns the number of frames pending transmission in the write queue. If the intent is to verify that all pending frames have been transmitted successfully, waiting for the Write Success state is preferable to this attribute.

The Write Entries Pending attribute for 847x and 847x with Sync series CAN and LIN interfaces does not return the number of frames pending transmission in the write queue because the number does not take into account the frames in transit over the USB or waiting to be transmitted to the interface over the USB.

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.
AttrValue returns the attribute value specified by AttrId.
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

ncGetAttr gets the value of the attribute specified by AttrId from the object specified by ObjHandle. Within NI-CAN objects, you use attributes to access configuration settings, status, and other information about the object, but not data.