Delacor Queued Message Handler Documentation

 

Introduction

DQMH Logo

The Delacor Queued Message Handler (DQMH) template is based on the National Instruments Queued Message Handler Project Template (NI QMH). The DQMH improves the NI QMH by:

  • providing safe, event-based message handling and scripting tools, which makes development easier
  • encouraging consistent style among different developers in the same project, which improves efficiency

The DQMH provides the greatest benefits in applications employing multiple modules running in parallel that communicate with each other. These different modules can run either with their front panel open or headless (with their front panel closed). The DQMH can also be used for applications that have a single module in which a Tester has the capability of eavesdropping on the different DQMH events and messages (both in development mode and in an executable).

Each DQMH module has a structure similar to a National Instruments Queued Message Handler module, and it has a Test DQMH Module API.vi (also known as the “Tester) to help troubleshoot, debug, and eavesdrop on the communications between the DQMH Module and its calling code. If the developer is creating an application that will employ multiple DQMH modules, the best place to start is with the Project Templates. This is done by clicking Create Project from the Getting Started Window in LabVIEW, and then clicking the DQMH Project Template. If the developer is creating a single DQMH module that will be called by their existing code or used as a stand-alone application, open an existing project and use the Tools>Delacor>Add DQMH Module utility.

This documentation assumes that you are familiar with Producer/Consumer design pattern and with the NI QMH Project Template. If you are not familiar with these topics, the NI QMH documentation can be found by clicking Create Project from the Getting Started Window in LabVIEW and then clicking the More Information link in the NI QMH project description. You can also create a project based on this template, which will include a copy of the documentation.

 

Table of Contents

 

Change History

 

  • Version 1.0.0.1: DQMH documentation for first public release.
  • Version 2.0.0.0: Added section on how to use the new Rename DQMH Module utility. Updated images. Fixed typos.
  • Version 2.1.0.2: Published documentation at: delacor.com/dqmh-documentation. Updated images to reflect DQMH 2.1 version. Added description of what “DQMH Module Main” refers to in the Nomenclature section. Clarified the titles for the shipping examples and provided a link to skip TestStand sections if not using it. Added links at the end of each section to go back to the Table of Contents.
  • Version 2.1.0.3: Added link to DQMH Best Practices document.
  • Version 3.0.0.0: Expanded Nomenclature section and added documentation for new DQMH features introduced with DQMH 3.0:
  • Version 3.0.0.1: Converted documentation to hnd/html. Added embedded videos for html and chm versions.

Table Of Contents

Use Cases

 

The DQMH template is useful for applications where multiple tasks occur in parallel, often at different rates. It is also useful when multiple instances of the same Front Panel are needed (this requires using a cloneable DQMH Module). For example, consider an application that controls a single temperature chamber and needs to log data from multiple units under test (UUTs). A cloneable DQMH Module would be used to implement a single UUT and a singleton DQMH Module would be used to implement the temperature chamber.

The Tools>Delacor>Add DQMH Module utility can add individual DQMH Modules to existing projects. This is useful for applications where a continuous running process needs to be added and the rest of the code needs to communicate with this process. For example, consider an application where communication with a serial instrument needs to poll the serial port continuously waiting for a series of commands to be received. A singleton DQMH module could implement the communication with the instrument. The existing application could start this singleton DQMH Module and register to listen to the serial port commands. The Test DQMH Module API.vi could then be used to eavesdrop on the communication between the Singleton DQMH Module and the rest of the code as well as a vehicle to test the instrument connected to the serial port as well.

The Tools>Delacor>Add DQMH Module utility can also be used to add a new DQMH module to a new project where the DQMH is intended to be the standalone application.

Another use of the DQMH Module template is for teams with different levels of proficiency. The DQMH Module could be designed and implemented by one team member, and others with less LabVIEW familiarity could just call the DQMH Module API VIs in their code, without having to understand how the DQMH Module itself is implemented.

Table Of Contents

DQMH Background

 

Implementing communication between DQMH modules using events is based on the concepts presented by Justin Goeres during CLA Summit 2011 and NIWeek 2011 (more information here). The main modifications to Justin’s approach were (1) changing the nomenclature from Private/Public events to Request/Broadcast events, and (2) using the NI QMH as the basis for the modules instead of the JKI State Machine.

 

Table Of Contents

Getting Started

 

 

 

 

 

 

DQMH Decisions Behind the Design video shows a presentation given at NI week 2016 where Fabiola De la Cueva gave an overview of what the DQMH is, the differences between DQMH and the NI QMH and some of the decisions behind DQMH design.

Look at the corresponding Main.vi diagram in the NI QMH documentation to contrast the differences with the DQMH Module Main.vi.

Here are the primary differences:


Nomenclature



DQMH Event: LabVIEW code that carries custom data throughout the application. Implemented using Custom Events (also known as User Events). These events allow different parts of an application to communicate asynchronously when the events are programmatically generated. An event structure handles both types of events: end user interaction with front panel (i.e., a value change event on a control) and programmatically generated user events. More details can be found on the LabVIEW Help entry for User Events (or custom events). A DQMH can send events to multiple Event Structures and multiple locations in the code can send events to a DQMH module. DQMH Events are many to many.

There are two types of DQMH Events:


Request: Code that fires an event requesting the DQMH Module Main.vi to do something. Multiple locations in the code can send events to the DQMH module. Request Events are many to one. Requests are asynchronous events, the code that fires the event does not wait for a response from the DQMH Module Main.vi. Creating a Request and Wait for Reply type of event makes the Request synchronous.


