Customization Examples

The topics listed below represent some of the ways in which you can customize the Advanced Design System environment.

Many of the topics presented here refer to the variables %HOME% and %HPEESOF_DIR%. On the PC these variables have the following meaning:

Creating a Custom Menu

You can add custom menus to the ADS Main window and Schematic and Layout windows by modifying the .ael file usermenu.ael.

Note
This procedure applies only to user-level custom menus. The number of slots available for custom menus is limited; you must use care so that you do not wipe out another user's menu.

To add a custom menu:

  1. Under $HOME/hpeesof, create the additional directories /de/ael.
  2. Copy the file usermenu.ael from $HPEESOF_DIR/de/ael to the new directory $HOME/hpeesof/de/ael and ensure you have write permission for this file.
  3. Using any text editor, open the file usermenu.ael.
  4. The file usermenu.ael contains sample code that can be uncommented to help you learn how to use the functions available for defining user menus. Before proceeding, review the descriptions of the following functions in the AEL manual: check_user_menu(), set_user_menu_label(), and add_menu(). After you understand how to use the sample code, replace it with your own code.The function app_add_user_menus() is the function in which you will add your custom code. The sample code provided includes the following function calls: 
    // to get the internal name of the first free user menu
decl freeMenuName = app_find_empty_user_menu(winType);
// uses the menu's internal name to set the label on a free user menu
set_user_menu_label("my first menu", freeMenuName);
// uses the menu's internal name to add a menu pick on a free user menu
add_menu( "menuPickA", "my_menu_cb", freeMenuName );

    Uncomment these lines in your file by removing the two slashes at the beginning of the three executable lines, as shown above. Do not delete the slashes from the comment lines.

  5. Save the file.
  6. Restart ADS to see the change.
Note
If this code is used as is, it will initialize the first user menu, unless your system already has user menus defined. If your system does not have any user menus defined by other applications, and you want to see what would happen if it did, you can uncomment the test function prefill_menus() and the call to it, both provided in usermenu.ael. This will initialize the first two user menus, so that a call to app_find_empty_user_menu() will return "User3" as the first available user menu.

Creating Custom Libraries

As with other aspects of ADS customization, you can create custom libraries at several levels: for site-wide use, for all your projects, and for individual projects. The procedures are presented in three different groupings, based on the following use models:

If creating libraries via the user interface method, before defining a Library Name-through the Design Parameters dialog box-for any given design, please review the following guidelines, as assigning a library name in this manner is not always recommended:

Assisted Customization

The procedures in this section are geared toward individuals working with a small number of designs, because this method is based on adding designs to a library one at a time. Once the libraries have been created, either restart ADS to see the changes or use the Configuration Explorer to explicitly read the modified de_sim.cfg file for the current session.

Note
Because this method is based on copying designs from their source location to a library location, if the source design is subsequently modified, you must repeat the process so that the design gets copied to the library again.

Keep in mind the following limitations when creating libraries in this manner:

Hint
To easily see the designs comprising a hierarchical design, from the ADS Main window, choose View > Design Hierarchies.

Site-Wide Customization (Assisted)

Copying designs to and removing designs from the site library requires write permission in that directory (by default, $HPEESOF_DIR/custom/circuit).

To copy a specific design to a site library making it available for all users:

  1. From the design you want to copy to the site library, choose Tools > Custom Library > Create > Site Part.
  2. Repeat this process for each design you want to be part of a site library.

To remove a specific design from a library:

Choose Tools > Custom Library > Delete > Site Part and select the design you want to remove from the library.

Hint
If the design you select to remove from the library references any data files, you are prompted to choose to keep or remove the data files.

To prevent an entire library of designs from being loaded when you start ADS:

Choose Tools > Custom Library > Disable > Site Library, and where applicable, select the library.

To enable the loading of a library that you previously disabled:

Choose Tools > Custom Library > Enable > Site Library, and where applicable, select the library.

Notes:

User Customization (Assisted)

To copy a specific design to a local library making it available for all your projects:

  1. From the design you want to copy to the library, choose Tools > Custom Library > Create > User Part.
  2. Repeat this process for each design you want to be part of a user library.

