ncWriteNetMult.vi

Purpose

Write multiple frames to 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.
	NumberToWrite indicates the number of frames in the Data array to write to the Network Interface. This input is optional. When this input is unwired, the function will write all valid frames listed in the Data array. The NumberToWrite input is most useful when you have a large array of frames, and you only want to transmit a subset of that array.
	Data is an array of clusters. Each cluster represents a CAN frame to write. The cluster uses the typedef CanFrameTimed.ctl, the same typedef as ncReadNetMult.vi. 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 Frame Types. The maximum number of clusters you can provide to each ncWriteNetMult.vi is 512. For more information, refer to the Writing Large Numbers of Frames.
	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.

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

Use ncWriteNetMult.vi to place one or more frames into the Network Interface write queue. This function does not wait for the frames to be transmitted on the network.

Timestamped Transmit

In addition to supporting multiple frames, this function is preferable to ncWriteNet.vi in that it supports timestamped frames. To enable timestamped transmit, use ncSetAttr.vi to set the Transmit Mode attribute to Timestamped Transmit mode (1).

In Timestamped Transmit mode, NI-CAN times the transmission according to the difference in timestamps between consecutive frames. For example, if every frame provided to ncWriteNetMult.vi increments by 10 milliseconds, the frames will be transmitted with a 10 millisecond gap.

If the timestamp of one frame is less than the timestamp of the preceding frame, the timeline is reset, and both frames transmit back to back. For example, if you write a frame with relative timestamp 30 ms followed by a frame with timestamp 15 ms, the two frames will be transmitted back to back. This sort of behavior can occur when you transmit a logfile of timestamped frames repeatedly, because on the second traversal of the logfile, the timestamp of the first frame will be less than the timestamp of the last frame.

The first frame that you provide to ncWriteNetMult.vi always transmits immediately, regardless of its timestamp. If you need to delay transmission of first frame after start, you can write a Delay frame or Start Trigger frame as described in Frame Types.

Timestamped Transmit applies only to Series 1 and Series 2 interfaces.

847x CAN and LIN products do not support timestamped transmit. These products ignore the timestamp provided in the cluster for ncWriteNetMult.vi. If you use ncWriteNetMult.vi to write header and full frame types out of the USB LIN acting as master, then the frames will be transmitted together as closely as possible. If you use ncWriteNetMult.vi to write response frame types to the LIN interface acting as slave, then the frames will be loaded into the response table as quickly as possible.

Immediate Transmit

The default value for the Transmit Mode attribute is Immediate Transmit mode (0).

In Immediate Transmit mode, NI-CAN ignores the timestamp in each frame, and transmits the frames as fast as possible. This behavior is equivalent to the ncWriteNet.vi function, except that you can write multiple frames for transmission in quick succession.

Writing Large Numbers of Frames

Although NI-CAN provides a large write queue to store frames pending transmission, writing timestamped frames from a logfile with thousands of frames can eventually fill this queue.

When the Network Interface write queue cannot hold all frames provided, ncWriteNetMult.vi returns an overflow error. When this overflow error is returned, none of the frames provided in the Data array have been written. This enables your application to try the same Data array again at a later time.

To determine when adequate space is available in the write queue, retry ncWriteNetMult.vi with the Write Multiple state. The Write Multiple state will transition from false to true when space is available for at least 512 frames. Since you must limit the Data input of ncWriteNetMult.vi to 512 frames or less, the Write Multiple state indicates that a retry will succeed.

Another technique to recover from a write queue overflow is to use ncGetAttr.vi with the Write Entries Free attribute. Although this technique requires you to call ncGetAttr.vi periodically until the desired number of frame entries is available, it avoids the need to determine a proper Timeout for ncWaitForState.vi. When the time difference between frames varies from milliseconds to seconds, it may be difficult to determine how long to wait for entries to become available.

After writing a sequence of timestamped frames with ncWriteNetMult.vi, you cannot close the Network Interface, because you must wait for the last timestamped frame to transmit onto the network. You can wait for the final transmit to complete using ncWaitForState.vi with the Write Success state. You can also use ncGetAttr.vi with the Write Entries Pending attribute to query periodically, which provides the option of aborting the timestamped transmission by closing the Network Interface.

Frame Types

Within each cluster of the Data array, 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.

Cluster with IsRemote value 0: CAN Data Frame