Broadcast: Code that fires an event broadcasting that the DQMH Module Main.vi did something. Multiple event structures can register to handle the Broadcast Events. Broadcast Events are one to many.


DQMH Module Main: Each DQMH Module has a Main.vi, the full name for the Main.vi is DQMH Library Name:Main.vi. For example My Singleton Module.lvlib:Main.vi or My Cloneable Module.lvlib:Main.vi. This document refers to this VI as “DQMH Module Main”. This VI can be renamed without breaking any of the DQMH scripting tools.


DQMH Module Main.vi Overview


The DQMH Module Main.vi repeatedly performs the following steps:

  1. A user interacts with the front panel, causing the Event structure in the Event Handling Loop (EHL) to produce a message. LabVIEW stores the message in a queue.
    1. The DQMH Module Main.vi also registers to listen to requests sent by other VIs. Another VI requests that the DQMH module do something, causing the Event structure in the EHL to produce a message. LabVIEW stores the message in a queue.

  1. The Message Handling Loop (MHL) dequeues a message from the message queue.
  2. The message is a string that matches one of the subdiagrams of the Case structure in the MHL. Therefore, reading the message causes the corresponding subdiagram of the Case structure to execute. This subdiagram is called amessage diagram” because it corresponds to a message.
  3. Optionally, the message diagram produces another message, storing it in the message queue.
    1. The DQMH Module Main.vi can optionally broadcast an event to other VIs that are registered to listen to them.

  1. In the NI QMH the EHL only registers to listen to the Stop message. In the DQMH the EHL registers to listen to all the request events.
  2. The DQMH Module Main.vi has Admin code that manages whether the module is a single instance (singleton) or it can be called multiple times in parallel (cloneable).

Notes:

  • The EHL is the producer loop. The MHL is the consumer loop. These loops run in parallel and are connected by the message queue, which facilitates communication between the loops.
  • The message queue is a LabVIEW queue that stores messages for consumption. The two loop architecture allows the EHL to receive external requests or user interactions and send them as messages to this queue while the MHL may be busy consuming previous messages. Each message queue belongs to a single MHL. Note that in the DQMH the VIs that manage the queues are not copied to the project like in the NI QMH. In the DQMH the queues are wrapped in a class and the managing VIs are stored in vi.lib. If the developer is comfortable with LabVIEW Object Oriented Programming, he can choose to override some of these VIs and create his own Message Queue class.
  • Every iteration of the MHL reads the message at the front of the message queue and then executes the corresponding message diagram. Although the MHL primarily consumes messages, it also can produce them.
  • Each loop handles errors using a loop-specific error handler subVI. If the DQMH Module Main.vi encounters an error in the MHL, LabVIEW displays an error message. These VIs are also wrapped in the DQMH Queue class and reside in vi.lib. If the developer is comfortable with LabVIEW Object Oriented Programming, he can choose to override some of these VIs and create his own Message Queue class.
  • Unlike the NI QMH template that encourages having an MHL for each task, the DQMH encourages having a new DQMH Module per task. With the DQMH scripting tools, the developer can select Tools>Delacor>DQMH>Add New DQMH Module… to quickly add a new module to his project.
  • Notice the Data cluster in the above diagram. This cluster contains data that each message diagram in the MHL can access and modify. In this template the cluster is defined as a typedef (Module Data–cluster.ctl). Each typedef belongs to a single DQMH module and should only be modified by code in Main.vi.


Test Module API.vi: The DQMH also has a Test Module API.vi for each DQMH module. This document refers to this VI as “Tester”. This provides a convenient way to test all the request and broadcast events implemented by the DQMH Module. The Test Module API.vi gets added when the developer selects Tools>Delacor>DQMH>Add New DQMH Module…, and it tests the request and broadcast events that come with a DQMH Module.

Test My Singleton Module API.vi also known as the Singleton DQMH API tester.

The tester for singleton DQMH Modules registers to listen to the broadcasts from the DQMH Module Main.vi and handles each broadcast event in the event structure. When the tester stops, the last request to be sent is to stop the module (in case it was not stopped earlier). It is important to execute that last request to avoid leaving the DQMH Module Main.vi running.

One of the advantages of the DQMH Module Main.vi design is that it can run headless. Another advantage is that the tester can be used as a “sniffer” to monitor the status of a DQMH module that is already running.


The Core Requests and Broadcasts that come with a DQMH Module are:



Requests:



  • Show Module Panel – By default the module does not show the front panel of its Main.vi when it is started. Execute this request to show the front panel of the DQMH Module Main.vi. This request cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Hide Module Panel – Execute this request to hide the front panel of the DQMH Module Main.vi. This request cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Get Module Execution Status – Execute this request to request the DQMH Module Main.vi to report its current execution status via the Update Module Execution Status broadcast. This request cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Show Diagram – Execute this request to show the block diagram of the DQMH Module Main.vi. This request does not work in executables. This request can be removed via Tools>Delacor>DQMH>Remove DQMH Event….  

  • Do Something – Execute this request to tell the DQMH Module Main.vi to do something. The Main.vi then will broadcast that it did something. This request can be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Do Something Else – Execute this request to tell the DQMH Module Main.vi to do something else. The Main.vi will display the payload received. This request can be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Do Something Else and Wait for Reply – Execute this request to tell the DQMH Module Main.vi to do something else and return the reply immediately. The reply is not returned via a broadcast. This type of event is useful when the developer requires a synchronous message. This request can be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Stop Module – Execute this request to stop the DQMH Module Main.vi. This request cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

