How to install Maestro 3.x

Maestro 3.x does not come packaged with an installer utility, but setting up the program itself is simply a matter of copying the required files to a selected directory in the host system and making one change in the Windows registry. In order to run experiments, of course, you will need to install the RTX runtime environment and all of the required hardware, but you need not install the drivers for these devices. You must have "Administrator" privileges to perform the installation.

Ensure the host machine satisfies Maestro's system requirements

A minimum 3GHz quad-core processor (Intel i5/i7) is recommended, with 2-4GB RAM. You'll need at least two open PCI-Express (PCIe) slots on the motherboard to hold the PCIe-6363 and Intel Gigabit CT network card, plus an open PCI slot for the Detroit C6x (and that slot must conform to PCI specification 2.2 or older; the PCI 2.3 and later specs do not allow 5V-only cards like the Detroit). An additional PCI or PCIe will be needed for a second network card if you will integrate Maestro with the EyeLink tracker. As the older PCI slot is being phased out in favor of the faster and more versatile PCIe standard, you may have to shop around for a vendor that supplies workstations with PCI. Finally, be sure that the 32-bit version of Windows 7 is installed on the system. The current version of RTX (RTX 2011) does not yet support Windows 7 64-bit. If you plan to use any legacy hardware, particularly any ISA-based devices, then you will have to look even harder for a computer to meet your needs. ISA devices are very old; the ISA bus was no longer included in mainstream PCs manufactured after January 2000. However, as recently as Mar 2009 we were able to purchase workstations with PCI and ISA slots from Orbit Micro.

Check the HAL

The Hardware Abstraction Layer is a low-level software component through which the operating system communicates with the hardware devices installed in the machine. IRQ assignment and handling is part of the HAL's job. Windows supports a number of different HALs, and the one that is installed on a machine depends on whether the motherboard/chipset sports a standard programmable interrupt controller (PIC) or the newer advanced PIC (APIC), whether or not it supports the Advanced Configuration and Power Interface (ACPI) specification, and whether or not it has multiple processors. The most basic HALs are the "Standard PC" (hal.dll) and "Advanced Configuration and Power Interface (ACPI) PC" (halacpi.dll). These lack support for the APIC (not ACPI! yes, it's confusing!), while the "ACPI Uniprocessor PC" (halaacpi.dll) and "ACPI Multiprocessor PC" (halmacpi.dll) support it. If either of these HALs are installed, you'll potentially have more flexibility with IRQs since the APIC supports up to 24 interrupt lines. The latest HAL and the one you're most likely to see in Windows 7 PCs with multi-core processors is the "ACPI x86-based PC" HAL.

RTX provides a real time-enabled extension to the HAL; it is compatible with all of the standard Windows HALs listed above. We recommend using the "ACPI x86-based PC" HAL, which supports message-signaled interrupts. Avoid the "ACPI Uniprocessor PC" and "ACPI Multiprocessor PC" HALs. While testing a newly configured Maestro 2.x-era machine, we found that an RMVideo trial would consistently abort after 5-7 seconds on a "duplicate frame error". This indicated that Maestro failed to provide frame update information in time to draw the next display frame. While we don't know for sure, we believe this is due to a delay in the RTX TCP-IP stack when the HAL is either "ACPI Uniprocessor PC" or "ACPI Multiprocessor PC"; when we changed the HAL, the problem went away.

To check the HAL, open the Windows Device Manager. Click on the Computer node in the device tree to expose the HAL type. To change the HAL, right-click on the HAL node and select Update Driver from the context menu. The "Hardware Update Wizard" appears. Choose option "No, not this time" and click Next; then choose option "Install from a list or..." and click Next; then choose option "Don't search. I will choose..." and clickNext. In the next stage, make sure the "Show compatible hardware" box is checked; all compatible HALs should then be listed. Choose one of these HALs, if available, in descending order of preference: "ACPI x86-based PC", "Advanced Configuration and Power Interface (ACPI) PC", or "Standard PC". Click Next to install the selected HAL. Click Finish and restart the machine. Upon restart, Windows will complete the HAL conversion and you'll have to restart once more. Be sure to change the HAL before installing RTX. If you discover that you must change the HAL after installing RTX, be sure to uninstall RTX before proceeding.

Install the RTX runtime environment

