QuickStartExplorer

Step 2: The LabRAD Explorer

Overview

Expect the LabRAD Explorer to become your new best friend. This program gives you access to your entire LabRAD system. It allows you to browse all available Server Modules and the list of functions they provide. You can even send Requests to these Servers and view the Responses. This makes the LabRAD Explorer a very powerful testing and debugging tool.

Running the Explorer

Just like the Manager, the Explorer is also available from the download section of this project and consists of a single executable - Explorer-v1.1.2.exe - that also does not require installation. Please execute it in the same way as the Manager. The Explorer will not save any configuration files.

Connecting to the Manager

All LabRAD Modules written in Delphi will most likely prompt you the same way for the information they need to connect to the Manager. The first of two dialogs will ask you which computer the Manager is running on. Since you probably have the Manager running on the same machine as the Explorer right now, the default (localhost) should be correct:

Next, you need to provide the same password that you told the Manager to use to authenticate connections:

The program window should now look something like this:

Troubleshooting

If you mistyped the password, or the Manager is not running on the computer given to the Explorer, or your firewall is blocking the connection, or the computer that the Explorer is running on is not in the list of accepted hosts in the Manager, the connection will fail, and the "Servers" list will remain empty. It should always at least show the "Manager" and "Registry" entries. If the network connection failed, you will receive an error message saying something like "Connect failed with error code 10061". If you provided the wrong password, you will probably just see a message saying "Connection to Manager lost". The Explorer, in its current version, will not give you the option to try again. So, simply close the program and start it fresh one more time. This really should not be happening right now, though...

Interface

This information is essentially provided in the little Welcome text in the top right corner of the program (which you can always get back to by hitting the refresh button above the "Servers" list), but let's go over it here anyways:

The top half of the program (the "red" part labeled "LabRAD System") allows you to browse all Servers connected to the LabRAD System to see the settings they provide and to retrieve the help texts that the developers have hopefully stored in them. Thus, the LabRAD Explorer should be usable as the primary source of documentation for all features of the LabRAD Setup. Let's play a little with this:

If you click on the Manager in the Servers list (or alternatively use [Tab] and the arrow keys), the Welcome text should change to show a very general description about its purpose.

If you double-click on the Manager (or click on the [+] icon, or use the right arrow), you can expand the list to see all the Settings provided by the Manager. Click on one of them (or use the arrows) and you should see the associated help text appear on the right. This help text consists of 3 to 4 parts: A quick sentence description of what this setting does, the Data Types (see below) accepted by the Setting (with optional description of what the specific format does, e.g. Help setting), the Data Types returned, and optionally some further notes.

Feel free to take a minute and look over some of the features provided by the Manager or Registry. We will go over some of them below.

Let's go over a small bit of background knowledge before we proceed:

There are three types of units of information that get passed around the LabRAD System: Requests, Responses, and Messages. As the names already suggest, Requests are used by Clients to instruct Servers to take a certain action or to return a certain result. Responses are the answers to the Requests. Every Request has to be honored with a Response, even if that Response contains no additional information. Let's not worry about Messages for now.

The difference between a Server and a Client Module is that Server Modules can receive and handle Requests. Both of these Modules can issue Requests and receive Responses, though.

The LabRAD Manager consists essentially of two parts: The networking backbone that routes packets behind the scenes, as well as a Server called "Manager" (the one you see in the list) that services a basic set of LabRAD Requests.

Requests can be bundled into Packets. As far as the Servers are concerned, though, there should be no difference between two Requests arriving in two separate Packets or in a single one.

Each Request has Data associated with it that contains the parameters of the requested action. LabRAD supports a small yet powerful set of basic types of data, as well as the option to combine these types into arrays (multi-dimensional rectangular tables of homogeneous elements) and clusters (one-dimensional collections of heterogeneous elements). Each piece of data is accompanied by a Type Tag, a sequence of letters and symbols that describes the Data Type. Each basic type has a letter associated with it, like i for an integer or s for a string (text). Arrays are denoted by nt where "n" specifies the dimensionality of the array and is optional for 1D arrays and "t" is a type tag describing the data in the array, e.g. 2s for a 2D array of text. Clusters are written as type tags enclosed in parentheses, e.g. (is) for a cluster containing an integer and a string. For more information refer to the Data Types section. In fact, why don't you open the Data Types page in a separate browser window and take a very quick look at it. It will be a good reference for the things to come until you feel comfortable with Type Tags.

Back to playing with the system:

Let's send a Request to the Manager to have it do some unit conversion for us. You can choose between three ways of using the Explorer: Keyboard, Mouse using clicks and menus, and Mouse using drag and drop. You can skip to your preferred method below:

Keyboard