Note: Deselect the Include “Do Something” events in new module? option when creating a new DQMH module to exclude the Do Something events described above.



Broadcasts:


  • Module Did Init – The DQMH Module Main.vi broadcasts that it initialized without issues. This broadcast cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Did Something – The DQMH Module Main.vi broadcasts that it did something. This broadcast can be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Status Updated – The DQMH Module Main.vibroadcasts a new status. This broadcast cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Error Reported – The DQMH Module Main.vi broadcasts that an error occurred. This broadcast cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Module Did Stop – The DQMH Module Main.vi broadcasts that it did stop. This broadcast cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

  • Update Module Execution Status – The DQMH Module Main.vi broadcasts whether it is currently running, this is used when the Start Module.vi executes and the module Main.vi is already running. This broadcast cannot be removed via Tools>Delacor>DQMH>Remove DQMH Event….

Note: Deselect the Include “Do Something” events in new module? option when creating a new DQMH module to exclude the Did Something event described above.



Table Of Contents

Nomenclature

 

 

Nomenclature


Table Of Contents

DQMH Project Structure Overview

 

 


The Delacor QMH project template (available in the Create Project dialog launched from the Getting Started window) has the following components:

  1. Testers that exercise the public API of the DQMH modules in the project. The Testers register for the broadcast events fired by the DQMH Module Main.vi and fire request events that will be acted upon in the DQMH Module Main.vi.
  2. Each DQMH module has its own project library (lvlib). This facilitates having the same icon header for all the members of the library and specifies which VIs are public and which VIs are only used by the library itself.
  3. Each DQMH module has a
    Public API virtual folder that lists the VIs that can be called by VIs outside the library.
  4. Within the Public API folder there is a Requests virtual folder that lists all the VIs wrapping the firing of the requests that can be sent to the DQMH Module Main.vi
  5. In order to start a DQMH Module, two VIs need to be called: Start Module.vi and Synchronize Module Events.vi. These two VIs take care of launching the DQMH Module Main.vi as well as making sure the DQMH Module Main.vi has created its own request and broadcast events before the calling VI can fire or register to listening to broadcast events.
  6. The Obtain Broadcast Events for Registration.vi can be used when the calling VI is not ready to start the DQMH Module Main.vi or it expects the DQMH Module Main.vi to have been started by another module. The Obtain Broadcast Events for Registration.vi will have the broadcast events if the DQMH Module Main.vi has already started or it will have empty references and it can be used to declare the event reference type for registration.
  7. The DQMH Module Main.vi is a private VI. This encourages developers to use the public API to interact with the DQMH module.
  8. The calling code can be another library or simple VIs. In the DQMH project template a Simple State Machine
    application is used to call the singleton and cloneable DQMH modules.
  9. The Build Specification for an executable that uses Application.lvlib:Main.vi as the startup VI.

Notes:

  • The DQMH Module Main.vi creates its request and broadcast
    events to ensure that even if the calling VI leaves memory the references are still valid. This feature of the DQMH module facilitates calling the DQMH modules via TestStand
    as well as easily defining the lifetime of a given module’s event references. The combination of Start Module.vi and Synchronize Module Events.vi ensures that the DQMH Module Main.vi is ready to receive requests and the calling VI is ready to receive broadcasts.

Start Module.vi, Register for Events and Synchronize Module Events.vi combination.


  • The code that calls the DQMH module can be very simple, not even needing an event structure (especially if the calling VI does not care about broadcast events or is only calling request and wait for reply events). Refer to the Thermal Chamber Control example available from the Help>Find Examples…>Directory Structure>DelacorDelacor QMH>DQMH Fundamentals – Thermal ChamberDQMH Fundamentals – Thermal Chamber.lvproj >> Thermal Chamber Controller.vi for an illustration of this approach.

Thermal Chamber Control example shows that calling code can be simple.

  • If the DQMH Module libraries are locked (right click the module .lvlib and choose Properties>Protection), only the public VIs appear in the Project Explorer window. This can be useful when sharing code with other members of the team to highlight the VIs that they will be using in calling code.

Table Of Contents

DQMH Singleton Module vs Cloneable Module Overview

 

 

A
Singleton DQMH module can have only one instance of its Main.vi running at any given time. Every time the Start Module.vi is called, the same DQMH Main.vi instance is used.

A
Cloneable DQMH module can have one or multiple instances of its Main.vi running in parallel. DQMH 3.0 adds code for cloneable modules to be executed as singletons. If the cloneable is running as a singleton, the same instance will be returned every time Start Module.vi
is called (Module ID = 0). If it is running as a cloneable, the cloneable module assigns a new Module ID number to each new instance that is started when calling the Start Module.vi.

The calling code needs to provide the Module ID as an input to every request and broadcast VI. The event structure inside the EHL in the cloneable DQMH Module Main.vi has to determine if a request event was sent specifically to that clone before enqueuing the message to the MHL. A Module ID value of -1 means that the event was intended for all instances of the cloneable module.

Event Handling Loop (EHL) inside a DQMH Cloneable Module.


A cloneable DQMH module library has a folder called
Multiple Instances; this folder contains the Action Engine that manages the different instances of the module.

