EventServer: Difference between revisions
>Clarkdudek m (Fixed broken link) |
>Juxe (Revised entire page. Fixed layout. Organized ToC.) |
||
Line 1: | Line 1: | ||
{{Incomplete}} | |||
{{XBMC faq toc Inline}} | {{XBMC faq toc Inline}} | ||
__TOC__ | __TOC__ | ||
__NOEDITSECTION__ | __NOEDITSECTION__ | ||
=Introduction= | |||
XBMC | EventServer is the part of XBMC that accepts remote device input on all platforms except the original Xbox. EventServer API is used to program event clients and simplifies interfacing input devices with XBMC. EventServer accepts commands from event clients such as LIRC, joysticks, PDAs, and iPhones. | ||
== | ====The Purpose of EventServer API in XBMC==== | ||
The EventServer in XBMC was created to satisfy a need to support many input devices across multiple hardware platforms. Adding direct support for a multitude of devices generally decreases performance and stability, and becomes difficult to maintain. The EventServer was created to provide a simple, reliable way to communicate with and control XBMC. | |||
==== | ====Event Clients and the EventServer==== | ||
XBMC's EventServer listens for commands from event clients. Anything that can communicate using UDP can be an event client. Many event client software packages are currently available for PCs, Macs, smartphones, PDAs, and more. Some event client software accepts commands from infra-red remotes, gamepad controllers, and others to translate and send to the EventServer. These event client software packages are often run on the same computer as XBMC, essentially as remote control addons. | |||
These | |||
====Pros and Cons==== | ====Pros and Cons==== | ||
EventServer can be compared to the older web control interface, [[WebServerHTTP-API|Web Server HTTP API (also known as "HTTPAPI")]]. Below are pros and cons of the EventServer system, compared to HTTP-API. | |||
* | =====EventServer Pros===== | ||
* | *is always active on localhost, which is much more stable for remotes (Not available on XBMC for Xbox.) | ||
* | *uses event-based communication instead of request-based communication. | ||
* | *is much easier to implement in programs. | ||
* | *can distinguish between different clients, and therefore have multiple distinct inputs. | ||
* | *is mappable through keymap.xml. | ||
* | *can notify the user when a connection is made. | ||
*is capable of displaying notifications on demand. | |||
=====EventServer Cons===== | |||
* | *currently cannot send any information back to clients. This is a planned feature. | ||
* | *is not designed to send built-in XBMC commands like playurl. This may change in the future. | ||
=XBMC Options= | |||
[[Image:Settings.network.remoteeveents.jpg|right|600px]] | |||
| | |||
;Enable Remote Events | ;Enable Remote Events | ||
: | :Check to enable the EventServer. | ||
;Remote Events Port | ;Remote Events Port | ||
: | :The starting port for the range of ports that EventServer will listen on. | ||
;Remote Events Port Range | ;Remote Events Port Range | ||
: | :The number of ports to listen on. Directly determines the port range. | ||
;Maximum Number of Clients | ;Maximum Number of Clients | ||
:The maximum of simultaneous | :The maximum number of simultaneous connections. | ||
---- | ---- | ||
;Receive events from other computers | ;Receive events from other computers | ||
: | :Check to listen on the network, not just on the local machine. | ||
---- | ---- | ||
;Initial Repeat Delay (ms) | ;Initial Repeat Delay (ms) | ||
: | :Delay, in milliseconds, before a continuously pressed button will begin registering as multiple, repeated presses. | ||
;Continuous Repeat Delay (ms) | ;Continuous Repeat Delay (ms) | ||
:The above | :The speed at which the above repeated presses will be entered. | ||
=Event Clients= | |||
The event clients and EventServer are under heavy development, so for up-to-date information please refer to the [http://xbmc.svn.sourceforge.net/viewvc/*checkout*/xbmc/branches/linuxport/XBMC/tools/EventClients/README.txt readme file] | |||
Most event clients can be configured using [http://en.wikipedia.org/wiki/Command-line_interface CLI]. Common CLI arguments are address and port number. The defaults are localhost and port 9777. | |||
Event clients can currently be recognized as one of the following: | |||
*Mouse | *Mouse | ||
Line 74: | Line 67: | ||
*Joystick | *Joystick | ||
==Joysticks== | |||
Joysticks are mappable in keymap.xml using the following convention: | |||
<joystick name="foo"> | <joystick name="foo"> | ||
<button id="1">ACTION1</button> | <button id="1">ACTION1</button> | ||
<button id="2">ACTIOn2</button> | <button id="2">ACTIOn2</button> | ||
<axis id="1" limit="-1">ACTION3</axis> | <axis id="1" limit="-1">ACTION3</axis> | ||
<axis id="2" limit="+1">ACTION4</axis> | <axis id="2" limit="+1">ACTION4</axis> | ||
</joystick> | </joystick> | ||
See [[Keymap.xml|Editing keymap.xml]] for more information on how to customize the keymap. | See [[Keymap.xml|Editing keymap.xml]] for more information on how to customize the keymap. | ||
There is initial support for the PS3 controller (sixaxis) and | |||
There is initial support for the PS3 controller (sixaxis) and | |||
====== | ===PS3 Blu-Ray Remote=== | ||
The | There is initial support for the PS3 Blu-Ray remote. | ||
The remote needs to be paired using one of two python scripts. 'ps3_remote.py' can be run as a user, but the controller must be paired every time the script is run. 'ps3d.py' will remember remotes between run-instances if it is executed as root, and it supports the PS3 Sixaxis controller as well. | |||
http://www.pabr.org/sixlinux/sixlinux.en.html | ===PS3 Sixaxis Controller (TODO)=== | ||
Pairing with the PS3 controller is not yet handled automatically, but it can be done using the program 'sixaxis.c' available from [http://www.pabr.org/sixlinux/sixlinux.en.html]. | |||
Once | Once paired, disable any existing HID servers that might currently be running and run 'ps3d.py' as root. The program requires root privileges because it listens on Bluetooth L2CAP PSMs 17 and 19. | ||
====Using the PS3 Sixaxis Controller==== | |||
Currently, all that is supported with the Sixaxis controller is | Currently, all that is supported with the Sixaxis controller is emulating the mouse behavior. Hold down the PS button and wave the controller to move the mouse cursor in XBMC. Tilt it from left to right (along your Z axis) to control horizontal motion. Tilt it towards or away from you to move it vertically. | ||
====WiiRemote==== | ====WiiRemote==== | ||
The executable depends on libcwiid and libbluetooth and is compiled using | The executable depends on libcwiid and libbluetooth and is compiled using | ||
# g++ WiiRemote.cpp -lcwiid -o WiiRemote | # g++ WiiRemote.cpp -lcwiid -o WiiRemote | ||
The WiiRemote will emulate mouse by default, this can be disabled by passing --disable-mouseemulation on the command line. | |||
The sensitivity of the | The WiiRemote will emulate the mouse by default, this can be disabled by passing --disable-mouseemulation on the command line. | ||
The sensitivity of the mouse emulation can be set using the --deadzone_x or --deadzone_y, followed by the percentage of the space to consider "dead." A higher numberm eans higher sensitivity. | |||
Other commands can be listed with --help | Other commands can be listed with --help | ||
The WiiRemote | The WiiRemote can be mapped in [[Keymap.xml|keymap.xml]] with the following button IDs: | ||
;WiiRemote | ;WiiRemote | ||
:1 = Up | :1 = Up | ||
Line 123: | Line 115: | ||
:10 = 1 | :10 = 1 | ||
:11 = 2 | :11 = 2 | ||
;Nunchuck | ;Nunchuck | ||
:21 = Up (axis) | :21 = Up (axis) | ||
Line 130: | Line 123: | ||
:25 = C | :25 = C | ||
:26 = Z | :26 = Z | ||
The name is by default WiiRemote, but this can be changed with the --joystick-name argument. | |||
==J2ME (Java Phone Application)== | |||
For | The J2ME client requires the following: | ||
*CLDC 1.0 and MIDP 1.0 | |||
*bluetooth connectivity | |||
*client must be able to initialize the connection | |||
For compiling the Java application, see Clients/J2ME and Client/README (precompiled versions exists in our forum). | |||
The Client can be mapped in the same manner as the PS3 controller in keymap.xml, but with the name J2ME: | |||
<joystick name="J2ME"> | |||
The | The KeyIDs are generated in terminal using j2me_remote.py. | ||
==Known Working EventClients== | ==Known Working EventClients== | ||
All clients are able to talk to any server on any | All clients are able to talk to any server on any OS, but the client software is often OS specific. | ||
===XBMC for Linux=== | |||
*Sony PlayStation 3 (PS3) Blu-ray Remote | *Sony PlayStation 3 (PS3) Blu-ray Remote | ||
*PS3 Sixaxis GamePad | *PS3 Sixaxis GamePad | ||
Line 149: | Line 148: | ||
*J2ME (CellPhone) | *J2ME (CellPhone) | ||
===XBMC for Mac OS X=== | |||
*Apple Remote | *Apple Remote | ||
*Sony PlayStation 3 (PS3) Blu-ray Remote | *Sony PlayStation 3 (PS3) Blu-ray Remote | ||
*J2ME (CellPhone) | *J2ME (CellPhone) | ||
===XBMC for Windows=== | |||
*Sony PlayStation 3 (PS3) Blu-ray Remote | *Sony PlayStation 3 (PS3) Blu-ray Remote | ||
*Xbox 360 Controller | *Xbox 360 Controller | ||
Line 160: | Line 159: | ||
*[http://forum.xbmc.org/showthread.php?t=38160 EventGhost] | *[http://forum.xbmc.org/showthread.php?t=38160 EventGhost] | ||
===XBMC for Xbox=== | |||
*There are no EventClients for the Xbox yet. | *There are no EventClients for the Xbox yet. | ||
==Known Caveats== | |||
*Most of the clients are using python and | *Most of the clients are using python, so PyBluez and Lightblue must be. | ||
*PyBluez only works with broadcom chipsets on | *PyBluez only works with broadcom chipsets on 32-bit Windows. | ||
Line 171: | Line 170: | ||
==Example demos of EventClients (open source code)== | ==Example demos of EventClients (open source code)== | ||
You can find several open source EventClient examples written in C++, Python, and Java in the XBMC SVN. | You can find several open source EventClient examples written in C++, Python, and Java in the XBMC SVN. Look under [http://xbmc.svn.sourceforge.net/viewvc/xbmc/branches/9.04_Babylon-linux-osx-win32/XBMC/tools/EventClients/ EventClients]. This directory contains seven event client sample programs that demonstrate XBMC's EventServer API. The different programs are in C++, Python, and Java. XBMC must be running to receive events. Please see README.txt for more information. | ||
Look under | |||
This directory contains seven | |||
[[Category:EventServer]] | [[Category:EventServer]] |
Revision as of 06:16, 27 October 2009
INCOMPLETE: This page or section is incomplete. Please add information or correct uncertain data which is marked with a ? |
Introduction
EventServer is the part of XBMC that accepts remote device input on all platforms except the original Xbox. EventServer API is used to program event clients and simplifies interfacing input devices with XBMC. EventServer accepts commands from event clients such as LIRC, joysticks, PDAs, and iPhones.
The Purpose of EventServer API in XBMC
The EventServer in XBMC was created to satisfy a need to support many input devices across multiple hardware platforms. Adding direct support for a multitude of devices generally decreases performance and stability, and becomes difficult to maintain. The EventServer was created to provide a simple, reliable way to communicate with and control XBMC.
Event Clients and the EventServer
XBMC's EventServer listens for commands from event clients. Anything that can communicate using UDP can be an event client. Many event client software packages are currently available for PCs, Macs, smartphones, PDAs, and more. Some event client software accepts commands from infra-red remotes, gamepad controllers, and others to translate and send to the EventServer. These event client software packages are often run on the same computer as XBMC, essentially as remote control addons.
Pros and Cons
EventServer can be compared to the older web control interface, Web Server HTTP API (also known as "HTTPAPI"). Below are pros and cons of the EventServer system, compared to HTTP-API.
EventServer Pros
- is always active on localhost, which is much more stable for remotes (Not available on XBMC for Xbox.)
- uses event-based communication instead of request-based communication.
- is much easier to implement in programs.
- can distinguish between different clients, and therefore have multiple distinct inputs.
- is mappable through keymap.xml.
- can notify the user when a connection is made.
- is capable of displaying notifications on demand.
EventServer Cons
- currently cannot send any information back to clients. This is a planned feature.
- is not designed to send built-in XBMC commands like playurl. This may change in the future.
XBMC Options
- Enable Remote Events
- Check to enable the EventServer.
- Remote Events Port
- The starting port for the range of ports that EventServer will listen on.
- Remote Events Port Range
- The number of ports to listen on. Directly determines the port range.
- Maximum Number of Clients
- The maximum number of simultaneous connections.
- Receive events from other computers
- Check to listen on the network, not just on the local machine.
- Initial Repeat Delay (ms)
- Delay, in milliseconds, before a continuously pressed button will begin registering as multiple, repeated presses.
- Continuous Repeat Delay (ms)
- The speed at which the above repeated presses will be entered.
Event Clients
The event clients and EventServer are under heavy development, so for up-to-date information please refer to the readme file
Most event clients can be configured using CLI. Common CLI arguments are address and port number. The defaults are localhost and port 9777.
Event clients can currently be recognized as one of the following:
- Mouse
- Keyboard
- Xbox Gamepad
- Xbox Remote
- Xbox Universal Remote
- LIRC (Only on Linux)
- Joystick
Joysticks
Joysticks are mappable in keymap.xml using the following convention:
<joystick name="foo"> <button id="1">ACTION1</button> <button id="2">ACTIOn2</button> <axis id="1" limit="-1">ACTION3</axis> <axis id="2" limit="+1">ACTION4</axis> </joystick>
See Editing keymap.xml for more information on how to customize the keymap.
There is initial support for the PS3 controller (sixaxis) and
PS3 Blu-Ray Remote
There is initial support for the PS3 Blu-Ray remote. The remote needs to be paired using one of two python scripts. 'ps3_remote.py' can be run as a user, but the controller must be paired every time the script is run. 'ps3d.py' will remember remotes between run-instances if it is executed as root, and it supports the PS3 Sixaxis controller as well.
PS3 Sixaxis Controller (TODO)
Pairing with the PS3 controller is not yet handled automatically, but it can be done using the program 'sixaxis.c' available from [1].
Once paired, disable any existing HID servers that might currently be running and run 'ps3d.py' as root. The program requires root privileges because it listens on Bluetooth L2CAP PSMs 17 and 19.
Using the PS3 Sixaxis Controller
Currently, all that is supported with the Sixaxis controller is emulating the mouse behavior. Hold down the PS button and wave the controller to move the mouse cursor in XBMC. Tilt it from left to right (along your Z axis) to control horizontal motion. Tilt it towards or away from you to move it vertically.
WiiRemote
The executable depends on libcwiid and libbluetooth and is compiled using
- g++ WiiRemote.cpp -lcwiid -o WiiRemote
The WiiRemote will emulate the mouse by default, this can be disabled by passing --disable-mouseemulation on the command line.
The sensitivity of the mouse emulation can be set using the --deadzone_x or --deadzone_y, followed by the percentage of the space to consider "dead." A higher numberm eans higher sensitivity.
Other commands can be listed with --help
The WiiRemote can be mapped in keymap.xml with the following button IDs:
- WiiRemote
- 1 = Up
- 2 = Down
- 3 = Left
- 4 = Right
- 5 = A
- 6 = B
- 7 = Minus
- 8 = Home
- 9 = Plus
- 10 = 1
- 11 = 2
- Nunchuck
- 21 = Up (axis)
- 22 = Dow (axis)
- 23 = Left (axis)
- 24 = Right (axis)
- 25 = C
- 26 = Z
The name is by default WiiRemote, but this can be changed with the --joystick-name argument.
J2ME (Java Phone Application)
The J2ME client requires the following:
- CLDC 1.0 and MIDP 1.0
- bluetooth connectivity
- client must be able to initialize the connection
For compiling the Java application, see Clients/J2ME and Client/README (precompiled versions exists in our forum).
The Client can be mapped in the same manner as the PS3 controller in keymap.xml, but with the name J2ME:
<joystick name="J2ME">
The KeyIDs are generated in terminal using j2me_remote.py.
Known Working EventClients
All clients are able to talk to any server on any OS, but the client software is often OS specific.
XBMC for Linux
- Sony PlayStation 3 (PS3) Blu-ray Remote
- PS3 Sixaxis GamePad
- Wii Remote
- J2ME (CellPhone)
XBMC for Mac OS X
- Apple Remote
- Sony PlayStation 3 (PS3) Blu-ray Remote
- J2ME (CellPhone)
XBMC for Windows
- Sony PlayStation 3 (PS3) Blu-ray Remote
- Xbox 360 Controller
- J2ME (CellPhone)
- EventGhost
XBMC for Xbox
- There are no EventClients for the Xbox yet.
Known Caveats
- Most of the clients are using python, so PyBluez and Lightblue must be.
- PyBluez only works with broadcom chipsets on 32-bit Windows.
Development of EventClients and the EventServer API
Example demos of EventClients (open source code)
You can find several open source EventClient examples written in C++, Python, and Java in the XBMC SVN. Look under EventClients. This directory contains seven event client sample programs that demonstrate XBMC's EventServer API. The different programs are in C++, Python, and Java. XBMC must be running to receive events. Please see README.txt for more information.