EventServer

INCOMPLETE: This page or section is incomplete. Please add information or correct uncertain data which is marked with a ?

XBMC can receive commands through our internal EventServer API.

Introduction

This article is here to describe what the EventServer API is meant for, why is it needed in XBMC, and how do I use it. It also goes through the existing EventClients available for this API as examples on how to fully utilize the EventServer API.

Why the EventServer API is needed in XBMC

With the ports becoming a reality it's harder to support all possible remotes inside the standard codebase, especially without having a performance drop. Many people doesn't need one remote but craves the other, and without forcing the user to compile there own build this is an impossibility. The solution is to make remotes plug n' play, which is why the Event Server was born.

What is an "Event Client" and "Event Server"

XBMC acts as the EventServer which listens for commands from the Event Clients. Currently, support for remotes or gamepad-controllers has been implemented as event clients, however anything that want to send commands to XBMC can be implemented as one. To keep this communication as fast and plug n' play as possible UDP was chosen. UDP is used in things such as network games and is one of the lowest layers of network communication. This grants low latencies and very little overhead.

These commands are completely cross platform, e.g you can have an EventClient on a Linux/Mac/Windows-based computer that sends the commands to XBMC for Xbox.

Pros and Cons

Some of you may have noticed this seems to be a lot like the Web Server HTTP API (also known as "HTTPAPI") for XBMC and there lies the pros for the EventServer.

• Always active on localhost which makes it much more stable for remotes (Not usable for XBMC for Xbox).
• Event based were the HTTPAPI is request based.
• Much easier to implement in programs
• Can distinguish between different clients and can therefor be used simultaneously, ie. for games with split screen.
• Mappable through keymap.xml if the client chooses so.
• Will notify the user when a connection is made
• Capable of displaying notifications on demand.

There are some cons with this approach as well:

• Currently EventServer cannot send any information back to the clients. This is something we plan to incorporate.
• EventServer is not designed to be able to send built in commands like playurl "foo". This might change in the future.

Setup

XBMC

Enable Remote Events If enabled XBMC's Event Server is activated. Remote Events Port This is the starting port for the port range that Event Clients can use. Remote Events Port Range This is the port range we can listen to Event Clients. Maximum Number of Clients The maximum of simultaneous remotes connection at one time. Receive events from other computers If enabled the Event Server will listen for connections beyond localhost. Initial Repeat Delay (ms) If a Event Client sends a held button this is the delay before it will be repeated. Continuous Repeat Delay (ms) The above buttons repeat speed.

Event Clients

The Event Clients and Event Server are in heavy development so for up-to-date information refer to the README.txt.

Most of the EventClients have the ability to be configured using arguments in the command-line. Among the standardized arguments are:

• --address were both IP or DNS should be working. If omitted, they default to localhost.
• --port (9777 being the default).

The EventClients can choose which controller type it will be recognised as, with the possibilities being:

• Mouse
• Keyboard
• Xbox Gamepad
• Xbox Remote
• Xbox Universal Remote
• LIRC (Only on Linux)
• Joystick

The one that is most interesting is the joystick which is perfectly mappable using this convention were foo is the Event Clients name (Chosen by the Event Client). The Event Client sends a button id which is a number ranging from 1 - 65554 and is also able to send an axis.

<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.

PS3 Sixaxis and PS3 Blu-Ray Remote Support

There is initial support for the PS3 controller (sixaxis) and the PS3 Blu-Ray remote.

Pairing of the PS3 Blu-Ray Remote

The remote needs to be paired initially with the 'ps3_remote.py' program in this directory which you can continue using if you do not want to run 'ps3d.py' as root. The disadvantage of using 'ps3_remote.py' is that pairing is required on every run. Once initial pairing is done, 'ps3d.py', when run as root, will automatically detect incoming connections from both the PS3 remote and the Sixaxis controller.

Pairing of the PS3 Sixaxis Controller (TODO)

The pairing of the PS3 controller is not yet handled automatically. It can however be done using the program "sixaxis.c" available from:

http://www.pabr.org/sixlinux/sixlinux.en.html

Once pairing for either or both has been done, run the ps3d.py program as root after disabling any existing HID servers that might currently be running. The program requires root privileges since it listens on Bluetooth L2CAP PSMs 17 and 19.

Using the PS3 Sixaxis Controller

Currently, all that is supported with the Sixaxis controller is to be able emulate the mouse behavior. Hold down the PS button and wave the controller around and watch the mouse cursor in XBMC move around. Tilt it from left to right (along your Z axis) to control horizontal motion. Tilt it towards or away from you

That's all for now.

WiiRemote

The executable depends on libcwiid and libbluetooth and is compiled using

1. 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 mouseemulation can be set using the --deadzone_x or --deadzone_y where the number is the percentage of the space to consider "dead", higher means higher sensitiveness. Other commands can be listed with --help

The WiiRemote is mappable with keymap.xml where button id's are the following:

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 standard WiiRemote but this can be changed with the --joystick-name

J2ME (Java Phone Application)

To use the J2ME client only CLDC 1.0 and MIDP 1.0 is needed. The client will also need bluetooth and must be able to initialize the connection. For compilation of the Java Application see Clients/J2ME Client/README (precompiled versions exists in our forum).

The Client is mappable in the same manner as PS3 in keymap.xml but with the name J2ME (<joystick name="J2ME">). The KeyID's generated in terminal when running j2me_remote.py.

Known Working EventClients

All clients are able to talk to any server on any O/S, still the clients are often O/S 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 and PyBluez/Lightblue and both are needed to be installed.
• PyBluez only works with broadcom chipsets on Win32.

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: "/xbmc/branches/linuxport/XBMC/tools/EventClients/"

This directory contains seven EventClient sample programs that demonstrate XBMC's EventServer API. The different programs are in C++, Python, and Java and work to demo this EventServer API for XBMC. XBMC also needs to be running (obviously) so that it can receive the events. Please see README.txt for more information.