Field Name	Data Type	Description
IsRemote		Value 0 specifies a CAN data frame. The CAN data frame transfers data on the network.
ArbitrationId		Specifies the arbitration ID to transmit in the CAN data frame. A standard ID (11-bit) is specified by default. In order to specify an extended ID (29-bit), OR in the bit mask 20000000 hex.
DataLength		Specifies the number of bytes in the Data array to transmit in the CAN data frame.
Data		Data bytes to transmit in the CAN data frame.
Timestamp		If the Transmit Mode attribute is Immediate Transmit (default), this field is ignored, and CAN frames transmit as quickly as possible. If the Transmit Mode attribute is Timestamped Transmit, this field specifies a timestamp. The timestamp is used to time transmission of CAN frames as described in Timestamped Transmit. The timestamp is a LabVIEW numeric DBL with Format and Precision of Absolute time (time and date) or Relative time (zero based). The integer part contains seconds, and the fractional part contains milliseconds and microseconds.

Cluster with IsRemote value 1: CAN Remote Frame

Field Name	Data Type	Description
IsRemote		Value 1 specifies a CAN remote frame. The CAN remote frame requests data for its arbitration ID.
ArbitrationId		Specifies the arbitration ID of the remote frame to transmit.
DataLength		Specifies the number of bytes requested. The value is transmitted in the CAN remote frame, but with no data.
Data		Ignored. No data bytes are contained in a CAN remote frame.
Timestamp		If the Transmit Mode attribute is Immediate Transmit (default), this field is ignored, and CAN frames transmit as quickly as possible. If the Transmit Mode attribute is Timestamped Transmit, this field specifies a timestamp. The timestamp is used to time transmission of CAN frames as described in Timestamped Transmit. The timestamp is a LabVIEW numeric DBL with Format and Precision of Absolute time (time and date) or Relative time (zero based). The integer part contains seconds, and the fractional part contains milliseconds and microseconds. You can use either absolute or relative time, because the timing is determined solely on the difference in the timestamps of sequential frames.

Cluster with IsRemote value 4: Start Trigger Frame

Field Name	Data Type	Description
IsRemote		Value 4 specifies a start trigger frame. When you use ncWriteNetMult.vi to write frames from a logfile for timestamped transmit, you can write the start trigger frame as the first frame. The start trigger frame reproduces the delay from start of communication to the first CAN frame. For example, if you write a start trigger frame followed by a CAN data frame with relative timestamp 20 ms, NI-CAN will delay 20 ms before transmitting the CAN data frame. If you write the CAN data frame without the start trigger frame, NI-CAN will transmit the CAN data frame immediately.
ArbitrationId		Value 0 is required.
DataLength		Value 1 is required.
Data		The single data byte in the array specifies the Timestamp Format (defined by ncSetAttr.vi) used for all subsequent CAN frames. The value is 0 for absolute timestamps, and 1 for relative timestamps. In order for NI-CAN to delay the proper time for the start trigger, this timestamp format must match the format used in all subsequent frames provided to ncWriteNetMult.vi.
Timestamp		Absolute timestamp of the start trigger. Within a logfile, this timestamp indicates the date and time at which CAN communication started. The timestamp is a LabVIEW numeric DBL 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 data/time information even when the CAN frames of a logfile use the relative format. When Data byte 0 specifies absolute format (0), the difference between this timestamp and the absolute timestamp of the subsequent CAN frame is used as the delay for transmit of that CAN frame. When Data byte 0 specifies relative format (1), this timestamp is ignored by NI-CAN, and the relative timestamp of the subsequent CAN frame is used as the transmit delay.

Cluster with IsRemote value 5: Delay Frame

Field Name	Data Type	Description
IsRemote		Value 5 specifies a delay frame. Use the delay frame to insert an additional delay between any two timestamped frames. For example, if you write a CAN frame with relative timestamp 20 ms, followed by a delay frame of 30 ms, followed by a CAN frame with timestamp 55 ms, NI-CAN will transmit the CAN frames 65 ms apart.
ArbitrationId		Value 0 is required.
DataLength		Value 0 is required.
Data		Ignored.
Timestamp		Specifies the delay to insert (not a timestamp). The delay is a LabVIEW numeric DBL with Format and Precision of Relative time. The integer part contains seconds, and the fractional part contains milliseconds and microseconds. The maximum delay supported is 180.0 seconds (3 minutes).

IsRemote value 16: LIN Response Entry Frame

