padrelay 1.0.0__tar.gz

padrelay-1.0.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog],
+and this project adheres to [Semantic Versioning].
+
+## [1.0.0] - 2025-06-14
+
+- initial release
+
+<!-- Links -->
+[keep a changelog]: https://keepachangelog.com/en/1.0.0/
+[semantic versioning]: https://semver.org/spec/v2.0.0.html
+
+<!-- Versions -->
+[1.0.0]: https://github.com/ssh-den/PadRelay/releases/tag/v1.0.0

padrelay-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Den
+
+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.

padrelay-1.0.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include requirements.txt
+include pyproject.toml
+include CHANGELOG.md
+recursive-include config *.ini
+recursive-include src *.py
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo

padrelay-1.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: padrelay
+Version: 1.0.0
+Summary: A client-server application for transmitting gamepad input over a network
+Author-email: ssh-den <sshden@duck.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ssh-den/PadRelay
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame
+Provides-Extra: server
+Requires-Dist: vgamepad; extra == "server"
+Dynamic: license-file
+
+# PadRelay
+
+**PadRelay** forwards gamepad input from a local machine to a Windows PC where a virtual controller is created using the `vgamepad` library.  The client captures input with `pygame` and the server emulates either an Xbox 360 or DualShock 4 gamepad.
+
+## Features
+
+- Works with Python 3.6+ on any system with `pygame` for the client
+- Windows server with [ViGEmBus](https://github.com/ViGEm/ViGEmBus) installs a virtual gamepad
+- Supports TCP (reliable) or UDP (low latency) transport
+- Challenge/response authentication for TCP and token authentication for UDP
+- Heartbeat and rate limiting to keep connections healthy
+- Configurable block duration and higher defaults for UDP to avoid false limits
+- Automatic reconnection if the server disconnects
+
+## Installation
+
+Clone the repository and install the Python requirements if you want to run the
+scripts directly from source:
+
+```bash
+pip install -r requirements.txt
+```
+
+After installing the dependencies, you can run the applications directly from source with: `python scripts/server.py` and
+`python scripts/client.py`.
+
+Alternatively install the package in editable mode to make the console commands
+available:
+
+```bash
+pip install -e .
+```
+
+This will expose `padrelay-server` and `padrelay-client` on your `PATH`. When the
+project will be published on PyPI you may also install it with `pip install
+padrelay`.
+
+When running the server on Windows install `vgamepad` and
+[ViGEmBus](https://github.com/ViGEm/ViGEmBus) as well.
+
+## Configuration
+
+Example INI files live in the `config/` directory.  A trimmed server configuration looks like:
+For a detailed explanation of every setting see [the full configuration reference](src/core/CONFIGURATION.md).
+
+```ini
+[server]
+host = 127.0.0.1
+port = 9999
+protocol = tcp
+password = your_secure_password
+rate_limit_window = 60
+max_requests = 100
+block_duration = 2
+```
+
+On first run the server will replace any plaintext `password` value with a
+PBKDF2 hash string so the file no longer contains the original secret.  Use the
+`PASSWORD` or `PASSWORD_HASH` environment variable to override the value without
+modifying the configuration file. When the password is stored as a hash the
+server automatically includes the hash parameters in its authentication
+challenge so clients using the original plaintext password continue to work.
+
+```ini
+[vgamepad]
+type = xbox360
+```
+
+and a matching client configuration:
+
+```ini
+[network]
+server_ip = 192.168.1.100
+server_port = 9999
+protocol = tcp
+password = your_secure_password
+
+[joystick]
+index = 0
+
+[client]
+update_rate = 60
+```
+
+## Usage
+
+If you installed the project with `pip install -e .` or from PyPI you can use
+the `padrelay-server` and `padrelay-client` commands. When running directly from
+source replace them with `python scripts/server.py` and
+`python scripts/client.py`.
+
+Start the server with your configuration:
+
+```bash
+padrelay-server --config config/server_config.ini
+```
+
+Then start the client and point it at the server:
+
+```bash
+padrelay-client --config config/client_config.ini
+```
+
+Both scripts accept command line flags (see `--help`) and load values from the configuration files if provided.
+The server also checks the `PASSWORD` or `PASSWORD_HASH` environment variables
+which override any configured value at runtime. Clients may specify a
+`--password-hash` argument, a `[network] password_hash` setting, or the
+`PASSWORD_HASH` environment variable when using UDP so the secret never needs to
+be stored in plaintext.
+
+When a client only has the plaintext password for UDP, it will automatically
+send an `auth_params_request` when connecting. Servers that store only a hashed
+password reply with their salt and iteration count so the client can derive the
+same key and authenticate using time‑based tokens. Servers using a plaintext
+password simply ignore the request and the client continues with the plaintext
+key.
+
+## Testing
+
+To run the unit tests:
+
+```bash
+pytest
+
+## Logging
+
+All components write logs to a single file in the `logs` directory at the project
+root by default. The directory will be created automatically if it does not
+exist. Set the ``PADRELAY_LOG_DIR`` environment variable to override this
+location. Logs are rotated automatically and never include passwords or tokens.
+
+## Disclaimer
+
+**Security Notice**
+
+PadRelay does **not** implement TLS or any built-in encryption. It is intended for use on **trusted, private networks** only.  
+You should always secure communication via a **VPN, SSH tunnel**, or other private channel. **Never expose the server directly to the public internet.**
+
+Use this software **at your own risk**. The author assumes no responsibility for data loss, damage, or security issues resulting from its use.
+
+**Bug Reports**
+
+This project is under active development. If you encounter any issues, misbehavior, or unexpected crashes, please open an issue on GitHub with steps to reproduce.  
+Contributions and pull requests are always welcome.

padrelay-1.0.0/README.md

@@ -0,0 +1,144 @@
+# PadRelay
+
+**PadRelay** forwards gamepad input from a local machine to a Windows PC where a virtual controller is created using the `vgamepad` library.  The client captures input with `pygame` and the server emulates either an Xbox 360 or DualShock 4 gamepad.
+
+## Features
+
+- Works with Python 3.6+ on any system with `pygame` for the client
+- Windows server with [ViGEmBus](https://github.com/ViGEm/ViGEmBus) installs a virtual gamepad
+- Supports TCP (reliable) or UDP (low latency) transport
+- Challenge/response authentication for TCP and token authentication for UDP
+- Heartbeat and rate limiting to keep connections healthy
+- Configurable block duration and higher defaults for UDP to avoid false limits
+- Automatic reconnection if the server disconnects
+
+## Installation
+
+Clone the repository and install the Python requirements if you want to run the
+scripts directly from source:
+
+```bash
+pip install -r requirements.txt
+```
+
+After installing the dependencies, you can run the applications directly from source with: `python scripts/server.py` and
+`python scripts/client.py`.
+
+Alternatively install the package in editable mode to make the console commands
+available:
+
+```bash
+pip install -e .
+```
+
+This will expose `padrelay-server` and `padrelay-client` on your `PATH`. When the
+project will be published on PyPI you may also install it with `pip install
+padrelay`.
+
+When running the server on Windows install `vgamepad` and
+[ViGEmBus](https://github.com/ViGEm/ViGEmBus) as well.
+
+## Configuration
+
+Example INI files live in the `config/` directory.  A trimmed server configuration looks like:
+For a detailed explanation of every setting see [the full configuration reference](src/core/CONFIGURATION.md).
+
+```ini
+[server]
+host = 127.0.0.1
+port = 9999
+protocol = tcp
+password = your_secure_password
+rate_limit_window = 60
+max_requests = 100
+block_duration = 2
+```
+
+On first run the server will replace any plaintext `password` value with a
+PBKDF2 hash string so the file no longer contains the original secret.  Use the
+`PASSWORD` or `PASSWORD_HASH` environment variable to override the value without
+modifying the configuration file. When the password is stored as a hash the
+server automatically includes the hash parameters in its authentication
+challenge so clients using the original plaintext password continue to work.
+
+```ini
+[vgamepad]
+type = xbox360
+```
+
+and a matching client configuration:
+
+```ini
+[network]
+server_ip = 192.168.1.100
+server_port = 9999
+protocol = tcp
+password = your_secure_password
+
+[joystick]
+index = 0
+
+[client]
+update_rate = 60
+```
+
+## Usage
+
+If you installed the project with `pip install -e .` or from PyPI you can use
+the `padrelay-server` and `padrelay-client` commands. When running directly from
+source replace them with `python scripts/server.py` and
+`python scripts/client.py`.
+
+Start the server with your configuration:
+
+```bash
+padrelay-server --config config/server_config.ini
+```
+
+Then start the client and point it at the server:
+
+```bash
+padrelay-client --config config/client_config.ini
+```
+
+Both scripts accept command line flags (see `--help`) and load values from the configuration files if provided.
+The server also checks the `PASSWORD` or `PASSWORD_HASH` environment variables
+which override any configured value at runtime. Clients may specify a
+`--password-hash` argument, a `[network] password_hash` setting, or the
+`PASSWORD_HASH` environment variable when using UDP so the secret never needs to
+be stored in plaintext.
+
+When a client only has the plaintext password for UDP, it will automatically
+send an `auth_params_request` when connecting. Servers that store only a hashed
+password reply with their salt and iteration count so the client can derive the
+same key and authenticate using time‑based tokens. Servers using a plaintext
+password simply ignore the request and the client continues with the plaintext
+key.
+
+## Testing
+
+To run the unit tests:
+
+```bash
+pytest
+
+## Logging
+
+All components write logs to a single file in the `logs` directory at the project
+root by default. The directory will be created automatically if it does not
+exist. Set the ``PADRELAY_LOG_DIR`` environment variable to override this
+location. Logs are rotated automatically and never include passwords or tokens.
+
+## Disclaimer
+
+**Security Notice**
+
+PadRelay does **not** implement TLS or any built-in encryption. It is intended for use on **trusted, private networks** only.  
+You should always secure communication via a **VPN, SSH tunnel**, or other private channel. **Never expose the server directly to the public internet.**
+
+Use this software **at your own risk**. The author assumes no responsibility for data loss, damage, or security issues resulting from its use.
+
+**Bug Reports**
+
+This project is under active development. If you encounter any issues, misbehavior, or unexpected crashes, please open an issue on GitHub with steps to reproduce.  
+Contributions and pull requests are always welcome.

padrelay-1.0.0/config/client_config.ini

@@ -0,0 +1,11 @@
+[network]
+server_ip = 172.26.8.240
+server_port = 9999
+protocol = udp
+password = 1234
+
+[joystick]
+index = 0
+
+[client]
+update_rate = 60

padrelay-1.0.0/config/server_config.ini

@@ -0,0 +1,42 @@
+[server]
+host = 127.0.0.1
+port = 9999
+protocol = tcp
+password = your_secure_password
+rate_limit_window = 60
+max_requests = 100
+block_duration = 2
+
+[vgamepad]
+type = xbox360
+
+[button_mapping_xbox360]
+0 = XUSB_GAMEPAD_A
+1 = XUSB_GAMEPAD_B
+2 = XUSB_GAMEPAD_X
+3 = XUSB_GAMEPAD_Y
+4 = XUSB_GAMEPAD_LEFT_SHOULDER
+5 = XUSB_GAMEPAD_RIGHT_SHOULDER
+6 = XUSB_GAMEPAD_BACK
+7 = XUSB_GAMEPAD_START
+8 = XUSB_GAMEPAD_LEFT_THUMB
+9 = XUSB_GAMEPAD_RIGHT_THUMB
+10 = XUSB_GAMEPAD_DPAD_UP
+11 = XUSB_GAMEPAD_DPAD_DOWN
+12 = XUSB_GAMEPAD_DPAD_LEFT
+13 = XUSB_GAMEPAD_DPAD_RIGHT
+14 = XUSB_GAMEPAD_GUIDE
+
+[axis_mapping]
+left_stick_x = 0
+left_stick_y = 1
+right_stick_x = 2
+right_stick_y = 3
+trigger_left = 4
+trigger_right = 5
+
+[axis_options]
+dead_zone = 0.1
+trigger_threshold = 0.1
+invert_left_y = false
+invert_right_y = false

padrelay-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "padrelay"
+version = "1.0.0"
+description = "A client-server application for transmitting gamepad input over a network"
+readme = "README.md"
+authors = [{ name = "ssh-den", email = "sshden@duck.com" }]
+license = "MIT"
+requires-python = ">=3.6"
+dependencies = ["pygame"]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.6",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Topic :: Games/Entertainment"
+]
+
+[project.optional-dependencies]
+server = ["vgamepad"]
+
+[project.scripts]
+padrelay-client = "padrelay.scripts.client:main"
+padrelay-server = "padrelay.scripts.server:main"
+
+[project.urls]
+Homepage = "https://github.com/ssh-den/PadRelay"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]

padrelay-1.0.0/requirements.txt

@@ -0,0 +1,10 @@
+# Core dependencies
+pygame==2.6.1
+
+# Windows-only dependency for emulating a gamepad (client or server)
+vgamepad==0.1.0; platform_system=="Windows"
+
+# Testing dependencies
+pytest==8.4.0
+pytest-asyncio==1.0.0
+

padrelay-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

padrelay-1.0.0/src/padrelay/__init__.py

@@ -0,0 +1,3 @@
+"""
+PadRelay - A client-server application for transmitting gamepad input over a network
+"""

padrelay-1.0.0/src/padrelay/client/__init__.py

@@ -0,0 +1 @@
+"""Client-side utilities for the PadRelay"""