To remove a specific design from a library:

Choose Tools > Custom Library > Delete > User Part, and select the design you want to remove from the library.

To prevent an entire library of designs from being loaded when you start ADS:

Choose Tools > Custom Library > Disable > User Library, and where applicable, select the library.

Manual Customization

This section is geared toward the librarian, or individual, working with a large number of designs, and working with the recommended directory structure.

For the two manual methods, each case involves the following basic steps, though the details vary:

Note
Do not include line breaks of any kind when setting variables; let the lines break wherever your text editor breaks them.

When customizing for any of the scenarios described in the manual methods, wherever you see < product_area >, replace it with one of the following:

Site-Wide Customization (Manual)

To make a specific design available for all users:

  1. Copy the .dsn files to $HPEESOF_DIR/custom/<product_area>/symbols/ directory. Example:

    Copy mydesign1.dsn and mydesign2 .dsn to $HPEESOF_DIR/custom/de/symbols/

  2. Copy the .ael files to the $HPEESOF_DIR/custom/<product_area>/ael/ directory. Example:

    Copy mydesign1.ael and mydesign2.ael to $HPEESOF_DIR/custom/de/ael/

  3. Edit or create a file $HPEESOF_DIR/custom/config/de_sim.cfg and set SITE_AEL equal to each of the .ael filenames (separated by semicolons or colons). Example:

    SITE_AEL=mydesign1;mydesign2

Note
If you want all .ael files in the directory to be loaded, a shortcut is to set the SITE_AEL variable to the directory. For example: SITE_AEL=$HPEESOF_DIR/custom/de/ael/. Be sure to include the trailing slash.

User Customization (Manual)

To make designs available for all your projects:

  1. Copy the .dsn files to $HOME/hpeesof/<product_area>/symbols/ directory. Example:

    Copy mydesign1.dsn and mydesign2.dsn to $HOME/hpeesof/de/symbols/

  2. Copy the .ael files to $HOME/hpeesof/<product_area>/ael/ directory. Example:

    Copy mydesign.ael and mydesign2.ael to $HOME/hpeesof/de/ael/

  3. Open $HOME/hpeesof/config/de_sim.cfg and set USER_AEL equal to each of the .ael file names (separated by semicolons or colons). Example:

    USER_AEL=mydesign1;mydesign2

Project Customization (Manual)

To make designs available in multiple-but not all-projects:

  1. Copy the .dsn files to $HOME/hpeesof/<product_area>/symbols/ directory. Example:

    Copy mydesign1.dsn and mydesign2.dsn to $HOME/hpeesof/de/symbols/

  2. Copy the .ael files to $HOME/hpeesof/<product_area>/ael/ directory. Example:

    Copy mydesign.ael and mydesign2.ael to $HOME/hpeesof/de/ael/

  3. For each project, open <project>/de_sim.cfg and set LOCAL_AEL to each of the .ael filenames (separated by semicolons or colons). Example:

    LOCAL_AEL=mydesign1;mydesign2

Advanced Library Customization Techniques

We recommend storing library designs for site-wide use in the following locations:

Note
The custom directory shown here is created during installation, but you must create the product-specific directories (beneath it) yourself.
  Analog/RF Digital Signal Processing
.dsn files $HPEESOF_DIR/custom/circuit/symbols/
or
$HOME/hpeesof/circuit/symbols/ 		$HPEESOF_DIR/custom/adsptolemy/symbols/
or
$HOME/hpeesof/adsptolemy/symbols/
.ael files $HPEESOF_DIR/custom/circuit/ael/
or
$HOME/hpeesof/circuit/ael/ 		$HPEESOF_DIR/custom/adsptolemy/ael/
or
$HOME/hpeesof/adsptolemy/ael/

If for some reason you cannot or do not want to store your files in the these directories and would rather locate your files elsewhere, you can.

  1. Copy the .dsn files to any directory. Example:

    Q:\ads_designs\library1\designs

  2. Copy the .ael files to any directory. Example:

    Q:\ads_designs\library1\ael

Choose one of the following customization schemes:

Note
There is no way to do this for project-level customization at this time.

