Table of Contents > QUARC > User's Guide > QUARC Communications 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 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:
Multicast IP Address Range |
Description |
---|---|
224.0.0.0 to 224.0.0.255 |
Local subnetwork only (not forwarded by routers) |
224.0.1.0 to 224.0.1.255 |
Internetwork control block (used over the Internet) |
224.0.2.0 to 224.0.255.255 |
Ad-hoc block #1 (globally routed) |
224.3.0.0 to 224.4.255.255 |
Ad-hoc block #2 (globally routed) |
232.0.0.0 to 232.255.255.255 |
Source-specific multicast only |
233.0.0.0 to 233.251.255.255 |
GLOP addressing |
233.252.0.0 to 233.255.255.255 |
Ad-hoc block #3 (globally routed) |
234.0.0.0 to 234.255.255.255 |
Prefix-based unicast |
239.0.0.0 to 239.255.255.255 |
Administratively scoped (private use within an organization) |
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 using the Stream Client, Stream Call, or Stream Connect blocks 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 using the Stream Server, Stream Answer, or Stream Listen blocks 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
.
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
|
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
Target |
Supported |
Comments |
---|---|---|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Fully supported. |
|
Yes |
Last fully supported in QUARC 2018. |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.