Multiple Instances folder contains the Action Engine that manages the different instances of the cloneable module.

  1. The cloneable DQMH module comes with a group of VIs to update a Module ID ring that can be used in the Tester or in the Application code to address the different instances of the module.
  2. Since the DQMH Module Main.vi owns the lifetime of the request and broadcast events, code is needed to determine if the first instance can close. Before stopping, the DQMH Module Main.vi checks to see if it was the first instance of the module that was launched (and hence, the owner of the event references). If it was the first instance launched, then the module will exit both EHL and MHL loops and hold in the
    Close.vi waiting for all the other instances to close. The VI continues to run (with its panel hidden) until it is the last instance running, at which point it destroys the event references and stops.
  3. The
    Clone Registration AE.vi is the action engine that manages all the DQMH cloneable module instances.
  4. These VIs are the public API for the Clone Registration Action Engine and are used for the following tasks:
    • Initialize the clone registry
    • Add a new clone to the registry
    • Remove a clone from the registry when it stops
    • List all the available clones
    • Check if a module was the first clone to be registered

The Clone Registration functionality resides in a library with a Public API, which allows the developer to implement the registry with a different underlying mechanism besides an action engine if he so desires.

  1. A simple tester is included to verify that the Clone Registration AE.vi works as expected.


Table Of Contents

Shipping Examples and Integration with TestStand

 

 


Note: The shipping examples do not require TestStand.

Note: For each TestStand example, there is a similar example VI.

Integration with TestStand

The fact that the DQMH Module owns its own event references facilitates integration with TestStand. Refer to the Thermal Chamber Control example available from the Help>Find Examples…>Directory Structure>DelacorDelacor QMH>DQMH Fundamentals – Thermal Chamber for the Thermal Chamber Controller TestStand example sequences.

TestStand Thermal Chamber Control example.


The ability to call the Public API methods of any DQMH module directly from TestStand results in a very clean TestStand sequence without the need for passing communication references or state data between the calling sequence and the code modules. A vital part of this architecture from a TestStand perspective is that the event reference lifetimes are owned by the DQMH module itself. TestStand can simply make a call to start a module and then make further calls to the module’s API as required. An added benefit of the DQMH module’s use of events is that the API Testers that are created with each DQMH module can be used as “sniffers” to aid in debugging. Likewise a TestStand sequence can make calls to a DQMH module that is already running, allowing you to treat the module as a service. As the TestStand sequence is only making calls on the Public API of a module, the majority of any debugging required will be carried out in LabVIEW.

To start a DQMH module from TestStand, a call should be made to the Start Module.vi of the module:

Calling DQMH Module API VIs from TestStand to start the DQMH Module.


Calling DQMH Module API VIs from TestStand to start the DQMH Module.


The Start Module.vi returns a Wait for Event Sync? value that should be passed to the Synchronize Module Events.vi of the same module – This Boolean value can be persisted in a sequence local in TestStand. This approach is used to ensure the events are appropriately created (and therefore “owned”) by the DQMH module before calls are made to it using request events.

Start Module.vi returns a "Wait for Event Sync?"


Synchronize Module Events.vi ensures the events are appropriately created by the DQMH module before calls are made to it using request events.

From this point onwards calls can be made directly to the Public API of the DQMH Module directly.

For cloneable DQMH modules the only additional point of note is that the Module ID should be provided to all API calls so the events will be handled by the correct instance of the module. The Module ID is returned by the call to Start Module.vi and should be persisted in a sequence local in TestStand so that subsequent calls to the module can be addressed correctly using this Module ID.

Start Module.vi starts a new Device Under Test instance.


Table Of Contents

LabVIEW Examples

 

 

Note: The shipping examples do not require TestStand.

Note: For each TestStand example, there is a similar example VI.

Table Of Contents

LabVIEW Example 1: Thermal Chamber Controller Example.vi

 

 

This example implements a Thermal Chamber Controller with a singleton Delacor QMH module. The chamber is configured to reach a temperature set point. Once the temperature is reached, the VI stops. This illustrates that there is no need to have an event structure in the calling code and provides an example of a DQMH module being used in a traditional “Configure > Read/Write > Close” application.

To get the example:

  1. Go to Help>Find Examples
  2. From the NI Example Finder window, select Directory Structure>Delacor>Delacor QMH>DQMH Fundamentals – Thermal Chamber.
  3. Open DQMH Fundamentals – Thermal Chamber.lvproj.
  4. Open Thermal Chamber Controller.vi.

LabVIEW Example 1: Thermal Chamber Controller Example.vi

Table Of Contents

LabVIEW Example 2: Thermal Chamber Controller with DUT.vi

 

 

This example implements a Thermal Chamber Controller with a single DUT, using a singleton Delacor QMH module for the controller, and a single instance of a cloneable Delacor QMH module for the DUT. The chamber is configured to reach a temperature set point. Once the temperature is reached, the Unit Under Test (UUT) performs a Self-Test and returns the result. The Unit Under Test code is configured for an 80% pass rate for demonstration purposes. This example illustrates that there is no need to have an event structure in the calling code and provides an example of two DQMH modules being used in a traditional  “Configure > Read/Write > Close” application.

To get the example:

  1. Go to Help>Find Examples
  2. On the NI Example Finder window, select Directory Structure>Delacor>Delacor QMH>DQMH Fundamentals – Thermal Chamber.
  3. Open DQMH Fundamentals – Thermal Chamber.lvproj.
  4. Open Thermal Chamber Controller with DUT.vi.

LabVIEW Example 2: Thermal Chamber Controller with DUT.vi

Table Of Contents

LabVIEW Example 3: Thermal Chamber Controller with Multiple DUTs.vi

 

 

This example implements a Thermal Chamber Controller with multiple DUTs, using a singleton Delacor QMH module for the controller, and multiple instances of a cloneable Delacor QMH module for the DUT. The chamber is configured to reach a temperature set point. Once the temperature is reached, multiple Units Under Test (UUTs) each perform a Self-Test and return the result. The Unit Under Test code is configured for an 80% pass rate for demonstration purposes.