Field Name	Data Type	Description
IsRemote		Value 16 represents a response entry frame for LIN communication. The behavior resulting from writing a response type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the LIN Sleep attribute is set to FALSE: A response entry frame is issued when it is desired to configure the LIN interface slave task to subscribe to or publish data, in response to a particular header ID received from a master task. Each response entry frame indicates the ID of the header for which it is to respond, whether the response is to publish data or subscribe to data, and if it is to publish data, the data length code (DLC) and data values. The DLC determines whether the response will be to subscribe (DLC = 0), or publish (DLC = data length), in response to a header containing the ID of the response frame. Sixty-four response entry frames (one for each of the sixty-four LIN IDs) may be written to the response queue in the LIN interface. When the Network Interface is created or reset, the interface is reset to act as a slave and to respond as subscriber to data for all LIN IDs. If the LIN Sleep attribute is set to TRUE: A response entry frame is issued when the LIN interface has been acting as a slave (processing master headers), has been put asleep, and is desired to be used to wake the bus and initiate the transmission of headers by the master. When the response entry type is written to the LIN interface, two things occur. First, the response queue is loaded with the ID, DLC, and data (if DLC is non-zero meaning the response is to publish), of the response entry frame. Next the interface transmits a wakeup break on the bus. Per the LIN specification, it either waits until the master acknowledges the wakeup break by writing a header within the specified time, or re-transmits the wakeup break if it does not. When the master responds with a header, the LIN interface sets the LIN Sleep attribute to FALSE, and responds to the ID contained in the header in the manner (publish or subscribe) specified for that ID in the response queue.
ArbitrationId		Zero to sixty-three.
DataLength		Zero if the response is to subscribe to data. Actual length of Data if the response is to publish data.
Data		Ignored if DataLength is zero. Data to publish if DataLength is non-zero.
Timestamp		Ignored.

IsRemote value 17: LIN Header Frame

Field Name	Data Type	Description
IsRemote		Value 17 represents a header frame for LIN communication. The behavior resulting from writing a header type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the LIN Sleep attribute is set to FALSE: A header frame is issued when it is desired to use the LIN interface as a master, querying a slave task to publish data. Issuing a header frame causes the LIN interface to write a break-sync-id sequence to the LIN bus, with the expectation that an external slave will publish data. Once a header frame is issued, the LIN interface will behave as a master until the next time it is started. If the LIN Sleep attribute is set to TRUE: A header frame is issued when the LIN interface has been acting as a master (transmitting header and full IsResponse types), has been put asleep, and is desired to be used to wake the LIN bus and query a slave task to publish data. Issuing a header frame causes the LIN interface to write a wakeup break followed by break-sync-id sequence to the LIN bus, with the expectation that all slaves will wake up and a slave task will publish data in response. The LIN interface also sets the LIN Sleep attribute to FALSE.
ArbitrationId		Zero to sixty-three.
DataLength		One to eight if the Enable DLC Check attribute is set to 1 (TRUE). If the Enable DLC Check attribute is set to 0 (FALSE), the data length is ignored.
Data		Ignored.
Timestamp		Ignored.

IsRemote value 18: LIN Full Frame

Field Name	Data Type	Description
IsRemote		Value 18 represents a full frame for LIN communication. The behavior resulting from writing a full type to the LIN interface depends upon whether the LIN Sleep attribute is set to TRUE or FALSE (the LIN interface is asleep or awake, respectively). If the LIN Sleep attribute is set to FALSE: A full frame is issued when it is desired to use the LIN interface as a master, publishing data to an external slave. Issuing a full frame causes the LIN interface slave task response queue to be updated, the master task to write a header to the LIN bus, then the LIN interface slave task to publish a response, with the expectation that one or more external slaves will subscribe to the data. Once a full frame is issued, the LIN interface will behave as a master until the next time it is started. If the LIN Sleep attribute is set to TRUE: A full frame is issued when the LIN interface has been acting as a master (transmitting header and full IsResponse types), has been put asleep, and is desired to be used to wake the LIN bus and publish data to one or more external slaves. Issuing a full frame causes the LIN interface slave task response queue to be updated, the master task to write a wakeup break followed by a header to the LIN bus, then the LIN interface slave task to publish a response, with the expectation that all slaves will wake up and one or more external slaves will subscribe to the published data. The LIN interface also sets the LIN Sleep attribute to FALSE.
ArbitrationId		Zero to sixty-three.
DataLength		One to eight.
Data		Data to publish.
Timestamp		Ignored.