Version 1.08 with public source code release.

2026-09-30 02:37:55 +03:00 · 2020-10-03 20:56:55 +02:00
parent 656148121d
commit 762bf140c0
555 changed files with 55502 additions and 3 deletions
@@ -0,0 +1,8 @@
+# Pumptools API
+The *api* sub-folder contains various headers that allow you to develop your own libraries to hook into various places
+inside pumptools.
+
+## IO
+* [PIUBTN](io/piubtn.md): The button board introduced with Pump It Up Pro
+* [PIUIO](io/piuio.md): Also known as the MK6 IO, the main IO board for pads and lights
+* [X11 input hook](io/x11-input-hook.md): Hook input processing to X11 to receive keyboard events
@@ -0,0 +1,58 @@
+# PIUBTN API
+This contains various PIUBTN related tools and libraries. PIUBTN is the button board that was first introduced with
+Pump PRO and officially works as an optional peripheral on all classic pump games starting Fiesta.
+
+## Pumptools PIUBTN API implementations
+The following libraries implement pumptool's PIUBTN API interface. Set the configuration value `patch.piubtn.emu_lib`
+in your hook configuration to point to the library you want to use, e.g.
+`patch.piubtn.emu_lib=./ptapi-io-piubtn-null.so`.
+
+### Null: ptapi-io-piubtn-null.so
+A null implementation for API dummy testing against libraries/applications calling API implementations.
+
+### Real PIUIO: ptapi-io-piubtn-real.so
+Support for a real USB PIUBTN. This library is not useful for games that already support the hardware natively.
+However, games that require an emulation layer need this.
+
+### Joystick/Gamepad: ptapi-io-piubtn-joystick.so
+Support all (USB) Joysticks and Gamepads that are detected by the Linux kernel. This uses the Kernel's joystick API.
+
+Button mappings are configured by using the `ptapi-io-piubtn-joystick-conf` (this is an executable!) tool. You might
+have to `chmod +x ptapi-io-piubtn-joystick-conf` it prior being able to run it: `./ptapi-io-piubtn-joystick-conf`. Run
+the tool and follow the instructions. Once successfully completed, a `piubtn-joystick-conf.bin` configuration file is
+located in the same folder. This must be located next to the `ptapi-io-piubtn-joystick.so` file which should be located
+next to your `piu` executable.
+
+Configure your `hook.conf` file accordingly:
+```
+patch.piubtn.emu_lib=./ptapi-io-piubtn-joystick.so
+```
+
+### Keyboard: ptapi-io-piubtn-keyboard.so
+Support for inputs via your standard keyboard using the X11 API.
+
+Button mappings are configured by using the `ptapi-io-piubtn-keyboard-conf` (this is an executable!) tool. You might
+have to `chmod +x ptapi-io-piubtn-keyboard-conf` it prior being able to run it: `./ptapi-io-piubtn-keyboard-conf`. Run
+the tool and follow the instructions. Once successfully completed, a `piubtn-keyboard-conf.bin` configuration file is
+located in the same folder. This must be located next to the `ptapi-io-piubtn-keyboard.so` file which should be located
+next to your `piu` executable.
+
+Configure your `hook.conf` file accordingly:
+```
+patch.piubtn.emu_lib=./ptapi-io-piubtn-keyboard.so
+patch_hook_main_loop.x11_input_handler=./ptapi-io-piubtn-keyboard.so
+```
+
+Setting the key `patch_hook_main_loop.x11_input_handler` is important. Otherwise, the library does not receive any
+input events from X11 and your configured keyboard input does not work in the game.
+
+## Pumptools PIUBTN API tester: ptapi-io-piubtn-test
+The tool *ptapi-io-piubtn-test* lets you easily test and debug your library implementing pumptool's piubtn API without
+having to setup and/or run any games.
+
+## Development
+The [piubtn header](../../src/api/ptapi/io/piubtn.h) contains all the prototypes to be implemented by your library to
+provide your own implementation for a PIUBTN. Checkout the header file for documentation.
+
+Checkout the [stub implementation](../../dist/api/ptapi-io-piubtn-stub.c) to get started with a simple example.
+Instructions are located in the header comment of the file.
@@ -0,0 +1,57 @@
+# PIUIO API
+This contains various MK6 USB PIUIO related tools and libraries. The hardware was first introduced with Exceed 2 and
+is supported by all games up to this day.
+
+## Pumptools PIUIO API implementations
+The following libraries implement pumptool's PIUIO API interface. Set the configuration value `patch.piuio.emu_lib`
+in your hook configuration to point to the library you want to use, e.g. `patch.piuio.emu_lib=./ptapi-io-piuio-null.so`.
+
+### Null: ptapi-io-piuio-null.so
+A null implementation for API dummy testing against libraries/applications calling API implementations.
+
+### Real PIUIO: ptapi-io-piuio-real.so
+Support for a real USB PIUIO. This library is not useful for games that already support the hardware natively.
+However, games that require an emulation layer need this to run on real PIUIO hardware, e.g. Exceed (1).
+
+### Joystick/Gamepad: ptapi-io-piuio-joystick.so
+Support all (USB) Joysticks and Gamepads that are detected by the Linux kernel. This uses the Kernel's joystick API.
+
+Button mappings are configured by using the `ptapi-io-piuio-joystick-conf` (this is an executable!) tool. You might have
+to `chmod +x ptapi-io-piuio-joystick-conf` it prior being able to run it: `./ptapi-io-piuio-joystick-conf`. Run the tool
+and follow the instructions. Once successfully completed, a `piuio-joystick-conf.bin` configuration file is located in
+the same folder. This must be located next to the `ptapi-io-piuio-joystick.so` file which should be located next to your
+`piu` executable.
+
+Configure your `hook.conf` file accordingly:
+```
+patch.piuio.emu_lib=./ptapi-io-piuio-joystick.so
+```
+
+### Keyboard: ptapi-io-piuio-keyboard.so
+Support for inputs via your standard keyboard using the X11 API.
+
+Button mappings are configured by using the `ptapi-io-piuio-keyboard-conf` (this is an executable!) tool. You might have
+to `chmod +x ptapi-io-piuio-keyboard-conf` it prior being able to run it: `./ptapi-io-piuio-keyboard-conf`. Run the tool
+and follow the instructions. Once successfully completed, a `piuio-keyboard-conf.bin` configuration file is located in
+the same folder. This must be located next to the `ptapi-io-piuio-keyboard.so` file which should be located next to your
+`piu` executable.
+
+Configure your `hook.conf` file accordingly:
+```
+patch.piuio.emu_lib=./ptapi-io-piuio-keyboard.so
+patch_hook_main_loop.x11_input_handler=./ptapi-io-piuio-keyboard.so
+```
+
+Setting the key `patch_hook_main_loop.x11_input_handler` is important. Otherwise, the library does not receive any
+input events from X11 and your configured keyboard input does not work in the game.
+
+## Pumptools PIUIO API tester: ptapi-io-piuio-test
+The tool *ptapi-io-piuio-test* lets you easily test and debug your library implementing pumptool's piuio API without
+having to setup and/or run any games.
+
+## Development
+The [piuio header](../../src/api/ptapi/io/piuio.h) contains all the prototypes to be implemented by your library to
+provide your own implementation for a PIUIO. Checkout the header file for documentation.
+
+Checkout the [stub implementation](../../dist/api/ptapi-io-piuio-stub.c) to get started with a simple example.
+Instructions are located in the header comment of the file.
@@ -0,0 +1,9 @@
+# X11 input hook API
+The [x11-input-hook header](../../src/api/ptapi/io/x11-input-hook.h) allows you to hook into the main loop of the game
+to receive X11 keyboard inputs. This might be useful for implementations of other APIs, e.g. PIUIO, to trigger PIUIO
+inputs when pressing keys on the keyboard.
+
+You have to configure your `hook.conf` accordingly that your implementation gets loaded by the hook library:
+```
+patch_hook_main_loop.x11_input_handler=./ptapi-io-my-x11-input-hook.so
+```