UDP Protocol :: RCP Communications Protocols

navigation bar

Table of Contents >Quanser Rapid Control Prototyping Toolkit >Communication Protocols >

UDP Protocol

The UDP protocol supports communications via UDP/IP datagrams.

Syntax

udp://hostname:port?option=value,... % Use UDP communications with host "hostname" on port "port"

Description

The UDP communications protocol supports communications over Ethernet. It is identified by using udp as the protocol name in a URI.

Because UDP is a datagram protocol rather than a stream protocol, it does not "listen" for client connections like the TCP/IP protocol. Hence, the CL Stream Listen VI does not establish a "listening" socket but simply returns a placeholder stream. The CL Stream Accept VI, on the other hand, creates a socket that is bound to the port specified in the URI parameter of the CL Stream Listen VI.

The CL Stream Accept VI does not wait for a "connection" from a remote host because UDP is a connectionless protocol. Instead, it returns immediately and the client stream may then be used to send and receive packets. How the protocol driver behaves once a datagram is received depends on the peer option. See the discussion of the peer option below for details. The default option is peer=one. In general, the server application should receive data first in order to establish the client to whom data will be sent. Otherwise, the -QERR_NO_DESIGNATED_PEER error may be returned.

Similarly, the CL Stream Connect VI does not actually "connect" to a remote host. Instead, it sets the address that will be used when sending packets. The first time a packet is sent the socket becomes implicitly bound to that address. Hence, when using the Stream Connect VI to create a stream, a send operation should always be done first. How the protocol driver behaves once a datagram is received depends on the peer option. See the discussion of the peer option below for details. The default option is peer=one.

The semantics of the UDP protocol driver are consistent with the paradigm of the Stream VIs and allow UDP to be used interchangeably with TCP/IP simply by changing the URI. However, UDP is inherently not a reliable protocol.

When the connection is closed, the UDP protocol implementation sends a zero-length datagram to the peer so that the peer will detect that the connection is "closed". This zero-length datagram may be disabled by setting the notify option to "no". See the discussion of the notify option below.

The hostname in the URI is used when connecting to a remote host. It is ignored when establishing a "listening" connection. The hostname may be a standard UDP hostname that is resolved via the normal name resolution mechanisms (DNS, hosts file, etc.) or it may be an IP address in dot notation (eg. 192.168.0.10).

The port in the URI determines the UDP port used for communications. For example, the URI udp://quanser-dev:18000 refers to a machine called quanser-dev "listening" on port 18000. The default port number is 18000. For "listening" streams, the port should not be used by other components in the system. In particular, multiple stream server VIs cannot share the same port number if they will be running at the same time on the same target and listening on the same port.

Limitations

Sharing of UDP ports

Warning Multiple stream server VIs cannot listen on the same UDP port if they will be running at the same time on the same target. If the VIs will not be run at the same time then they may use the same UDP port.

Polling restrictions

Warning The UDP protocol never blocks waiting to "connect" or to "accept" a connection, so it should never be necessary to poll on these events. Attempting to poll a "listening" stream for a pending client connection will return immediately with success.

Send and receive buffer sizes

Warning The target operating system may limit the UDP send and receive buffers to a specific range of values. Also, setting the send and/or receive buffer sizes to a value less than the system default has been known to cause severe performance degradation on some systems.

Options

bufsize

Set this option to set the size of the UDP send and receive buffers. Setting this option is equivalent to setting both the sndsize and rcvsize options to this value. If none of these options are set then the system default is used.

sndsize

Set this option to set the size of the UDP send buffer. If this option is not set then the system default is used.

rcvsize

Set this option to set the size of the UDP receive buffer. If this option is not set then the system default is used.

peer

