7. Simulation Control Plugins

7. Simulation Control Plugins
	Chapter 5. Plugin Reference

Simulation Control plugins are used to control NanoHive-1.

7.1. ConsoleCommand

The ConsoleCommand plugin provides a command-line interface to NanoHive-1 from the very same shell that was used to invoke NanoHive-1. See the Running Simulations section for command usage.

7.1.1. Configuration

The following is an example of how to configure the ConsoleCommand plugin in the NanoHive-1 configuration file.

  commandqueue.plugin.1=ConsoleCommand
  ConsoleCommand.resultCodesFile=data/local/en_resultCodes.txt

Table 5.14. ConsoleCommand Plugin Configuration Parameters

Parameter	Description
`ConsoleCommand.resultCodesFile`	The file to use to translate NanoHive-1 responses into human-readable form.

7.2. RMI_Control

Remote Method Invocation (RMI) is a popular inter-process communication method used in Java applications. The RMI_Control plugin provides an RMI interface to NanoHive-1. All NanoHive-1 controls are exposed via the RMI_Control API.

The following figure shows where and how the RMI_Control plugin fits in the NanoHive-1 system.

The RMI_Control plugin uses Java Native Interfaces (JNI) to launch and communicate with a Java Virtual Machine (JVM) process. Inside the JVM is an RMI server that receives simulation commands from RMI clients and sends responses.

Here is the RMI_Control Client Java API documentation describing how the RMI client is to interact with the RMI server. Additionally, included with the RMI_Control plugin source is a test client that shows an example of communicating with the RMI_Control plugin.

7.2.1. Configuration

The following is an example of how to configure the RMI_Control plugin in the NanoHive-1 configuration file.

  commandqueue.plugin.0=RMI_Control
  RMI_Control.classPath=c:/Program Files/NanoHive-1/classes/RMI_Control.jar
  RMI_Control.errFile=c:/Program Files/NanoHive-1/log/Java-Err.log
  RMI_Control.rmiRegistryPort=2001

Table 5.15. RMI_Control Plugin Configuration Parameters

Parameter	Description
`RMI_Control.classPath`	Where to find the RMI_Control.jar file.
`RMI_Control.errFile`	Where to write the JVM's standard error stream to - for debugging purposes.
`RMI_Control.rmiRegistryPort`	The port that the RMI Registry is running on. The default is 1099 if not specified.

7.2.2. Running the Test Client

Windows - check the jdk-home variable in C:\Program Files\NanoHive-1\bin\win32-x86\set-env.bat
Unix - check the JDK_HOME variable in /usr/local/share/NanoHive-1/scripts/set-env

Configure your configs.txt file as described above.
The RMI Registry must be running before you start NanoHive-1.
- Windows - open a command line in the C:\Program Files\NanoHive-1\bin\win32-x86 directory, run the set-env.bat script, then run start rmiregistry [port]
- Unix - open a command line in the /usr/local/share/NanoHive-1/scripts directory, source set-env, then run rmiregistry [port] &
where [port] is either set to value you specified in the configuration, or blank if you didn't specify (default is 1099)
Run NanoHive-1 from the same command line with: nh

Open another command line and set the environment with the set-env script again as was described in step 2 above, then run the RMI_Control_client [port] script.

Something like the following should result:

  load simulation from file
  >> Ok.
  load simulation from string (clobber previous one)
  >> Ok.
  run simulation
  >> Simulation "cnt55" has been started.
  let it run for a bit.....
  stop simulation
  >> Stopping simulation "cnt55"...
  >> Simulation "cnt55" has been stopped.
  get lastRunSerial variable
  >> lastRunSerial=20050223153841
  run simulation again
  >> Simulation "cnt55" has been started.
  check status
  >> Simulation "cnt55" is running: 25% done.
  >> Simulation "cnt55" is running: 85% done.
  >> Simulation "cnt55" is done.
  simulation done
  terminate NanoHive-1
  >> NanoHive-1 terminated.

7.2.3. Troubleshooting

The best place to start is looking at the log/NanoHive-1.log and log/Java-Err.log files. If there are still problems, visit the NanoHive-1 Support page for several options.

7.2.3.1. When I run my RMI_Control_client command, I get an Exception: Connection refused to host: localhost

7.2.3.1.	When I run my `RMI_Control_client` command, I get an `Exception: Connection refused to host: localhost`
	Make sure you include the `port` argument, for example, `RMI_Control_client 2001`

7.3. SocketsControl

The SocketsControl plugin allows NanoHive-1 to be controlled via a TCP socket connection. Connections are restricted to localhost until authentication is built in.

7.3.1. Configuration

The following is an example of how to configure the SocketsControl plugin in the NanoHive-1 configuration file.

  commandqueue.plugin.0=SocketsControl
  SocketsControl.ipAddress=127.0.0.1
  SocketsControl.port=3000
  SocketsControl.clientTimeout=30000

Table 5.16. SocketsControl Configuration Parameters

Parameter	Description
`SocketsControl.ipAddress`	The IP address to connect to. Note Using the loopback address (127.0.0.1) prevents outside connections. Using internal, or NAT'ed addresses (192.168.., 10...*, for example) prevents connections from outside your network.
`SocketsControl.port`	The TCP port number to use.
`SocketsControl.clientTimeout`	When to timeout clients (in milliseconds.)

7.3.2. Communication

The format for sending commands to the plugin (and subsequently to NanoHive-1) is the same for entering commands via the ConsoleCommand plugin. See the Running Simulations section for command format. Simply send the command as a string of characters.

The format for receiving results from the plugin is as follows.

  b1 b2 b3 b4 response-body

The first four bytes, b1..b4, contain the length of the message-body. Here's some code that decodes those four bytes.

  unsigned int responseLength;
  responseLength = (unsigned int)b1;
  responseLength |= (unsigned int)(b2 << 8);
  responseLength |= (unsigned int)(b3 << 16);
  responseLength |= (unsigned int)(b4 << 24);
  char* response = new char[responseLength + 1];

The response-body has the following format.

  response-code \t response-param-1 \t response-param-2 ...

The data/local/en_resultCodes.txt file can be used to decode the meaning of the response. Here's an example entry and explanation.

  # NH_SIM_RUNNING
  # Synchronous
  # param 1 is the sim id
  # param 2 is the percentage complete
  5=Simulation "###" is running: ###% done.

So if the response-code is 5, there will be two response parameters: response-param-1 will contain the identifier of the simulation and response-param-2 will contain an integer indicating what percentage of the simulation has completed.

The Synchronous and Asynchronous designations refer to whether the result is the first thing returned after processing a command (Synchronous), or if it can be returned at any time (Asynchronous). Asynchronous results are queued internally and if present, fed out to status commands until the queue is empty. Otherwise the normal status command response is sent.


6. Data Import/Export Plugins		Chapter 6. NanoHive-1 Software Development

Documentation