Earthworm Module Window
Any EW module/exe using the Display NewConsole or MinNewConsole parameter in the startstop configuration file will have its own display window. Unlike the STDOUT window, these windows will send any keyboard input to the module it is monitoring. Each module can have its own window and process settings.
Besides the normal background color, text color and font settings the user can control how often the DLL Hook monitors the module's screen buffer for changes. See the technical information below for more information. The Window Update Interval is the main parameter controlling how often the thread in the DLL Hook is allowed to check for console screen buffer changes. Any changes in the screen buffer are then sent to the appropriate EwConsole window. The Update Wait Time is the time to wait (in milliseconds) after any changes in the STDOUT handle of the EW module. It is unknown at this time if this parameter is needed.
Like other EwConsole windows, a popup menu can be opened using a right click mouse input. There the user has the option to open the Settings dialog box above, Copy any selected text to the clipboard, Clear the screen or pause the display. When paused, up to 100 lines of text will be saved in a queue and displayed after unpausing the window.
EwConsole Settings and HYPO Ring Monitoring
The above dialog box, opened using the File / EwConsole Settings menu items, is used to control EwConsole settings and preferences. Here is a description of the dialog fields:
Exit program warn message:
If checked EwConsole will display a warning message before closing down the program.
Check for events on HYPO Ring:
This feature is not found in the startstop_nt.exe module. If enabled EwConsole will monitor the HYPO Ring for TYPE_HYP2000ARC type messages and do the following:
- Run the command entered in the New Event Command edit box
- Play the sound file entered in the Play this file on new event field
- Open an Acknowledge Dialog box
- Replay the sound file if Repeat enabled or play the Count number of times
New Event Command:
Program or batch file to run on new events.
Acknowledge Event Command:
Program or batch file to run when the event is acknowledge.
Play this file on new event:
The mp3 file specified in this field will be played when a new event is received on the HYPO Ring. EwConsole can play one of six files based on the magnitude by using %m as part of the file name. As an example event%m.mp3 would play a file called event1.mp3 for any events below 1.0 and up to 1.49. The file event2.mp3 will be played for any events between 1.5 and 2.49 etc. Any events with magnitudes above 5.5 will use 6 for the %m number.
Repeat:
If checked, EwConsole will replay the mp3 file Count number of times or the user acknowledges the event.
Count:
Specifies the number of times to repeat the file if the Repeat check box is checked. Using 0 will repeat the file continuously until the event is acknowledged.
Acknowledge New Event File:
The program can use the presence of a file specified in this field to acknowledge new events. When the New Event Acknowledge dialog box is opened one of the things the program will do is to check for the acknowledge file once a second. If the file is found the New Event dialog box will be closed. EwConsole does not read the file so the contents is not used, just the fact that the file shows up in the directory is all that is needed to acknowledge an event.
Test new event:
This check box can be used to test the above new event feature. If this checkbox is checked, and after the user press the Ok button, EwConsole will simulate receiving a HYPO Ring messages. The Test Mag number will be used as the simulated HYPO Ring magnitude.
Test Mag:
Used with the Test new event check box above. This is the magnitude number that will be used in the test of the new event processing.
Ok:
Closes the dialog box.
Cancel:
Closes the Settings dialog box without making any changes.
New Event Acknowledge Dialog Box
The above screenshot shows the New Event Acknowledge dialog box. The New Events count will be updated as new HYPO messages are received. When the user press the Acknowledge button, or the program finds the Acknowledge New Event File file, EwConsole will do the following:
- Run the command entered in the Acknowledge Event Command edit box
- Stop playing the sound file
- Reset the event counter
- Close the Acknowledge dialog box
DLL Injection:
EwConsole uses a technique called DLL Injection to monitor the EW module process. Each module is started up using the CreateProcess () function in the suspend mode, then some code is injected into the new process that creates a monitor thread. After the code is injected into the process the EW module is allowed to run. The thread that is injected into the module does the following:
At startup all EW modules are created with a hidden console. As the EW module writes characters to its screen buffer, using output function calls like printf(), the monitoring thread detects the new characters and passes the information to the EwConsole window monitoring the module. Information to/from the EW module is done using shared map memory regions for each module. How often the thread checks for new characters is controlled in the Module Settings dialog box Window Update Interval field.
Modules with the NoNewConsole display attribute will still be monitored using the DLL Injection so the output can be sent to the STDOUT Window.
Modules not sending their output to STDOUT Window will receive keyboard input characters if the user press a key in a EW module window. So functions like kbhit() and getc() should work as expected.
DLL Injection seems to work fine with java.exe if you use the 32-bit version. One change with the shutdown process in EwConsole is waiting for Java modules to exit. These are terminated early on in the shutdown presses and not added to the list of handles to wait for before being forced to terminate.
The one problem we see with EwConsole, besides the added complexity of the DLL Injection, is the added recourses needed to monitor the EW module. Besides the EW module process itself, two other threads are created per module. One is the DLL Injection thread and the other is a thread used to receive/send data to the DLL thread. Since most modules send very little information to the screen the CPU usage for both module monitoring threads should be very low.
Compiling EwConsole:
To compile EwConsole you will need Visual Studio 2005 or above. You will also need the current version of the Boost library (http://www.boost.org/) installed on your system. The EwConsole project file will need to be updated with the location of your Boost library location. The program needs to be linked to msvfw32.Lib so the program can play a sound file when a new event is detected on the HYPO Ring. Before you can compile the program you will need to comment out some lines in the startstop_lib.h file that is located in your EW include directory. This is needed to prevent duplicate global variables when linking the program.
Here are the lines that need to be commented out.
//int oldNChild; /* original number of children before a reconfig request */ //int newNRing; /* new NRing total */ //#ifdef _WINNT //DWORD badProcessID; /* increment this to keep track of bad processes */ //#else /* shared by both Solaris and Linux/unix */ //pid_t badProcessID; /* increment this to keep track of bad processes */ //#endif //char * lockfile; /* create a lock so only a single instance of startstop runs */ //int lockfile_fd;
Running EwConsole Under Linux Using Wine:
EwConsole can be run under Linux using Wine. Wine is a software application that allows Linux users to run Windows programs like EwConsole and the Earthworm modules that have been compiled to run under Windows. Below is a screenshot of EwConsole running the Earthworm Memphis test suite.
Testing of EwConsole under Linux was performed using Ubuntu version 12.4 LTS and Wine beta 1.6. EwConsole was complied using the Earthworm version 7.6 source code. EwConsole and the Earthworms modules must be compiled using a 32-Bit compiler. The program can not run 64-Bit based programs do to the DLL Injection used to run the EW modules . See the following documentation for more information on running Windows programs under Wine: Running WinQuake and WinSDR on Linux. When setting up Wine on your system make sure you run the following command in a terminal to install the DLLs needed to run the program:
'winetricks vcrun2005'
As with any EW installation you will need to edit the ew_nt.cmd file to update the paths to various directories. You can then open a Wine console by typing 'wineconsole' in a terminal. Before you can run EwConsole you will need to copy the EwConsole.exe and ConsoleHook.dll files to your EW bin directory. Once you have done that and updated your *.d and *.desc configuration files you should be able to run EW by typing 'ewconsole.exe' at the command prompt. This will start EW using the default startstop_nt.d configuration file. You can also specify a startup file by adding it to the command line. Example: 'ewconsole.exe test_ew.d'