This option determines how the UDP protocol handles communication with multiple clients or "peers". It may be set to one of three values: one, any or broadcast. If the peer option is set to one then the UDP protocol driver communicates with a single peer. For client connections established with the CL Stream Connect VI it will only send and receive datagrams from the designated peer. To allow the client and server to be run on the same machine, client connections do not bind the UDP socket explicitly to the port specified in the URI. Instead, the socket is bound implicitly to the port by the first send operation. Hence, for client connections, a send operation should always be done before the first receive operation . Failure to do so will result in a -QERR_CONNECTION_NOT_BOUND error. For server connections established using the CL Stream Accept VI it establishes a "designated peer" based on the first peer from whom data is received. All subsequent send and receive operations will communicate only with that designated peer. Datagrams received from other peers will be silently discarded. Hence, a "connection" is established with the designated peer in this fashion. Thus, for server connections, a receive operation should always be done before the first send operation . Failure to do so will result in a -QERR_NO_DESIGNATED_PEER error. Closure of the "connection" is detected by reception of a zero-length datagram. See the notify option for further discussion. If the peer option is set to any then the UDP protocol driver communicates with multiple peers. For server connections established using the CL Stream Accept VI the last peer from whom data is received is stored as the "designated peer". All subsequent send operations will communicate only with that designated peer. Thus, for server connections, a receive operation should always be done before the first send operation . Failure to do so will result in a -QERR_NO_DESIGNATED_PEER error. Datagrams received from other peers will change the designated peer so that subsequent send operations will go to the new peer. For client connections established with the CL Stream Connect VI, the initial designated peer is the one specified in the VI options. However, each datagram received changes the designated peer in the same way as server connections. Note that to allow the client and server to be run on the same machine, client connections do not bind the UDP socket explicitly to the port specified in the URI. Instead, the socket is bound implicitly to the port by the first send operation. Hence, for client connections, a send operation should always be done before the first receive operation . Failure to do so will result in a -QERR_CONNECTION_NOT_BOUND error. If the peer option is set to broadcast then the UDP protocol driver communicates with all peers at once. For connections established with the CL Stream Connect or CL Stream Accept VI, send operations will broadcast each datagram to all peers at the same time. Datagrams are received from any peer. There is no notion of "designated peer" because send operations always broadcast. The default peer is one since it corresponds most closely with the way TCP/IP functions, making switching between protocols in a VI as simple as changing the URI.

notify

This option determines whether the UDP protocol driver sends a zero-length datagram when the stream is closed. The purpose of the zero-length datagram is to notify the peer that the "connected" stream is being closed. The notify option may be set to either "yes" or "no". The values "y" or "1" may also be used instead of "yes". Likewise "n" or "0" may be used instead of "no". If this option is set to "yes" then the zero-length datagram is sent. The destination of this zero-length datagram depends on the peer option. If the peer option is set to "one" then the datagram is sent to the designated peer. The notification works well in this case because only the designated peer needs to be notified of the "connection" being shut down. If the peer option is set to "any" then the zero-length datagram is sent to the last peer from which data was received. The notification only works well in this case if peers access the host UDP port one at a time, so that the last peer to send data to the host is the only one actively communicating with the host. Finally, if the peer option is set to "broadcast" then the zero-length datagram is sent to all peers, such that all peers are notified that the "connection" is being shut down. The zero-length datagram notification works well in this circumstance because all peers, whether actively sending data or not, are notified of the shut down of the host "connection". If the notify option is set to "no" then the zero-length datagram is never sent. Set this option to "no" with caution however, because it prevents the UDP protocol driver from detecting when the peer is no longer going to be sending data. Hence, it may wait indefinitely for data to arrive when none is forthcoming. The default setting is notify=yes because using the notification makes it easier to switch between protocols simply by changing the URI.

nic

This option is used to bind the UDP socket to a particular Network Interface Card (NIC). It is particularly useful when the peer option is set to broadcast. The value of the nic option is a string containing either the IP address associated with the NIC or the host name. For a server, the nic option determines the NIC from which the server may receive UDP datagrams. If the nic option is not specified, then the server will receive datagrams from all the NICs. In either case, the server will only receive datagrams sent to the specified UDP port. For a client, the nic option forces the client to use the specified NIC for sending and receiving datagrams. This option is really only useful for clients when the peer option is set to broadcast. On most operating systems, UDP datagrams are broadcast to every NIC when broadcast mode is being used. However, on Windows 7 or later versions, UDP datagrams are only broadcast on one of the NICs in a system containing multiple NICs. Windows 7 or later versions make the choice arbitrarily if no NIC is specified. The nic option allows the NIC used for broadcasting datagrams to be specified explicitly rather than letting Windows 7 or later versions decide.

unreachable

This option determines whether ICMP Port Unreachable messages are received under Windows. The option is not supported on other operating systems. An ICMP Port Unreachable message indicates that a previous UDP send operation targeted a host for which no server is listening on the UDP port. By default, this option is unreachable=no so that ICMP Port Unreachable messages are ignored. To enable reception of these messages, set unreachable=yes. Enabling this option causes a -QERR_PORT_UNREACHABLE error to be returned when the ICMP Port Unreachable message is received under Windows. Unfortunately, this error can cause VIs designed around the RCP Communications palette to continually close and reopen the UDP port if errors are used to cause the VI to reconnect. Worse, these packets accumulate so that large delays can occur in connecting from the client once the UDP server is actually up and running. Enabling this option is not recommended unless special handling of the QERR_PORT_UNREACHABLE error is implemented.

Driver

The driver supporting UDP communications is called qrt_udp.

Targets

Target	Supported	Comments
RCP Windows (64-bit) Target	Yes	Fully supported.