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 Stream Listen block does not establish a "listening" socket but simply returns a placeholder stream. The Stream Accept block, on the other hand, creates a socket that is bound to the port specified in the URI parameter of the Stream Listen block.

The Stream Accept block 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 Stream Connect block 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 block 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 blocks and allow UDP to be used interchangeably with TCP/IP simply by changing the URI. However, UDP is inherently not a reliable protocol so it should not be used for host-model communications.

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, two models 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.

The UDP protocol is capable of multicasting. Multicasting is a means of communicating with a group of peers simultaneously. Unlike broadcasting, however, multicasting limits the communication to only those peers who subscribe to the multicast group. The group is identified by a multicast IP address, such as 224.0.5.128, which must be specified in the group option. If no group option is provided then multicasting is not employed.

The following table shows the IP address ranges reserved for multicasting:

When using multicast, the notify option should typically be set to no to prevent the zero-length datagram from being sent when the stream is closed.

For example, the ATI Net F/T sensor supports a discovery protocol in which a potential client broadcasts a packet onto the network requesting a response from any sensors on the network. It will use a URI such as udp://224.0.5.128:51000?peer=broadcast,notify=no to "connect" to any sensors on the network. The 224.0.5.128 address is the multicast address on which the sensors are listening.

At the same time, the client sets up a "listening" stream that joins the multicast group for the sensors. It would use a URI such as udp://localhost:28250?group=224.0.5.128,notify=no, where the group option is set to the multicast address employed by the sensors. Note that a different port is used in this case. After sending the request on its "connect" stream the client then accepts a connection on its "listening" stream and waits to receive responses from the sensors on the network.

Limitations

Sharing of UDP ports

Models listening on the same UDP port at the same time on the same target may compete for datagrams. Such competition can lead to unusual behaviour in which one models is receiving datagrams and then all of a sudden the other model starts receiving them instead. The exception is when peer is set to broadcast for both models, because in that case they both receive all datagrams.

Receiving only

UDP clients must send a datagram in order to be implicitly bound to a local address and port. If no datagram is sent then the UDP client will not be able to receive datagrams from the UDP server.

Sending only

UDP servers must receive at least one datagram when peer=one or peer=any in order to send data to clients unless the hostname or IP address of the client is specified in the nic option of the URI. Otherwise the server doesn't know the address to which to send the datagram.

QUARC Target Manager

The UDP protocol cannot be used for communicating with the target (via a target URI) because the UDP protocol does not allow multiple connections on the same port by multiple threads. Nor should it be used for the protocol of a model URI since it is inherently not a reliable protocol.

Polling restrictions

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

The target operating system may limit the UDP send and receive buffers to a specific range of values. For example, RT-TCP/IP under RTX limits the buffer sizes to 64K bytes. 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 four values: one, any, broadcast or manual.

If the peer option is set to one then the UDP protocol driver communicates with a single peer. For client connections established with the Stream Connect block 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 Stream Accept block 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 Stream Accept block 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.

The peer equal to any option is best when clients are connecting one at a time. If more than one client connects at the same time then all the clients will be sending datagrams to the server. The server will receive all the client datagrams without any problem. However, any data sent from the server to the clients is sent to the client whose datagram was received most recently. As the order in which UDP datagrams arrive is indeterminate, some clients may get starved of data if their UDP datagrams aren't the last to arrive when the server decides to send data. As a result, the server data received at the clients may look decimated or randomly sampled. Hence, this option is best suited for the situation where clients are either connecting one at a time, or they are not receiving any data from the server.

For client connections established with the Stream Connect block, the initial designated peer is the one specified in the block parameters. However, each datagram received changes the designated peer in the same way as it does for server connections when the client has the peer option set to any.

If the peer option is set to broadcast then the UDP protocol driver communicates with all peers at once. For connections established with the Stream Connect or Stream Accept block, 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.

Due to the way UDP sockets are bound differently for client blocks such as Stream Connect or Stream Client, and server blocks such as Stream Accept or Stream Server, use a server block for both server and client models when the peer option is set to broadcast. While this may seem counter-intuitive, the UDP protocol requires it for broadcast datagrams.

If the peer option is set to manual then the UDP protocol driver communicates with the peer set using the Stream Set Property block and the STREAM_PROPERTY_PEER_ADDRESS string property code. The peer address can be changed at any time to communicate with a new peer.

To retrieve the peer from which a datagram was last received, use the Stream Get Property block and the STREAM_PROPERTY_PEER_ADDRESS string property code.

The default peer is one since it corresponds most closely with the way TCP/IP functions, making switching between protocols in a model 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 and above, UDP datagrams are only broadcast on one of the NICs in a system containing multiple NICs. Windows 7 and above 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 and above 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 Simulink models designed around the QUARC Communications blocksets to continually close and reopen the UDP port if errors are used to cause the model 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.

group

This option specifies the hostname or IP address of a multicast group. When this option is specified the socket joins the multicast group.

Driver

The driver supporting UDP communications is called qrt_udp.

Targets

See Also

• Communications
• QUARC Communications Protocols
• Communications Using the C Language

Copyright ©2023 Quanser Inc. This page was generated Thu 05/04/2023. Submit feedback to Quanser about this page.