Dashboards are collections of Graphs and text labels that may be displayed and updated when a SIMPROCESS model is simulated. For more on creating Dashboards and associating them with elements of SIMPROCESS models, see the Dashboard menu and Chapter 16 of the SIMPROCESS User's Manual.
Each Dashboard is stored in a file with the extension of ".spd" and stored anywhere you choose. To display Dashboards when a SIMPROCESS model runs, you need one or more Dashboard Servers running. If no Dashboard Server is available at the locations indicated in the SIMPROCESS model, it will still simulate normally.
When SIMPROCESS was installed, it included a directory named dashboardserver, which contains almost all that's needed to run a Dashboard Server. In fact, you can start a Dashboard Server right from within SIMPROCESS using only those files and one or more Dashboard files.
Files and Directories
You can run a Dashboard Server on any system that is equipped with a Java Runtime Environment fully compatible with Sun's Java 2 Platform version 1.4 provided it supports a graphical display. It has been tested on multiple versions of Windows and Linux. What follows is a list of the files and directories installed:
dbServer.jar: This is a Java Archive file containing the Dashboard Server program itself. If you have a Java Runtime Environment (JRE) installed separately from SIMPROCESS on a Windows system, you can double-click this file to start the server. This also works on Mac OS X. Whether it works on any other system is dependent on that system's configuration and capabilities. This jar file is dependent on some of the other items listed below.
jfreechart.jar: This is a Java Archive file containing the open source JFreeChart which is used in Dashboards. You can find more information at the JFreeChart web site at http://www.jfree.org/jfreechart/index.html. The files available from that site include numeric values indicating the version. In order to support using newer versions as needed, we have renamed the files to exclude the version information.
jcommon.jar: This is a Java Archive file containing the open source JCommon library, on which JFreeChart depends. The files available from the above web site include numeric values indicating the version. In order to support using newer versions as needed, we have renamed the files to exclude the version information.
server.properties: This file is not strictly required unless you want to use values other than the defaults used by the Dashboard Server, or if you wish to use a multicast group (see below). As installed, it contains two entries:
dashboard.server.port=5555
dashboard.server.directory=./dashboards/
The first property, dashboard.server.port, indicates the network port on which the Dashboard Server will listen for requests to display and/or update Dashboards. Valid port numbers are from 1025 through 65535. You may need to consult your local network administrator to ensure that the port you want to use is available.
The second property, dashboard.server.directory, is the name of the directory where the Dashboard Server will attempt to find Dashboard files. If a request is received for a Dashboard with no corresponding file in the named directory, it will be discarded by the server. This provides the flexibility to decide which Dashboards will actually be displayed for any running SIMPROCESS model by simply controlling which files are present in this directory. The default entry assumes that the "dashboards" directory is in the same directory as the dbServer.jar file, though it may contain a complete path-qualified name. NOTE: When entering paths on Windows systems, it may be necessary to place additional backslash characters next to each one already included, e.g., change "C:\Program Files\MyDir" to "C:\\Program Files\\MyDir" instead.
The installed file contains a third entry which is disabled, #dashboard.server.multicast.address=230.1.2.3. To enable this line, remove the "#" character at the beginning. A multicast address is a special kind of Internet Protocol address (see below) that supports broadcasting messages to groups of subscribers. If this property is found, the Dashboard Server will subscribe to the designated group. Then, the SIMPROCESS model(s) wishing to send data to it should use that IP address instead of an actual host system's address. All servers subscribing to the same multicast group will then receive the same messages. A Dashboard Server subscribing to a multicast group will still receive messages addressed to its specific IP address.
dashboards: This directory is the one used by the Dashboard Server if no properties file exists. As described above, any other directory can be used if its name is present in the properties file. Simply place the Dashboard files in this directory in order for the Dashboard Server to find them at runtime.
server.bat and server.sh: These files are provided as examples only. One is a batch file which can be used on Windows systems, and the other is a shell script file suitable for use on Linux, Mac OS X, or other Unix-like systems. As installed, these specifically refer to a "java" command expected to be found in a "jre" directory typically installed with SIMPROCESS. It is possible to copy this complete directory structure anywhere else on the system where SIMPROCESS is running and update the path to point to the installed "jre" directory, or you can remove the path reference entirely if your system's environment will find a suitable executable.
Network and Port Details
Communication with a Dashboard Server is done via the User Datagram Protocol (UDP). The technically curious may read more about UDP at http://www.faqs.org/rfcs/rfc768.html. The only known problem that may be encountered using UDP is that some network administrators do not allow UDP packets to pass through their firewalls. So if you plan to communicate through one or more firewalls and have difficulties, you may need to consult your network administrator.
As indicated above, the Dashboard Server will listen by default on the arbitrarily selected port 5555. Consider a port as somewhat similar to a specific frequency on your radio, or channel on your television set. In order for your SIMPROCESS model and Dashboard Server to communicate, you must ensure that both are referring to the same port. You may need to ask your network administrator to recommend an appropriate port.
A Dashboard Server will attempt to join a multicast group if the properties file contains an entry like the one described above. The technically curious can read more on IP multicasting at http://www.faqs.org/rfcs/rfc988.html. Valid IP addresses for multicast groups are Class D addresses (defined in the referenced RFC) in the range of 224.0.0.0 through 239.255.255.255 inclusive. You may want to ask your network administrator to recommend an appropriate multicast group address for your use. If you enter an IP address for this property that does not represent a valid multicast group, the server will display an error message.
What a Dashboard Server Does
If a SIMPROCESS model runs and no Dashboard Server is receiving its requests to display Dashboard data, it will continue to operate as normal. If more than one model is sending requests to a Dashboard Server, it will honor all provided it has Dashboard files for each request it receives. This should not pose a problem unless both are sending requests concerning the same Dashboard file and cause inconsistent data displays.
When started, the Dashboard Server looks for the properties file described above. If it cannot find it, or if its contents are not valid (the directory listed isn't available, or the port is invalid), it resorts to defaults. Then it simply waits for requests to display Dashboard data.
Each item in SIMPROCESS for which a Dashboard update is desired will identify the host system where it anticipates finding a Dashboard Server (typically an Internet Protocol, or IP, address), along with the port where it expects that server to be listening. It will need to name the Dashboard and the specific graph, and provide data appropriate to that type of graph. Multiple Dashboard Servers can easily be run on a Linux or other system, each listening on a different port, so that a wide range of Dashboard displays can be available at any time. And any single SIMPROCESS model can communicate with any number of Dashboard Servers.
When a request is first received for a Dashboard, a Dashboard Handler is started internally which will handle all subsequent requests for that Dashboard. If a request is received for a Dashboard whose file is not in the indicated directory, it will be ignored. The Dashboard Handler will read the relevant Dashboard File and construct a window which resembles the one seen in the Dashboard Preview when defining Dashboards in SIMPROCESS. Then it will process the first and all subsequent packets of information it receives, updating any graph referred to with information contained in the packet. If any packet refers to a graph which is not in the Dashboard file, it will be discarded.
The window displayed for a Dashboard cannot be closed manually. It will remain open until the Dashboard Server shuts down, which can be done from its File menu or by closing the main server window. Dashboard windows also cannot be resized, as their sizes are determined when the Dashboard is created in SIMPROCESS.