iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
The NRT Designer

Starting NRT Loaders and the Designer

The NRT Designer is a graphical user interface (GUI) that allows users to create networks of interconnected modules througfh simple drag and drop actions.

The NRT designer itself is just a graphical representation. Actual computation is done elsewehere.

A distributed blackboard federation in NRT is typically run by starting one or more NRT loaders on one or more computers. Each NRT loader can be instructed to load, unload, configure, start and stop one or more NRT modules. The NRT designer interacts with the NRT loaders by sending load, unload, etc instructions as the user issues mouse actions in the Designer.

The first loader that is started should assume the role of blackboard federation master. Subsequently started loaders will assume the role of client and will connect to the master. See Messages, Blackboard and Modules for discussion of these roles.

Before starting your loaders on your diffrerent computers, you need to let them know where they can find collections of NRT modules that can be dynamically loaded. This is achieved by setting the NRTMODULEPATH environment variable, which is a comma-separated list of directories in which NRT should look for Modules.

Make sure that the NRTMODULEPATH environment variable is set. For example, if you are using the nrtilab collection of modules, you would issue:

export NRTMODULEPATH="${HOME}/nrtilab/src/Modules"

Typically, you would use shell scripts or other helpers to start/stop your loaders, but in the end those should issue:

  • On the master machine:
    nrtLoader --master
  • On each client machine:
    nrtLoader --masterip=MASTIP

Where you would replace MASTIP by the I.P. address (or host name) of the machine on which the master nrtLoader was started. See the documentation of nrtLoader for details.

Once you are running your loaders, you can start the NRT Designer:

nrtDesigner --masterip=MASTIP

Where MASTIP should be the I.P address (or host name) of the master machine. This will open the NRT Designer's graphical interface in a new window.

The NRT Designer Interface

The NRT Designer graphical interface contains 4 basic panels (which you can re-arrange by simply dragging them):

  1. Center panel: The main network canvas. This is the area in which you will drag NRT modules and connect them together.
  2. Left sidebar: Displays a list of availalable modules that can be dragged into the network canvas, or, when a module in the canvas is selected, displays that module's parameters and other information.
  3. Top sidebar: When a module is selected, displays the documentation of that module.
  4. Bottom sidebar: Displays the NRT loaders currently running as one blackboard federation, and some statistics about each loader (CPU usage, memory usage, etc).
designer.png

Finding a module

You can find modules by first clicking in a blank region of the network canvas (to un-select any currently selected module) and then browsing or searching in the left sidebar. Once you find a module, you can simply drag it from the left sidebar into the network canvas.

Note
The machine that is currently selected in the bottom sidebar is the one onto which any module you drag into the network canvas will be loaded. It is also the one that determines the list of available modules displayed in the left sidebar (in case not all of your computers have access to the same collection of modules, for example, if one of the loaders of a robotic system is running on some exotic CPU hardware and only a few modules have been compiled for it).
module-search.png

Image above: Searching for a module. Here we first selected the machine that we want to run the next module on (bottom sidebar). Then we used the search feature in the left sidebar. We can click on a module to see its documentation appear in the top sidebar. Once the desired module is found, we can drag it from the left sidebar into the network canvas, which will in effect load that module on the selected computer.

Basic designer operation

The designer's interface is quite intuitive and allows you to:

  • Zoom the network canvas in and out using your scroll wheel;
  • Move modules using the left mouse button to drag them;
  • Select a module by clicking once on it. This displays its information and parameters in the left sidebar. Click in the white background of the network canvas to revert the left sidebar back to the list of available modules;
  • See information about a port by hovering your mouse over that port;
  • Connect one port to another by left-clicking and holding on that port. This displays, using dashed lines, all the other ports that you could connect to, if any (those must have matching message and return types). To select one of these candidate connections, simply move your mouse towards the port that you want to connect to. When your mouse is sufficiently close to the target port that there is no ambiguity that you want to select that one, the corresponding connection turns from grey to black. You can then just release the left mouse button and the connection will be created;
  • Delete a connection by clicking on it to select it, then pressing the Delete key on your keyboard;
  • Delete a module by clicking on it to select it, then pressing the Delete key on your keyboard;
  • Split or un-split a port, if the message type of that port indeed is splittable, by right-clicking on that port;
  • Create or import a macro-module by right-clicking an a blank region of the network canvas. More details on macro-modules below.
create-connection.png
Creating a connection between two ports using the left mouse button.

Saving / loading your work

Use the main program menu to save your work. You will provide a directory name and the contents of your network canvas will be saved into that directory, possibly creating sub-directories for macro-modules.

You can re-load your work later from that same directory.

Running your Network

Use the Start / Stop button just above the top sidebar to start/stop your network.

Pressing Start will basically switch all modules to running state (where they can receive and process messages) and will start all the run() functions of all modules. As we have seen in Module Types, source modules will then start posting data. This in turn will trigger filter modules, which will receive the data, transform it, and post results. This will possibly trigger more filter modules and also possibly some sink modules.

Note
You can still change parameters, add/delete connections, and even add/delete modules while the system is running. This is actually quite cool to do, as you will see the effects of what you do immediately on the data that you are processing.

Macro-modules

Macro-modules are simple containers that make a whole network of modules appear just like one module. Macro-modules are very convenient to create repetitive structures and to develop complex networks of modules in a clean and hierarchical manner.

To create a macro-module, right-click in a blank region of the network canvas and select Create Macromodule. Then give a name to your macro-module. A new box will appear in the network canvas for your macro-module, with its name and initially no port.

To enter a macro-module, double-click on it. In the top-left corner of the network canvas you will notice a macromodule description path, which indicates how deeply inside nested macro-modules you currently are. You can click on any of the levels shown to navigate in and out of the macro-modules.

In a macro-module, you will notice three grey boxes called Subscribe, Post and Check. Those are hot zones that will allow you to create ports for your macro-module. To create a new port, simply drag a connection from one of the modules inside your macro-module to one of these zones. You will be asked to choose a name, this is the name that you want to give to this port. This name is viewed on the outside of the macro-module when users hover the mouse over the port, so you should use a descriptive name.

macro-module1.png

Image above: Inside a macro-module where we have instantiated and connected three modules, then creating one subscriber and one poster port for the macro-module.

macro-module2.png

Image above: Outside view of the macro-module from the previous image, where we can see the subscriber and poster ports that have been created. These ports can be used just like any other port, and the macro-module is used just like any other module.

Note
Macro-modules are also sometimes called namespaces in NRT. Indeed, there is no real shell or physical boundary for a macro-module. What makes the inside of a macro-module special is that it is isolated from the outside, and this is achieved in NRT by placing all the inside modules into a namespace that is unique to the macro-module instance. This means, in particular, that there is nothing wrong with having different modules running on different machines in one macro-module. A macro-module is just a logical grouping of several modules into an isolated namespace.