About Instruments Components

ADS Ptolemy supports a suite of components that provide interfaces from the schematic to:

New Connection-Manager-based components are available with the 2003C release; these benefits are provided:

Connection Manager

The Connection-Manager-based instrument link components (named CM_ and located in the Instruments library) perform measurements based on the Connection Manager (CM) architecture. The term measurement is a general term used here to describe functions in a server library; generally, a measurement includes gathering physical data from one or more instruments, but a measurement is not limited to instrument control.

The Connection-Manager-based simulation components are part of the client half of the CM client/server system and operate through an instance of the CM server. You can think of the CM-based simulation components as interfaces into the measurements available on the server. For more information, refer to Client-Server Architecture under the section on Operational and Functional Concepts in the Connection Manager documentation.

The client also provides instrument discovery that makes it easy to identify the instruments that are connected to your server workstation, enabling the client to easily associate a particular instrument with a particular measurement. For more information, refer to Discovering Connected Hardware under the section on Getting Started with Connection Manager in the Connection Manager documentation.

Detailed information regarding Connection Manager basics, server IO setup and functional concepts is provided in the Connection Manager documentation.

Instrument Selection

The CM components enable interactive selection of the instrument before simulation. These components include an Instrument parameter that is set to a string following a specific syntax:

[GPIB::20::INSTR][localhost][4790]

To interactively select an instrument:

  1. From the ADS Schematic window, double-click a CM component symbol to access the component dialog box.
  2. Select Instrument from the parameter list.
  3. Click Select Instrument to access the Set Server dialog box.
  4. Enter the DNS host name or IP address of the workstation on which an instance of the Connection Manager server is running.
  5. Enter the port number on which the server is waiting for incoming connection requests. Unless the server settings have been manually changed, use the default port number 4790.
  6. Click OK to access the Remote Instrument Explorer dialog box.

    This dialog box shows the VISA Resource identifiers of all instruments that are currently connected through interfaces configured on the workstation running the Connection Manager server. A VISA Resource identifier is similar to an IP address and can uniquely identify an instrument among all instruments connected to the workstation through configured interfaces.
    To map the VISA Resource identifiers to the associated instrument model number, select one or more of the VISA Resource entries and click Query Instruments' IDs to tell the Connection Manager server to send the standard IEEE 488.2 identification command *IDN? to the instrument(s). Most modern instruments that understand this command respond with an identification string. After all selected instruments are queried, the Instrument IDs are displayed:
  7. Select a specific instrument based on the Instrument ID string displayed and click OK.
  8. In the component dialog box, click OK to return to the Schematic window. Click Cancel in any of the dialogs to retain your old settings.

For information on renaming the instrument IDs, refer to Customizing Instrument Identification Strings under the section on Getting Started with Connection Manager in the Connection Manager documentation.

VeeLink Setup

ADS Ptolemy supports the VeeLink component which enables you to use VEE UserFunctions as if these are integral parts of your Ptolemy simulation. Typical uses for the VeeLink component include:

Requirements for using VeeLink are:

For details on installing and configuring Agilent IO libraries, refer to "Configuring IO Interfaces" in the Agilent IO Libraries Installation and Configuration Guide; you can download the latest version of this document at http://www.agilent.com/find/iolib.

Note
Agilent VEE runtime environments are not supported by VeeLink.

Required Support Files

Before you can use the VeeLink component, you must install certain DLL and VEE Service Manager files.

VeeLink component implementation depends on the presence of two DLLs in the directory paths listed in your environment PATH variable.

Using VeeLink requires a program called VEE Service Manager.

For more information about the VEE Service Manager, refer to VEE Service Manager.

Using VeeLink

The VeeLink component is listed in the Instruments palette. Static configuration information, such as the name of the VEE library containing the VEE UserFunction you want to call, is specified using the component's configuration parameters. Arguments to the function and the function return values are supplied through data flow (described in the next section on Data Flow Semantics). For information about developing VEE UserFunctions, refer to the Agilent VEE documentation.

The VeeLink component provides an extension mechanism which you can use to implement additional functionality in an ADS Ptolemy schematic.

To use a VeeLink component:

  1. In the Agilent VEE development environment, develop a VEE UserFunction that implements the additional functionality you need.
  2. In an ADS Ptolemy schematic, include the VeeLink component to gain schematic access to that UserFunction.

Data Flow Semantics

Ptolemy calls your VEE UserFunction when data is delivered to the VeeLink component's input pin. You should understand the relationship of data inputs and outputs, and data types between a UserFunction and the VeeLink component; these are discussed in the following sections.

VEE UserFunction Arguments - Data Types

The number of input data connections to the VeeLink component must match exactly the number of data input terminals contained in your VEE UserFunction. The data types you can specify currently include:

Note that the matrix types must have one data row. These can have as many columns as you want in that row.

