HS Event Dispatch System
Beta Version 0.4.53 for testers
(For Evaluation Only)
DOCUMENTATION
version 0.1.4 – 2014/08/11
Page 1 | 11
Table Of Content
1 Introduction............................................................................................................................................3
2 Disclaimer/Limitation on Liability.........................................................................................................3
3 System Requirements.............................................................................................................................4
3.1 System Mandatory Requirements..................................................................................................4
3.2 System Recommended Requirements............................................................................................4
4 System Limitation..................................................................................................................................4
4.1 Known problems ('bugs')................................................................................................................4
5 Users suitable basic knowledge.............................................................................................................4
6 Technical Information............................................................................................................................4
7 HS Event Dispatch System (EDS) Overview........................................................................................4
7.1 EDS HQ - Configuration module (visual API – do not launch during gaming)............................4
7.2 The launch module (light weight (176kb) , invisible to users - no GUI , functional API only).....5
7.3 EDS_ClassLibrary.dll (core engine, very lightweight 14kb).........................................................5
8 EDS Command line parameters (Param 1, Param 2, Param 3)..............................................................5
9 EDS Configuration & Controls GUI......................................................................................................6
9.1 Table Fields definition....................................................................................................................6
10 Application Setup.................................................................................................................................9
11 For Developers.....................................................................................................................................9
Page 2 | 11
1 Introduction
Recently (November 2014), I developed HyperMarquee to manage multiple displays. I had to face one
reality constraint, Hyperspin events are single thread and single application call... HS cannot launch
more than one application at wheel event, letting users with the difficult decision to choose between
HyperSpeech, LEDBlinky, HyperSpinHelper, HyperMarquee etc... To give Hyperspinners more
flexibility, here is a Hyperspin Event Dispatcher System (EDS) that allows you to launch as many
applications on HS events that you like. This should be beneficial for the community where basically,
this is a tool to extend Hyperspin possibilities and let users the possibility to manage multiple
applications on HS events.
Cheers,
Special thanks to:
• Brolly & Gooch for advises, support and graciously volunteer for beta testing.
• Users! (For testing, bugs report and improvement ideas)
• Bad Boy Billy for great inspiration and Hyperspin Front end.
• Nemo1966 for Async NamedPipe Client & Server code example.
• My Girlfriend France, who always supports me.
This is free and it will always be. To encourage development, you can send a donation of your choice
through PayPal to [email protected].
2 Disclaimer/Limitation on Liability.
The software and all libraries are supplied "as is" and all use is at your own risk. I disclaim all
warranties of any kind, either express or implied, as to the software, including, but not limited to,
implied warranties of fitness for a particular purpose, merchantability or non infringement of
proprietary rights. Neither this agreement nor any documentation furnished under it is intended to
express or imply any warranty that the operation of the software will be uninterrupted, timely, or error
free.
Under no circumstances shall I be liable to any user for direct, indirect, incidental, consequential,
special, or exemplary damages, arising from or relating to this agreement, the software, or use or
misuse of the software or embedded component. Such limitation of liability shall apply whether the
damages arise from the use or misuse of the software or any other services supplied by me.
(including such damages incurred by third parties), or errors of the software.
Page 3 | 11
3 System Requirements
3.1 System Mandatory Requirements.
• Microsoft Windows (Tested on Windows 7 & Windows 8.1)
• .Net Framework 4.5.1 (not provided - link)
• Xceed.Wpf.Toolkit.dll (provided)
3.2 System Recommended Requirements.
• None for now
4 System Limitation
4.1 Known problems ('bugs').
• Circular effect when calling EDS is calling itself.
• The content of the settings file may disappears letting the configuration file completely empty.
This behavior has been reported by one user only so far, and the origin of the problem has not
been identified. Suspecting using obsolete configuration file version. Status: under observation
5 Users suitable basic knowledge.
– Basic understanding on Inter-Communication Process (ICP).
– Basic understanding on Hyperspin system & configuration.
6 Technical Information.
– Development Environment : Microsoft Visual Studio Express 2013 for Windows Desktop
– Development Languages : C# 2013, WPF 2013, XAML 2013
7 HS Event Dispatch System (EDS) Overview
There are three (3) EDS modules;
7.1 EDS HQ – HyperSpin Applications Integrator
The Graphical user Interface (GUI) to set user configurations. (do not launch during gaming)
Page 4 | 11
7.2 The launch module - “EDS_LaunchModule (rename me).exe”
• Light weight (176kb) , hidden to users - no GUI , functional API only
• This is the command line application ('Proxy' / middle app) application to be called by
Hyperspin to launch application on events. With this module, HS can launch 3rd party
applications like LedBlinky, HyperSpeach, HyperSpin Helper, HyperMarquee, etc..
• For Hyperspin users, this is the .exe module to be renamed ledblinky.exe.
7.3 Core engine, very lightweight 14kb - “EDS_ClassLibrary.dll”
• EDS core functionality engine. Works in conjunction with the LaunchModule.
8 EDS Command line parameters (Param 1, Param 2, Param 3)
There are 3 possible parameters (Same as LedBlinky); event, rom & system.
Parameter Parameter 1 Parameter 2 Parameter 3
Front-End Start (1) Code: [1] type:<event> Nil Nil
Front-End Stop (2) Code: [2] type:<event> Nil Nil
Game Launch (3) Code: [3] type:<event> Type:<rom> Type:<system>
Game Stop (4) Code: [4] type:<event> Nil Nil
Screensaver Start (5) Code: [5] type:<event> Nil Nil
Screensaver Stop (6) Code: [6] type:<event> Nil Nil
System Select (7) Code: [7] type:<event> Type:<system> Nil
List Change (8) Code: [8] type:<event> Nil Nil
Game Select (9) Code: [9] type:<event> Type:<rom> Nil
Animation Stop (11) Code: [11] type:<event> Nil Nil
Page 5 | 11
Load MAME Controller File (12) Code: [12] type:<file> Nil Nil
Reset Ultrastik 360 (13) Code: [13] type:<map> Nil Nil
Note:
• Use double quotes around parameters if the parameter value may include spaces.
• If you start a game without specifying the emulator, MAME is the default.
• There is also GameStart <rom> <emulator>, but I am not sure what is the difference with Game
Launch (3).
Page 6 | 11
9 EDS Configuration & Controls GUI. (App Integrator Module)
9.1 Table Fields definition.
– Application : Specifying application .exe location.
– IPC Methods
1. CLI : Command-Line Interface. Will call the specified application and passing defined
parameters on application launch. (By OS nature, parameters can be passed only one time,
i.e when the application is called). This can be much slower than Named Pipe, since the
application has to be launched each time an event is fired by HyperSpin.
PROS;
– Compatible with every .exe and can launch some applications with other file extension.
– Most users are already familiar with this approach.
– Easier integration with Hyperspin.
CONS;
– The slowest solution and the less responsive one.
– Needs to be closed/loaded the remote application each time user refreshed the HS wheel
event.
Page 7 | 11
– Hungrier on system resources
USAGE; (See HM documentation - command line parameter section 9 for me information)
– Hyper Marquee.exe false Mame-Image “GALAGA” “MAME”
2. Pipe : Set EDS as a Pipe Client in order to send parameters information to the specified
remote application acting has a Pipe Server using Named Pipe technology. This feature has
to be supported by the remote application. See remote application documentation to see if
its support NamedPipes. The name of the Pipe is declared within the Pipe ID column. Side
note: The local Named Pipes protocol is the preferred option within EDS. Local named
pipes runs in kernel mode and is extremely fast, see this Microsoft link for more
information. Named pipes are faster than TCP/IP for IPC on the same machine. Remote
application developers can integrate Piper Server support to be fully compatible with EDS
and enhanced the their application responsiveness with HyperMarquee.
PROS;
– Bring best performance compared to other IPC options. (OS Kernel Low Level
communication)
– No need to reload HyperMarquee each time your artworks and text get updated. The
artworks or messages are updated at HM run time
– It is lightest option on system resources
– Capable of more than 8000 calls/seconds for 128bytes messages. NB: Performance may
decrease according to the size of your image and/or the power of your computer. Large
images could be stored on SSD rather than Hard Disk.
CONS;
– New approach where users may not be not yet familiar with.
– Remote applications needs to implement NamePipeServer to support this IPC. (the code
is available to developers)
3. Pipe (CLI) : This is a combination of two IPC Methods (CLI & NamedPipe). First, EDS
will send a message (parameters) to the NamedPipe server (the remote application) if exists.
Otherwise, EDS will launch the application and pass the parameters to it using CLI. EDS is
much faster than CLI, since the application stay loaded in memory at each HyperSpin event
call. Named Pipe is Low Level OS call.
– CBR : Close Before Rerun. This works with CLI, it is not meant for Pipe where it defeats the
purpose of it. Basically, this will close the application if running, before launching a new
instance to avoid multiple undesired instances of the same application. NB : This is not suitable
for Pipes, since this is opposed to the pipe objective.
– App (TRY) : Self explanatory, this will launch the application using the specified parameters as
a test.
– Close : Self explanatory, this will close (kill) the running application using the application
Process ID (PID).
Page 8 | 11
– Parameters : This is the parameters that will be passed to the remote application. You can write
everything that you like, but see remote application documentation to understand how to use the
parameters syntax which the given parameters protocol belongs to. Beside static parameters,
there are for (4) dynamic parameters that you can use; [event], [system], [game] and
[ledblinky]. NB : Dynamic parameter has to be set between square brackets. Use double quotes
directly around the parameters if it may contains spaces ( ex: “[game]” ).
Available parameters;
Event : The event issued by the Front End. See section 8.
System : This is the given system (the emulator, console, etc..).
Game : The is the game name that you to pass as a parameter.
LedBlinky : This format automatically set Ledblinky parameters and pass them according to
the specific event type.
– Disable : Disable application to be launched or used by EDS.
– Pipe ID : This is the name of the Pipe to send the message between EDS and the remote
application. Please refer the remote application documentation to see which shared name to be
use. For HyperMarquee, it is the name of the configuration file by default.
– Event Filter : The specified events list accepted parameters to launch the application. Here you
are specifying all the events that can be suitable to launch the application. Application will be
launched (CLI mode) or parameter will get passed (Pipe mode), only if event is part of the event
filter list or the list is empty. Usage: empty list = all events pass, otherwise only the events in
the list are allowed.
– Close Filter : This feature allows closing the application using its Process ID (PID) for
application that does not manage closing by themselves. EDS will close (killed) the remote
application if the HS event is part of the specified events list. Usually it's meant for Game Stop
(4) and/or Front-End Stop (2), but you can close the application on any defined events that you
like. NB : You shouldn't overlap/duplicate specific event with Event Filter, which this make no
sense and may leads to undesired EDS behavior.
– System Filter : This feature allows restricting the remote application from being launched by
all System (emulator) but the defined ones. HitToText, for instance, only works for MAME and
wouldn't be of any use for other systems. This will also gives you the possibility the have an
another specialized HiScore tool for other systems when exist. Usage: empty list = all systems
pass, otherwise only the defined systems in the list are allowed.
Page 9 | 11
10 Application Setup
There is no setup application to execute in order to use HS Event Dispatch System (EDS). The
application will use the installed .Net Framework and some few external libraries already provided
within the main application folder to run properly.
Here are the steps to configure EDS.
1. Install the fonts that are part of the distribution (optional but recommended)
2. Install .Net framework 4.5.1 if not already done.
3. Rename EDS_LaunchModule.exe application by Ledblinky.exe (for HS users)
4. Run HyperSpinEventIntegrator.exe (EDS GUI) to configure your apps that you would like to
use.
5. Configure and enable EDS within your favorite Front End. Within HyperHQ, set the path for
EventDispatchSystem root folder and enable LEDBlinky.
11 For Developers
The Complete code is available for developers. Refer to the download section.
– PipeServer: The remote application receiving the message on HS events from EDS pipeClient.
– PipeClient: EDS sending the message on HS events to your remote application (PipeServer).
– For testing, PipeServer.exe application and PipeClient.exe application with source code are
available for developers that wishes to integrate this technology within their remote application
or simply to run pipe tests during EDS configuration.
Page 10 | 11
Page 11 | 11