This example illustrates that there is no need to have an event structure in the calling code and provides an example of two DQMH modules being used in a traditional  “Configure > Read/Write > Close” application. The example also illustrates how to manage multiple instances of a cloneable DQMH module.

To get the example:

  1. Go to Help>Find Examples
  2. On the NI Example Finder window, select Directory Structure>Delacor>Delacor QMH>DQMH Fundamentals – Thermal Chamber.
  3. Open DQMH Fundamentals – Thermal Chamber.lvproj.
  4. Open Thermal Chamber Controller with Multiple DUTs.vi.

LabVIEW Example 3: Thermal Chamber Controller with Multiple DUTs.vi

Table Of Contents

TestStand Examples

 

 

Note: The shipping examples do not require TestStand.

Note: For each TestStand example, there is a similar example VI.

Table Of Contents

TestStand Example 1: Thermal Chamber Controller Example.seq

 

 

This example sequence is a very simple introduction into calling the Public API of a DQMH module from TestStand. This example starts a Thermal Chamber Controller DQMH module (singleton) and executes the following sequence:

  1. Update the Set Point, Ramp Rate and Heater State (to allow heating).
  2. Monitor the status until the target Set Point is reached.

This example provides an example of a DQMH module being used in a traditional “Configure > Read/Write > Close” application. TestStand can be used to quickly define sequential operations to be performed by a DQMH module.

See LabVIEW Example 1: Thermal Chamber Controller Example.vi for a similar example in LabVIEW.

To get the example:

  1. Go to Help>Find Examples
  2. On the NI Example Finder window, select Directory Structure>Delacor>Delacor QMH>DQMH Fundamentals – Thermal Chamber.
  3. Open DQMH Fundamentals – Thermal Chamber.lvproj.
  4. Open Thermal Chamber Controller Example.seq.



Table Of Contents

TestStand Example 2: Thermal Chamber Controller Example With DUT.seq

 

 

This example sequence is an introduction into calling the Public API of multiple DQMH modules from TestStand. This example starts a Thermal Chamber Controller DQMH module (singleton) and a single instance of the Device Under Test DQMH Module (cloneable) and executes the following sequence:

  1. Update the Set Point, Ramp Rate and Heater State (to allow heating).
  2. Monitor the status until the target Set Point is reached.
  3. Perform a simulated self-test of the DUT.

To get the example:

  1. Go to Help>Find Examples
  2. On the NI Example Finder window, select Directory Structure>Delacor>Delacor QMH>DQMH Fundamentals – Thermal Chamber.
  3. Open DQMH Fundamentals – Thermal Chamber.lvproj.
  4. Open Thermal Chamber Controller Example With DUT.seq.

See LabVIEW Example 2: Thermal Chamber Controller with DUT.vi for a similar example in LabVIEW.

Table Of Contents

TestStand Example 3: Thermal Chamber Controller Example With Multiple DUTs.seq

 

 

This example sequence is an advanced example calling in to the Public API of multiple DQMH modules from TestStand. This example starts a Thermal Chamber Controller DQMH module (singleton) and multiple instances of the Device Under Test DQMH Module (cloneable) in addition to a TestStand Manager DQMH Module (singleton). The TestStand Manager acts as a relay, monitoring the execution status of the TestStand sequence and calling the Stop Module.vi of the other modules should the sequence be terminated or aborted. This prevents the likelihood of being left with orphaned running DQMH modules.

We utilize batch synchronization in TestStand to ensure that only a single thread will execute code associated with Thermal Chamber Controller operations. However, all threads will communicate and interact with a unique instance of the Device Under Test module. For more information on Batch Synchronization and Thread Scheduling please refer to the TestStand 1: Test Development course provided by National Instruments.

Note: This sequence programmatically sets TestStand to execute using the BatchModel.seq process model file in order to better demonstrate the use of cloneable DQMH modules.

See LabVIEW Example 3: Thermal Chamber Controller with Multiple DUTs.vi for a similar example in LabVIEW.

To get the example:

  1. Go to Help>Find Examples
  2. On the NI Example Finder window, select Directory Structure>Delacor>Delacor QMH>DQMH Fundamentals – Thermal Chamber.
  3. Open DQMH Fundamentals – Thermal Chamber.lvproj.
  4. Open Thermal Chamber Controller Example With Multiple DUTs.seq.




Table Of Contents

Running the DQMH Project Template

 

 



If the developer is creating an application employing multiple DQMH modules, start with the Project Templates:

  1. Click Create Project from the Getting Started Window in LabVIEW.
  2. Click the Delacor QMH Project Template.
  3. The following section assumes that the Include “Do Something” events in new module? option was selected and that the “My Singleton” and “My Cloneable” DQMH modules were not renamed when the project was created.

Select Delacor QMH Project Template



Create Project Wizard.

Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH.

  1. In the Project Explorer window, open and run My Singleton Module.lvlib:Main.vi.
  2. Click the front panel controls and watch the Status indicator display messages.
  3. Stop the VI by closing the front panel. Since the module was started as a standalone module, the front panel does not close, but the VI stops.
  4. Now run the Test My Singleton Module API.vi under the Testers virtual folder.
  5. Click the Start Module button and wait for the LED indicating that the Module is running to turn on.
  6. Click the front panel controls and watch the tester update according to the requests sent and the broadcasts received.
  7. Stop the tester by closing the front panel.

Table Of Contents

Using the Tester VI to Troubleshoot an Application while the Application is Running

 

 

