For general Joystick Gremlin documentation - consult https://whitemagic.github.io/JoystickGremlin/
This custom version adds to release 13.3 of Gremlin:
- Update to x64 bit from x32 bit
- Update to Python 11.x (improved execution speed over Python 10)
- Update to QT6 UI framework
- Improved stability when loading a plugin that has an error on load
- Remote data control of another GremlinEx client on the local network
- OSC message handling (for touch screen support going to Gremlin via TouchOSC for example)
- VjoyRemap plugin for control
- MapToMouseEx plugin for enhanced mouse control
I suggest you make VjoyRemap the default action in the options panel as this plugin is what provides many enhancements over the default Remap plugin. Same for mouse output - MapToMouseEx provides enhanced options for the mouse macro functions.
This said, the default plugins are all functional but they won't be aware of the new features in GremlinEx.
I updated this code repository for my own purpose as I ran across my hardware cockpit needs for my PC based simulators and thought to myself - hey - would love if this did [that]! I was quickly confined though to the base functionality and realized soon that some deeper surgery was needed. I also wanted the code to use current platform tools as there is for example a significant boost in performance just by using a new Python environment.
As such, the code may have some bugs and other things I'm missed in my own testing, so please report issues you encounter as you find them and I'll do my best to fix them.
The core repository was substantially modified in some areas to support remote control, including some new events, adding improved support for user scripts (so they are aware of state information for example). Some UI elements were also modified a bit to improve the visuals and to simplify certain aspects of Gremlin. For example, all buttons support a release action without going through more complex hoops for setup, as a check box is simpler to setup in this use-case. This made it much simpler for me to map physical switches on throttles that have a single state to multi-state and do what used to be complex mappings essentially a checkbox affair.
I have attempted to use the base project as much as possible, and I am grateful to WhiteMagic and his excellent ideas as Gremlin is simply the best mapping utility I have ever seen or used in decades of simulation and hardware input mapping to games. The architecture is also excellent and made my modifications very simple.
I am using this code daily for my simulation needs but that's not a guarantee everything works as expected. Feedback welcome!
GremlinEx can auto-highlight hardware joystick input devices by clicking a button or moving an axis on them. This eliminates the guesswork on how the hardware maps to buttons or axes.
Automatic detection is only active when a profile is not running.
When in this mode, GremlinEx will attempt to display the correct input - I say attempt because it can get confused sometimes with multiple active concurrent inputs.
The default behavior is it waits for an axis or a button to be activated before displaying anything, so the initial load up UI may not reflect the input until it's touched again.
GremlinEx has a built in protection against multiple inputs, but will display the last detected input if multiple inputs were sent.
There are three options that control this behavior in the GremlinEx options panel:
| Option | Description |
|---|---|
| Highlight currently used input (axis + button) | Will switch focus to the input device for axis or button changes - this can make it difficult to just pick a button |
| Highlight currently used buttons | Detects button changes only (axis movement is ignored but can be overriden - see below (this is recommended) |
| Highlight swaps device tabs | Changes input tabs automatically (this is a recommended) |
A pair of modifiers can be used to modify how input is detected.
| Option | Description |
|---|---|
| Left shift | If you hold the left shift key, GremlinEx will track axes instead of just buttons regardless of the options selected . |
| Left control | If you hold the left control key, GremlinEx will only track axes regardless of the options selected . |
Recommend that you set the default behavior is to track buttons only as it's very easy to trigger an axis by pressing a button because many hardware devices are very sensitive. Use the left shift or control key to modify that behavior on the fly.
Note that whatever is first detected will go to that item (axis or button) if nothing is selected. This is on purpose to pick a starting point.
Holding the left-shift key down when in button detect mode temporarily enables axis detection as well as button detection. This is the same as the first option in the table above.
Holding the left-shift key and the left-control key when in button detect mode temporarily enables exclusive axis detection and ignores button presses. This is helpful when you have a hardware axis that also has detents along the way that send button inputs. In this mode, these buttons will be ignored.
GremlinEx adds a feature to link multiple GremlinEx instances running on separate computers. This is helpful to share a single set of controls and a single profile on a master machine to one or more client machines on the local network.
The use-case for this need came up in a couple of scenarios in my own setup: I wanted to be able to share my hardware panels and input controllers with another machine without having to duplicate them.
Events sent over the network include all GremlinEX output functions:
- VJOY joystick axis events (when an axis is moved)
- VJOY joystick button events
- keyboard output events (press/release keys including extended keys)
- mouse output events (pres/release mice button 1 to 5, mouse wheel events, and mouse motion events)
- Gremlin macro outputs
By output events, we mean that inputs into GremlinEx are not broadcast to clients, only events that GremlinEx outputs are synchronized with clients.
To use the remote control features, it is intended you use the new plugins VjoyRemap and MapToMouseEx
The master machine is the machine responsible for broadcasting control events to clients on the local network. Thus it will typically be the primary system with all the physical hardware managed by GremlinEx.
The broadcast machine or master system will have the broadcast option enabled and an available UDP port setup (default 6012). When the broadcast feature is enabled, GremlinEx will broadcast all output events.
Important: to broadcast, the option must be enabled in the checkbox, and the GremlinEx profile must also have enabled the broadcast functionality on. This is needed because when GremlinEx first starts, it defauts to local control only.
Profile commands can be mapped via the VjoyRemap plugin to control whether GemlinEx sends outputs to the local (internal) or clients, or both concurrently.
While more than one master machine can broadcast, it's recommended to only have one. Multiple machines will allow more than one machine to send broadcast commands to clients for unique setup needs.
The enable speech checkbox can be selected for GremlinEx to send a verbal mode change event whenever local/remote mode control is changed in case the GremlinEx window is not visible.
GremlinEx shows what output mode is active in the status bar.
GremlinEx options setup for a broadcast machine:
In this mode, GremlinEx sends VJOY, keyboard and mouse events to the local machine.
The status bar displays
In this mode, GremlinEx sends VJOY, keyboard and mouse events to clients on the network. The clients must have the remote control checkbox enabled, match the port number, and have a profile running (empty profile is fine) to respond to the broadcast events.
The status bar displays
GremlinEx can send to the local and remote clients at the same time (concurrent mode) by sending the Concurrent command.
Each GremlinEx client needs to have the remote control option enabled in options to be able to receive events from the master machine. The master machine must also be setup to broadcast these events.
The client must be in run mode to accept broadcast events, and the profile can be empty. No profile needs to be loaded on the client when the client is in remote control mode.
Clients will only output to VJOY outputs that match the master. So if the client has the same setup for VJOY (number of VJOY devices, button counts and hat counts) as the master machine, all VJOY events will be synchronized with the master machine. This is the recommended setup.
Clients will ignore events for devices that do not exist on the client (such as an invalid VJOY device number, or an invalid button for that defined device).
GremlinEx options setup for a client:
The enable remote control checkbox is checked, and the port (default 6012) must match the broadcast machine's port.
Local and broadcast (sending output to remote GremlinEx instances on network machines) control can be enabled or disabled via GremlinEx commands bound to a joystick button (or in script).
Commands are available in the VjoyRemap plugin when bound to a joystick button and available from the drop down of actions for that button.
The VjoyRemap commands are:
| Command | Description |
|---|---|
| Set Remote Control Only | Enables broadcast mode and disables local output mode. In this mode, GremlinEx only sends output to network clients. |
| Set Local Control Only | Enables local mode and disables broadcast mode. In this mode, GremlinEx only sends output to the local machine. |
| Enable Remote Control | Enables broadcast mode. This activates broadcast mode regardless of the local output setting. |
| Disable Remote Control | Disables broadcast mode. This disables broadcast mode regardless of the local output setting. |
| Enable Local Control | Enables local mode. This activates local output mode regardless of the broadcast output setting. |
| Disable Local Control | Disables local mode. This disables local output mode regardless of the broadcast output setting. |
| Enable Concurrent Local + Remote Control | Enables both local and broadcast modes. GremlinEx output goes to both local and remote machines at the same time. |
| Toggle Control | Inverts current output settings for both local and broadcast controls, whatever they are. |
The commands are only available to button bindings at this time.
| Command | Description |
|---|---|
| Button Press | Outputs a single button to the given VJOY device. The exec on release option sends the output when the physical button is released. Start mode sets the output status on profile start. |
| Pulse | Outputs a single button to the given VJOY device momentarily. The default pulse duration is 250 milliseconds, which can be adjusted. The exec on release option sends the output when the physical button is released. Start mode sets the output status on profile start. |
| Toggle | Toggles (flips) the button output on the given VJOY device. If it was on, it's off, if it was off, it toggles on. Useful for on/off type activites. |
| Invert Axis | Inverts the specified output axis on the VJOY device. This flips the direction of output of the axis on the fly by mapping it to a button. This is specific to games that map the same axis but they are inverted (example in Star Citizen is ship throttle vs vehicle throttle). When mapped to a physical switch on the throttle, converts from ship mode to vehicle mode for the throttle. |
| Set Axis Value | Sets the axis value on the given VJOY axis to a specific value between -1 (min) and +1 (max). This is useful for detent programming. |
| Set Axis Range | Modifies the output range of an axis in VJOY. The output will be calibrated to the new min/max and has convenience buttons to set half ranges. Use-case: increase sensitivity of physical axis, such as, for landing or roll. |
| Enable remote pairing | When set, the button output locally will also be output remotely regardless of the control mode |
| Disable remote pairing | Turns off remote pairing mode |
| Command | Description | |
|---|---|---|
| Axis | Maps source axis to a VJOY output axis. Options: | |
| Reverse | Inverts the output of the axis | |
| Absolute | The value of the output matches the raw input value | |
| Relative | The value of the output is relative to the raw input value | |
| Start Value | The default axis position on profile start | |
| Scale | Scaling factor applied to the raw input. Use case: increase sensitivity. | |
| Min/Max Range | Sets the default output min/max range. The raw input is calibrated to only output between the two values (scale is computed automatically) |
| Command | Description |
|---|---|
| Axis To Button | Maps a raw input range to a specific button. While the raw input is in that range, the button will be output. Combine multiples of those to create more than one trigger. Use-case: detent programming based on axis position. |
This plugin is identical to the Map to Mouse plugin but adds a wiggle function, easy execute on release and button hold functionality. When wiggle is enabled, the mouse will move slightly by itself every 10 to 40 seconds and move back. It will do that until wiggle mode is turned off.
The purpose of wiggle is to keep an application alive. Wiggle is turned on/off separately for remote/local clients.
| Command | Description |
|---|---|
| Mouse Button | Outputs one of the mouse buttons |
| Mouse Axis | Moves the mouse |
| Wiggle Enable (local) | Jolts the mouse every few seconds |
| Wiggle Disable (local) | Stops the mouse wiggling if it was turned on. |
| Wiggle Enable (remote) | Jolts the mouse every few seconds on remote clients |
| Wiggle Disable (remote) | Stops the mouse wiggling if it was turned on for remote clients |
Mouse commands can forced to be sent to remote hosts only, or to send them concurrently to the remote host regardless of the remote control state.
GremlinEx adds a few custom Gremlin script decorators to facilitate custom scripting and control from Python.
Called when a profile is started - lets a script to initialization when a profile starts to run
Called when a profile is stopped - lets a script cleanup when the profile stops running
Called when the mode is changed (use def mode_change(mode) - mode will be a string) - lets a script get a notification when there is a profile mode change somewhere in GremlinEx.
Called when the state information is changed (local, remote or broadcast mode). The event properties is_local, is_remote and is_broadcast are flags that contain the current state of GremlinEx.
Some hardware controllers only have a trigger on one (two) positions out of two (three). Usually the center doesn't have a button mapped.
In GremlinEx VjoyRemap a button trigger can easily be output for each position of a switch by adding a release mapping to the hardware positions that do trigger on. The trigger occurs then when the switch leaves the position and turns off.
One responds to button presses on the raw hardware, the other responds to a button release on the raw hardware.
| Mapping | Description |
|---|---|
| Send VJOY output | Sends a button press to VJOY device and button when the position of the button is active. |
| Send VJOY output (on release) | Sends a button press to VJOY device and button when the position of the button is no longer active. The checkbox "execute on release" is selected in this case. |
The equivalent pulse commands can be send to send a momentary pulse rather than having the button on all the time if that is needed.
Any logic that depends on reading more than one hardware value is best done as a plugin. Plugins are Python files "attached" to a GremlinEx profile and the script enhancements make it possible to run a function when a hardware event occurs.
You use a Python decorator to map a function to a hardware event. The decorator starts with the @ sign and tells GremlinEx what hardware and input you are mapping to.
GremlinEx adds a Script Generator button to the Device Information dialog that copies all current hardware device names, IDs and automatically creates decorators out of them that can be pasted directly into a Python script file.
https://github.com/shauleiz/vJoy
Installs one or more virtual programmable HID joysticks on Windows with up to 8 axes, 4 hats and 128 buttons per the DirectInput specification.
https://github.com/muchimi/TouchOsc
Transforms any touch screen into a game control surface, similar to GameGlass.
This tool hides raw hardware only exposing the VJOY devices. Essential to not confuse games or simulators.
https://github.com/ViGEm/HidHide
A touch enabled surface designer initially setup for the OSC (open sound control) and MIDI protocols to control musical instruments, DAWs and live performances. Supports multiple platforms. Has a free version but the license is well worth the price. Simple set of controls, but very powerful because of the available LUA based scripting and works on any platform, thus making your phone, tablet or touch-enabled desktop function as an input device.
I also recommend the Protokol tool to diagnose any OSC issues.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent