QUARC Mailslot Server Demo

This example consists of three Simulink models: a server and two clients. It demonstrates how to use the Basic Communications blockset from the QUARC Targets Library to implement a mailslot server capable of servicing multiple clients. In this particular example, the server receives data from two clients at the same time. Since the mailslot protocol is unidirectional, the clients always send data and the server always receives data. The clients may be run on the local machine or on remote hosts. For general information on the Basic Communications feature of QUARC, you can refer to the Basic Communications section. Be sure to investigate the Important Considerations section below to understand the design considerations that went into this demonstration.

Configuring the Demonstration

This demonstration can be run with all three models running on the local host, or it can be run with each client running on a remote target and communicating with the local host. Refer to the appropriate section below for the desired configuration. Quanser recommends trying the demonstration on the local host first before attempting to run the clients on remote targets.

Running on Local Host

To run the demonstration on the local Windows host no configuration should be required. The defaults should work.

Running on Remote Hosts

To run the clients on remote targets, some configuration is required. Specifically:

• QUARC must be installed on the remote targets if it is not installed already. Make sure the same version of QUARC is installed as the host machine.
• An exception for UDP port 138 and TCP port 139 may have to be added to the firewall on the host machine and remote targets to ensure that the mailslot datagrams are not blocked by the firewalls.
• An exception for TDP port 17000 must be added to the firewall on the remote targets to ensure that the QUARC can communicate with the QUARC Target Manager on the remote targets.
• An exception for TDP port 17001 must be added to the firewall on the remote targets to ensure that the QUARC can communicate with models downloaded to the remote targets.
• The URI of the Stream Server block of the server model, quarc_mailslot_server_demo.mdl, must be changed so that the host name refers to a domain (typically '-' for the primary domain).
• The URI of the Stream Client block of the two client models: quarc_mailslot_client1_demo.mdl and quarc_mailslot_client2_demo.mdl must be changed so that the host name matches the NetBIOS name of the server machine (as opposed to the TCP/IP host name).
• The model URI of the client models must be configured to refer to the remote target machines.

To change the URI of the Stream Server block, double-click on the block to open its configuration dialog, as shown below.

In the URI upon which to listen field, add a hostname to the URI containing only a hyphen, for the primary domain, or a NetBIOS domain name. For example:

            mailslot://-/mymail
        

Click OK to close the configuration dialog.

To change the URI of each Stream Client block, double-click on the block to open its configuration dialog, as shown below.

In the URI of host to which to connect field, add a hostname to the URI containing the NetBIOS name of the machine running the server. For example:

            mailslot://qci-tom/mymail
        

where qci-tom> is the NetBIOS name of the server machine. Note that TCP/IP host names and IP addresses are not recognized. The mailslot protocol operates over the datagram distribution service of NetBIOS and thus requires NetBIOS names instead.

Click OK to close the configuration dialog.

To modify the model URI of a client so that the client model is run on the desired remote target, open the Configuration Parameters dialog by selecting Configuration Parameters... from the Simulation menu, or by pressing Ctrl+E. Then navigate to the Code Generation/Interface pane in the Select treeview.

In the MEX-file arguments field, append the model URI of the remote target in single quotes. Be sure to separate the model URI from the model arguments with a comma. For example, if the remote machine is called "remhost", then a suitable model URI is "tcpip://remhost:17001" and the MEX-file arguments would look like:

            '-w -d %d -uri %u','tcpip://remhost:17001'
        

For more information on model URIs and running QUARC models on remote targets, please refer to the Specifying a Model and/or Target URI page in the QUARC documentation. For a general discussion of model URIs, refer to Real-Time Code - the Model URI section of the Communicating with the Target documentation.

Configure the Stream Client block and model URI of each client model. Don't forget the firewall exceptions for UDP port 138 and TCP ports 139, 17000 and 17001.

Demonstration

Select Build from the QUARC menu of each diagram, or press Ctrl+B while the diagram is the active window. A great deal of output will appear in the Diagnostic Viewer about the progress of the build. If you cannot see the Diagnostic Viewer, you can open it by selecting View/Diagnostic Viewer from the menu of the diagram, or clicking on the View Diagnostics hyperlink at the bottom of the diagram. If you have MATLAB R2013b or earlier then the output will appear in the MATLAB Command Window.