The Tester VI can be used as a “sniffer” that displays the broadcast events fired by the DQMH Module Main.vi, and it can also send request events.

Follow these steps:

  1. Run Application.lvlib:Main.vi.
  2. On the Application.lvlib:Main.vi that is running and is titled “Application”, click the Start My Singleton Module button once, a My Singleton panel will show. Then go back to the Application window and click the Start New Instance button several times. Several My Cloneable module panels should appear.
  3. Click the front panel controls in Application.lvlib:Main.vi and observe the behavior of the DQMH Module Main VIs depending on the actions you performed.
  4. Choose different module instances to communicate with by selecting different options in the Select Cloneable Module Instance ring.
  5. Run the Test My Singleton Module API.vi under the Testers virtual folder.
  6. Click the Start Module button (at this point, this is only needed to get the correct state on the Module Running? indicator).
  7. See how actions on the Application.lvlib:Main.vi are reported in the tester. Also, actions can be initiated from the tester.
  8. Repeat steps 5-7 by running Test My Cloneable Module API.vi under the Testers virtual folder.
  9. Click the Refresh button to update the list of clones currently running.
  10. See how actions on the Application.lvlib:Main.vi are reported in the tester. Also, actions can be initiated from the tester.

Table Of Contents

Modifying this Template

 

 

The DQMH project template installs several utilities available in the Tools>>Delacor>>DQMH menu:

DQMH Productivity tools installed in LabVIEW Tools menu.

Table Of Contents

Adding a New DQMH Module

 

 

A DQMH module represents a task the application can perform, such as acquiring data or logging data, in parallel with other tasks. Each DQMH module can be divided into sub-tasks that correspond to states. The DQMH also responds to requests that other VIs can make in order to ask it to perform certain actions. It can also broadcast information to any VI that is registered to receive its broadcasts.

To create a new module:

  • Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH
  1. Go to Tools>Delacor>DQMH>Add New DQMH Module
  2. Provide a Module Name in the Add New DQMH Module dialog. This will be the name of the DQMH Module library.
  3. Provide a Module Save Path. By default, if this project was created using the DQMH project template, the module will be saved under the Libraries<Module Name> subfolder next to the .lvproj file on disk. A different path can be specified.
  4. Select the Module Type, either Singleton or Cloneable. A Singleton module only ever exists as a single instance. A Cloneable module can have one or multiple reentrant instances running simultaneously. See Adding a new DQMH Module from a Custom Template section for steps to add your own module types.
  5. Specify whether or not you want to Include “Do Somethingevents in new module? If you are already familiar with creating DQMH modules, you can deselect this option, which will create a DQMH module with the minimum required set of events.
  6. Optionally, click the Edit Overlay button. This overlay will be used by the new DQMH Module library and its VIs. This overlay can be later changed by right-clicking on the Module Library and selecting Properties>General Settings>Edit Icon.
  7. Click OK to create the new DQMH Module. The new module .lvlib and Tester VI will be selected in the project explorer window after the new module is created.

Add New DQMH Module wizard.

Table Of Contents

Adding a New DQMH Module from a Custom Template

 

 

The previous section describes how to add a new DQMH Module. This option lists “Singleton” and “Cloneable” DQMH modules as the only two types supported. Follow the steps below to create a custom DQMH Module template and add it to the list of available DQMH Module Types.  After completing the steps below, the available types will be “Singleton”, “Cloneable”, and “MyNewModule”. Where “MyNewModule” is the name of the new custom DQMH module template.

To create a new DQMH Custom Template:

  • Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH .

A DQMH Template Example can be downloaded from Delacor’s website.

  1. Create a new DQMH Module and customize it to fit your needs. Save your DQMH Module. This document refers to this new DQMH module as <MyNewModule>. Replace <MyNewModule> with the new DQMH Module name. Make sure that the DQMH module was created using Tools>Delacor>DQMH>Add New DQMH Module… and if you need to rename the DQMH Module, use Tools>Delacor>DQMH>Rename DQMH Module….
  2. Save the DQMH Custom Template in <LabVIEW Data>DQMH Module TemplatesSource<MyNewModule> folder.
  3. Save the Test <MyNewModule> API.vi in <LabVIEW Data>DQMH Module TemplatesSource<MyNewModule> folder.
  4. Create the DQMH Module Template MetaData XML file and save it as <LabVIEW Data>DQMH Module TemplatesMetaData<MyNewModule>.xml

XML Contents are:

<?xml version=”1.0″ encoding=”Windows-1252″ standalone=”yes”?>

<MetaData>

<DQMHTemplate>

<Title><MyNewModule></Title>

<Description>Replace the description with <MyNewModule> description. A sample DQMH module that demonstrates the plug-in functionality of the Add New DQMH Module utility.</Description>

<LocationPath>Delacor/<MyNewModule> </LocationPath>

<LibraryPath><MyNewModule>.lvlib</LibraryPath>

<TesterPath>Test <MyNewModule> API.vi</TesterPath>

<CustomVIPath></CustomVIPath>

</DQMHTemplate>

</MetaData>

  1. Go to Tools>Delacor>DQMH>Add New DQMH Module… and verify that <MyNewModule> is offered as an option for Module Type and the description text from the <MyNewModule>.xml file is displayed.

DQMH Template Example Disk Hierarchy.

Table Of Contents

Creating a New DQMH Event

 

 

