CAN Read.vi
Purpose
Read samples from a CAN task initialized as input. Samples are obtained from received CAN messages. The poly VI selection determines the data type to read.
To select the data type, right-click the VI, go to Select Type, and select the type by name. For LabVIEW 7.0 and later, you can right-click the VI and select Visible Items»Poly VI Selector to select the data type from within the diagram. For an overview of CAN Read, refer to the Read and Read Timestamped sections of Using the Channel API.
Format
Inputs
 | task reference in is the task reference from the previous NI-CAN VI. The task reference is originally returned from CAN Init Start.vi, CAN Initialize.vi, or CAN Create Message.vi, and then wired through subsequent VIs. The mode initialized for the task must be either Input or Timestamped Input. | ||||||
| number of samples to read specifies the number of samples to read for the task. For single-sample Poly VI types, CAN Read always returns one sample, so this input is ignored. | ||||||
 | 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.
|
Outputs
| task reference out is the same as task reference in. Wire the task reference to subsequent VIs for this task. | ||||||
| number of samples returned indicates the number of samples returned in the samples output. | ||||||
 | The poly output samples returns the samples read from received CAN messages. The type of the poly output is determined by the Poly VI selection. For information on the different poly VI types provided by CAN Read, refer to the Poly VI Types section. To select the data type, right-click the VI, go to Select Type, and select the type by name. | ||||||
| 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.
|
Poly VI Types
The name of each Poly VI type uses the following conventions:
- The first term is either Single-Chan or Multi-Chan. This indicates whether the type returns data for a single channel or multiple channels. Multi-Chan types return an array of analogous Single-Chan types, one entry for each channel initialized in channel list of CAN Init Start. Single-Chan types are convenient because no array indexing is required, but you are limited to reading only one CAN channel.
- The second term is either Single-Samp or Multi-Samp. This indicates whether the type returns a single sample, or an array of multiple samples. Single-Samp types are often used for single point control applications, such as within LabVIEW RT.
- The third term indicates the data type used for each sample. The word Dbl indicates double-precision (64-bit) floating point. The word Wfm indicates the waveform data type. The words 1D and 2D indicate one and two-dimensional arrays, respectively. The words Time & Dbl indicate a cluster of a LabVIEW timestamp and a double-precision sample.
Single-Chan Single-Samp Dbl
Returns a single sample for the first channel initialized in channel list.
If the initialized sample rate is greater than zero, this poly VI type waits for the next sample time, then returns a single sample. This enables you to execute a control loop at a specific rate.
If the initialized sample rate is zero, this poly VI immediately returns a single sample.
The samples output returns a single sample from the most recent message received. If no message has been received since you started the task, the Default Value of the channel is returned in samples.
You can use error out to determine whether a new message has been received since the previous call to CAN Read (or CAN Start). If no message has been received, the warning code 3FF62009 hex is returned in error out. If a new message has been received, the success code 0 is returned in error out.
To use this type, you must set the initialized mode to Input (not Timestamped Input).
Unless an error occurs, number of samples returned is one.
Multi-Chan Single-Samp 1D Dbl
Returns an array, one entry for each channel initialized in channel list. Each entry consists of a single sample.
The order of channel entries in samples is the same as the order in the original channel list.
If the initialized sample rate is greater than zero, this poly VI type waits for the next sample time, then returns a single sample for each channel. This enables you to execute a control loop at a specific rate.
If the initialized sample rate is zero, this poly VI immediately returns a single sample for each channel.
The samples output returns a single sample for each channel from the most recent message received. If no message has been received for a channel since you started the task, the Default Value of the channel is returned in samples.
You can specify channels in channel list that span multiple messages. A sample from the most recent message is returned for all channels.
You can use error out to determine whether a new message has been received since the previous call to CAN Read (or CAN Start). If no message has been received for one or more channels, the warning code 3FF62009 hex is returned in error out. If a new message has been received for all channels, the success code 0 is returned in error out.
To use this type, you must set the initialized mode to Input (not Timestamped Input).
Unless an error occurs, number of samples returned is one. The samples array is indexed by channel, and the entry for each channel contains a single sample.
If you need to determine the number of channels in the task after initialization, get the Number of Channels property for the task reference.
Single-Chan Multi-Samp 1D Dbl
Returns an array of samples for the first channel initialized in channel list.
The initialized sample rate must be greater than zero for this poly VI, because each sample in the array indicates the value of the CAN channel at a specific point in time. In other words, the sample rate specifies a virtual clock that copies the most recent value from CAN messages for each sample time. The changes in sample values from message to message enable you to view the CAN channel over time, such as for comparison with other CAN or DAQ input channels.
This VI waits until all samples arrive in time before returning. To avoid internal waiting within the VI, you can use CAN Get Property to obtain the Number Of Samples Pending, and pass that as the number of samples to read.
If the initialized sample rate is zero, this poly VI returns an error. If the intent is simply to read the most recent sample for a task, use the Single-Chan Single-Samp Dbl type.
If no message has been received since you started the task, the Default Value of the channel is returned in all entries of the samples array.
You can use error out to determine whether a new message has been received since the previous call to CAN Read (or CAN Start). If no message has been received, the warning code 3FF62009 hex is returned in error out. If a new message has been received, the success code 0 is returned in error out.
To use this type, you must set the initialized mode to Input (not Timestamped Input).
Unless an error occurs, the number of samples returned is equal to number of samples to read.
Multi-Chan Multi-Samp 2D Dbl
Returns an array, one entry for each channel initialized in channel list. Each entry consists of an array of samples.
The order of channel entries in samples is the same as the order in the original channel list.
The initialized sample rate must be greater than zero for this poly VI, because each sample in the array indicates the value of each CAN channel at a specific point in time. In other words, the sample rate specifies a virtual clock that copies the most recent value from CAN messages for each sample time. The changes in sample values from message to message enable you to view the CAN channels over time, such as for comparison with other CAN or DAQ input channels.
This VI waits until all samples arrive in time before returning. To avoid internal waiting within the VI, you can use CAN Get Property to obtain the Number Of Samples Pending, and pass that as the number of samples to read.
If the initialized sample rate is zero, this poly VI returns an error. If the intent is simply to read the most recent samples for a task, use the Multi-Chan Single-Samp 1D Dbl type.
If no message has been received for a channel since you started the task, the Default Value of the channel is returned in samples.
You can specify channels in channel list that span multiple messages. At each point in time, a sample from the most recent message is returned for all channels.
You can use error out to determine whether a new message has been received since the previous call to CAN Read (or CAN Start). If no message has been received for one or more channels, the warning code 3FF62009 hex is returned in error out. If a new message has been received for all channels, the success code 0 is returned in error out.
To use this type, you must set the initialized mode to Input (not Timestamped Input).
Unless an error occurs, the number of samples returned is equal to number of samples to read.
If you need to determine the number of channels in the task after initialization, get the Number of Channels property for the task reference.
Single-Chan Multi-Samp Wfm
Returns a single waveform for the first channel initialized in channel list.
The initialized sample rate must be greater than zero for this poly VI, because each sample in the array indicates the value of the CAN channel at a specific point in time. In other words, the sample rate specifies a virtual clock that copies the most recent value from CAN messages for each sample time. The changes in sample values from message to message enable you to view the CAN channel over time, such as for comparison with other CAN or DAQ input channels.
This VI waits until all samples arrive in time before returning. To avoid internal waiting within the VI, you can use CAN Get Property to obtain the Number Of Samples Pending, and pass that as the number of samples to read.
The start time of a waveform indicates the time of the first CAN sample in the array. The delta time of the waveform indicates the time between each sample in the array, as determined by the original sample rate.
If the initialized sample rate is zero, this poly VI returns an error. If the intent is to simply read the most recent sample for a task, use the Single-Chan Single-Samp Dbl type.
If no message has been received since you started the task, the Default Value of the channel is returned in all entries of the samples waveform.
You can use error out to determine whether a new message has been received since the previous call to CAN Read (or CAN Start). If no message has been received, the warning code 3FF62009 hex is returned in error out. If a new message has been received, the success code 0 is returned in error out.
To use this type, you must set the initialized mode to Input (not Timestamped Input).
Unless an error occurs, the number of samples returned is equal to number of samples to read.
Multi-Chan Multi-Samp 1D Wfm
Returns an array, one entry for each channel initialized in channel list. Each entry consists of a single waveform.
The order of channel entries in samples is the same as the order in the original channel list.
The initialized sample rate must be greater than zero for this poly VI, because each sample in the array of a waveform indicates the value of the CAN channel at a specific point in time. In other words, the sample rate specifies a virtual clock that copies the most recent value from CAN messages for each sample time. The changes in sample values from message to message enable you to view the CAN channel over time, such as for comparison with other CAN or DAQ input channels.
This VI waits until all samples arrive in time before returning. To avoid internal waiting within the VI, you can use CAN Get Property to obtain the Number Of Samples Pending, and pass that as the number of samples to read.
The start time of a waveform indicates the time of the first CAN sample in the array. The delta time of a waveform indicates the time between each sample in the array, as determined by the original sample rate.
If the initialized sample rate is zero, this poly VI returns an error. If the intent is simply to read the most recent samples for a task, use the Multi-Chan Single-Samp 1D Dbl type.
If no message has been received for a channel since you started the task, the Default Value of the channel is returned in samples.
You can specify channels in channel list that span multiple messages. At each point in time, a sample from the most recent message is returned for all channels.
You can use error out to determine whether a new message has been received since the previous call to CAN Read (or CAN Start). If no message has been received for one or more channels, the warning code 3FF62009 hex is returned in error out. If a new message has been received for all channels, the success code 0 is returned in error out.
To use this type, you must set the initialized mode to Input (not Timestamped Input).
Unless an error occurs, the number of samples returned is equal to number of samples to read.
If you need to determine the number of channels in the task after initialization, get the Number of Channels property for the task reference.
Single-Chan Multi-Samp 1D Time & Dbl
Returns an array of clusters. Each cluster corresponds to a received message for the first channel initialized in channel list. Each cluster contains the sample value, and a timestamp that indicates when the message was received.
To use this type, you must set the initialized mode to Timestamped Input (not Input).
The Timeout property determines whether this VI will wait for the number of samples to read messages to arrive from the network. The default value of Timeout is zero, but you can change it using CAN Set Property.vi.
If Timeout is greater than zero, the VI will wait for number of samples to read messages to arrive. If number of samples to read messages are not received before the Timeout expires, an error is returned. Timeout is specified as milliseconds.
If Timeout is zero, the VI will not wait for messages, but instead returns samples from the messages received since the previous call to CAN Read. The number of samples returned is indicated in the number of samples returned output, up to a maximum of number of samples to read messages. If no new message has been received, number of samples returned is 0, and error out indicates success.
Because the timing of values in samples is determined by when the message is received, the sample rate input is not used with this poly VI type.
Multi-Chan Multi-Samp 2D Time & Dbl
Returns an array, one entry for each channel initialized in channel list. Each entry consists of an array of clusters. Each cluster corresponds to a received message for the channels initialized in channel list. Each cluster contains the sample value, and a timestamp that indicates when the message was received.
The order of channel entries in samples is the same as the order in the original channel list.
To use this type, you must set the initialized mode to Timestamped Input (not Input).
You cannot specify channels in channel list that span multiple messages.
The Timeout property determines whether this VI waits for the number of samples to read messages to arrive from the network. The default value of Timeout is zero, but you can change it using CAN Set Property.vi.
If Timeout is greater than zero, the VI will wait for number of samples to read messages to arrive. If number of samples to read messages are not received before the Timeout expires, an error is returned. Timeout is specified as milliseconds.
If Timeout is zero, the VI will not wait for messages, but instead returns samples from the messages received since the previous call to CAN Read. The number of samples returned is indicated in the number of samples returned output, up to a maximum of number of samples to read messages. If no new message has been received, number of samples returned is 0, and error out indicates success.
Because the timing of values in samples is determined by when the message is received, the sample rate input is not used with this poly VI type.
If you need to determine the number of channels in the task after initialization, get the Number of Channels property for the task reference.