ncWrite
Purpose
Write a single frame to a CAN or LIN Network Interface Object.
Format
| NCTYPE_STATUS | ncWrite(
|
Input
ObjHandle
Object handle.
DataSize
Size of the data in bytes.
DataPtr
Data written to the object. You provide the data using the pointer DataPtr.
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
ncWrite writes a single frame to the object specified by ObjHandle.
DataPtr points to the variable from which the data is written. Its type is undefined so that you can use the appropriate host data type. DataSize indicates the size of variable pointed to by DataPtr, and is used to verify that the size you provide is compatible with the configured write size for the object.
You use ncWrite to place data into the write queue of an object. Because NI-CAN handles the write queue in the background, this function does not wait for data to be transmitted on the network. To make sure that the data is transmitted successfully after calling ncWrite, wait for the NC_ST_WRITE_SUCCESS state. The NC_ST_WRITE_SUCCESS state transitions from false to true when the write queue is empty, and NI-CAN has successfully transmitted the last data item onto the network. The NC_ST_WRITE_SUCCESS state remains true until you write another data item into the write queue.
When communication starts, the NC_ST_WRITE_SUCCESS state is true by default.
When you configure an object to transmit data onto the network periodically, it obtains data from the object write queue each period. If the write queue is empty, NI-CAN transmits the data of the previous period again. NI-CAN transmits this data repetitively until the next call to ncWrite.
If an object write queue is full, a call to ncWrite returns the CanErrOverflowWrite error and NI-CAN discards the data you provide. One way to avoid this overflow error is to set the write queue length to zero. When ncWrite is called for a zero length queue, the data item you provide with ncWrite simply overwrites the previous data item without indicating an overflow. A zero length write queue is often useful when an object is configured to transmit data onto the network periodically, and you simply want to transmit the most recent data value each period. It is also useful when you plan to always wait for NC_ST_WRITE_SUCCESS after every call to ncWrite. You can use the NC_ATTR_WRITE_Q_LEN attribute to configure the write queue length.
For information on the proper data type to use with DataPtr, refer to the CAN Network Interface Object and CAN Object descriptions below.
Network Interface Object
The data type that you use with ncWrite of the Network Interface is NCTYPE_CAN_FRAME. When calling ncWrite, you should pass size of (NCTYPE_CAN_FRAME) for the DataSize parameter.
Within the NCTYPE_CAN_FRAME structure, the IsRemote (frame type) field determines the meaning of all other fields. The following tables describe the fields of NCTYPE_CAN_FRAME 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
NCTYPE_CAN_FRAME Fields for IsRemote NC_FRMTYPE_DATA (0)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | NC_FRMTYPE_DATA (0)
Transmit a CAN data frame. |
| ArbitrationId | NCTYPE_CAN_ARBID | Specifies the arbitration ID of the frame to transmit.
The NCTYPE_CAN_ARBID type is an unsigned 32-bit integer that uses the bit mask NC_FL_CAN_ARBID_XTD (0x20000000) to indicate an extended ID. A standard ID (11-bit) is specified by default. In order to specify an extended ID (29-bit), OR in the bit mask NC_FL_CAN_ARBID_XTD. |
| Data | Array of 8 NCTYPE_UINT8 | Specifies the data bytes of the frame. |
| DataLength | NCTYPE_UINT8 | Specifies the number of data bytes to transmit. This number of valid data bytes must be provided in Data. |
NCTYPE_CAN_FRAME fields for IsRemote NC_FRMTYPE_REMOTE (1)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | NC_FRMTYPE_REMOTE (1)
Transmit a CAN remote frame. Both Series 1 and Series 2 hardware can transmit remote frames using the Network Interface. |
| ArbitrationId | NCTYPE_CAN_ARBID | Specifies the arbitration ID of the frame to transmit.
The NCTYPE_CAN_ARBID type is an unsigned 32-bit integer that uses the bit mask NC_FL_CAN_ARBID_XTD (0x20000000) to indicate an extended ID. A standard ID (11-bit) is specified by default. In order to specify an extended ID (29-bit), OR in the bit mask NC_FL_CAN_ARBID_XTD. |
| Data | Array of 8 NCTYPE_UINT8 | Remote frames do not contain data, so this array is empty. |
| DataLength | NCTYPE_UINT8 | Specifies the Data Length Code to transmit in the remote frame. |
NCTYPE_CAN_FRAME fields for IsRemote NC_FRMTYPE_RESPONSE_ENTRY_FRAME (16)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | 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 | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | Array of 8 NCTYPE_UINT8 | Zero if the response is to subscribe to data. Actual length of Data if the response is to publish data. |
| Data | NCTYPE_UINT8 | Ignored if DataLength is zero. Data to publish if DataLength is non-zero. |
NCTYPE_CAN_FRAME fields for IsRemote NC_FRMTYPE_LIN_HEADER_FRAME (17)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | 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 a slave task 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 | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | Array of 8 | NCTYPE_UINT8 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 | NCTYPE_UINT8 | Ignored. |
NCTYPE_CAN_FRAME fields for IsRemote NC_FRMTYPE_LIN_FULL_FRAME (18)
| Field Name | Data Type | Description |
|---|---|---|
| IsRemote | NCTYPE_UINT8 | 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 in response. 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 | NCTYPE_CAN_ARBID | Zero to sixty-three. |
| DataLength | Array of 8 NCTYPE_UINT8 | One to eight. |
| Data | NCTYPE_UINT8 | Data to publish. |
CAN Object
The data type that you use with ncWrite of the CAN Object is NCTYPE_CAN_DATA. When calling ncWrite, you should pass size of (NCTYPE_CAN_DATA) for the DataSize parameter. The following table describes the fields of NCTYPE_CAN_DATA.
NCTYPE_CAN_DATA Field Name
| Field Name | Data Type | Description |
|---|---|---|
| Data | Array of 8 NCTYPE_UINT8 | Data array specifies the data bytes (8 maximum). The actual number of valid data bytes depends on the CAN Object configuration specified in ncConfig.
If the Communication Type of the CAN object specifies Receive, data frames are received, not transmitted, so Data is ignored. For this Communication Type, the ncWrite function is used solely for transmission of a remote frame. If the Communication Type of the CAN object specifies Transmit, Data must always contain Data Length valid bytes, where Data Length was configured using ncConfig. |