Follow instructions provided with the RTX runtime package from IntervalZero (formerly known as Ardence, Inc.). As mentioned in the System Requirements section, you'll need an RTX 2011 Runtime license. We recommend the Basic edition, which supports a quad-core processor. There is no need to purchase the far more expensive SDK license, unless you plan to do code development with the RTX software development kit.

After installing RTX, it must be configured appropriately to run Maestro's RTSS driver. Open the System tab on the RTX Properties panel and set the Startup Type to "PnP Automatic" so that the RTX subsystem starts at boot time. On the same tab, open the Behavior Settings dialog and set the HAL Timer Period to 50µs and check the box "Free stack on TerminateThread calls". On the Control tab, verify that two of the available processors are dedicated to RTX, and the rest to Windows (remember, your system should at least be quad-core). On the Starvation tab, configure RTX so that it yields to Windows after a 5-second starvation timeout. Finally, on the TCP/IP tab, be sure to enable the RTX-TCP/IP stack and specify the full path to the configuration file for the network adapter that will connect to RMVideo (see below for details). If your particular installation will not use RMVideo, you can use the default "configuration file" provided by RTX. However, you still must enable TCP/IP support, or Maestro's hardware interface controller (cxdriver.rtss) will fail to load.

[Caveat: The layout and content of the RTX Properties panel changes from version to version. These instructions apply to RTX 2011; you may have to hunt around to find the particular settings in your version.]

Install Maestro program files

Copy Maestro's executable and support files to a selected "home directory" on the local hard drive. The required program files are listed in the side panel and are available for download as a ZIP archive. Unzip the archive and copy the files therein to the designated directory.

IMPORTANT: If you're updating your machine to a new Maestro release, you will likely copy the program files into an existing Maestro home directory, overwriting the files representing a previous release. If you do this, please take care with the RMVideo NIC sample files. Those should NOT be copied, as they are merely templates. The .ini file that pertains to the network card in your machine has been modified so that the "EA" entry is set to the Ethernet address of that particular card. I strongly advise using a different name for this .ini file, rather than one of the names of the NIC sample files listed in the side panel. Users have made this mistake before, and discover that their updated Maestro no longer runs properly!

