ncConfig
Purpose
Configure an object before using it.
Format
| NCTYPE_STATUS | ncConfig(
|
Input
ObjName
ASCII name of the object to configure.
The 847x and 847x with Sync series LIN interfaces do not support ncConfig.
NumAttrs
Number of configuration attributes.
AttrIdList
List of configuration attribute identifiers.
AttrValueList
List of configuration attribute values.
Output
Return Value
Status of the function call, returned as a signed 32-bit integer. Zero means the function executed successfully. Negative specifies an error, meaning the function did not perform expected behavior. Positive specifies a warning, meaning the function performed as expected, but a condition arose that might require attention. For more information, refer to ncStatusToString.
Description
ncConfig initializes the configuration attributes of an object before opening it. The first NI-CAN function in the application will normally be ncConfig of the CAN Network Interface Object.
NumAttr indicates the number of configuration attributes in AttrIdList and AttrValueList. AttrIdList is an array of attribute IDs, and AttrValueList is an array of values. The host data type for each value in AttrValueList is NCTYPE_UINT32, which all configuration attributes can use.
The Frame API and Channel API cannot use the same CAN network interface simultaneously. If the CAN network interface is already initialized in the Channel API, this function returns an error.
The following sections describe how to use ncConfig with the Network Interface and CAN Object. The description for each object specifies the syntax for ObjName, plus a description of the commonly used attributes for AttrIdList.
CAN Network Interface Object
ObjName is the name of the CAN Network Interface Object to configure. This string uses the syntax "CANx ", where x is a decimal number starting at zero that indicates the CAN network interface (CAN0, CAN1, up to CAN63). CAN network interface names are associated with physical CAN ports using the Measurement & Automation Explorer (MAX).
The special ObjName values "CAN256" and "CAN257" refer to virtual interfaces. For virtual interfaces, the only valid attribute is NC_ATTR_START_ON_OPEN. All other attributes in the AttrIdList are ignored. The mask and comparator attributes are always zero for virtual interfaces (receive all frames).
For more information on usage of virtual interfaces, refer to Frame to Channel Conversion.
The following attribute IDs are commonly used for CAN Network Interface Object configuration.
For the 847x and 847x with Sync series CAN interfaces, only NC_ATTR_START_ON_OPEN and NC_ATTR_BAUD_RATE are valid configuration attributes. All other configuration attributes are ignored.
NC_ATTR_BAUD_RATE (Baud Rate)
Baud Rate is the baud rate to use for communication. Common baud rates are supported, including 33333, 83333, 100000, 125000, 250000, 500000, and 1000000. If you are familiar with the Bit Timing registers used in CAN controllers, you can use a special hexadecimal baud rate of 0x8000zzyy, where yy is the desired value for register 0 (BTR0), and zz is the desired value for register 1 (BTR1) of the CAN controller.
NC_ATTR_CAN_COMP_STD (Standard Comparator)
Standard Comparator is the CAN arbitration ID for the standard (11-bit) frame comparator. For information on how this attribute is used to filter received frames for the Network Interface, refer to the following NC_ATTR_CAN_MASK_STD (Standard Mask) attribute.
If you intend to open the Network Interface, most applications can set this attribute and the Standard Mask to 0 in order to receive all standard frames.
If you intend to use CAN Objects as the sole means of receiving standard frames from the network, you should disable all standard frame reception in the Network Interface by setting this attribute to the special value CFFFFFFF hex. With this setting, the Network Interface is best able to filter out incoming standard frames except those handled by CAN Objects.
NC_ATTR_CAN_COMP_XTD (Extended Comparator)
Extended Comparator is the CAN arbitration ID for the extended (29-bit) frame comparator. For information on how this attribute is used to filter extended frames for the Network Interface, refer to the following NC_ATTR_CAN_MASK_XTD (Extended Mask) attribute.
If you intend to open the Network Interface, most applications can set this attribute and the Extended Mask to 0 in order to receive all extended frames.
If you intend to use CAN Objects as the sole means of receiving extended frames from the network, you should disable all extended frame reception in the Network Interface by setting this attribute to the special value CFFFFFFF hex. With this setting, the Network Interface is best able to filter out incoming extended frames except those handled by CAN Objects.
NC_ATTR_CAN_MASK_STD (Standard Mask)
Standard Mask is the bitmask used in conjunction with the Standard Comparator attribute for filtration of incoming standard (11-bit) CAN frames. For each bit set in the mask, NI-CAN compares the corresponding bit in the Standard Comparator to the arbitration ID of the received frame. If the mask/comparator matches, the frame is stored in the Network Interface queue, otherwise it is discarded. Bits in the mask that are clear are treated as don't-cares. For example, hex 00000700 means to compare only the upper 3 bits of the 11-bit standard ID.
If you set the Standard Comparator to CFFFFFFF hex, this attribute is ignored, because all standard frame reception is disabled for the Network Interface.
Most applications can set this attribute and the Standard Comparator to 0 to receive all standard frames. This is particularly advisable for Series 2 hardware, because the Philips SJA1000 CAN controller does not support distinct filters for standard and extended IDs. For Series 2, nonzero values for this attribute are implemented in software, as an additional filter applied after the Series 2 Filter Mode. When you set this attribute to zero for Series 2, filtering is optimized to use only the Series 2 Filter Mode attribute for the SJA1000.
NC_ATTR_CAN_MASK_XTD (Extended Mask)
Extended Mask is the bitmask used in conjunction with the Extended Comparator attribute for filtration of incoming extended (29-bit) CAN frames. For each bit set in the mask, NI-CAN compares the corresponding bit in the Extended Comparator to the arbitration ID of the received frame. If the mask/comparator matches, the frame is stored in the Network Interface queue, otherwise it is discarded. Bits in the mask that are clear are treated as don't-cares. For example, hex 1F000000 means to compare only the upper 5 bits of the 29-bit extended ID.
If you set the Extended Comparator to CFFFFFFF hex, this attribute is ignored, because all extended frame reception is disabled for the Network Interface.
Most applications can set this attribute and the Extended Comparator to 0 to receive all extended frames. This is particularly advisable for Series 2 hardware, because the Philips SJA1000 CAN controller does not support distinct filters for standard and extended IDs. For Series 2, nonzero values for this attribute are implemented in software, as an additional filter applied after the Series 2 Filter Mode. When you set this attribute to zero for Series 2, filtering is optimized to use only the Series 2 Filter Mode attribute for the SJA1000.
NC_ATTR_LISTEN_ONLY (Listen Only)
Listen Only specifies whether to use the listen only feature of the Philips SJA1000 CAN controller.
NC_False disables listen only mode (default). Received frames are ACKnowledged, and frames can be transmitted using ncWrite.
NC_True enables listen only mode. The Network Interface and CAN Objects can only receive frames. The interface does not transmit on the network: no ACKnowledgements are transmitted for received frames, and ncWrite will return an error. The Philips SJA1000 CAN controller enters request/response state when listen only is enabled.
The listen only mode is not available on the Intel 82527 CAN controller used by Series 1 CAN hardware. For Series 1 hardware, this attribute must be left out of the AttrIdList.
NC_ATTR_NOTIFY_MULT_LEN (ReadMult Size for Notification)
Sets the number of frames used as a threshold for the Read Multiple state. For more information on the Read Multiple state, refer to ncWaitForState.
The default value is one half of Read Queue Length.
This attribute applies only to Series 1 and Series 2 interfaces.
NC_ATTR_READ_Q_LEN (Read Queue Length)
Read Queue Length is the maximum number of unread frames for the internal read queue of the CAN Network Interface Object. The recommended value is 100.
The internal read queue exists between the CAN hardware and the NI-CAN device driver. This internal read queue holds frames temporarily prior to transfer a larger queue in the NI-CAN device driver. The larger NI-CAN device driver queue grows as needed in order to accommodate high bus loads.
NC_ATTR_SELF_RECEPTION (Self Reception)
Specifies whether to echo successfully transmitted CAN or LIN frames into the read queue of the Network Interface and/or CAN Objects. Each reception occurs just as if the frame were received from another CAN or LIN device.
For self reception to operate properly, another CAN or LIN device node must receive and acknowledge each transmit. If a transmitted frame is not successfully acknowledged, it is not echoed into the read queue.
NC_False disables Self Reception mode (default). Transmitted frames do not appear in read queues.
NC_True enables Self Reception mode. Transmitted frames appear in read queues as if they were received from another CAN or LIN device.
The Self Reception mode is not available on the Intel 82527 CAN controller used by Series 1 CAN hardware. For Series 1 hardware, this attribute must be left out of the AttrIdList.
NC_ATTR_SERIES2_FILTER_MODE (Series 2 Filter Mode)
The Philips SJA1000 CAN controller provides sophisticated filtering of received frames. This attribute specifies the filtering mode, which is used in conjunction with the Series 2 Mask and Series 2 Comparator attributes.
This attribute is not supported for Series 1, 847x LIN, or 847x with Sync LIN interfaces (returns error). For Series 1, the Standard Mask/Comparator and Extended Mask/Comparator attributes are programmed directly into the Intel 82527 CAN controller. Use those attributes to specify filtering of received frames on Series 1 hardware.
The Philips SJA1000 does not support distinct standard and extended masking. Therefore, on Series 2 interfaces the Standard Mask/Comparator and Extended Mask/Comparator attributes are implemented in software (for backward compatibility). Since software masking can have an adverse impact on receive performance, National Instruments recommends that you disable software masking for Series 2 interfaces. Disable software masking by specifying don't-care (0) for all four mask/comparator attributes.
Since the format of the Series 2 filters is very specific to the Philips SJA1000 CAN controller, 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 NC_ATTR_HW_SERIES attribute to verify that the CAN hardware is Series 2, 847x, or 847x with Sync.
The filtering specified by this attribute and the Series 2 Mask/Comparator applies to the CAN Network Interface Object and all CAN Objects for that interface. For example, if you specify filters that discard ID 5, then open a CAN Object to receive ID 5, the CAN Object will not receive data.
The default value for this attribute is NC_FILTER_SINGLE_STANDARD.
This attribute uses the following values:
NC_FILTER_DUAL_EXTENDED (Dual Extended)
Filter all extended (29-bit) frames using a two separate mask/comparator filters. If either filter matches the frame, it is received. The frame is discarded only when neither filter detects a match.
The following figure describes the format of the Series 2 Mask and Series 2 Comparator attributes for this filter mode.
Mask/Comparator for Dual-Extended Filter Mode
Each Upper 16 ID filter compares the 16 most significant bits of the 29-bit extended ID.
NC_FILTER_DUAL_STANDARD (Dual Standard)
Filter all standard (11-bit) frames using a two separate mask/comparator filters. If either filter matches the frame, it is received. The frame is discarded only when neither filter detects a match.
The following figure describes the format of the Series 2 Mask and Series 2 Comparator attributes for this filter mode.
Mask/Comparator for Dual-Standard Filter Mode
Filter 1 includes the 11 Bit ID, the RTR bit, and the first data byte in the frame. Filter 2 includes the 11 bit ID, and the RTR bit (no data).
NC_FILTER_SINGLE_EXTENDED (Single Extended)
Filter all extended (29-bit) frames using a single mask/comparator filter.
The following figure describes the format of the Series 2 Mask and Series 2 Comparator attributes for this filter mode.
Mask/Comparator for Single-Extended Filter Mode
The 29 Bit ID compares all 29 bits of extended IDs. The RTR bit determines whether the filter compares remote (0) or data (1) frames. Bits marked as "X" are reserved, and should be cleared to zero by the application.
NC_FILTER_SINGLE_STANDARD (Single Standard)
Filter all standard (11-bit) frames using a single mask/comparator filter.
The following figure describes the format of the Series 2 Mask and Series 2 Comparator attributes for this filter mode.
Mask/Comparator for Single-Standard Filter Mode
The 11 Bit ID compares all 11 bits of standard IDs. The RTR bit determines whether the filter compares remote (1) or data (0) frames. Bits marked as X are reserved, and should be cleared to zero by the application. Data 0 compares the first data byte in the frame, and Data 1 compares the second data byte.
NC_ATTR_SERIES2_COMP (Series 2 Comparator)
Specifies the filter comparator for the Philips SJA1000 CAN controller. This attribute is not supported for Series 1, 847x LIN, or 847x with Sync LIN interfaces (returns error).
This attribute specifies a comparator value that is checked against the ID, RTR, and data bits. The NC_ATTR_SERIES2_MASK (Series 2 Mask) determines the applicable bits for comparison. The default value of this attribute is zero.
The mapping of bits in this attribute to the ID, RTR, and data bits of incoming frames is determined by the value of the NC_ATTR_SERIES2_FILTER_MODE (Series 2 Filter Mode) attribute. Refer to NC_ATTR_SERIES2_FILTER_MODE (Series 2 Filter Mode) attribute to understand the format of this attribute as well as the Series 2 Mask.
NC_ATTR_SERIES2_MASK (Series 2 Mask)
Specifies the filter mask for the Philips SJA1000 CAN controller. This attribute is not supported for Series 1, 847x LIN, or 847x with Sync LIN interfaces (returns error).
This attribute specifies a bit mask that determines the ID, RTR, and data bits that are compared. If a bit is clear in the mask, the corresponding bit in the NC_ATTR_SERIES2_COMP is checked. If a bit in the mask is set, that bit is ignored for the purpose of filtering (don't care). This interpretation is the opposite of the legacy Standard/Extended Mask attributes.
The default value of this attribute is hex FFFFFFFF, which means that all frames are received.
The mapping of bits in this attribute to the ID, RTR, and data bits of incoming frames is determined by the value of the NC_ATTR_SERIES2_FILTER_MODE attribute. Refer to NC_ATTR_SERIES2_FILTER_MODE to understand the format of this attribute as well as the Series 2 Comparator.
NC_ATTR_SINGLE_SHOT_TX (Single Shot Transmit)
Specifies whether to retry failed CAN frame transmissions (Series 2, 847x CAN, and 847x with Sync CAN interfaces only).
NC_False enables retry as defined in the CAN specification (default). If a CAN frame is not transmitted successfully, the CAN controller will immediately retry.
NC_True enables single-shot transmit behavior (no retry). If a CAN frame is not transmitted successfully, the CAN controller will not retry.
For Series 1, 847x LIN, and 847x with Sync interfaces, this attribute must be left out of the AttrIdList.
NC_ATTR_START_ON_OPEN (Start On Open)
Start On Open indicates whether communication starts for the CAN Network Interface Object (and all applicable CAN Objects) immediately upon opening the object with ncOpenObject.
For Series 1 and Series 2 interfaces, the default is NC_True (1), which starts communication when ncOpenObject is called. If you set Start On Open to NC_False (0), you can call ncSetAttribute after opening the interface, then ncAction to start communication. You can use the ncSetAttribute function to set attributes that are not contained within the ncConfig function.
For 847x interfaces, the default is NC_False (0).
NC_ATTR_WRITE_Q_LEN (Write Queue Length)
Write Queue Length is the maximum number of frames for the internal write queue of the CAN Network Interface Object awaiting transmission. The recommended value is 10.
The internal write queue exists between the CAN hardware and the NI-CAN driver. This internal write queue holds frames temporarily prior to transfer to CAN hardware from a larger queue in the NI-CAN device driver.
For more information on writing to the CAN Network Interface object, refer to ncWriteMult.
The following attribute ID is used to enable logging of transceiver faults.
NC_ATTR_LOG_COMM_ERRS (Log Comm Warnings)
Log Comm Warnings specifies whether to log communication warnings (including transceiver faults) to the Network Interface read queue.
When set to NC_False (default), the Network Interface reports CAN communication warnings (including transceiver faults) in the return status of read functions. For more information, refer to ncReadMult.
When set to NC_True, the Network Interface reports CAN communication warnings (including transceiver faults) by storing a special frame in the read queue. The communication warnings are not reported in the return status. For more information on communication warnings and errors, refer to ncReadMult. The special communication warning frame uses the following format:
Arbitration ID: Error/warning ID (refer to ncReadMult)
Timestamp: Time when error/warning occurred
IsRemote: 2
DataLength: 0
Data: N/A (ignore)
When calling ncRead or ncReadMult to read frames from the Network Interface, you typically use the IsRemote field to differentiate communications warnings from CAN frames. Refer to ncReadMult for more information.
RTSI is a bus that interconnects National Instruments DAQ, IMAQ, Motion, and CAN boards. This feature allows synchronization of DAQ, IMAQ, Motion, and CAN boards by allowing exchange of timing signals. Using RTSI, a device (board) can control one or more slave devices.
The following attribute IDs are used to enable RTSI synchronization between two or more National Instruments cards:
NC_ATTR_RTSI_MODE (RTSIMode)
RTSI Mode specifies the behavior of the Network Interface with respect to RTSI, including whether the RTSI signal is an input or output:
NC_RTSI_NONE
Disables RTSI behavior for the Network Interface (default). All other RTSI attributes are ignored.
NC_RTSI_OUT_ACTION_ONLY
The Network Interface will output the RTSI signal whenever the ncAction function is called with the Opcode value set to NC_OP_RTSI_OUT. This RTSI mode can be used to manually toggle/pulse a RTSI output within the application.
NC_RTSI_OUT_ON_RX
The Network Interface will output the RTSI signal whenever a CAN frame is stored in the read queue.
If the interface is Series 2, NI-CAN connects a terminal of the Philips SJA1000 CAN controller to the RTSI output. This hardware connection provides jitter in the nanoseconds range, enabling triggering of external oscilloscopes and so on.
NC_RTSI_OUT_ON_TX
The Network Interface will output the RTSI signal whenever a CAN frame is successfully transmitted from the write queue.
NC_RTSI_TIME_ON_IN
When the RTSI input transitions from low to high, a timestamp is measured and stored in the read queue of the Network Interface. The special RTSI frame uses the following format:
Arbitration ID: 40000001 hex
Timestamp: Time when RTSI input transitioned from low to high
IsRemote: 3 (NC_FRMTYPE_RTSI)
DataLength: RTSI signal detected (RTSI Signal)
Data: N/A (ignore)
When calling ncRead or ncReadMult to read frames from the Network Interface, use the IsRemote field to differentiate RTSI timestamps from CAN frames. Refer to ncReadMult for more information.
NC_RTSI_TX_ON_IN
The Network Interface will transmit a frame from its write queue when the RTSI input transitions from low to high. To begin transmission, at least one data frame must be written using ncWrite. If the write queue becomes empty due to frame transmissions, the last frame will be retransmitted on each RTSI pulse until another frame is provided using ncWrite.
NC_ATTR_RTSI_SIG_BEHAV (RTSI Behavior)
RTSI Behavior specifies whether to pulse or toggle a RTSI output. This attribute is ignored when RTSI Mode specifies input (detected low to high):
RTSI_SIG_PULSE
Pulse the RTSI output. For Series 1 CAN cards, the pulse is at least 100 µs. For Series 2 CAN interfaces, the pulse is at least 100 ns.
RTSI_SIG_TOGGLE
If the previous state was high, the output toggles low, then vice-versa.
NC_ATTR_RTSI_SIGNAL (RTSI Signal)
RTSI Signal defines the RTSI signal associated with the RTSI Mode. Valid values are 0 to 6,corresponding to RTSI 0 to RTSI 6 on other National Instruments cards.
Series 1 and 2 CAN interfaces each have limitations regarding RTSI. For information on these limitations, refer to Valid Combinations of Source/Destination in the ncConnectTerminals function of the Channel API for LabVIEW.
NC_ATTR_RTSI_SKIP (RTSI Skip)
RTSI Skip specifies the number of RTSI inputs (low-to-high transitions) to skip for RTSI input modes. It is ignored for RTSI output modes. For example, for RTSI Mode NC_RTSI_TIME_ON_IN, if the RTSI input transitions from low to high every 1 ms, RTSI Skip of 9 means that a timestamp will be stored in the read queue every 10 ms.
CAN Object
ObjName is the name of the CAN Object to configure. This string uses the syntax "CANx::STDy" or "CANx::XTDy". CANx is the name of the CAN network interface that you used for the preceding ncConfig function. STD indicates that the CAN Object uses a standard (11-bit)arbitration ID. XTD indicates that the CAN Object uses an extended (29-bit)arbitration ID. The number y specifies the actual arbitration ID of the CAN Object. The number y is decimal by default, but you also can use hexadecimal by adding "0x" to the beginning of the number. For example, "CAN0::STD25"indicates standard ID 25 decimal on CAN0, and "CAN1::XTD0x0000F652" indicates extended ID F652 hexadecimal on CAN1.
In order to configure one or more CAN Objects, you must configure the CAN Network Interface Object first.
The special virtual interface names "CAN256" and "CAN257" are not supported for CAN Objects.
The following attribute IDs are commonly used for CAN Object configuration:
NC_ATTR_COMM_TYPE (Communication Type)
Communication Type specifies the behavior of the CAN Object with respect to its ID, including the direction of data transfer:
NC_CAN_COMM_RX_BY_CALL (Receive By Call Using Remote)
Transmit remote frame for a specific ID by calling ncWrite. The CAN Object places the resulting data frame response in the read queue.
Period specifies a minimum interval, and Receive Changes Only specifies whether to place duplicate data frames into the read queue. Transmit by Response is ignored.
NC_CAN_COMM_RX_PERIODIC (Receive Periodic Using Remote)
Periodically transmit a remote frame for a specific ID in order to receive the associated data frame. Every Period, the CAN Object transmits a remote frame, and then places the resulting data frame response in the read queue. If the data frame is not received in response to the transmit remote frame, the periodic transmission is put on hold.
Period specifies the periodic rate, and Receive Changes Only specifies whether to place duplicate data frames into the read queue. Transmit by Response is ignored.
NC_CAN_COMM_RX_UNSOL (Receive Unsolicited)
Receive data frames for a specific ID.
This type is useful for receiving a few IDs (1-10) into dedicated read queues. For high performance applications (more IDs, fast frame rates), the Network Interface is recommended to receive all IDs.
Period specifies a watchdog timeout, and Receive Changes Only specifies whether to place duplicate data frames into the read queue. Transmit by Response is ignored.
NC_CAN_COMM_TX_BY_CALL (Transmit Data By Call)
Transmit data frame when ncWrite is called. When ncWrite is called quickly, data frames are placed in the write queue for back to back transmit.
Period specifies a minimum interval, and Transmit by Response specifies whether to retransmit the previous data frame in response to a remote frame. Receive Changes Only is ignored.
NC_CAN_COMM_TX_PERIODIC (Transmit Data Periodically)
Periodically transmit data frame for a specific ID. When the CAN Object transmits the last entry from the write queue, that entry is used every period until you provide a new data frame using ncWrite. If you keep the write queue filled with unique data, this behavior allows you to ensure that each period transmits a unique data frame.
If the write queue is empty when communication starts, the first periodic transmit does not occur until you provide the first data frame with ncWrite.
Period specifies the periodic rate, and Transmit by Response specifies whether to transmit the previous period data in response to a remote frame. If Transmit by Response is true, the data from the previous (periodic) transmit will be retransmitted in case a remote frame is received, even if there are frames pending in the write buffer. Receive Changes Only is ignored.
NC_CAN_COMM_TX_RESP_ONLY (Transmit By Response Only)
Transmit data frame for a specific ID only in response to a received remote frame. When you call ncWrite, the data is placed in the write queue, and remains there until a remote frame is received. The number of objects for the communication type usable at the same time is limited to 12.
Period specifies a watchdog timeout. Transmit by Response is assumed as True regardless of the attribute setting. Receive Changes Only is ignored.
NC_CAN_COMM_TX_WAVEFORM (Transmit Periodic Waveform)
Transmit a fixed sequence of data frames over and over, one data frame every Period.
The following steps describe typical usage of this type:
Configure CAN Network Interface Object with Start On Open False, then open the Network Interface.
Configure the CAN Object as Transmit Periodic Waveform and a nonzero Write Queue Length, then open the CAN Object.
Call ncWrite for the CAN Object, once for every entry specified for the Write Queue Length.
Use ncAction to start the Network Interface (not the CAN Object). The CAN Object transmits the first frame in the write queue, then waits the specified period, then transmits the second frame, and so on. After the last frame is transmitted, the CAN Objects waits the specified period, then transmits the first frame again.
If you need to change the waveform contents at runtime, or if you need to transmit very large waveforms (more than 100 frames), we recommend using the NC_CAN_COMM_TX_PERIODIC type. Using that type, you can write frames to the Write Queue until full (overflow error), then wait some time for a few frames to transmit, then continue writing new frames.
This communication type has the following limitations:
Write Queue Length must be greater than zero.
You must write exactly Write Queue Length values before starting communication (no less).
Once communication is started, you cannot write additional values.
Period specifies the periodic rate. Transmit by Response and Receive Changes Only are ignored.
NC_ATTR_DATA_LEN (DataLength)
Data Length specifies the number of bytes in the data frames for this CAN Object ID. This number is placed in the Data Length Code (DLC) of all transmitted data frames and remote frames for the CAN Object. This is also the number of data bytes returned from ncRead when the communication type indicates receive.
NC_ATTR_NOTIFY_MULT_LEN (ReadMult Size for Notification)
Sets the number of frames used as a threshold for the Read Multiple state. For more information on the Read Multiple state, refer to ncWaitForState.
The default value is one half of Read Queue Length.
NC_ATTR_PERIOD (Period)
Period specifies the rate of periodic behavior in milliseconds.
The behavior depends on the Communication Type as follows:
NC_CAN_COMM_RX_BY_CALL
Period specifies a minimum interval between subsequent transmissions. Even if ncWrite is called very frequently, frames are transmitted on the network at a rate no more than Period. Setting Period to zero disables the minimum interval timer.
NC_CAN_COMM_RX_PERIODIC
NC_CAN_COMM_RX_UNSOL
Period specifies the time between subsequent transmissions, and must be set greater than zero.
NC_CAN_COMM_TX_BY_CALL
NC_CAN_COMM_TX_PERIODIC
NC_CAN_COMM_TX_RESP_ONLY
Period specifies a watchdog timeout. If a frame is not received at least once every period, a timeout error is returned. Setting Period to zero disables the watchdog timer.
NC_CAN_COMM_TX_WAVEFORM
NC_ATTR_READ_Q_LEN (Read Queue Length)
Read Queue Length is the maximum number of unread frames for the read queue of the CAN Object. For more information, refer to ncRead.
If Communication Type is set to receive data, a typical value is 10. If Communication Type is set to transmit data, a typical value is 0.
NC_ATTR_RX_CHANGES_ONLY (Receive Changes Only)
Receive Changes Only applies only to Communication Type selections in which the CAN Object receives data frames (ignored for other types). For those configurations, Receive Changes Only specifies whether duplicated data should be placed in the read queue. When set to NC_False (default), all data frames for the CAN Object ID are placed in the read queue. When set to NC_True, data frames are placed into the read queue only if the data bytes differ from the previously received data bytes.
This attribute has no effect on the usage of a watchdog timeout for the CAN Object. For example, if this attribute is NC_True and you also specify a watchdog timeout, NI-CAN restarts the watchdog timer every time it receives a data frame for the CAN Object ID, regardless of whether the data differs from the previous frame in the read queue.
NC_ATTR_TX_RESPONSE (Transmit By Response)
Transmit By Response applies only to Communication Type of Transmit Data by Call and Transmit Data Periodically (ignored for other types). For those configurations, Transmit By Response specifies whether the CAN Object should automatically respond with the previously transmitted data frame when it receives a remote frame. When set to NC_False (default), the CAN Object transmits data frames only as configured, and ignores all remote frames for its ID. When set to NC_True, the CAN Object responds to incoming remote frames.
NC_ATTR_WRITE_Q_LEN (Write Queue Length)
Write Queue Length is the maximum number of frames for the write queue of the CAN Object awaiting transmission. For more information, refer to ncWrite.
If Communication Type is set to receive data, a typical value is 0. If Communication Type is set to transmit data, a typical value is 10.
RTSI is a bus that interconnects National Instruments DAQ, IMAQ, Motion, and CAN boards. This feature allows synchronization of DAQ, IMAQ, Motion, and CAN boards by allowing exchange of timing signals. Using RTSI, a device (board) can control one or more slave devices.
The following attribute IDs are used to enable RTSI synchronization between two or more National Instruments cards:
NC_ATTR_RTSI_FRAME (RTSI Frame)
RTSI Frame specifies a 4-byte pattern used to differentiate RTSI timestamps from CAN data frames. It is provided as a U32, and the high byte is stored as byte 0 from ncRead. For example, AABBCCDD hex is returned as AA in byte 0, BB in byte 1, and so on.
This attribute is used only for RTSI Mode NC_RTSI_TIME_ON_IN. It is ignored for all other RTSI Mode values.
NC_ATTR_RTSI_MODE (RTSIMode)
RTSI Mode specifies the behavior of the CAN Object with respect to RTSI, including whether the RTSI signal is an input or output:
NC_RTSI_NONE
Disables RTSI behavior for the CAN Object (default). All other RTSI attributes are ignored.
NC_RTSI_OUT_ACTION_ONLY
The CAN Object will output the RTSI signal whenever the ncAction function is called with Opcode NC_OP_RTSI_OUT. This RTSI mode can be used to manually toggle/pulse a RTSI output within the application.
NC_RTSI_OUT_ON_RX
The CAN Object will output the RTSI signal whenever a CAN frame is stored in its read queue.
In order to use this RTSI Mode, you must configure the CAN Object Communication Type to Receive Unsolicited.
NC_RTSI_OUT_ON_TX
The CAN Object will output the RTSI signal whenever a CAN frame is successfully transmitted.
In order to use this RTSI Mode, you must configure the CAN Object Communication Type to either Transmit Data by Call, Transmit Data Periodically, or Transmit Periodic Waveform.
NC_RTSI_TIME_ON_IN
When the RTSI input transitions from low to high, a timestamp is measured and stored in the read queue of the CAN Object. The special RTSI frame uses the following format:
Timestamp: Time when RTSI input transitioned from low to high.
NC_RTSI_TX_ON_IN
The CAN Object will transmit a frame from its write queue when the RTSI input transitions from low to high. To begin transmission, at least one data frame must be written using ncWrite. If the write queue becomes empty due to frame transmissions, the last frame will be retransmitted on each RTSI pulse until another frame is provided using ncWrite.
In order to use this RTSI Mode, you must configure the CAN Object Communication Type to either Transmit Data by Call, Transmit Data Periodically, or Transmit Periodic Waveform. The Period attribute is ignored when this RTSI mode is selected.
NC_ATTR_RTSI_SIG_BEHAV (RTSI Behavior)
RTSI Behavior specifies whether to pulse or toggle a RTSI output. This attribute is ignored when RTSI Mode specifies input (detected low to high):
RTSI_SIG_PULSE
Pulse the RTSI output. For Series 1 CAN cards, the pulse is at least 100 µs. For Series 2 CAN cards, the pulse is at least 100 ns.
RTSI_SIG_TOGGLE
If the previous state was high, the output toggles low, then vice-versa.
NC_ATTR_RTSI_SIGNAL (RTSI Signal)
RTSI Signal defines the RTSI signal associated with the RTSI Mode. Valid values are 0 to 6, corresponding to RTSI0 to RTSI6 on other National Instruments cards.
Series 1 and 2 CAN cards each have limitations regarding RTSI. For information on these limitations, refer to Valid Combinations of Source/Destination in the ncConnectTerminals function of the Channel API for LabVIEW.
NC_ATTR_RTSI_SKIP (RTSI Skip)
RTSI Skip specifies the number of RTSI inputs (low-to-high transitions) to skip for RTSI input modes. It is ignored for RTSI output modes. For example, for RTSI Mode NC_RTSI_TIME_ON_IN , if the RTSI input transitions from low to high every 1 ms, RTSI Skip of 9 means that a timestamp will be stored in the read queue every 10 ms.
Examples of Different Communication Types
The following figures demonstrate how you can use the Communication Type attribute for actual network data transfer. Each figure shows two separate NI-CAN applications that are physically connected across a CAN network.
The following figure shows a CAN Object that periodically transmits data to another CAN Object. The receiving CAN Object can queue up to five data values.
Example of Periodic Transmission
The following figure shows a CAN Object that polls data from another CAN Object. NI-CAN transmits the CAN remote frame when you call ncWrite.
Example of Polling Remote Data Using ncWrite
The following figure shows a CAN Object that polls data from another CAN Object. NI-CAN transmits the remote frame periodically and places only changed data into the read queue.
Example of Periodic Polling of Remote Data
Example of Periodic Polling of Remote Data
ncConfig is not supported for 847x LIN. This function is supported for 847x CAN, but the only two attributes in the CAN Network Interface Config cluster supported are NC_ATTR_START_ON_OPEN and NC_ATTR_BAUD_RATE.