Double-click on the "Client 1 Data" and "Client 2 Data" Scopes in the quarc_mailslot_server_demo.mdl model to open its Scopes.

Click on the Connect to Target button or select Connect to Target from the Simulation menu of the diagrams to connect to the models.

Start the models by clicking on the Run button or selecting Run from the Simulation menu of each diagram. The Start item of the QUARC menu may also be used to both connect and start each model in one operation. Note that the order in which you start the models is not important. However, in practical situations, the server side should generally be running before the clients start.

The server model receives a sawtooth wave from client #1 and a square wave from client #2.

Click on the Stop button or select Stop from the Simulation menu of the diagram to stop the model. The Stop item of the QUARC menu may also be used.

Important Considerations

A number of important decisions were made in designing this demonstration to ensure that communications with multiple clients operated correctly. This section deals with the important factors that were considered and drove the implementation of this example. It will also highlight changes from the default settings that were required.

Send Options on the Server

The mailslot protocol is a unidirectional datagram protocol in which servers only receive data while clients only send data. Therefore, the Send options parameter of the Stream Server block has been configured to Do not send data, which removes all the input ports of the block as they are not needed. The Send buffer size in bytes is also set to zero, since no data is being sent.

Receive Options on the Client

The mailslot protocol is a unidirectional datagram protocol in which servers only receive data while clients only send data. Therefore, the Receive options parameter of the Stream Client block of each client has been configured to Do not receive data, which removes the output ports used for receiving data. The Receive buffer size in bytes is also set to zero, since no data is being received by the clients.

Decimating the Client Data

All three models run at the same sampling rate. Let the sampling rate be Ts. The Stream Server is receiving data from both clients at the same time. If both clients were sending data at the sampling rate Ts then the server would be receiving two mailslot datagrams every sampling instant. However, the Stream Server block is only reading one datagram at a time from the stream. It can only read one datagram every Ts seconds, not two. If both clients were sending data every Ts seconds then the Stream Server block would not be able to keep up with the data from the clients.

To avoid overwhelming the server with data, each client decimates the data it sends to the server. This decimation is accomplished using a Pulse Generator block connected to the en input of the Stream Client block.

The Pulse Generator is configured to produce a pulse every N sampling instants, where N is the number of clients. In this case there are only two clients, so N is 2, and the Pulse Generator produces a pulse every other sampling instant.

As a result, each client is sending data every N*Ts seconds and the server receives a datagram every Ts seconds on average. The Stream Server block is not overwhelmed with data.

A natural question is why the Stream Server block should only process one datagram at a time. Why not configure it to receive N datagrams at a time, and then the N clients will not need to decimate their data? The problem with this solution is that not all clients may be running. For example, if the user stops one of the clients then the server will no longer be receiving N datagrams each sampling instant. Hence, it will have to wait for another sampling instant before it has a full N datagrams and can output anything from its rcv port. Since it is not uncommon for a client not to be running, particularly when the topology is started up or shut down, this situation will occur and is not ideal. It can however be detected by monitoring the new output of the Stream Server block.

Another possible alternative is to place the Stream Server block in a For Iterator Subsystem which executes N times. The loop could be aborted if the new output was false. This solution may effectively resolve the decimation issue but was not attempted for this example because of the added complexity.

Client Identifiers

The Stream Server block does not provide any mechanism for knowing the NetBIOS name associated with each mailslot datagram received since it is a generic Stream block used for any communications protocol. As a result, the server cannot use the NetBIOS name to distinguish between the data sent from each client.

To enable the server to associate each datagram with a particular client, an identifier value was added to the data sent by each client.

The above figure shows the client identifier being muxed into the data sent to the server. The server uses this identifier to route the client's data to its own Scope via a Demultiplexer block. The Demultiplexer block acts like a digital demultiplexer and routes its input signal to one of N outputs based on the selection input. The client identifier is passed to the selection input to route the data received to the appropriate plot.

Running the example on a different target

To run the example on a different target, refer to the instructions on the Running QUARC Examples on Remote Targets page.

Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.

Link to this page.