VEE UserFunction input terminals can be constrained to expect data of specific types and shapes. A data shape describes the dimensionality of the data. For example, a data shape could be constrained to be a scalar (a single value) or an array with one dimension. The defaults, when you add a terminal to a UserFunction, are data type Any and data shape Any. In this case, Any means that the terminal accepts any data type or shape that the VEE system understands. When you constrain a terminal, you restrict the data type or shape the terminal accepts. In the event that you supply data to a UserFunction that does not specifically match the type or shape a terminal specifies, VEE tries to coerce the supplied data to match the type and shape the function expects. There are some conversions VEE cannot make, since doing so causes a loss of data precision. If it cannot perform the data type or shape conversion, VEE emits an error, which is propagated back to the VeeLink component.

VEE UserFunction Arguments - Evaluation Order

A VEE UserFunction shares another characteristic with functions typically written in a textual language: the arguments are evaluated based on position, not based on the terminal name. For instance, if a UserFunction has three arguments, the first argument you supply is sent to the top-most pin, the second argument is sent to the middle pin, and so on.

There is no requirement to connect anything to the VeeLink component's input pin, unless the VEE UserFunction has an input terminal. When connections are required, if you simply connect Ptolemy components to the VeeLink component, Ptolemy calls the function supplying arguments whose order is based on the order in which you connected the data source to the VEE link component input. Sometimes this is acceptable. However, if it is important that a particular data source maps to a particular UserFunction input terminal, you can use a Bus Merge component (located in Numeric Control) to specify the ordering of arguments. Note that the Bus Merge component sends out data from bottom to top, so the bottom-most pin on the Bus Merge component directs data to the top-most UserFunction data terminal and so on.

VEE UserFunction Results

A VEE UserFunction can return any number of values, all of which are carried on the VeeLink component's single data output pin. The number of UserFunction results actually propagated into the rest of the Ptolemy simulation depends on the number of connections you make to the VeeLink component's output pin. You do not need to match the number of VeeLink component output pin connections to the number of output terminals the VEE UserFunction has. The VeeLink component propagates UserFunction output terminal results sequentially from top to bottom.

For example, suppose your VEE UserFunction has three output terminals. If you have two connections to the VeeLink component output pin, results from the two top-most UserFunction output terminals propagate into the Ptolemy schematic. The results from the remaining (bottom) UserFunction output terminal are discarded. If, for example, you want results from the first and third UserFunction outputs only, you must make three connections to the VeeLink component output pin.

A VEE UserFunction can return different types on the same output terminal on different invocations. Because of this, the VeeLink component output terminal is of data type Anytype. The VeeLink component constructs a Ptolemy particle whose type corresponds to the data type and shape that the VEE UserFunction returns. Output data types currently supported are:

Note that the matrix types currently support only one data row, having as many columns as there are elements in the VEE UserFunction result array.

Results propagate from the VeeLink according to the order in which you make output pin connections. VEE UserFunction results are position dependent, so if you need to specify that a specific UserFunction terminal result propagates to a given VeeLink component output pin connection, you must use a BusSplit component (located in the Numeric Control library). The BusSplit component propagates the VEE UserFunction results from bottom to top: the bottom-most BusSplit component output pin propagates the top-most VEE UserFunction result terminal; the next BusSplit output pin up propagates the next UserFunction terminal down; and so on.

Data Type Resolution

Both the VeeLink input and output pins are of type Anytype. In order for the Ptolemy simulator to resolve the data types flowing through data connections, the connections you make to the VeeLink component must have concrete data types. Connecting the VeeLink component to a component having a data pin with a concrete type, enables the data type resolution to determine the type of data to flow from the VeeLink component.

VEE Service Manager

The VEE Service Manager is a Windows Service that wraps itself around the veesm.exe executable. Veesm.exe is a library that enables other programs to make RPC calls to VEE functions across a network. Veesm is just a Win32 executable; it has no UI. In the past, to make VEE RPC calls into a server workstation, there needed to be an interactive logon session running, and that session had to start veesm.exe. Most people would put veesm.exe in the system startup program group. Then, when someone logged into the system, veesm would start up in the security context of the interactively logged-on user. When the user logged out, the system would shut veesm.exe down, breaking whatever connection a client had to an instance of a VEE server.

The necessity to have an interactively logged-on user causes a subtle problem. Because veesm would run in the environment provided by the user's logon session, the VEE server programs would look for the IO configuration files in the home directory of whoever logged in. If Lucy wrote a VEE server program you were interested in using, she would probably reference instruments in the IO configuration in her home directory. But if Ricky logs into the server workstation, veesm runs using his account credential, and his IO configuration files may not have the instruments Lucy's program needs.

Wrapping a Windows Service around veesm solves the problems created by requiring an interactive logon session. You can configure a service to start automatically at system startup, and that service remains available through all interactive logons and logoffs, until the system shuts down or someone whose account has appropriate privileges stops it. Also, you can configure a service to start only when specifically directed to do so and specify which user account environment you want a Service to run under. Because the service has control of the environment under which the spawned veesm runs, the service can direct veesm to the correct IO configuration file.