Using the Windows registry editor (regedt32.exe), store the full pathname of the chosen directory in the REG_SZ-valued registry entry "Home" under the key HKEY_LOCAL_MACHINE\SOFTWARE\HHMI-LisbergerLab\Maestro. Finally, as a convenience to users, create a desktop shortcut to the main application executable, maestro.exe. [NOTE: If you fail to create the registry entry correctly, Maestro might start but it will expect the program files to be in a (hard-coded) default directory, c:\Maestro. If that directory does not exist, the application will be unable to find and start its RTX-based hardware controller. Worse yet, if it does exist but contains the incorrect version of the hardware controller, you'll get some odd behavior!]

Install and configure hardware

Prior to Maestro 3, successfully installing and configuring the AI, AO and other devices in the computer proved to be the most elusive step in getting the program up and running. This is because we had to ensure that the AI board and the network card linked to RMVideo each had exclusive access to an interrupt request (IRQ) line. With IRQs a scarce PC resource, this was often difficult to do. This problem goes away with the advent of devices supporting message-based interrupts (MSI). The currently recommended hardware configuration supports MSI.

Hardware vendors typically recommend that you install their device driver and support software before you install the device itself. You may wish to do so for the PCIe-6363, since National Instruments provides software tools by which you can re-calibrate the analog input and output subsystems of the board, if necessary. Since Windows will find and install most network drivers automatically, there's no need to pre-install a driver for the Intel Gigabit CT or whatever network adapters you use to connect to the RMVideo and EyeLink tracker PCs. Do NOT install device drivers for the Detroit C6x DSP card or any of the still-supported legacy hardware. These drivers can sometimes cause problems; in at least one case, a Windows driver - RTX conflict caused the system to crash when Maestro started up.

Keep in mind that Maestro does not rely on any vendor-supplied device drivers; its RTX hardware controller talks directly to each device using RTX device-management functions. If you install the Windows driver for a Maestro device, you must transfer "ownership" of the device from Windows to RTX so that Maestro's hardware controller (an RTSS process) can communicate with the device without conflicting with the Windows driver. By transferring ownership, you ensure the Windows driver is not loaded at boot time. If you do not install a Windows driver (and Windows does not install one itself), then the device is disabled from Window's point of view, and you may not have to transfer ownership to RTX. [As of v3.2.0, there's one exception to this rule: communications with the EyeLink 1000+ eye tracker uses a network card that remains under Windows control and is handled by a Win32 thread that runs with time-critical priority in Maestro's GUI process.]

Step-by-step for the recommended hardware configuration:

• 1. (Optional) Install the device driver and support software for PCIe-6363, if you wish. You will be transferring control of the device from Windows to RTX (see below), so the National Instruments' driver won't be loaded. If, at some later time, you wish to use NI tools to re-calibrate the analog subsystems on the PCIe-6363, you'll need to temporarily transfer device ownership to Windows, perform the calibration, then transfer ownership back to RTX before running Maestro again.

  2. Turn off the computer. Carefully install the PCIe-6363, the Intel Gigabit CT adapter, and -- optionally -- the Detroit C6x. The PCIe-6363 and the network card are installed in PCI-Express x1 slots, while the Detroit requires a PCI slot. If you plan to use Maestro with the EyeLink tracker, you'll need a second network card for that connection. We do this separately (see step 7) because it may be difficult to identify which NIC is which in the Windows Device Manager, especially if they are the same brand.

  3. Turn on the computer. Windows will likely find and load the driver for the Intel network adapter. If you installed the NI driver, the same will be true for the PCIe-6363. If Windows cannot find a driver for any device you added, a "Found New Hardware" wizard may pop up. You can cancel out of this wizard. From Windows' point of view, the device is unavailable.

  4. Transfer ownership of the PCIe-6363 from Windows to RTX. Open the RTX Properties panel. From the Hardware tab, open the PnP Device Settings dialog. In the dialog's tree view, expand the Windows node and look for the entry identifying the PCIe-6363. Right-click on the entry and select Add RTX INF Support. Then click the Apply button. Next, use the push-button on the dialog to open the Windows Device Manager. Find the node for the PCIe-6363 in the Windows device tree, right-click on it, and choose Uninstall from the context menu. The device node will disappear. Now select Action|Scan for hardware changes from the Device Manager's menu. The "Found New Hardware" wizard appears. Select option "No" for the "Can Windows connect to..." question, then hit Next. If Windows finds more than one driver for the device (eg, the Windows driver and the generic RTX INF version), it will ask you to select one. Be sure to select the entry that includes the phrase "RTX Supported". Complete the installation of the RTX driver, then return to the PnP Device Settings dialog and hit the Refresh button. The PCIe-6363 should now be under the RTX node; RTX now "owns" the device. Right-click on the PCIe-6363 node and choose Properties. If installation was successful, the Status message should read "Device is MSI capable and should work properly for message-based interrupts". You do NOT need nor want to obtain a line-based IRQ resource for the PCIe-6363. You may have to reboot the computer at least once to complete this process.

  5. Transfer ownership of the Intel Gigabit CT adapter from Windows to RTX. Add RTX INF support as you did for for the PCIe-6363. Then, instead of uninstalling the adapter, right-click on its node in the Device Manager and select Update Driver Software. In the popup dialog, choose Browse My Computer for Software, then Let me pick, then choose the "RTX Supported" entry from the device driver list. (If you try to uninstall the adapter and then scan for hardware changes as in Step 4, Windows simply reinstalls the original Intel driver and the device is not transferred to RTX ownership.) Like the PCIe-6363, the CT adapter supports MSI.

  6. Configure the RTX TCP/IP subsystem to use the Intel Gigabit CT network adapter. On the TCP/IP tab of the RTX Properties panel, enable RTX TCP/IP support and specify the full path to the .INI configuration file for the Intel CT adapter. This configuration file tells the RTX TCP/IP subsystem which network adapter in the computer should be used and defines a number of driver and protocol parameters. For a full discussion of the configuration file, see the RTX documentation. At the bottom of this page are three examples of actual configuration files for different network adapters that have been used in the Lisberger lab. Some of the key parameters in the configuration file: Driver is the name of the IntervalZero-supplied NIC driver to be used; EA is the unique Ethernet address of the adapter (so RTX TCP/IP can find it in a machine that might have more than one NIC installed); IPAddr is the IP address assigned to the adapter. Regardless the particular NIC installed, IPAddr must be set to 10.1.1.2, which is the only IP address from which RMVideo will accept a client connection. The NIC on the RMVideo side must be assigned the IP address 10.1.1.1. Note that both IP addresses are in an address range reserved for private use; they were chosen precisely for this reason -- they are never routed onto the Internet. It is important that the RMVideo-Maestro link not carry any broadcast garbage coming across the Internet or a local intranet via a second NIC installed in either machine! Finally, for the MSI-capable Intel Gigabit CT adapter, it is important to include the parameters LineBasedOnly=0 and PreferMsi=1. The first ensures that RTX uses message-based interrupts for the Intel CT, and the second ensures that MSI mode is used rather than MSI-eXtended mode. In early testing we found that the IntervalZero-provided RTE1000.dll driver for the Intel CT (and other network cards using the Intel 82574 chip set) failed frequently if the card was used in MSI-X mode. Also for the Intel Gigabit CT, note the priority levels assigned to the timer (66), interrupt (64), and receive (63) threads. These are RTX-specific priority levels, and we recommend that you use these specific values. In any event, they should all be greater than 50, the RTX priority assigned to the main worker thread in Maestro's hardware device controller, cxdriver.rtss.

  7. If you plan to use the EyeLink 1000+ eye tracker with Maestro, you will need to install a second network card for the Ethernet connection to the EyeLink's Host PC. Turn off the computer, install a suitable NIC (such as the Intel Gigabit CT) in an available slot (and label it on the outside of the computer!), and restart. Windows will automatically install the driver for the NIC. However, you'll need to manually set the IP address for that NIC to 100.1.1.2. In Windows 7, go to Control Panel > Network and Internet > Network and Sharing Center. Click on "Change adapter setting", double-click on the network card icon that represents the NIC you just installed, and select the "Properties" button. Select the list item "Internet Protocol Version 4" and click the "Properties" button below the list. In the pop-up dialog, select "Use the following IP address" and enter 100.1.1.2. Enter a subnet mask of 255.255.255.0. Leave the default gateway and all other settings blank. Click "OK" (several times) to save the changes.

If you will be using any supported legacy hardware in your Maestro setup, then the basic procedures above still apply. However, if you are using the PCI-6070E for analog input or an RMVideo NIC that does not support message-based interrupts, then you have some extra work to do to ensure that both devices get exclusive access to an IRQ line.

• • Before installing any hardware, you should go into the system BIOS and disable non-essential motherboard devices such as the USB, serial, and parallel ports. You'll likely have to disable the sound card and the "SMBus controller". You can live without all of these, and disabling them will free up some precious IRQ lines.

  • Next, install only the PCI-6070E, then reboot the computer and go through the process of transferring device ownership from Windows to RTX. Once RTX has control of the device, and if the system HAL supports the Advanced Configuration and Power Interface (ACPI) standard, you may be able to manually reassign the device to an available IRQ. Right-click on the device entry under the RTX node in the PnP Device Settings dialog and select Properties. If the device is properly configured, the popup dialog will tell you so. If the system is ACPI-compatible, you may be able to change the IRQ line and its disposition (shared or exclusive); otherwise, these widgets are disabled. If you are unable to assign an exclusive IRQ to the board, then you will have try it in different PCI slots until an exclusive IRQ is found. This process typically requires one or more reboots.

  • Once you've successfully installed the PCI-6070E, then you'll have to go through the same process for the NIC that will connect to RMVideo.

  • Finally, install all remaining Maestro devices (AO board, XYScope controller DSP card, etc.). After installing the board(s) and rebooting, cancel out of the "Found New Hardware" wizard that should come up when Windows starts. You'll want to disable these devices in the Windows Device Manager; otherwise, the hardware wizard will appear every time you restart the machine. It does not matter if they are disabled in Windows; Maestro's RTX-based driver will still be able to communicate with these boards, and it will disable their interrupts to ensure they do not interfere with the AI or NIC boards. Open the RTX Properties panel and ensure that the PCI-6070E and, if applicable, the RMVideo NIC are still properly configured with exclusive-access IRQs.

Run Maestro and verify operation

Start the program and wait for the main frame window to come up. Open up the Message Log (if it is not already open) and check the startup messages. Ensure all of the boards you installed have been recognized and are available for use. Both Trial and Continuous operational modes should be enabled.