git.oblomov.eu Git - wiimote-pad/blob - README.md

   1 # Wiimote-Pad
   2
   3 This is a small tool to use a Wiimote as a gamepad.
   4
   5 ## Introduction
   6
   7 Linux has had built-in support for the Wii Remote (Wiimote for short)
   8 since v3.1, support which was significantly cleaned up and improved
   9 since v3.11. However, the low-level kernel driver exposes each component
  10 of the Wiimote (accelerator, buttons, IR camera), as well as each
  11 extension, as a distinct device, none of which is (fully) functional as
  12 a controller ‘out of the box’ (the ‘buttons’ device —which the driver
  13 calls the controller ‘proper’— does appear as a joystick device to
  14 Linux, since it has a BTN\_A mapping, but it's a device with no axes and
  15 thus not really usable).
  16
  17 A higher level interface (built on top of the Linux driver) is provided
  18 by [xwiimote][], which provides a library for ‘coalesced’ access to the
  19 Wiimote and its extension. As programs need to be designed specifically
  20 to make use of the library, this still doesn't allow an ‘out of the box’
  21 experience.
  22
  23 The purpose of this tool is to allow any application to use a Wiimote
  24 —held sideways— as if it were a standard gamepad, with a 2-axes joystick
  25 (using the accelerometer), and a D-Pad.
  26
  27 ## Usage
  28
  29 Associate your Wiimote with your computer (details on how to do this are
  30 not discussed here, but you may want to look at [xwiimote][]'s page for
  31 additional information), then start the program. As long as the program
  32 is running, a virtual controller (called “Nintendo Remote in gamepad
  33 mode”) will be available. Just press Ctrl+C to terminate the program and
  34 ‘disconnect’ the virtual controller.
  35
  36 Syntax:
  37
  38         wiimote-pad [device]
  39
  40 where _device_ is the path to a Linux-created device associated with the
  41 Wiimote (e.g. `/dev/input/js0` or something like that). If no _device_
  42 is specified, the program will look for the first device that it can
  43 associate with and use that.
  44
  45 ## D-pad orientation
  46
  47 Since 2017, by default, the D-pad will be oriented in landscape mode (the
  48 arm closest to the A button will be mapped to _right_ rather than
  49 _down_), in accordance to the Wiimote orientation.
  50
  51 This is a break from the previous behavior of the program. If you prefer
  52 the old behavior, you can pass the command-line option `--dpad
  53 portrait`, which will set the D-pad in portrait mode (arm closest to the
  54 A button will be mapped to _down_). You can enforce the new behavior
  55 with `--dpad landscape`, and even specify different D-pad settings for
  56 different Wiimotes, for example:
  57
  58         wiimote-pad --dpad portrait /dev/input/js0 --dpad landscape /dev/input/js1
  59
  60 will set the `js0` Wiimote with the D-pad in portrait mode, and the
  61 `js1` one with the D-pad in landscape mode.
  62
  63 ### Note
  64
  65 `wiimote-pad` is _specifically_ designed to expose the sideways Wiimote
  66 as a gamepad. All other Wiimote uses (especially the ones involving
  67 the infrared (IR) sensor) are outside of its scope. Please refer to the
  68 `xwiimote` and `xf86-input-wiimote` projects for those.
  69
  70 ## `udev` rules
  71
  72 This repository also provides a set of `udev` rules to:
  73
  74 * change the group and the permissions of all Wiimote-related devices
  75   (both the kernel ones and the virtual one created by `wiimote-pad`);
  76 * create descriptive symlinks for the event devices associated with
  77   Wiimotes.
  78
  79 By default the group assigned to Wiimote devices is `bluetooth`, you
  80 might need to tune it for your system. The group and permission change
  81 is needed so that applications that use the event interface instead of
  82 the joystick interface can still access the Wiimote.
  83
  84 ## Requirements
  85
  86 Dependencies for `wiimote-pad` are `libudev` and `libxwiimote`. The
  87 latter should be version 2 or higher.
  88
  89 ## Compile
  90
  91 Just running
  92
  93         make
  94
  95 should work.
  96
  97 If you compiled and built `libxwiimote` yourself, you might
  98 need to fix the include path in the `Makefile` to point to the correct
  99 locations to look for the headers, or run
 100
 101         make XWIIMOTE=/path/to/xwiimote/sources
 102
 103 instead. By default, aside from standard locations, the `Makefile` will
 104 look for an `xwiimote` source directory in the parent of the
 105 `wiimote-pad` directory.
 106
 107 [xwiimote]: http://dvdhrm.github.io/xwiimote