In this application note, we will look at the new process functions introduced in ADS 2022 Update 2. These functions enable bi-directional communication with external programs from within ADS.
Most examples shown here are based on code excerpts shown in ADS online help, chapter “Process Functions”. The workspace provided here adds complete code, including menu items for testing.
Custom menu items
We want to add menu items in ADS main window, so that we can easily test our code. This is implemented using a boot mechanism that we know from ADS design kits: an eesof.lib file in the library directory tells ADS to load an AEL boot script. From there, we can load additional code and set up the custom menus.
Code for creating the custom menus is not described here, if you are interested look at menu.ael in the attached workspace.
Process functions
When an item from the custom menu is selected, this triggers an AEL callback function. In the attached workspace, functions executed from the menu callback can be found in test_process_api.ael
We use code screenshots here because that allows color code and indentation for easier reading. All code is available for copy & paste in the example workspace.
Start an external program
The simplest use of process function is to call an external program, with no parameters. To simplify this task, we create a function run_simple_process(), as described in ADS online help. In addition, we define run_process_with_params () for those cases where command line parameters must be supplied.
With these utility functions, it is very easy to invoke an external program that is already in the PATH. If you need to add directory specification to the command itself or to a commandline parameter, be careful with accidental escape characters like \t that will be replaced by a tab character. One solution would be to use slash instead of backslash, these seem to be handled gracefully by ADS to simplify cross-platform coding. Another solution would be to enclose the string in two single quotes each instead of “, which prevents escape character handling in that ADS string.
Exchange data with external program
The code for menu item “Test some commands” demonstrates some exercises using Windows commandline, with reading program output and sending commands to that program after starting it.
Relevant functions here are process_write_data(), process_read_line() and process_read_all(). Function process_wait_until_ready_to_read_line() will halt ADS until the external program returns output. Default timeout is 30s, but we can specify shorted timeout if desired.
First, the code will start windows commandline, check for success and display the program output (here: Windows command prompt) in a message dialog. Next, a command is sent from our AEL code to that running commandline process, to query the username. The result is shown in another message dialog.
Next, an invalid command is sent. This doesn’t return an error at AEL level because the command was successfully sent to the external program, but it will cause an error message that is sent by the running program to STDERR stream. The code waits 500ms after sending the command, then checks for possible error messages on STDERR. If there is no such error message, it assumes the command was processed succesfully.
Finally, the commandline process is killed from the AEL script. If we didn’t kill it, it would keep running.
Invoke Python
Two more menu items are dedicated to invoking Python from our AEL code, and run some Python script. Python is an interesting addition to ADS automation because it provides many powerful modules and enables very efficient coding.
We will use the Python version that ships with ADS. In startup code boot.ael we already extracted ADS path from HPEESOF_DIR environment variable, and we now extend that to have a full path for the Python executable. Similarly, we compose the full path to the test.py code in our workspace directory, and pass it as a parameter when invoking Python.
This will run the Python script and show its output in an ADS message dialog. Working directory is explicitely set to the workspace path.
Contents of test.py is very simple: it prints one line to the terminal STDOUT (this is what ADS reads and displays in the message dialog) and in addition it writes one file to disk. The current directory was set by ADS command process_set_working_directory() before starting Python.
Interpret AEL code sent from Python
The second Python example is very similar, but we use the return string differently: instead of displaying the string, we interpret it as an AEL command using the execute() function. This sounds weird, but it enables external access to all ADS AEL functionality from an external program. We can remote control ADS that way … at least this gives an idea what would be possible.
The Python code is very simple: we just print AEL commands to terminal STDOUT, which will be read and interpreted by our AEL code when the Python program has finished. Note this is not a “permanent live link” with the code shown here, it just runs Python once and evaluates the return string once.
Looking at the AEL command sent from the Python code below, we can see what will happen in ADS: First a message dialog is shown, then a schematic window will be opened. Note that this sequence of actions is completely defined in the Python (!) code by sending (printing) the corresponding AEL command strings.
Note the use of “” for ADS string delimiters inside Python strings enclosed in single quotes.
Example workspace
Click here to download the example workspace with all source codes discussed above (*.zip, 1MB)
ADS2022U2_external_control_wrk.zip