Offline Antidoc documentation and some more DQMH questions

[Roey]

Hello,

1. I  start working now on a big project using DQMH framework.I want to use Antidoc add-on for documentation, but unfortunately I do not have intetrnet access in my workspace. So after some research I succeeded to download and install Antidoc and its dependencies (I dounloaded the Ruby zip folder and extracted it manually in its place), but then I realized that the rendering process (to PDF etc.) also needs online environment. Only when I got into the render sub vi and deleted the call for the url adress I succeeded to create a PDF document, but it was without all the diagrams..

My question is, is there a way to create a complete PDF or HTML (or other format) document without an internet access?

2. Another question is about the diagrams inside the document (I created (in an online PC) a document for a DQMH project that I dounloaded (file attached)):

    In chapter 2.2. there is a diagram of modules overview which has only one arrow betrween any two modules. In contrast, in chapter 2.3.2 there are two arrows represents requests for one module to itself. The question is why there isn't only one arrow that represent all the requests from the module to itself? (as it is writen before that one arrow can represent one or more events...)

3. Is there any tool for pre-design of the project? like bubbles diagram, tables of events etc. And in general - what is the best way for thinking about the project architecture?

4. More specifically to 3, I tried to think about some rules for deciding what has to be a separate module:

    1) It has a separate UI.

    2) It is used to controll a specific HW

    3) It may run as a stand alone application.

Are these rules makes sense? is there other criterions for making something a module?

5) During my previous work I realized that there are some cases in which I have dependencies between modules, For example - Module A gets request that - in its turn - requests module B (which can request other modules etc.). Should I avoid this scenario? (I know that I cannot use the tester in this case without initialize all the relevant modules. Are there other problems? is it possible to make a whole project without such dependencies?)

I know this are a lot of questions... I appriciate your help.

Thanks a lot,

Roey

[Ozfarmboy]

Hi Roey,

I'll leave the Antidoc questions for Olivier!

---

3. Is there any tool for pre-design of the project? like bubbles diagram, tables of events etc. And in general - what is the best way for thinking about the project architecture?

At one point we were exploring this as a feature of OpenGDS .  In the latest version, you can use the UML diagram tool to create a DQMH diagram. However it didn't get completed, and the project fell by the wayside due to other priorities taking precedence!

But what we do at Wired-in is the following.  These are both important design steps that we go through for EVERY DQMH-based project:

1) Create a block diagram of all of the modules and their general interfaces - simply using Powerpoint or other drawing tool.  This helps everyone get on the same page for what we are developing and each module's purpose.

2) We create a spreadsheet to map out all of the events we'll need in the system and then in a matrix map the events to the calling/receiving modules.

4. More specifically to 3, I tried to think about some rules for deciding what has to be a separate module:

    1) It has a separate UI.

    2) It is used to controll a specific HW

    3) It may run as a stand alone application.

Are these rules makes sense? is there other criterions for making something a module?

---

This was discussed recently here:

Solved: Re: DQMH Register for Events height for large "ish" applications - Page 2 - NI Community

and here:

DQMH overhead - NI Community

Put simply, my guidelines are:

Create a DQMH module if the code needs to be dynamic, self-managed, asynchronous, dependent on classes and is likely to be called in multiple places, or has a UI element. 

---

5) During my previous work I realized that there are some cases in which I have dependencies between modules, For example - Module A gets request that - in its turn - requests module B (which can request other modules etc.). Should I avoid this scenario? (I know that I cannot use the tester in this case without initialize all the relevant modules. Are there other problems? is it possible to make a whole project without such dependencies?)

---