Service Manager Composition

The VEE Service Manager consists of these files:

Putting the Vee Service Manager Under SCM Control

All Services, including device drivers (Windows Services are degenerate forms of device drivers) run under the auspices of the system Service Control Manger (SCM). The Windows Control Panel contains a Services applet.

The Services applet is a system component that enables you to control a Service. To put the Vee Service Manager under SCM control, run VeeService.exe -install. After installation, you see that there is an entry in the Services applet. By default, this entry has been marked to start manually. To run the program, push the Service Start button. In a release build, we set the Service to start automatically when the system starts.

Unwiring from the System

To remove the Service from the SCM, effectively making it inaccessible, run VeeService.exe -remove. This stops the service if the service is running, then removes it from the SCM list of configured Services.

Starting and Stopping

You can start or stop the Service from the command line, by running VeeService -start or VeeService -stop. Or, you can use the start and stop buttons on the Services Control Panel applet.

Configuring

When using a Service, you should consider the environment in which you expect it to run. One implication here is that any processes the service spawns runs under the same environment as the Service itself, unless the Service makes special provisions to do otherwise. The VEE Service Manager has made no such provisions.

When Does It Start?

The Service installs itself to start automatically at system startup. You can always use the Services Control Panel applet to change its startup time, pressing Startup, which opens this dialog.

Who Does It Run As?

The Service window Log On As part of the Services Control Panel applet defines the environment under which a Service runs. If you do not do anything else, the Service runs under the System Account. This account exists on every Windows 2000 and XP machine. It is a privileged account, in that the account has most of the rights normally granted to the Administrator group. On Windows 2000 and later OS versions, the System account does have network share privileges.

Notice the check box labeled Allow Service to Interact with Desktop; and, note that this check box is not available if you choose to run the Service under an account other than the System account. This check box enables the Service to create an interactive window on the active desktop. When ADS installs the Vee Service, ADS sets the account to be Local System and enables the Allow Service to Interact with Desktop capability. Most services do not have a UI; instead, these provide a special-purpose Control Panel applet to configure them. This has some important implications for Callable VEE clients. If your VEE server program needs to have UI interaction, you must check this box. This condition can show up if the called VEE function has a button (or whatever) on a panel. Also, this condition can happen if a Ptolemy simulation has a VeeLink component with the Debug property set.

You can run the Service under the environment of a particular account. In this display, you can see that the Service, and the veesm process which it spawned, are running under the System account.

If you change the account the Service runs under (as displayed),

this change is reflected the next time the Service starts.

If you run under an account other than the System account, you must supply a password. Also, the Service is not able to interact with the desktop when running under an account other than the System account.

Checking Its Health

The Service logs informational and error messages to the system Event Viewer.

When the Service starts, the program inserts an informational message that contains text similar to this:

If the Service encounters an error, the Service logs the error with a message that is flagged with a stop sign.

Where the Service Finds Its vee.io File

When the Service starts up, the program looks for a registry entry like this:

The service expects the registry entry to be a single directory path.

If the service finds this entry, it spins off the veesm.exe program with the -veeio option, which instructs any instances of Vee resolving remote User Function calls to reference the instrument names contained in the file the registry entry points to. Otherwise, the service starts veesm without any options. This is an important point, because the content of the IO file resolves references to instruments in your Vee User Functions. If your User Function contains a reference to an instrument named Lucy, you are referring to the Lucy instrument name in the IO file the registry entry identifies. Another IO file might contain an instrument definition also called Lucy, which may or may not point to the same instrument as the IO file specified in the registry. Another important point is that, for your Vee User Function to load, all instruments your function references must be defined in the IO file. Otherwise, the simulation generates an error.

A Windows Control Panel applet provides a convenient mechanism to specify where you want the VEE Service to look for the VEE IO configuration file. When launching the Control Panel, you should see an entry titled VEE Service Manager.

When you launch this configuration utility, you see a wizard dialog.

You can get help on any component by clicking ? in the title bar; then, when the cursor changes to ?, select the component.

The File Location field contains the path to the IO file used to resolve references to instrument names. The Vee RPC server must see this path without spaces; so the server uses what is known as the short path form, which is recognized by ~ characters in the path.

The Display IO Config button opens an instance of Vee Pro, displaying the IO Manager dialog with the contents of the IO file listed.

To select a different IO file for future use in the Vee Service, press the Change button; select the file from the dialog box that opens.

To apply your changes immediately, press Apply Changes and Restart Service. This stops Vee Service (disconnecting any clients), then starts the service, picking up the value of the new IO file. To apply your changes to future sessions without having an immediate effect on Vee Service, click OK. To discard any changes (preventing those changes from effecting future sessions) click Cancel.

 

Privacy Statement  | Terms of Use  | Legal | Contact Us  | © Agilent 2000-2008 

Contents
Additional Resources