From 56507d7ac27d0562689ea7c505fa026ecc38494f Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 2 May 2020 16:55:13 +0200 Subject: Implement keyboard output for wininput --- backends/wininput.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 backends/wininput.md (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md new file mode 100644 index 0000000..672a24e --- /dev/null +++ b/backends/wininput.md @@ -0,0 +1,114 @@ +### The `wininput` backend + +This backend allows using the mouse and keyboard as input and output channels on a Windows system. +For example, it can be used to create hotkey-like behaviour (by reading keyboard input) or to control +a computer remotely. + +As Windows merges all keyboard and mouse input into a single data stream, no fine-grained per-device +access (as is available under Linux) is possible. + +#### Global configuration + +This backend does not take any global configuration. + +#### Instance configuration + +This backend does not take any instance-specific configuration. + +#### Channel specification + +The mouse is exposed as two channels for the position (with the origin being the upper-left corner of the desktop) + +* `mouse.x` +* `mouse.y` + +as well as one channel per mouse button + +* `mouse.lmb` (Left mouse button) +* `mouse.rmb` (Right mouse button) +* `mouse.mmb` (Middle mouse button) +* `mouse.xmb1` (Extra mouse button 1) +* `mouse.xmb2` (Extra mouse button 2) + +All keys that have an [assigned virtual keycode](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) +are mappable as MIDIMonster channels using the syntax `key.`, with *keyname* being one of the following specifiers: + +* One of the keynames listed below (e.g., `key.enter`) +* For "simple" keys (A-z, 0-9, etc), simply the key glyph (e.g. `key.a`) +* A hexadecimal number specifying the virtual keycode + +Keys are pressed once the normalized event value is greater than `0.9`, and released if under that. + +The following keynames are defined in an internal mapping table: + +| Key name | Description | +|-------------------------------|-----------------------| +| `backspace` | | +| `tab` | | +| `clear` | | +| `enter` | | +| `shift` | | +| `control` | | +| `alt` | | +| `capslock` | | +| `escape` | | +| `space`, | | +| `pageup`, `pagedown` | | +| `end` | | +| `home` | | +| `pause` | | +| `numlock` | | +| `scrolllock` | | +| `insert` | | +| `delete` | | +| `printscreen` | | +| `up`, `down`, `left`, `right` | | +| `select` | | +| `print` | | +| `execute` | | +| `help` | | +| `apps` | | +| `sleep` | | +| `num0` - `num9` | | +| `multiply` | | +| `plus` | | +| `comma` | | +| `minus` | | +| `dot` | | +| `divide` | | +| `f1` - `f24` | | +| `lwin`, `rwin` | | +| `lshift`, `rshift` | | +| `lctrl, `rctrl` | | +| `lmenu`, `rmenu` | | +| `previous`, `next` | Browser controls | +| `refresh` | Browser controls | +| `stop` | Browser controls | +| `search` | Browser controls | +| `favorites` | Browser controls | +| `homepage` | Browser controls | +| `mute` | | +| `voldown`, `volup` | | +| `nexttrack`, `prevtrack` | | +| `stopmedia`, `togglemedia` | | +| `mediaselect` | | +| `mail` | | +| `app1`, `app2` | | +| `zoom` | | + +Example mappings: +``` +generator.x > wi1.mouse.x +input.a > wi1.key.a +input.X > wi1.key.escape +``` + +#### Known bugs / problems + +Keyboard and mouse input is subject to UIPI. You can not send input to applications that run at a higher +privilege level than the MIDIMonster. + +Some antivirus applications may detect this backend as problematic file, because it uses the same system +interfaces to read keyboard and mouse input as any malicious application would. While it is definitely +possible to configure the MIDIMonster to do malicious things, the code itself does not log anything. +You can verify this by reading the backend code yourself. -- cgit v1.2.3 From f9886f3b06ce8e32aea893208646053f93a00a6c Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 2 May 2020 17:20:13 +0200 Subject: Reformat wininput table --- backends/wininput.md | 94 +++++++++++++++++++--------------------------------- 1 file changed, 34 insertions(+), 60 deletions(-) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index 672a24e..6455dd1 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -24,11 +24,11 @@ The mouse is exposed as two channels for the position (with the origin being the as well as one channel per mouse button -* `mouse.lmb` (Left mouse button) -* `mouse.rmb` (Right mouse button) -* `mouse.mmb` (Middle mouse button) -* `mouse.xmb1` (Extra mouse button 1) -* `mouse.xmb2` (Extra mouse button 2) +* `mouse.lmb`: Left mouse button +* `mouse.rmb`: Right mouse button +* `mouse.mmb`: Middle mouse button +* `mouse.xmb1`: Extra mouse button 1 +* `mouse.xmb2`: Extra mouse button 2 All keys that have an [assigned virtual keycode](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) are mappable as MIDIMonster channels using the syntax `key.`, with *keyname* being one of the following specifiers: @@ -41,60 +41,34 @@ Keys are pressed once the normalized event value is greater than `0.9`, and rele The following keynames are defined in an internal mapping table: -| Key name | Description | -|-------------------------------|-----------------------| -| `backspace` | | -| `tab` | | -| `clear` | | -| `enter` | | -| `shift` | | -| `control` | | -| `alt` | | -| `capslock` | | -| `escape` | | -| `space`, | | -| `pageup`, `pagedown` | | -| `end` | | -| `home` | | -| `pause` | | -| `numlock` | | -| `scrolllock` | | -| `insert` | | -| `delete` | | -| `printscreen` | | -| `up`, `down`, `left`, `right` | | -| `select` | | -| `print` | | -| `execute` | | -| `help` | | -| `apps` | | -| `sleep` | | -| `num0` - `num9` | | -| `multiply` | | -| `plus` | | -| `comma` | | -| `minus` | | -| `dot` | | -| `divide` | | -| `f1` - `f24` | | -| `lwin`, `rwin` | | -| `lshift`, `rshift` | | -| `lctrl, `rctrl` | | -| `lmenu`, `rmenu` | | -| `previous`, `next` | Browser controls | -| `refresh` | Browser controls | -| `stop` | Browser controls | -| `search` | Browser controls | -| `favorites` | Browser controls | -| `homepage` | Browser controls | -| `mute` | | -| `voldown`, `volup` | | -| `nexttrack`, `prevtrack` | | -| `stopmedia`, `togglemedia` | | -| `mediaselect` | | -| `mail` | | -| `app1`, `app2` | | -| `zoom` | | +| Key name | Description | Key name | Description | +|-------------------------------|-----------------------|-------------------------------|-----------------------| +| `backspace` | | `tab` | | +| `clear` | | `enter` | | +| `shift` | | `control` | | +| `alt` | | `capslock` | | +| `escape` | | `space` | | +| `pageup`, `pagedown` | | `end` | | +| `home` | | `pause` | | +| `numlock` | | `scrolllock` | | +| `insert` | | `delete` | | +| `printscreen` | | `up`, `down`, `left`, `right` | | +| `select` | | `print` | | +| `execute` | | `help` | | +| `apps` | | `sleep` | | +| `num0` - `num9` | | `multiply` | | +| `plus` | | `comma` | | +| `minus` | | `dot` | | +| `divide` | | `f1` - `f24` | | +| `lwin`, `rwin` | | `lshift`, `rshift` | | +| `lctrl, `rctrl` | | `lmenu`, `rmenu` | | +| `previous`, `next` | Browser controls | `refresh` | Browser controls | +| `stop` | Browser controls | `search` | Browser controls | +| `favorites` | Browser controls | `homepage` | Browser controls | +| `mute` | | `voldown`, `volup` | | +| `nexttrack`, `prevtrack` | | `stopmedia`, `togglemedia` | | +| `mediaselect` | | `mail` | | +| `app1`, `app2` | | `zoom` | | Example mappings: ``` @@ -108,7 +82,7 @@ input.X > wi1.key.escape Keyboard and mouse input is subject to UIPI. You can not send input to applications that run at a higher privilege level than the MIDIMonster. -Some antivirus applications may detect this backend as problematic file, because it uses the same system +Some antivirus applications may detect this backend as problematic because it uses the same system interfaces to read keyboard and mouse input as any malicious application would. While it is definitely possible to configure the MIDIMonster to do malicious things, the code itself does not log anything. You can verify this by reading the backend code yourself. -- cgit v1.2.3 From eabdc18aa2209f3526d1068510991ce7f17a4fe6 Mon Sep 17 00:00:00 2001 From: cbdev Date: Mon, 4 May 2020 20:25:00 +0200 Subject: Implement wininput input direction --- backends/wininput.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index 6455dd1..6ead158 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -61,7 +61,7 @@ The following keynames are defined in an internal mapping table: | `minus` | | `dot` | | | `divide` | | `f1` - `f24` | | | `lwin`, `rwin` | | `lshift`, `rshift` | | -| `lctrl, `rctrl` | | `lmenu`, `rmenu` | | +| `lctrl`, `rctrl` | | `lmenu`, `rmenu` | | | `previous`, `next` | Browser controls | `refresh` | Browser controls | | `stop` | Browser controls | `search` | Browser controls | | `favorites` | Browser controls | `homepage` | Browser controls | @@ -82,6 +82,10 @@ input.X > wi1.key.escape Keyboard and mouse input is subject to UIPI. You can not send input to applications that run at a higher privilege level than the MIDIMonster. +Due to inconsistencies in the Windows API, mouse position input and output may differ for the same cursor location. +This may be correlated with the use and arrangement of multi-monitor desktops. If you encounter problems with either +receiving or sending mouse positions, please include a description of your monitor alignment in the issue. + Some antivirus applications may detect this backend as problematic because it uses the same system interfaces to read keyboard and mouse input as any malicious application would. While it is definitely possible to configure the MIDIMonster to do malicious things, the code itself does not log anything. -- cgit v1.2.3 From 5e4c3fe5a81f548243aab01a42973333b559004f Mon Sep 17 00:00:00 2001 From: cbdev Date: Thu, 11 Jun 2020 12:27:57 +0200 Subject: Query joystick buttons --- backends/wininput.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index 6ead158..6e665bb 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -79,8 +79,11 @@ input.X > wi1.key.escape #### Known bugs / problems +Joysticks can only be used as input to the MIDIMonster, as Windows does not provide a method to emulate +Joystick input from user space. This is unlikely to change. + Keyboard and mouse input is subject to UIPI. You can not send input to applications that run at a higher -privilege level than the MIDIMonster. +privilege level than the MIDIMonster. This limitation is by design and will not change. Due to inconsistencies in the Windows API, mouse position input and output may differ for the same cursor location. This may be correlated with the use and arrangement of multi-monitor desktops. If you encounter problems with either -- cgit v1.2.3 From 7b3245de94d5e9453ec1f817aa810f6bd3e64c28 Mon Sep 17 00:00:00 2001 From: cbdev Date: Sat, 13 Jun 2020 10:32:43 +0200 Subject: Implement joystick axis input --- backends/wininput.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index 6e665bb..bcf6a1b 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -77,6 +77,33 @@ input.a > wi1.key.a input.X > wi1.key.escape ``` +Joystick and gamepad controllers with up to 32 buttons and 6 axes plus POV hat can be mapped as inputs to the +MIDIMonster. When starting up, the MIDIMonster will output a list of all connected and usable game controllers. + +Controllers can be mapped using the syntax + +* `joy.` for axes, where `` is the ID of the controller and `` is one of + * `x`, `y`: Main joystick / analog controller axes + * `z`: Third axis / joystick rotation + * `r`: Fourth axis / Rudder controller / Slider + * `u`, `v`: non-specific fifth/sixth axis +* `joy.button` for buttons, with `` again being the controller ID and `b` being the button number between + 1 and 32 (the maximum supported by Windows) + +Use the Windows game controller input calibration and configuration tool to identify the axes and button IDs +relevant to your controller. + +For button channels, the channel value will either be `0` or `1.0`, for axis channels it will be the normalized +value of the axis (with calibration offsets applied), with the exception of the POV axis, where the channel value +will be in some way correlated with the direction of view. + +Example mappings: +``` +input.joy1.x > movinghead.pan +input.joy1.y > movinghead.tilt +input.joy1.button1 > movinghead.dim +``` + #### Known bugs / problems Joysticks can only be used as input to the MIDIMonster, as Windows does not provide a method to emulate -- cgit v1.2.3 From e131992bbe0893a3e5b79cf9423830ea90b4a4d7 Mon Sep 17 00:00:00 2001 From: cbdev Date: Tue, 18 Aug 2020 06:37:01 +0200 Subject: Implement wininput mouse wheel control (Fixes #65) --- backends/wininput.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index bcf6a1b..87e9321 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -11,6 +11,12 @@ access (as is available under Linux) is possible. This backend does not take any global configuration. +| Option | Example value | Default value | Description | +|---------------|-----------------------|-----------------------|---------------------------------------| +| `interval` | `100` | `50` | Data polling interval in milliseconds. Lower intervals lead to higher CPU load. This value should normally not be changed. | +| `wheel` | `4000 2000` | `65535 0` | Mouse wheel range and optional initial value. To invert the mouse wheel control, specify the range as a negative integer. As the mouse wheel is a relative control, we need to specify a range incoming absolute values are mapped to. This can be used control the wheel resolution and travel size. | +| `wheeldelta` | `20` | `1` | Multiplier for wheel travel | + #### Instance configuration This backend does not take any instance-specific configuration. @@ -30,6 +36,11 @@ as well as one channel per mouse button * `mouse.xmb1`: Extra mouse button 1 * `mouse.xmb2`: Extra mouse button 2 +The (vertical) mouse wheel can be controlled from the MIDIMonster using the `mouse.wheel` channel, but it can not be used +as an input channel due to limitations in the Windows API. All instances share one wheel control (see the section on known +bugs below). The mouse wheel sensitivity can be controlled by adjusting the absolute travel range, its initial value and +a wheel delta multiplier. + All keys that have an [assigned virtual keycode](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) are mappable as MIDIMonster channels using the syntax `key.`, with *keyname* being one of the following specifiers: @@ -120,3 +131,7 @@ Some antivirus applications may detect this backend as problematic because it us interfaces to read keyboard and mouse input as any malicious application would. While it is definitely possible to configure the MIDIMonster to do malicious things, the code itself does not log anything. You can verify this by reading the backend code yourself. + +Since the Windows input system merges all keyboard/mouse input data into one data stream, using multiple +instances of this backend is not necessary or useful. It is still supported for technical reasons. +There may be unexpected side effects when mapping the mouse wheel in multiple instances. -- cgit v1.2.3 From 436bcf59c7dcf4acf42f5f812d0e6c4839326757 Mon Sep 17 00:00:00 2001 From: cbdev Date: Tue, 18 Aug 2020 06:40:01 +0200 Subject: Update wininput documentation --- backends/wininput.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index 87e9321..bffa000 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -9,8 +9,6 @@ access (as is available under Linux) is possible. #### Global configuration -This backend does not take any global configuration. - | Option | Example value | Default value | Description | |---------------|-----------------------|-----------------------|---------------------------------------| | `interval` | `100` | `50` | Data polling interval in milliseconds. Lower intervals lead to higher CPU load. This value should normally not be changed. | -- cgit v1.2.3 From dc7303cc07565a725eec19aeff46f64ad4275c21 Mon Sep 17 00:00:00 2001 From: cbdev Date: Wed, 19 Aug 2020 12:46:31 +0200 Subject: wininput sanity check and minor documentation update --- backends/wininput.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'backends/wininput.md') diff --git a/backends/wininput.md b/backends/wininput.md index bffa000..797d879 100644 --- a/backends/wininput.md +++ b/backends/wininput.md @@ -12,7 +12,7 @@ access (as is available under Linux) is possible. | Option | Example value | Default value | Description | |---------------|-----------------------|-----------------------|---------------------------------------| | `interval` | `100` | `50` | Data polling interval in milliseconds. Lower intervals lead to higher CPU load. This value should normally not be changed. | -| `wheel` | `4000 2000` | `65535 0` | Mouse wheel range and optional initial value. To invert the mouse wheel control, specify the range as a negative integer. As the mouse wheel is a relative control, we need to specify a range incoming absolute values are mapped to. This can be used control the wheel resolution and travel size. | +| `wheel` | `-4000 2000` | `65535 0` | Mouse wheel range and optional initial value. To invert the mouse wheel control, specify the range as a negative integer. As the mouse wheel is a relative control, we need to specify a range incoming absolute values are mapped to. This can be used control the wheel resolution and travel size. | | `wheeldelta` | `20` | `1` | Multiplier for wheel travel | #### Instance configuration @@ -35,11 +35,11 @@ as well as one channel per mouse button * `mouse.xmb2`: Extra mouse button 2 The (vertical) mouse wheel can be controlled from the MIDIMonster using the `mouse.wheel` channel, but it can not be used -as an input channel due to limitations in the Windows API. All instances share one wheel control (see the section on known +as an input channel due to limitations in the Windows API. All instances share one `wheel` control (see the section on known bugs below). The mouse wheel sensitivity can be controlled by adjusting the absolute travel range, its initial value and a wheel delta multiplier. -All keys that have an [assigned virtual keycode](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) +All keyboard keys that have an [assigned virtual keycode](https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) are mappable as MIDIMonster channels using the syntax `key.`, with *keyname* being one of the following specifiers: * One of the keynames listed below (e.g., `key.enter`) -- cgit v1.2.3