Echelon OpenLDV - Manual (Page 66)

58 Sending and Receiving Messages with the OpenLDV API
Constructing Messages
You can construct outgoing messages for OpenLDV application using application
buffer structures, and send that data to the network interface using the
ldv_write() function. Use the ldv_read() function to retrieve data from the
network interface, using the same application buffer structures. The following
section describes the application buffer structure.
The OpenLDVdefinitions.h header file contains example code that defines the
formats of these application buffer structures for Layer 5 devices. This header
file is included with the OpenLDV Developer Example; see Chapter 4, The
OpenLDV Developer Example, on page 89.
The ldv_read() and ldv_write() functions take a msg_p parameter, which is a
pointer to a buffer for the data that is to be received or sent. These functions also
take a len parameter, which specifies the size (in bytes) of the buffer or data to
write. See The OpenLDV API on page 15 for a description of these functions.
Application Buffer Structure
Figure 5 on page 59 shows the application buffer structures used by OpenLDV
L ON W ORKS interface devices. All OpenLDV L ON W ORKS interface devices support
the serial interface control block (SICB) buffer format. Some L
ON
W
ORKS
interface devices also support an extended (LdvEx) buffer format. You can use
the ldv_open_cap() function to specify which format to use; see ldv_open_cap()
on page 25.
The SICB buffer format begins with a simple header, the Network Interface
Header. The structure of this header depends on the type of command being
processed:
• For commands that use a message queue, the header includes 4 bits for
the queue type, four bits for the command, and a byte for the length of
the payload.
• For commands that do not use a message queue (such as the immediate
commands), the header includes a byte for the command and a byte for
the length of the payload.
For some commands, the value of the length byte can be zero. An optional,
variable-length data field (as indicated by the header’s length byte) follows the
header.
The LdvEx buffer format encapsulates the SICB format; it adds extra timestamp
information and extended data (where applicable; this extended data is not
interpreted by the OpenLDV software). Unless specifically stated, an
“application buffer” refers to the SICB format buffer.