ncWriteDnetExplMsg (Write DeviceNet Explicit Message)
Purpose
Write an explicit message request using an Explicit Messaging Object.
Format
LabVIEW
C
| NCTYPE_STATUS | ncWriteDnetExplMsg(
NCTYPE_OBJH ObjHandle,
NCTYPE_UINT8 ServiceCode,
NCTYPE_UINT16 ClassId,
NCTYPE_UINT16 InstanceId,
NCTYPE_UINT16 ServDataLength,
NCTYPE_ANY_P ServData); |
Input
| ObjHandle | Object handle of an open Explicit Messaging Object |
| ServiceCode | Identifies the service being requested |
| ClassId | Identifies the class to which service is directed |
| InstanceId | Identifies the instance to which service is directed |
| ServDataLength | Number of service data bytes for request |
| ServData | Service data for request |
Output
None
Function Description
ncWriteDnetExplMsg writes an explicit message request using an Explicit Messaging Object.
The two most commonly used DeviceNet explicit messages are the Get Attribute Single service and the Set Attribute Single service. The easiest way to execute the Get Attribute Single service on a remote device is to use the NI-DNET ncGetDnetAttribute function. The easiest way to execute the Set Attribute Single service on a remote device is to use the NI-DNET ncSetDnetAttribute function.
To execute services other than Get Attribute Single and Set Attribute Single, use the following sequence of function calls: ncWriteDnetExplMsg, ncWaitForState, ncReadDnetExplMsg. The ncWriteDnetExplMsg function sends an explicit message request to a remote DeviceNet device. The ncWaitForState function waits for the explicit message response, and the ncReadDnetExplMsg function reads that response.
Some DeviceNet services that use ncWriteDnetExplMsg are Reset, Save, Restore, Get Attributes All, and Set Attributes All. Although the DeviceNet Specification defines the overall format of these services, in most cases their meaning and service data are object specific or vendor specific. Unless your device requires such services and documents them in detail, you probably do not need them for your application. For more information, refer to the NI-DNET User Manual.
Parameter Descriptions
ObjHandle
| Description | ObjHandle must contain an object handle returned from ncOpenDnetExplMsg. In LabVIEW, ObjHandle passes through the VI as an output so that it can be used for subsequent function calls for the object. |
| Values | The encoding of ObjHandle is internal to NI-DNET. |
ServiceCode
| Description | Identifies the service being requested. You can find service code values for the commonly used DeviceNet services in the DeviceNet Specification (Volume 1, Appendix G, DeviceNet Explicit Messaging Services). The device's vendor documents vendor-specific service codes. |
| Values | 00 to FF hex |
ClassId
| Description | Identifies the class to which service is directed. You can find descriptions and identifiers for each standard DeviceNet class in the DeviceNet Specification (Volume 2, Chapter 6, The DeviceNet Object Library). The device's vendor documents vendor-specific classes. Although the DeviceNet Specification allows 16-bit class IDs, most class IDs are 8-bit. NI-DNET automatically uses the class ID size (16-bit or 8-bit) that is appropriate for your device. |
| Values | 00 to FFFF hex |
InstanceId
| Description | Identifies the instance to which service is directed. Instance ID 0 is used to direct the service toward the class itself. Other instance IDs typically are numbered starting at 1. For example, the primary Identity Object in a device uses instance ID 1. Although the DeviceNet Specification allows 16-bit instance IDs, most instance IDs are 8-bit. NI-DNET automatically uses the instance ID size (16-bit or 8-bit) that is appropriate for your device. |
| Values | 00 to FFFF hex |
ServDataLength
| Description | Number of service data bytes for the request. This length also specifies the number of bytes provided in ServData. |
| Values | 0 to 240 |
ServData
| Description | Service data bytes for the request. The format of this data is specific to the service code being used. For commonly used services which are not object specific, the format of this data is defined in the DeviceNet Specification (Volume 1, Appendix G, DeviceNet Explicit Messaging Services). For object-specific service codes, the format of this data is defined in the object specification. For vendor-specific service codes, the format of this data is defined by the device vendor. The ServDataLength parameter specifies the number of service data bytes sent in the request (and provided in this buffer). |
| Values | Service data bytes for the request |
Examples
LabVIEW
Save the parameters of Parameter Object instance 2 to non-volatile memory. The service code for Save is 16 hex. The Parameter Object is class ID 0F hex. The Parameter Object does not define any service data bytes for Save.
C
Reset a DeviceNet device to its power on state using the Explicit Messaging Object referenced by objh. The service code for Reset is 05 hex. The Identity Object (class ID 1, instance ID 1) is used to reset DeviceNet devices. The Identity Object defines a single byte of service data, where 0 is used to simulate a power cycle and 1 is used to reset the device to its out-of-box state.
NCTYPE_STATUS status;
NCTYPE_OBJH objh;
NCTYPE_UINT8 type_of_reset;
type_of_reset = 0;
status = ncWriteDnetExplMsg(objh, 0x05, 0x01, 0x01, 1, &type_of_reset);