A DQMH Event can be either a request or a broadcast. A request is code that fires an event that the DQMH Module Main.vi has to act on. A broadcast is code that fires an event that informs other VIs that are registered to listen that the DQMH Module Main.vi
has done something. There are also synchronous events of the type request and wait for reply. These events are fired when the DQMH Module Main.vi needs to return a reply to the VI that called the request and this calling VI must wait until it gets that reply (or the request times out).

To create a new event:

  • Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH
  1. Go to Tools>Delacor>DQMH>Create New DQMH Event….
  2. Two windows will open: the Create New DQMH Event window and the Arguments Window.
  3. In the Create New DQMH Event window select the DQMH module for which you wish to create a new event. This drop down menu will only list valid DQMH modules found within the project.
  4. In the Create New DQMH Event window, specify the type of event you wish to create. A description of each event type appears next to the drop down selection:
    • Request: An event generated by a caller that the module is registered to receive.

Typically a request event is a request for the module to “Do something”.

5.     Specify the name of the new event (in the case of the Round Trip option, specify the name for the request and the name for the broadcast).

6.     Add controls to the Arguments window. These values will be the arguments sent along with the event when it fires. Use a descriptive label for each control.

    • There is no need to wrap the arguments with a cluster in that window. The utility will take the controls in the Arguments window and add them to an Arguments typedef cluster. If you wish to receive all the arguments as a single cluster in the event loop, when the event fires, you may choose to wrap the arguments in a cluster. Examples include an x,y point, or a left, right, top, bottom values for a rectangle etc.
    • For Request and Wait for Reply events, a notifier reference does not need to be added in the Arguments window. The Create New DQMH Event utility will create the notifier and its typedef cluster payload automatically.
    • If the event is being created for a cloneable module, there is no need to add the Module ID control. The Create New DQMH Event utility will add the Module ID control to the Arguments typedef cluster automatically.
    • Existing typedefs can be added to the Arguments window.
    • If a new typedef is created in the process of adding controls to the Arguments window, you will be prompted to save the typedef before the event can be created.
    • At least one control has to be added to the Arguments window. This will make it easier to modify the code if the developer changes his mind and an argument is needed in the future. At that point a typedef argument cluster will be available for the developer to add other arguments.
  1. (Optional) Enter a description for the event. This description will be included as the VI documentation for the VIs that this tool created to fire the event created.
  2. Click OK to create the new event(s). The new event VI(s) will be selected in the project explorer window after creation is complete.
  3. The DQMH Module Main.vi and Tester VI will be broken. The developer has to complete several actions to complete the creation of this code, all of which are identified with #CodeNeeded bookmarks that can be explored with the Bookmark Manager window. DQMH 3.0 adds automatic wiring of event structure frames when used in LabVIEW 2016 or later.
  4. The developer needs to complete the following actions:
        1. Add a new front panel control to test the new request event.
        2. Open the block diagram, which should be showing the newly added event frame with the new request VI inside. Right-click on the event structure,  select Edit Events Handled by This Case, and select the control added in the previous step.
        3. By default, all the inputs of the request VI are required. Wire appropriate inputs to the request VI.
        4. The Tester VI should no longer be broken (assuming it was not broken before the new event was added).
        1. Open the block diagram, which should be showing the newly added event frame in the EHL and the newly added case frame in the MHL.
        2. Right-click the event structure, select Edit Events Handled by This Case, and select the newly created request that should be listed under Dynamic>><Module Name> Request Events.
        3. Wire the event data (<arguments label(s)>) to the Bundle function in the event frame.
        4. Add necessary code to the <request name> frame in the MHL case structure.
        1. Open the block diagram, which should be showing the newly added event frame with the #CodeNeeded bookmark. Right-click the event structure, select Edit Events Handled by This Case, and select the newly created broadcast that should be listed under Dynamic>><Module Name> Broadcast Events.
        2. Add code to process the event data sent by the broadcast event.
        3. The Tester VI should no longer be broken (assuming it was not broken before the new event was added).
        1. Open the block diagram, which should have the newly created broadcast VI on the left side with a #CodeNeeded bookmark.
        2. Move that VI wherever the newly created broadcast event needs to be called.
        1. Add a new front panel control to test the new request event.
        2. Open the block diagram, which should be showing the newly added event frame with the new request VI inside. Right-click the event structure, select Edit Events Handled by This Case, and select the control added in the previous step.
        3. By default, all the inputs of the request VI are required. Wire appropriate inputs to the request VI.
        4. Process the reply payload output from the new request VI.
        5. If the payload argument needs to be changed, open the new request VI and right-click the Reply Payload indicator to open its typedef and edit it accordingly.
        6. The Tester VI should no longer be broken (assuming it was not broken before the new event was added).
        1. Open the block diagram, which should be showing the newly added event frame in the EHL and the newly added case frame in the MHL.
        2. Right-click the event structure, select Edit Events Handled by This Case, and select the newly created request that should be listed under Dynamic>><Module Name> Request Events.
        3. Wire the event data (<arguments label(s)>) to the Bundle function in the event frame. Take special care to wire the Wait Notifier event node output to the Bundle function that the utility added.
        4. Add necessary code to the <request name> frame in the MHL case structure.
        5. Wire the proper reply to the Send Notification function.

Create New DQMH Event wizard.



Table Of Contents

Removing an Existing DQMH Event

 

 