Site-Wide Customization (Advanced)

Edit the $HPEESOF_DIR/custom/config/de_sim.cfg file as follows:

  1. The SITE_AEL variable needs to be set to load your .ael files. Typically you would set it to point to the directory containing your .ael files. Example:
    SITE_AEL=Q:\ads_designs\library1\ael (Loads all .ael files in directory)
    Be sure to include the trailing slash. Note that you cannot not use relative paths; you must use either an absolute path or an environment variable.
    Alternatively, you can list specific files that you want to load. Example:
    SITE_AEL=Q:\ads_designs\library1\ael\myfile
  2. Set the SITE_DSN_PATH variable equal to the directory you copied the .dsn files to earlier. Example:
    SITE_DSN_PATH=Q:\ads_designs\library1\designs (absolute path) or
    SITE_DSN_PATH={$ADS_DESIGNS}\library1\designs (environment variable)
    Important
    If you set the SITE_AEL variable (in step 1) to a path, rather than a list of individual designs, you are done; if you listed designs individually, continue with the next two steps.

Edit the $HPEESOF_DIR/custom/config/de_sim.cfg file as follows:

  1. Note that every user will already have the variable AEL_PATH set in their $HOME/hpeesof/config/de_sim.cfg file. It will be set to one of the following variables, based on the choice they made in the setup dialog box the first time they started ADS: 
    {%ANALOG_RF_AEL_PATH}
{%DSP_AEL_PATH}
{%BOTH_ANALOG_RF_FIRST_AEL_PATH}
{%BOTH_DSP_FIRST_AEL_PATH}
    Note
    The setting chosen on startup can be changed at any time from within ADS from the Main Window through Options > Advanced Design System Setup.

    The default definitions of these four variables can be found in $HPEESOF_DIR/config/de_sim.cfg.
    Copy all four variables from $HPEESOF_DIR/config/de_sim.cfg and add them to the $HPEESOF_DIR/custom/config/de_sim.cfg file.

  2. Modify each variable to add the path-that you copied the .ael files to earlier-to the front of the existing path. Example:

    ANALOG_RF_AEL_PATH=Q:\ads_designs\library1\ael:{%HOME_CIRC...
    DSP_AEL_PATH=Q:\ads_designs\library1\ael:{%HOME_HPTOL...
    BOTH_ANALOG_RF_FIRST_AEL_PATH=Q:\ads_designs\library1\ael:{%HOME_...
    BOTH_DSP_FIRST_AEL_PATH=Q:\ads_designs\library1\ael:{%HOME_HP...

    Now, even if a user changes their setup (from within ADS) to start with a different design type-thereby updating their local AEL_PATH variable-the designs can still be found because the search path is provided for all cases.

User Customization (Advanced)

Edit the $HOME/hpeesof/config/de_sim.cfg file as follows:

  1. Set the USER_AEL variable equal to the design filenames (separated by semicolons or colons). Example:

    USER_AEL=mydesign1;mydesign2

    Note
    If you want all .ael files in the directory to be loaded, a shortcut is to set the USER_AEL variable to the directory. For example: USER_AEL=$HOME/hpeesof/MyLibrary/ael/. Be sure to include the trailing slash.
  2. Set the USER_DSN_PATH variable equal to the directory you copied the .dsn files to earlier. Example:

    USER_DSN_PATH={$HOME}/hpeesof/MyLibrary/Designs/

    Note
    If you set the USER_AEL variable (in step 1) to a path, rather than a list of individual designs, you are done; if you listed designs individually, continue with the next step.
  3. Add the path-you copied your .ael files to earlier-to the front of the current AEL_PATH definition. Example:

    AEL_PATH={$HOME}/hpeesof/MyLibrary/ael;{%BOTH_ANALOG_RF_FIRST_AEL_PATH}

    Note
    If you have customized the AEL_PATH path variable and you change the design type startup setting through Options > Advanced Design System Setup, in the Main window and click OK, this variable will be overwritten and you will lose your customized path. If you need to change your setup, you will either have to change it manually in your de_sim.cfg file, or re-establish your customized path after changing it through the dialog box.

Example

The steps that follow can be used as a shortcut for creating a library from a single project.

  1. Create a project, such as library_prj.
  2. Place in library_prj/networks only those parts you are interested in using directly.
  3. Modify the variables USER_AEL and USER_DSN_PATH, shown in the example below, in the file $ HOME/hpeesof/config/de_sim.cfg. Example:

    USER_AEL = /eesof/users/kclarke/library_prj/networks/
    USER_DSN_PATH = /eesof/users/kclarke/library_prj/networks/

Modifying the List of Available Symbol Names


To assign a symbol to a schematic, you must supply a Symbol Name in the Design Definitions dialog box ( File > Design Parameters ). You can type a symbol name or you can select one from the default list of commonly used symbols. You can modify this list and add names of other supplied symbols as well as the names of custom symbols you have created.

To modify the list of names, you modify the AEL function set_design_choices in the file shown next, in accordance with its intended use ( circuit vs. adsptolemy ):

To modify this file for individual use, modify a local copy of it; to modify this file for site use, modify a copy of this file on a shared drive. We recommend that you maintain the established directory structure for storing and referring to .ael files. Note that the custom directory shown below is created during installation, but you must create the product-specific directories (beneath it) yourself.

Use this directory structure on UNIX:

Individual Use $HOME/hpeesof/circuit/ael
$HOME/hpeesof/adsptolemy/ael
Site Use $HPEESOF_DIR/custom/circuit/ael
$HPEESOF_DIR/custom/adsptolemy/ael

Use this directory structure on the PC:

Individual Use %HOME%/hpeesof/circuit/ael
%HOME%/hpeesof/adsptolemy/ael
Site Use %HPEESOF_DIR%/custom/circuit/ael
%HPEESOF_DIR%/custom/adsptolemy/ael

%HOME% represents the path you specified as the Home Folder during installation (C:\users\default by default);
%HPEESOF_DIR% represents the path you specified as your Program Folder during installation (C:\AdvDesSys).

Note
If you use a directory other than one of those shown in the tables for storing the modified file ( gemini.ael or spdsndef.ael ), then you must declare the variable USER_AEL and provide the search path. The custom directory shown here is created during installation, but you must create the product-specific directories (beneath it) yourself.

To take advantage of the modified version of the gemini.ael or spdsndef.ael file-if stored in a directory other than one of the defaults:

  1. Using any text editor, open the file $HOME/hpeesof/config/de_sim.cfg.
  2. Add the variable USER_AEL and set it equal to the path you have chosen for your modified file.
  3. Save the file.

Once you modify geminidsndef.ael or spdsndef.ael, you must also modify the variable USE_RELATIVE_AEL_PATHS (regardless of the location of the modified file). This should be done in the file $HOME/hpeesof/config/de_sim.cfg and you must set the variable equal to TRUE (USE_RELATIVE_AEL_PATHS =TRUE). For information on modifying search paths, "Modifying Search Paths" in the Schematic Capture and Layout book.

Once you have created the directory structure, copy the geminidsndef.ael (circuit) or spdsndef.ael (adsptolemy) file from the installation directory to the newly created local / ael directory.

To modify the list of symbol names appearing for selection:

  1. Using any text editor, open the copied geminidsndef.ael or spdsndef.ael file in the local / ael directory.
  2. Locate the heading

    /* symbol list: DMDESIGN_SYMBOL_CHOICES */

    followed by the function

    set_design_choices

    Notice that the function name is followed by a list of symbol names, each surrounded by quotation marks, separated by commas (including sequential numbering and commas), all enclosed in parentheses.

  3. Add the desired names to the list using the same format.
  4. Save the file.

After you have completed this process, you will be able to select your custom symbol from the drop-down Symbol Name list (in the Design Definitions dialog box).
If the program is currently running, you need to restart the program to see these changes take effect.

Adding Online Help for User-Defined Items

When you create your own items, you can also create documentation for them and make that documentation available online. The starting point of this procedure assumes you have already created the items.

Note
Refer to the DesignGuide Developer Studio manual for more information on how to create custom DesignGuides for the Advanced Design System.
Note
This procedure requires the ability to write to the installation directory.
  1. Create a directory, for example my_items, under $HPEESOF_DIR/doc for storing your new documentation files (where $HPEESOF_DIR represents your complete installation path).
  2. Change the write permission to this directory as needed, based on the users who will create documentation for the new items.
  3. Create documentation for the new items using the HTML format (one file for each item) and move (or copy) the files to the new directory. While filenames can be any name you choose-except for the required .htm extension-we recommend using < item_name >. htm. See Optional Document Template for a html template.
  4. Create a text file, for example my_items_help.txt, containing pointers to the new items, using the following syntax (note the spaces before and after the first exclamation point and before the final exclamation point):

    item_name ! <path>/<filename> !

    where

    item_name_ is the element name you used in the AEL create_item() function
    path_ is the directory you created below $HPEESOF_DIR/doc to store the HTML files you created (for example, my_items )

    This file should contain one line for each new item you created. An example line is shown next.

    PIPAD ! my_items/pipad.htm !

  5. The file that contains the pointers for help on all components is named hshpeesofsim_index and can be found in $HPEESOF_DIR/doc. Create a copy of this file (as a safeguard), for example, hshpeesofsim_index.sav.
  6. Using any text editor, add the contents of the help file you created (in this example, my_items_help.txt), to the bottom of the hshpeesofsim_index file.
    Optionally, on UNIX, you can use the cat command (instead of a text editor) and concatenate the files:

    cat my_items_help.txt }} >> {{ hshpeesofsim_index

    The help file now contains pointers to the documentation you created.

  7. Save the file (no extension) and restart ADS to verify your changes.

The following figure illustrates the directory structure for the user-defined files.

Directory Structure for User-Defined Help

Optional Document Template

Use the following html code when you create your document.

Adding Custom Documentation for Online Access

It is possible to create your own custom documentation for online access. For instance, you can put custom documentation for a specific project in that project folder. You can also put documentation in other areas outside of $HPEESOF_DIR, circumventing the issue of access permissions for $HPEESOF_DIR.

  1. Create a directory, for example custom_doc, for storing your new documentation files. The LOCAL_DOC_PATH, and LOCAL_BOOK_NAMES variables will need to be added to the hpeesofhelp.cfg file, so that your custom doc will be accessed, instead of the standard ADS documentation. See Customizing Configuration Variables for more information on the location of .cfg files. See Variables in the File hpeesofhelp.cfg for more information on the LOCAL_DOC_PATH and LOCAL_BOOK_NAMES variables.
  2. Create documentation using the HTML format and move (or copy) the files to the new directory. While filenames can be any name you choose-except for the required .htm extension-we recommend using < item_name >. htm. See Optional Document Template for a html template.
  3. Create a file, for example custom_doc_index, (no extension, _index required) __ containing pointers to the items that will be accessed in your documentation, using the following syntax (note the spaces before and after the first exclamation point and before the final exclamation point): 
    Index ! <filename>.html !
Topics and Index ! <filename>.htm !
item_name ! <path>/<filename> !
where
     Index              is the file that you would like the user to be directed to if a topic 
                        is not found. 
                        The standard for ADS documentation is $HPEESOF_DIR/doc/adshelp.html,
                        if you choose to use your own file, make sure that it is located in 
                        your custom_doc directory. (See note below) 

     Topics and Index   is the file that is opened when the user selects Topics and Index from 
                        the Help Menu. 
                        The standard for ADS documentation is $HPEESOF_DIR/doc/manuals.htm, 
                        if you choose to use your own file, make sure that it is located in 
                        your custom_doc directory. (See note below) 

     item_name          is the element name you used in the AEL _create_item()_ function

     path               is the directory you created to store the HTML files you created 
                        (for example, _custom_doc_

    This file should contain one line for each new item you created. An example line is shown next.

    PIPAD ! custom_doc/pipad.htm !

    Note
    If you point to custom Index and Topics and Index files within a specific project, and the project is moved, your paths will no longer be correct.
  4. Save the file (no extension) and restart ADS to verify your changes.

The following figure illustrates the directory structure for custom documentation files.

Directory Structure for Custom Documentation
 

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

Contents
Additional Resources