Merge pull request #1 from quantumsnowball/dev

Dev

.gitignore

@@ -0,0 +1,6 @@
+.python-version
+pyrightconfig.json
+__pycache__/
+waylandmap.egg-info/
+build/
+dist/

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Quantum Snowball
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,102 @@
+# WaylandMap
+
+I started to code this program because I want to use RightAlt + hjkl as system-wide arrow keys. Everyone has been using `xmodmap` to remap keys on linux. However, after switching to Wayland window system, `xmodmap` stopped working. I started to look for ready-to-use solution but with no luck. Probably Wayland are still too new for the community to catch up. Luckly, Google gave me some hints on how to achieve this task. The key is to go to lower level! This module makes use of `evdev` and `uinput` module to achieve keymapping. Therefore it should work on any Desktop, such as X11 or Wayland.
+
+## Install
+Simply install using `pip` and run it as a cli application:
+```
+pip install waylandmap
+```
+It is recommended to install the package to its own virtual environment, especially when installed as a linux system service. For example, install using `pipx`:
+```
+pipx install waylandmap
+```
+
+## Usage
+Your can run the keymapper directly by supplying the name of keyboard and the keymap file.
+```bash
+sudo waylandmap -n <name-of-your-keyboard> <path/to/config.yml>
+```
+You can see the key event inputs and outputs printed out in real time by running in debug mode. You can also check the string name required by the config file.
+```bash
+sudo waylandmap --debug -n <name-of-your-keyboard> <path/to/config.yml>
+```
+
+## Configuration
+The program accept a config file path as argument. The config file should be in yaml format.
+```yaml
+# keymaps.yaml
+
+# simply swap two single key (to be implemented)
+- type: swap
+  target1: KEY_CAPSLOCK
+  target2: KEY_ESC
+# map one single key with another (to be implemented)
+- type: map
+  source: KEY_LEFTALT
+  target: KEY_LEFTCTRL
+# map 2-keys-chord into a new key
+# # RightAlt + hjkl to arrows
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_H
+  target: KEY_LEFT
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_J
+  target: KEY_DOWN
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_K
+  target: KEY_UP
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_L
+  target: KEY_RIGHT
+# # remap home + pgdn + pgup + end
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_N
+  target: KEY_HOME
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_M
+  target: KEY_PAGEDOWN
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_COMMA
+  target: KEY_PAGEUP
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_DOT
+  target: KEY_END
+# # remap backspace + delete
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_Y
+  target: KEY_BACKSPACE
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_U
+  target: KEY_BACKSPACE
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_I
+  target: KEY_DELETE
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_O
+  target: KEY_DELETE
+# more key combo options is coming
+
+```
+
+## Install as Linux system services
+
+After writing your config file and test running it without problem, your can install the program as a system services. This should automatically start the keymapper everytime when you login. You may use `systemctl/waylandmap.service` as a template to edit the services file, and then install the service as follows:
+
+```
+sudo cp systemctl/waylandmap.service /etc/systemd/system/
+sudo systemctl enable waylandmap.service
+```
+

defaults/keymaps.yaml

@@ -0,0 +1,61 @@
+# simply swap two single key
+- type: swap
+  target1: KEY_CAPSLOCK
+  target2: KEY_ESC
+# map one single key with another
+- type: map
+  source: KEY_LEFTALT
+  target: KEY_LEFTCTRL
+# map 2-keys-chord into a new key
+# # RightAlt + hjkl to arrows
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_H
+  target: KEY_LEFT
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_J
+  target: KEY_DOWN
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_K
+  target: KEY_UP
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_L
+  target: KEY_RIGHT
+# # remap home + pgdn + pgup + end
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_N
+  target: KEY_HOME
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_M
+  target: KEY_PAGEDOWN
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_COMMA
+  target: KEY_PAGEUP
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_DOT
+  target: KEY_END
+# # remap backspace + delete
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_Y
+  target: KEY_BACKSPACE
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_U
+  target: KEY_BACKSPACE
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_I
+  target: KEY_DELETE
+- type: combo 
+  modifier: KEY_RIGHTALT
+  source: KEY_O
+  target: KEY_DELETE
+# more key combo options is coming

requirements/common.txt

@@ -0,0 +1,4 @@
+evdev
+python-uinput
+click
+pyyaml

requirements/dev.txt

@@ -0,0 +1,6 @@
+evdev
+python-uinput
+click
+pyyaml
+grip
+twine

setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+
+with open('README.md', 'r') as f:
+    long_description = f.read()
+
+setup(
+    name='waylandmap',
+    packages=['waylandmap', ],
+    version='1.0.0',
+    description='A keymapper that works under both X11 or Wayland',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    author='Quantum Snowball',
+    author_email='[email protected]',
+    url='https://github.com/quantumsnowball/waylandmap',
+    keywords=['wayland', 'keymappers', 'evdev', 'python-uinput', ],
+    python_requires='>=3.6',
+    install_requires=['click', 'evdev', 'python-uinput', 'pyyaml' ],
+    entry_points={
+        'console_scripts': [
+            'waylandmap=waylandmap.main:cli',
+        ]
+    }
+)
+

systemctl/waylandmap.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=WaylandMap
+After=multi-user.target
+
+[Service]
+Type=simple
+Restart=always
+ExecStart=/path/to/your/waylandmap -n <your-keyboard-name> /path/to/your/keymaps.yaml
+
+[Install]
+WantedBy=multi-user.target

waylandmap/constants.py

@@ -0,0 +1,34 @@
+import uinput
+
+# {'ITEM_XXX': (0,0)}
+EVENTS_NAME_VALUE_DICT = {
+    k:v for k,v in vars(uinput.ev).items()
+    if k.startswith(('KEY_', 'BTN_', 'REL_', 'ABS_', ))}
+
+# {'KEY_XXX': (0,0)}
+KEYS_NAME_VALUE_DICT = {
+    k:v for k,v in EVENTS_NAME_VALUE_DICT.items()
+    if k.startswith('KEY_')}
+
+# {(0,0), ...}
+KEYS_VALUE_TUPLE = KEYS_NAME_VALUE_DICT.values()
+
+# {(0,0): 'KEY_XXX'}
+KEYS_VALUE_NAME_DICT = {
+    v:k for k,v in KEYS_NAME_VALUE_DICT.items()}
+
+# {'KEY_XXX': 0}
+KEY_NAME_CODE_DICT = {
+    k:v[1] for k,v in KEYS_NAME_VALUE_DICT.items()}
+
+# {0: 'KEY_XXX'}
+KEY_CODE_NAME_DICT = {
+    v:k for k,v in KEY_NAME_CODE_DICT.items()}
+
+def name_to_code(name: str) -> int:
+    code = KEY_NAME_CODE_DICT[name]
+    return code
+
+def code_to_name(code: int) -> str:
+    name = KEY_CODE_NAME_DICT[code]
+    return name

waylandmap/devices.py

@@ -0,0 +1,14 @@
+import evdev
+
+
+def get_devices() -> list:
+    devices = [evdev.InputDevice(dev) for dev in evdev.list_devices()]
+    return devices
+
+def get_device_path(name):
+    for dev in get_devices():
+        if name == dev.name:
+            return dev.path
+    else:
+        raise FileNotFoundError('Failed to look up device name.')
+