You can switch between the different lists and text fields using [Tab]. Inside them you navigate with the arrow keys as always. So, let's press [Tab] until the "Servers" list is highlighted. In there, use the up and down arrows to select the Manager. Use [Ctrl]+[Enter] to begin a new packet for the Manager. This should add an entry to the "Available Packets" list and expand the settings that the Manager offers (if needed). Now use the arrow keys to move down in the "Servers" list until you find the "Convert Units" entry. Again press [Ctrl]+[Enter]. This should add a Record to the Packet under "Available Packets" and move the focus into the Content Editor in the bottom right quadrant of the program. In this field, let's type 1.2 in^3, 'm^3' (the space between 1.2 and in^3 is important!). The editor should highlight 1.2 in^3 in dark blue and 'm^3' in gray, showing that it correctly identified the data types. Also, below the edit field, the "Type Tag" should read v[in^3]s, i.e. a value in units of cubic inches followed by a string. Now press [Esc] and you will find yourself in the "Available Packets" list. Highlight "Convert Units" and press [F2]. You can now rename this Record to something a little more descriptive, like Convert 1.2in^3 to m^3 (complete the editing with [Enter]). This is an "Explorer only" convenience feature. The actual LabRAD Request does not have Packet or Record labels associated with it. Now, press the up arrow to highlight the "Manager" Packet (not the "Convert..." Record) and press [Ctrl]+[Enter]. This sends off the Request. You should now find yourself in the "Received Packets" list highlighting the Response Packet. A quick down arrow will select the Reply to our "Convert ..." Request and show the content in the editor on the right. The bottom half of your Explorer window should now look pretty much like that in the screenshot at the beginning of this page.

Clicks and Menus

Find the "Manager" entry in the "Servers" list and right-click it. From the popup menu select "New Packet". This should add an entry to the "Available Packets" list and expand the settings that the Manager offers (if needed). Find the "Convert Units" entry in the "Servers" list, left-click on it to highlight the entry, then right-click it and select "Add to Packet". This should add a Record to the Packet under "Available Packets" and move the focus into the Content Editor in the bottom right quadrant of the program. In this field, let's type 1.2 in^3, 'm^3' (the space between 1.2 and in^3 is important!). The editor should highlight 1.2 in^3 in dark blue and 'm^3' in gray, showing that it correctly identified the data types. Also, below the edit field, the "Type Tag" should read v[in^3]s, i.e. a value in units of cubic inches followed by a string. Now, in the "Available Packets" list, right-click the "Convert Units" Record and select "Rename". You can now rename this Record to something a little more descriptive, like Convert 1.2in^3 to m^3. This is an "Explorer only" convenience feature. The actual LabRAD Request does not have Packet or Record labels associated with it. Now, left-click on the "Manager" Packet (not the "Convert..." Record) to highlight it, then right-click and select "Send". This sends off the Request. You should now find yourself in the "Received Packets" list highlighting the Response Packet. Click on the "Convert ..." Record and you will see the content in the editor on the right. The bottom half of your Explorer window should now look pretty much like that in the screenshot at the beginning of this page.

Drag and Drop

Find the "Manager" entry in the "Servers" list and drag it into the "Available Packets" list. This should add an entry to the "Available Packets" list and expand the settings that the Manager offers (if needed). Find the "Convert Units" entry in the "Servers" list and drag it on top of the "Manager" Packet in the "Available Packets" list. This should add a Record to the Packet under "Available Packets" and move the focus into the Content Editor in the bottom right quadrant of the program. In this field, let's type 1.2 in^3, 'm^3' (the space between 1.2 and in^3 is important!). The editor should highlight 1.2 in^3 in dark blue and 'm^3' in gray, showing that it correctly identified the data types. Also, below the edit field, the "Type Tag" should read v[in^3]s indicating a value in units of cubic inches followed by a string. Now, in the "Available Packets" list, click the "Convert Units" Record to highlight it. Wait a quick second and click it one more time (make sure you wait long enough so that your two clicks are not identified as a double-click). You can now rename this Record to something a little more descriptive, like Convert 1.2in^3 to m^3. This is an "Explorer only" convenience feature. The actual LabRAD Request does not have Packet or Record labels associated with it. Now, drag the "Manager" Packet (not the "Convert..." Record) down into the Received Packets list. This sends off the Request. You should now find yourself in the "Received Packets" list highlighting the Response Packet. Click on the "Convert ..." Record and you will see the content in the editor on the right. The bottom half of your Explorer window should now look pretty much like that in the screenshot at the beginning of this page.

Congratulations

You have just completed your first LabRAD Request! You should probably play a bit more with this and convert a couple more units, like for example use the "array" way of doing so, i.e. type [1.2 in^3, 3.9 in^3, 6.2 in^3], 'm^3' in the content editor. Also, check out the "Pretty Print" Setting that can accept any Data Type and returns a string describing it.

Note that the help information provided by the Settings will tell you about the Type Tag that the setting expects (__(vs)__) rather than how to enter the data into the Content Editor ([1.0 in, 2.5 in], 'm'*). Type Tags are the LabRAD way of describing Data and are valid for any method of talking to the LabRAD system, including through the APIs for different programming languages. The Content Editor is simply an interface provided by the Explorer to allow you to create these data structures and requires syntax that deviates from the type tags. Below the editor you will see a field labeled "Type Tag" that shows you the Type Tag of the data you just entered. To the left of the editor is a color key that helps you visually verify that the Explorer parsed your data correctly. If you hold the mouse over one of the color letters or brackets, a tool-tip will give you examples of how to enter this data type. You should play with the Content Editor and the "Convert Units" and "Pretty Print" setting until you feel comfortable building data structures. You can also find more in-depth explanations and examples in the Data Types section.

For Manager Settings that actually do something useful, you can use the "Whitelist" and "Blacklist" Settings to add and remove computers to and from the Access Restrictions list in the Manager. You can see their effect if you select the Manager and click on the icon. What's most important is that you get a feeling for the different available Data Types, how to type them into the Explorer such that it identifies them correctly, and what can go wrong if you send the wrong data type, or incompatible units, etc. Also, the Explorer uses standard LabRAD Requests to build the "Servers" list and grab the help texts. Try to reproduce these features manually.

Next

 

~ Markus Ansmann, Dec 27th, 2007