Improved XBMC event client for Wii remotes.
Go to file
Paul van Tilburg 5dc187e268 Update the REAMDE for the changes by PR #7
Also bump the required Kodi version to 17.0 and replace XBMC by
Kodi where applicable.  Leave XBMC in the name of the script/project
for now.
2019-08-21 19:55:58 +02:00
COPYING Initial import 2011-12-10 21:56:53 +01:00 Update the REAMDE for the changes by PR #7 2019-08-21 19:55:58 +02:00
xbmc-wiimote Update the event map to CC to work with Kodi >= 17 2019-08-20 21:41:22 +02:00

Improved XBMC Wiimote Gateway

A Kodi event client that receives input from a Wii remote via bluetooth and feeds them to Kodi.

While Kodi comes with a Wii remote event client already (xbmc-wiiremote), this project aims to improve upon it by adding some additional features such as automatic disconnect, by having better error handling and to be more hackable by using the Python bindings.


  • Automatic disconnect after a period of disuse
  • On connect…
    • notifications in Kodi,
    • rumble, and
    • battery status report
  • Supports key repeating when holding a button down
  • Rudimentary error handling
  • Usage of a specific Wii remote to be able to pair quickly
  • Uses the official Kodi EventServer API
  • Uses the custom controller keymap with Kodi (>= 17.0)


XBMC Wiimote Gateway is an Kodi event client, so it needs:

  • Kodi (>= 17), with
    • Kodi Event Client Python bindings
  • Python (>= 2.6), with
    • Python CWIID bindings (>= 0.6)
  • Bluez (>= 4.96)

and of course a working bluetooth controller.

Installation & Use

First, install a keymap file WiiRemote.xml in $HOME/.kodi/userdata/keymaps:

    <customcontroller name="WiiRemote">
      <button id="1">Up</button>
      <button id="2">Down</button>
      <button id="3">Left</button>
      <button id="4">Right</button>
      <button id="5">Select</button>
      <button id="6">Back</button>
      <button id="7">VolumeDown</button>
      <button id="8">ActivateWindow(Home)</button>
      <button id="9">VolumeUp</button>
      <button id="10">ContextMenu</button>
      <button id="11">ActivateWindow(PlayerControls)</button>
    <customcontroller name="WiiRemote">
      <button id="8">Fullscreen</button>
      <button id="10">ActivateWindow(Favourites)</button>
      <button id="11">ActivateWindow(ShutdownMenu)</button>
    <customcontroller name="WiiRemote">
      <button id="1">Pause</button>
      <button id="2">Stop</button>
      <button id="3">StepBack</button>
      <button id="4">StepForward</button>
      <button id="5">OSD</button>
      <button id="6">Info</button>
      <button id="7">VolumeDown</button>
      <button id="8">ActivateWindow(Home)</button>
      <button id="9">VolumeUp</button>
      <button id="10">CodecInfo</button>
      <button id="11">AspectRatio</button>

(Feel free to modify it to your liking.)

Then install the script itself, xbmc-wiimote, can be put anywhere. Preferably, put it somewhere that is in the system's/in your path.


$ xbmc-wiimote -b <Wii remote bluetooth address>

You should see a notification pop up in Kodi that tells you that the XBMC Wiimote Gateway has connected.

If you don't know the bluetooth address of your Wii remote, run

$ hcitool scan

and quickly press 1+2 on the Wii remote to find the address


XBMC Wiimote Gateway free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see

N.B. The source code of this program includes code from which is licensed under the Apache License 2.0, see also: