nctCreateMessage
Purpose
Creates a message configuration and associated channel configurations within the application.
Format
| nctTypeStatus | nctCreateMessage(
|
Inputs
MessageConfig
Configures properties for a new message. This function creates a task for a single message with one or more channels. You provide the properties in a C struct.
The properties are similar to the message properties in MAX:
u32 MsgArbitrationID
Configures the arbitration ID of the message.
Use the Extended Boolean to specify whether the ID is standard (11-bit) or extended (29-bit).
u32 Extended
Configures a Boolean value that indicates whether the message arbitration ID is standard 11-bit format (0) or extended 29-bit format (1).
u32 MsgDataBytes
Configures the number of data bytes in the message. The range is 0 to 8.
NumberOfChannels
Specifies the number of channel configurations you provide in ChannelConfigList.
ChannelConfigList
Configures the list of channels for the new message. ChannelConfigList is an array of a C struct, with one C struct for each channel.
The properties of each channel are similar to the channel properties in MAX:
u32 StartBit
Configures the starting bit position in the message. The range is 0 (lowest bit in first byte), to 63 (highest bit in last byte).
u32 NumBits
Configures the number of bits in the message. The range is 1 to 64.
u32 DataType
Configures the data type of the channel in the message. Values are nctDataSigned, nctDataUnsigned, and nctDataFloat.
u32 ByteOrder
Configures the byte order of the channel in the message. Values are nctOrderIntel (little-endian), and nctOrderMotorola (big-endian).
f64 ScalingFactor
Configures the scaling factor used to convert raw bits of the message to/from scaled floating-point units. The scaling factor is the A in the linear scaling formula AX+B, where X is the raw data, and B is the scaling offset.
f64 ScalingOffset
Configures the scaling offset used to convert raw bits of the message to/from scaled floating-point units. The scaling offset is the B in the linear scaling formula AX+B, where X is the raw data, and A is the scaling factor.
f64 MaxValue
Configures the maximum value of the channel in scaled floating-point units.
The nctRead and nctWrite functions do not coerce samples when converting to/from CAN messages. You can use this value with the user-interface functions of the development environment to set the range of front-panel controls and indicators.
f64 MinValue
Configures the minimum value of the channel in scaled floating-point units.
The nctRead and nctWrite functions do not coerce samples when converting to/from CAN messages. You can use this value with the user-interface functions of the development environment to set the range of front-panel controls and indicators.
f64 DefaultValue
Configures the default value of the channel in scaled floating-point units.
For information on how the DefaultValue is used, refer to the nctRead and nctWrite functions.
const str Unit
Configures the unit string of the channel. The string is no more than 64 characters in length.
You can use this value to display units (such as volts or RPM) along with the samples of the channel.
Interface
Specifies the CAN interface to use for this task.
The interface input uses an enumeration in which value 0 selects CAN0, value 1 selects CAN1, and so on.
The default baud rate for the Interface is defined within MAX, but you can change it by setting the nctPropIntfBaudRate property with nctSetProperty.
The special interface values 256 and 257 refer to virtual interfaces. For more information on usage of virtual interfaces, refer to Frame to Channel Conversion.
Mode
Specifies the I/O mode for the task. For an overview of the I/O modes, including figures, refer to the Channel API Basic Programming Model.
nctModeInput
Input channel data from received CAN messages. Use the nctRead function to obtain input samples as single-point, array, or waveform. Each sample value that you write is transmitted in a message on the network. If you write an array or waveform, the samples are buffered for subsequent transmit.
Use this input mode to read waveforms of timed samples, such as for comparison with NI-DAQ or NI-DAQmx waveforms. You also can use this input mode to read a single point from the most recent message, such as for control or simulation.
nctModeOutput
Output channel data to CAN messages for transmit. Use the nctWrite function to write output samples as single-point, array, or waveform.
nctModeOutputRecent
Output channel data to CAN messages for transmit. This mode is used with sample rate greater than zero (periodic transmit). Use nctWrite to provide a single sample per channel. Each periodic message uses the sample values from the most recent nctWrite.
For this mode, there are restrictions on using channels in channel list that are contained in multiple messages. Refer to nctWrite for more information.
nctModeTimestampedInput
Input channel data from received CAN messages. Use the nctRead function to obtain input samples as an array of sample/timestamp pairs (refer to nctReadTimestamped).
Use this input mode to read samples with timestamps that indicate when each message is received from the network.
SampleRate
Specifies the timing to use for samples of the task. The sample rate is specified in Hertz (samples per second). A sample rate of zero means to sample immediately.
For Mode of NctModeInput, SampleRate of zero means nctRead returns a single point from the most recent message received, and greater than zero means nctRead returns samples timed at the specified rate.
For Mode of NctModeOutput, SampleRate of zero means CAN messages transmit immediately when nctWrite is called, and greater than zero means CAN messages are transmitted periodically at the specified rate.
For mode of nctModeOutputRecent, SampleRate must be greater than zero (periodic transmit).
For Mode of NctModeTimestampedInput, SampleRate is ignored.
When the Interface specifies a virtual interface (256 or 257), and Mode is nctModeOutput or nctModeOutputRecent, this SampleRate must be zero (greater than zero not supported).
Outputs
TaskRef
Use TaskRef with all subsequent functions to reference the task. Pass this task reference to nctStart before you read or write samples for the message.
Return Value
The return value indicates the status of the function call as a signed 32-bit integer. Zero means the function executed successfully. A negative value specifies an error, which means the function did not perform the expected behavior. A positive value specifies a warning, which means the function performed as expected, but a condition arose that may require attention.
Use the ncStatusToString function of the Frame API to obtain a descriptive string for the return value. The ncStatusToString and ncGetHardwareInfo functions are the only Frame API functions that can be called within a Channel API application.
Description
To use message and channel configurations from MAX or a CAN database, use the nctInitStart or nctInitialize functions. The nctCreateMessage function provides an alternative in which you create the message and channel configurations within the application, without use of MAX or a CAN database.
nctCreateMessage returns a task reference you wire to nctStart to start communication for the message and its channels.