QUARC Mailslot WAITFOR Demo

This example consists of two Simulink models and a batch script. It demonstrates how to use the Basic Communications blockset from the QUARC Targets Library to implement synchronization between QUARC models and a batch script using the WAITFOR command. The WAITFOR command is used in Windows to send and receive signals using the mailslot protocol.

In this particular example, the quarc_mailslot_waitfor_demo.mdl model waits for a signal from the quarc_mailslot_waitfor_script.bat batch script. In the meantime, the quarc_mailslot_waitfor_signal_demo.mdl model signals the batch script every time the 'A' key is pressed. The batch script waits for the signal from theh quarc_mailslot_waitfor_signal_demo.mdl model and then signals the quarc_mailslot_waitfor_demo.mdl model.

Thus, this example illustrates how to both send and receive signals between the WAITFOR command and QUARC models. The client model and batch script can 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.

Mailslot WAITFOR Demo Simulink Diagram

Mailslot WAITFOR Signal Demo Simulink Diagram

rem QUARC Mailslot WAITFOR Batch Script
rem
rem Wait for a signal from the quarc_mailslot_waitfor_signal_demo. The user must
rem press the 'A' key to get it to send a signal to this script.

:loop

echo.
echo Waiting for a signal from the QUARC Mailslot WAITFOR Signal Demo.
echo A signal is sent by this model when the 'A' key is pressed.

waitfor mysignal

echo.
echo The signal was received! Notifying the quarc_mailslot_waitfor_demo model.

waitfor /si mywait

goto :loop

Configuring the Demonstration

This demonstration can be run with both models running on the local host, or it can be run with the 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 a Remote Host

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

QUARC must be installed on the remote target 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 target 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 target to ensure that the QUARC can communicate with the QUARC Target Manager on the remote target.
An exception for TDP port 17001 must be added to the firewall on the remote target to ensure that the QUARC can communicate with models downloaded to the remote target.
The URI of the Stream Client block of the signaling model, quarc_mailslot_waitfor_signal_demo.mdl, must be changed so that the host name matches the NetBIOS name of the local machine (as opposed to the TCP/IP host name).
The model URI of the client model must be configured to refer to the remote target machine.

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

Stream Client parameters

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/WAITFOR.EXE/mymail

where qci-tom is the NetBIOS name of the local 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.

QUARC Mailslot WAITFOR Signal Configuration Parameters dialog

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.

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 the 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 "Is Signaled" Scope in the quarc_mailslot_waitfor_demo.mdl model to open its Scope.

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

When connecting to the quarc_mailslot_waitfor_demo.mdl model the quarc_mailslot_waitfor_script.bat batch file is run automatically. It's title bar will contain the caption "WAITFOR_Script" to make it easy to identify. Move the window to one side if necessary so it remains visible but does not interfere with the Simulink diagrams or plots.

Start the models by clicking on the Run button or selecting Run from the Simulation menu of the 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.

Once both models are running as well as the batch file, press the 'A' key to cause the quarc_mailslot_waitfor_signal_demo.mdl model to send a signal to the batch file. The batch file will display:

SUCCESS: Signal received.

The signal was received! Notifying the quarc_mailslot_waitfor_demo model.

SUCCESS: Signal sent.

Waiting for a signal from the QUARC Mailslot WAITFOR Signal Demo.
A signal is sent by this model when the 'A' key is pressed.

At the same time, the batch file sends a signal to the quarc_mailslot_waitfor_demo.mdl model, which will display a corresponding pulse in its Is Signaled plot as shown below:

Is Signalled Scope with pulse

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 Waiting Model

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.

Stream Server parameters

Receive Options on the Signaling Model

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.

Stream Client parameters

WAITFOR Signal Names

The WAITFOR command uses signal names internally of the form WAITFOR.EXE/signal where signal is the signal name specified in the WAITFOR command itself. Hence, the URIs for the Stream Server and Stream Client blocks contain the additional "WAITFOR.EXE/" prefix on the signal names.

WAITFOR Protocol

The WAITFOR command expects two datagrams to wake up in response to a signal. Hence, the quarc_mailslot_waitfor_signal_demo.mdl model sends a datagram on both the key press and the key release. These semantics are not obvious, but the two datagrams occur because the new port of the Host Keyboard block outputs a pulse every time the state of the key changes - including both pressing the key and releasing the key.

It should also be noted that the WAITFOR command sends the first three Unicode characters of the NetBIOS name followed by an ASCII hyphen character when it sends a signal. These bytes can be seen when looking at the Data Scope in the quarc_mailslot_waitfor_demo.mdl model. Hence, the new output of the Stream Server block is used to simplify the detection of a signal from the batch file.

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.