To remove an existing event:

  • Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH
  1. Go to Tools>Delacor>DQMH>Remove DQMH Event….
  2. Select the DQMH Module containing the event you wish to remove. This drop down menu will only list valid DQMH modules found within the project.
  3. Specify the event you wish to remove. This drop down menu will let you select between all the request and broadcast events in the module.
    • Note that several requests and broadcasts are considered part of the DQMH core, and cannot be removed:
      • Core Requests:
        • Show Module Panel.vi
        • Hide Module Panel.vi
        • Get Module Execution Status.vi
        • Stop Module.vi
      • Core Broadcasts:
        • Module Did Init
        • Status Updated
        • Error Reported
        • Module Did Stop
        • Update Module Execution Status
    • Note that if the selected event is the request part of a round trip pair, both events will be removed.
  1. Click OK and the specified event will be removed.
  2. The error window will be displayed. The developer needs to complete the following actions:
    • In the case of a Request:
      • In the Tester VI:
        • Open the block diagram and find the event frame configured to test calling this request.
        • Right-click the event structure and select Delete This Event Case. This action should also remove the control added to test this request.
        • If prompted to save the request VI and its argument, select Don’t Save.
      • In the DQMH Module Main.vi:
        • Open the block diagram and find the event frame configured for this request (It might no longer be listed and instead say something like “Unknown Event (0x0)”).
        • Right-click the event structure and select Delete This Event Case.
        • Find the associated <request name> in the MHL case structure, right-click on the case structure, and select Delete This Case.
        • If prompted to save the request VI and its argument, select Don’t Save.
    • In the case of a Broadcast:
      • In the Tester VI:
        • Open the block diagram and find the event frame configured for this broadcast. (It might no longer be listed and instead say something like “Unknown Event (0x0)”.)
        • Right-click the event structure and select Delete This Event Case.
        • If prompted to save the broadcast VI and its argument, select Don’t Save.
      • In the Module Main VI:
        • Open the block diagram and find the places where the broadcast VI is called and remove it.
        • If prompted to save the broadcast VI and its argument, select Don’t Save.

Remove DQMH Event wizard.


Table Of Contents

Renaming an Existing DQMH Event

 

 

To rename an existing event:

  • Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH
  1. Go to Tools>Delacor>DQMH>Rename DQMH Event….
  2. Select the DQMH Module containing the event you wish to remove. This drop down menu will only list valid DQMH modules found within the project.
  3. Specify the event you wish to rename. This drop down menu will let you select between all the request and broadcast events in the module.
    • Note that several requests and broadcasts are considered part of the DQMH core, and cannot be renamed:
      • Core Requests:
        • Show Module Panel.vi
        • Hide Module Panel.vi
        • Get Module Execution Status.vi
        • Stop Module.vi
      • Core Broadcasts:
        • Module Did Init
        • Status Updated
        • Error Reported
        • Module Did Stop
        • Update Module Execution Status
  1. Specify the new name for the event.
  2. Click OK and the specified event will be renamed.

Note: The renamed DQMH Event VI will include a note in its documentation indicating “This VI was renamed by the DQMH Rename Event utility. Make sure the VI Description is updated to reflect the new event name, then delete this comment”. Also, none of the arguments nor MHL cases will be renamed. This is a security measure, because other code might be enqueuing to that case in the MHL loop.

Rename DQMH Event wizard.

Table Of Contents

Renaming an Existing DQMH Module

 

 

To rename an existing DQMH module:

  • Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH
  1. Go to Tools>Delacor>DQMH>Rename DQMH Module….
  2. Select the DQMH Module you wish to rename. This drop down menu will only list valid DQMH modules found within the project.
  3. Enter the new name for the module.
  4. Click the OK button and wait for the module to be renamed.
  5. Right-click Renamed Module.lvlib>>Properties>>General Settings>>Edit Icon and edit the Icon Text>>Line 1 text to make the header reflect the new module’s name. Make any other changes like color and click OK when done.
  6. Click the OK button on the Library Properties window, and when prompted to apply the new icon to all the VIs in the library, click Yes. Accept saving all VIs when prompted.
  7. Run the Test Renamed Module API.vi and observe how all the places where used to have the old module’s name have the new one.

Rename DQMH Module wizard.


Do not forget to edit the icon for the DQMH renamed module!

Table Of Contents

Validating an Existing DQMH Module

 

 

Each DQMH release adds new features and improvements.

The Validate DQMH utility analyzes a DQMH module and suggests fixes to implement the improvements from the newer versions.

Videos demonstrating the following steps and other examples are available at: bit.ly/DelacorQMH

  1. Go to Tools>Delacor>DQMH>Validate DQMH Module….

Table Of Contents

Related Information

 

 

The Delacor Queued Message Handler (DQMH) template is based on the National Instruments Queued Message Handler Project Template (NI QMH) that ships with LabVIEW 2012 and later. The NI QMH documentation can be found by clicking Create Project from the Getting Started window in LabVIEW and then clicking the More Information link in the NI QMH project description. You can also create a project based on this template, which will include a copy of the documentation.

Implementing communication between DQMH modules using events was based on the concepts presented by Justin Goeres during CLA Summit 2011 and NIWeek 2011 (more information here). The main modifications to Justin’s approach were (1) changing the nomenclature from Private/Public events to Request/Broadcast events, and (2) using the NI QMH as the basis for the modules instead of the JKI State Machine.

Refer to the Thermal Chamber Control example available from the Help>Find Examples…>Directory Structure>DelacorDelacor QMH>DQMH Fundamentals – Thermal Chamber for examples on how to use this template in applications.


Getting started videos and demonstrations can be found at: bit.ly/DelacorQMH


DQMH Best Practices and Guidelines can be found at: DQMH Best Practices

Table Of Contents

Legal Information

 

 

Copyright © 2015-2016 by Delacor, LLC. All Rights Reserved.

Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of Delacor, LLC.



Table Of Contents