Don't be afraid to make some modules dependent on other modules.  This is ok.  Just don't make them circular dependent!  (In other words, don't allow two different modules to send requests both ways - only request one way, and broadcast the other).

It's good design to keep your modules generally independent, if you expect you'll reuse those modules in future applications.  ie. You might have a module that is managing a motion control device.  If you make this independent, then it's easy to port that across to another project in the future. 

But you'll always have some sort of project specific parts of your code that are not reusable, and will be dependent on other modules.

We tend to have a top level module that is pretty much dependent on everything, but then you might have some middle layer modules that depend on lower layer modules which is unavoidable.  So you need to ensure that the launching of the lower level modules is handled by the middle layer, so that you can still fire up the API tester for the middle layer module to be able to test it.  It is dependent on the lower level, so you can simply not avoid that from running.

[Olivier-JOURDAN]

Hello @Roey 

I'm glad you're using Antidoc (and hope you find it useful)

Concerning your questions:

1. It's completely possible to generate the final document offline but really difficult to automate the installation of all the needed components. That being said, I encourage you to read this conversation on the Wovalab Open-Source Zulip chat. You should find there all the needed information.

2. Multiple requests to a module should be represented by a single arrow. As far as we are on a specific case (message to itself), there's probably a bug. An existing issue related to this already exist that asks to remove those arrows when they are part of the framework-level implementation -> https://gitlab.com/wovalab/open-source/antidoc-document-types/labview-project/-/issues/56. Implementing this will probably fix the issue you raised. Anyway, fill free to fill in a new related issue for the specific error you are reporting.

Note: for questions related to Antidoc, please use the Zulip chat. This allows to gather all support discussions and help all Antidoc users 🙂 

[roey_p]

Thank you for your answers!

Christofer,

I read the issues you linked above and it was very helpful. I will be happy if you can explain in detail about the layers principle and the recommended limitation of 3. If for example I have one main UI module and in addition I have 2 or 3 mudules for HWs - Does the UI module is the upper layer and the HW's modules are the middle layer? what will be for example the lower layer in this case? 

In addition, can you explain what is the reason for not making 2 modules depend on one each other? If for example module A requests module B to do something which requests module A to do another thing - so if I now using module A API Tester i can fire both events separately even if module B is not running now.. Isn't it? 

Olivier, I will try the instructions you linked and I will continue the conversation in Zulip Chat if necessary, as you suggested.

Thanks again!

Roey

[Ozfarmboy]

Hi Roey,

DQMH module layers

To be clear, we are talking about generally limiting your application to 3 layers (not 3 modules).  But it really comes down to what your application needs.

How I usually see it (from the bulk of applications we build), is that we typically have one or more instrument/hardware device modules.  I see these as the lower layers.  Other lower layers we typically have are event/error logging, configuration editor, help panel, database, etc. For the most part, we simply then have an upper layer module that is the application module, and user interface.  So just 2 layers (typically).

Occasionally, we need a middle layer to help manage the devices in a specific way.  We might have a large number of devices and we want to coordinate or synchronise their data, and not burden the application layer with this management activity. So we set up a "device manager" module that sits in between the upper layer and the lower layers. OR we may require a UI module that is a middle layer, that depends on the lower modules, and the upper layer needs to be aware of it's activity.

Circular Dependencies

If you have two modules depending on each other, then this is a circular dependency and you can get into corner case situations that are very difficult to track down.  I did it when I first implemented DQMH and it was confusing and took a while to work out what was wrong!

• Module A should use Module B requests, request and wait for replies, and roundtrips. 
• Module A should be registered to Module B's broadcasts. 
• Module B shouldn't use Module A requests. 
• Module B shouldn't be registered to Module A's broadcasts.   

Basically Module B shouldn't really know that Module A exists, or what Module A is.  But it does hope that another module out there is listening to it's broadcasts.

So instead of say Module A requesting Module B to do something, and then Module B requesting Module A to do something else - tweak this approach to instead have Module B broadcast to say it's finished it's task or it's ready for something to happen (which is essentially notifying Module A to do something).  This could be done using a Roundtrip event.

I think if Module A depends on Module B, then when you're testing Module A, you also need Module B running, which is why I suggested earlier that Module A should be launching Module B.

I am speaking very generically here, so not sure if this is helpful.  I highly recommend reaching out to DQMH.org for some consultation advice to get your project off and running on the right track.  I did this five years ago when I first started using DQMH and it helped us so much and saved so much time on our project (and future projects).

[Roey]

Hi Christofher,

Thank you for your detailed answer! if it is OK I want to ask some more questions about things that you nentioned..

1. As I understand, the lower layer is, in addition to the HW modules, some "helper modules". So do you have separate modules for error logs? for help? I didn't see such modules in DQMH projects that I learned from. Can you go into details about that?

2. I do have a lot of HWs in my application. How do I build the device manager module? Do you mean to classses (Object Oriented)?

3. I have in my project a logger module, but I need to log the data twice - ones before processing and secondly after it. Is this the case for making the logger module cloneable?

4. Circular dependancy - In the CML UI template the data is sent to the logger module as a request to log, and to the UI module as a broadcast. Actually the data could be sent to the UI also as a request to display it. Is the reason for sending it as a broadcast is to avoid circular dependancy?

If you have any link to a more complicated DQMH project that can help me understand the subjects above, I appriciate if you can share it with me.

Thank you,

Roey  

[joerg.hampel]

Feel free to take a look at our HSE Application Template. It is not a complex project per se, but it might give you some inspiration:

https://dokuwiki.hampel-soft.com/code/dqmh/hse-application-template

I'd say that there are no "right" answers to your questions, much of this depends on the situation and the requirements, what other libraries you might have etc.

⭐️ These topics are also discussed in the Official DQMH Training Course.

[Roey]

Thank you Joerg!

I spent a lot of time in your page 🙂

There is so much information there so I sometimes get lost but I will try again to learn the template.

Roey 

[Ozfarmboy]

---

@Roey wrote:

...

1. As I understand, the lower layer is, in addition to the HW modules, some "helper modules". So do you have separate modules for error logs? for help? I didn't see such modules in DQMH projects that I learned from. Can you go into details about that?

Yes we have a separate error/event log module.  The way we do this is all errors are sent to our main module (top layer), and then these errors are pushed to the error log module.  We siphon them all through the main so that the main application can make a decision if the error is serious.

---

2. I do have a lot of HWs in my application. How do I build the device manager module? Do you mean to classses (Object Oriented)?

---

No I didn't mean classes.  Just creating a module to manage multiple devices and bring data together - especially useful if you're managing clones.

---

3. I have in my project a logger module, but I need to log the data twice - ones before processing and secondly after it. Is this the case for making the logger module cloneable?

---

Sure, you could do that.

---

4. Circular dependancy - In the CML UI template the data is sent to the logger module as a request to log, and to the UI module as a broadcast. Actually the data could be sent to the UI also as a request to display it. Is the reason for sending it as a broadcast is to avoid circular dependancy?

---

I'm not familiar with the CML sample project.  I'll let someone else answer that one.

[Roey]

Ok, thanks a lot for your help and advices! I'll try to continue from here and I guess there will be some more questions in the future...

Roey