5.10. Custom program using a system command

5.10. Custom program using a system command
	Chapter 5. Configuring programs for use with the BCVTB

This page explains how to call a custom program from the BCVTB at each time step by using the SystemCommand actor. This allows for example to call a batch file (on Windows), a shell script (on Mac or Linux), or any other executable program. The input to this programs can be done either through program flags, or by writing an input file from Ptolemy II, using actors from the library Actors->IO.

To explain how to use this actor, we will show how to call a program that implements a proportional controller with output limitation for a room with closed loop control. The program is implemented in the C language. (Note that such a controller could be directly implemented in Ptolemy II. However, for illustration, we implemented this controller in a C program.) The program writes the control signal to a text file, which will then be parsed by Ptolemy II. We assume that the program needs to be called with two arguments, i.e., the numerical values of the control error e and the proportional gain kP, as

  pcontroller e kP

where the numerical values e and kP may change at each call. We assume that the program writes the output file output.txt that needs to be read by Ptolemy II to receive the control signal. We also assume that the program returns the exit value 0 if no error occurred, or non-zero otherwise.

The next sections explain how to build such a system.

5.10.1. Create a Ptolemy II model

First, build a Ptolemy II block diagram that includes the SystemCommand actor from the library Actors->Simulator. Such a system model is implemented in the file bcvtb/examples/systemCommand/system.xml that is shown in Figure 5.33 .

Figure 5.33. Ptolemy II system model that links the SystemCommand actor, which calls a C program to compute the new room temperature, with actors that parse output files and compute the room temperature.

Ptolemy II system model that links the SystemCommand actor, which calls a C program to compute the new room temperature, with actors that parse output files and compute the room temperature.

5.10.2. Configure the ports of the `SystemCommand` actor

The SystemCommand actor has three predefined output ports: The port exitValue outputs the exit value of the program. The port output contains the standard output stream of the program, and the port error contains the standard error stream of the program.

Next, we will configure the input ports of the SystemCommand actor by right-clicking on the actor, and selecting Customize->Ports. This will show the following window:

Figure 5.34. Input form that is used to add new ports to the actor.

Next, click the Add button and enter the input ports e and kP. The port names can be selected arbitrarily by the user, and there can be as many input ports as needed. After adding the ports, the window should look as follows:

Figure 5.35. Input form after new ports have been added to the actor.

5.10.3. Configure the parameters of the `SystemCommand` actor

Finally, configure the parameters of the SystemCommand actor by double-clicking on its icon. This will show an input form where various parameters of the actor can be configured. The parameters of the SystemCommand actor are as desribed in Table 5.3, “Parameters of the SystemCommand actor.” .

Table 5.3. Parameters of the SystemCommand actor.

Parameter	Description
programName	The name of the executable that starts the simulation.
programArguments	Arguments needed by the simulation. Text arguments need to be enclosed in apostrophes.
workingDirectory	Working directory of the program. For the current directory, enter a period.
simulationLogFile	Name of the file to which the BCVTB will write the console output and error stream that it receives from the simulation program. Use a separate file for each simulation program. This file typically shows what may have caused an error.
showConsoleWindow	Check box; if activated, a separate window will be opened that displays the console output of the program.

To pass the current value of port variables to the program as its argument, configure the actor as follows:

Figure 5.36. Configuration of the parameters of the SystemCommand actor.

This configuration will cause Ptolemy II to call the command pcontroller $e $kP at each time step, with the values $e and $kP being replaced by the current value of the input token. There are also two built-in variables called $time, which is the current simulation time, and $iteraton which is the current iteration step of Ptolemy II. No port needs to be defined for these two variables.

For example, for the configuration above, if at some time step the input ports are e=1 and kP=2, then the BCVTB will fire the command

  pcontroller 1 2

and wait until the program pcontroller terminates. Upon successful termination, the port exitValue will have the token 0.

For an explanation of all parameters of the SystemCommand actor, right-click on the actor and select Documentation->Get Documentation.


5.9. Functional Mock-up Unit for Co-Simulation Import		5.11. Radiance