partial linux support

README.md

@@ -1,12 +1,21 @@
 # Virtual Gamepad
-Virtual XBox360 and DualShock4 gamepads in python
+Virtual XBox360 and DualShock4 gamepads in python.
 
 ---
 
 Virtual Gamepad (```vgamepad```) is a small python library that emulates XBox360 and DualShock4 gamepads on your system.
 It enables controlling e.g. a video-game that requires analog input, directly from your python script.
 
-Under the hood, ```vgamepad``` uses the [ViGEm](https://github.com/ViGEm) C++ framework on Windows, for which it essentially provides python bindings and a user-friendly interface. On Linux, we use `libevdev` directly instead.
+On Windows ```vgamepad``` uses the [ViGEm](https://github.com/ViGEm) C++ framework, for which it essentially provides python bindings and a user-friendly interface.
+
+---
+
+__Status:__
+
+|     Windows     |                      Linux                       |
+|:---------------:|:------------------------------------------------:|
+| *Full support.* | *Alpha,*<br/>see [Linux notes](readme/linux.md). |
+
 
 ## Quick links
 - [Installation](#installation)
@@ -19,15 +28,22 @@ Under the hood, ```vgamepad``` uses the [ViGEm](https://github.com/ViGEm) C++ fr
 ---
 
 ## Installation
+
+### Windows:
 Open your favorite terminal (e.g. anaconda prompt) and run:
 ```bash
 pip install vgamepad
 ```
-This automatically runs the installer of the ViGEmBus driver on Windows.
+
+This automatically runs the installer of the ViGEmBus driver.
 Accept the licence agreement, click ```Install```, allow the installer to modify you PC, wait for completion and click ```Finish```.
 
 ```vgamepad``` is now installed in your active python environment.
 
+### Linux:
+
+See [Linux notes](readme/linux.md).
+
 ---
 
 ## Getting started
@@ -224,7 +240,7 @@ class DS4_SPECIAL_BUTTONS(IntFlag):
     DualShock 4 special buttons
     """
     DS4_SPECIAL_BUTTON_PS = 1 << 0
-    DS4_SPECIAL_BUTTON_TOUCHPAD = 1 << 1
+    DS4_SPECIAL_BUTTON_TOUCHPAD = 1 << 1  # Windows only, no effect on Linux
 ```
 
 Triggers and joysticks (integer values):
@@ -247,7 +263,7 @@ gamepad.right_joystick_float(x_value_float=-1.0, y_value_float=0.8)  # values be
 gamepad.update()
 ```
 
-* **Note:** The Y axis on joysticks is inverted for consistency with the X360 API.
+* **Note:** Since version `0.1.0`, the DS4 Y axis on joysticks is inverted compared to the X360 API (native VIGEm behavior).
 
 Directional pad (hat):
 ```python
@@ -330,9 +346,9 @@ time.sleep(1.0)
 
 ### Rumble and LEDs:
 
-`vgamepad` enables registering custom callback functions to handle updates of the rumble motors, and of the LED ring.
+_**Note**: Rumble and LEDs are supported on Windows only (not yet ported to Linux)._
 
-**Note**: The callback functionality has not yet been ported to Linux.
+`vgamepad` enables registering custom callback functions to handle updates of the rumble motors, and of the LED ring.
 
 Custom callback functions require 6 parameters:
 ```python

readme/linux.md

@@ -0,0 +1,55 @@
+# Linux
+
+`vgamepad` is now partly supported on Linux.
+
+Contrary to Windows, support for Linux is experimental and subject to future breaking changes.
+If your python project for Linux relies on `vgamepad`, please use the exact `vgamepad` version you are relying on in your project dependencies.
+
+## Differences with Windows
+On Windows, `vgamepad` is currently a wrapper around Nefarius' [Virtual Gamepad Emulation](https://github.com/nefarius/ViGEmBus) framework.
+As such, it emulates true physical DS4 and X360 gamepads.
+
+On Linux, `vgamepad` currently relies on `libevdev`.
+It emulates a subset of the X360 and DS4 capabilities in `evdev` by managing a virtual `uinput` device.
+
+While we are trying to make this emulation close to the real thing, we are not quite there yet.
+If you know how to advance toward this goal, your contribution would be **very appreciated** :heart_eyes:
+
+For now, most basic `vgamepad` calls work on Linux, but you shouldn't expect your app to react exactly as if an actual X360 / DS4 gamepad were connected to your machine.
+However, the corresponding `evdev` event should be similar.
+
+**What you should know:**
+- Detected buttons, ordering and axes directions are typically different from Windows (depending on your app)
+- Force feedback / LEDS are not implemented on Linux yet
+- DS4 touchpad / motion sensor are not implemented on Linux yet (no extended report)
+- Real DS4s fire a button event when you press the triggers (on top of the axis event), this button event is not implemented in `vgamepad` at the moment
+
+## Installation
+
+### Prerequisite
+
+On Linux, `vgamepad` needs access to `uinput`.
+
+To give yourself permission to access `uinput` for the current session, open a terminal and execute:
+```bash
+sudo chmod +0666 /dev/uinput
+```
+
+Create a `udev` rule to set the permission permanently (otherwise the permission will be removed next time you log in):
+```bash
+sudo nano /etc/udev/rules.d/50-uinput.rules 
+```
+In `nano`, paste the following line:
+```bash
+KERNEL=="uinput", TAG+="uaccess"
+```
+Save by pressing `CTRL+o`, `ENTER`, and exit `nano` by pressing `CTRL+x`
+
+#### vgamepad installation
+
+Run:
+```bash
+pip install vgamepad
+```
+
+```vgamepad``` is now installed in your active python environment.

setup.py

@@ -5,6 +5,10 @@
 import sys
 import warnings
 
+
+assert platform.system() in ('Windows', 'Linux'), "vgamepad is only supported on Windows and Linux."
+
+
 VIGEMBUS_VERSION = "1.17.333.0"
 
 archstr = platform.machine()
@@ -66,7 +70,7 @@
     url='https://github.com/yannbouteiller/vgamepad',
     download_url='https://github.com/yannbouteiller/vgamepad/archive/refs/tags/v0.1.0.tar.gz',
     keywords=['virtual', 'gamepad', 'python', 'xbox', 'dualshock', 'controller', 'emulator'],
-    install_requires=['libevdev~=0.11'] if is_windows is False else [],
+    install_requires=['libevdev~=0.11'] if not is_windows else [],
     classifiers=[
         'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',