EventServer: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
>Nuka1195
mNo edit summary
 
(92 intermediate revisions by 23 users not shown)
Line 1: Line 1:
XBMC can recieve commands through our internal EventServer. But what is this EventServer, why is it needed and how do I use it?
{{mininav|[[Development]]}}


==Introduction==
{{cleanup}}
EventServer is the part of Kodi that accepts remote device input on all platforms. EventServer API is used to program event clients and simplifies interfacing input devices with Kodi. EventServer accepts commands from event clients such as LIRC, joysticks, PDAs, and iPhones.


====Why?====
== The Purpose of EventServer API in Kodi ==
The EventServer in Kodi 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 Kodi.


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.
== Event Clients and the EventServer ==
Kodi'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 Kodi, essentially as remote control addons.


====What is an Event Client and Event Server====
To change the default Event Server port on Kodi, you must modify guisettings.xml under <services>, find this line "<esport>9777<esport/>", change the port number and save. The file is here: ~/.kodi/userdata/guisettings.xml (this has worked with Openelec for the Raspberry Pi).


XBMC acts as the Event Server which listens for commands from the Event Clients. The Event Client is currently remotes or gamepads but can be anything that want to send commands to XBMC. To keep this communication as fast and plug n' play as possible UDP was chosen. UDP is used in network games and is one of the lowest layers of network communication, this grants low latencies and very little overhead.
== v11 Eden options ==
:In v11 (Eden), the event server is enabled through the "Allow programs on other systems to control Kodi" option. It runs by default on 9777, and can be confirmed by looking in the log at startup for "Starting UDP Event server on 0.0.0.0:9777"
:To change the default port, you must modify advancedsettings.xml , but the exact setting is not known at this time.


These commands are completely crossplattform and makes it possible to have a Event Client on a XBMC for Linux that sends the commands to XBMC for Xbox and it will respond as if it were sending these command to XBMC for Linux.
== Event Clients ==
The event clients and EventServer are under heavy development, so for up-to-date information please refer to the [https://github.com/xbmc/xbmc/blob/master/tools/EventClients/README.txt readme file]


====Pros and Cons====
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.


Some of you may have noticed this seems to be alot like our HTTPApi so here's some important differences:
Event clients can currently be recognized as one of the following:


*Event Server is always active on localhost which makes it much more stable for remotes (Not usable for XBMC for xbox).
* Mouse
* Keyboard
* LIRC (Only on Linux)
* Joystick


*Event Server is event based were the httpapi is request based.
=== Joysticks ===
 
Joysticks are mappable in keymap.xml using the following convention:
*Event Server is much easier to implement in programs
  <joystick name="foo">
 
*Event Server can distinguish between different clients and can therefor be used simultaneously, ie for games with split screen.
 
*Event Server is mappable through keymap.xml if the client chooses so.
 
*Event Server will notify the user when a connection is made
 
*Event Server is capable of displaying notifications on demand.
 
There are some cons with this approach aswell:
 
*Event Server is dependent on port forwarding
 
*Currently Event Server cannot send any information back to the clients but it's something that will be incorporated.
 
*Event Server is not designed to be able to send raw commands like playurl "foo". This might change in the future.
 
==Setup==
 
====XBMC====
 
{|
 
| valign="top" |
 
;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.
 
| [[Image:Settings.network.remoteeveents.jpg|right|600px]]
 
|}
 
====Event Clients====
 
The Event Clients and Event Server are in heavy development so for up-to-date information refer to the [http://xbmc.svn.sourceforge.net/viewvc/*checkout*/xbmc/branches/linuxport/XBMC/tools/EventClients/README.txt README.txt].
 
Most (all?) of the eventclients have the ability to be setup using arguments in the command line. Among the standardized arguments are:
 
*--address were both IP or DNS should be working. localhost are standard.
*--port were 9777 is standard.
 
The Event Clients can choose which controller type it will be recognized as were the possibilities are:
 
*Mouse
*Keyboard
*Xbox DVDRemote
*Xbox GamePad
*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="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.
 
====PS3 Sixaxis and Blu-Ray Remote Support====
 
There is also 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)======
See [[keyboard.xml]] for more information on how to customize the keymap.


The pairing of the PS3 controller is not yet handled automatically. It can however be done using the program "sixaxis.c" available from:
There is initial support for the PS3 controller (sixaxis) and


http://www.pabr.org/sixlinux/sixlinux.en.html
==== 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.


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.
==== 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]. Or if you want to do it the gui way [http://ubuntuforums.org/showthread.php?t=1190061]


======Using the PS3 Sixaxis Controller======
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. (This is not nessecary using the gui tool)


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 in XBMC mouse. Tilt it from left to right (along your Z axis) to control horizontal motion. Tilt it towards and away from you along (along your X axis) to control vertical mouse movement.
===== Using the PS3 Sixaxis Controller =====
There is xml configuration file for the ps3 controller under your keymaps folder.
You need to change the name of the joystick in you xml configfile to containg the mac adress of your controller.  
"grep PLAYSTATION /proc/bus/input/devices" from a terminal will give you what you need.


That's all for now.
==== WiiRemote ====
To use the WiiRemote:
1. Open a terminal window and type/paste xbmc-wiiremote (do not press enter yet)
2. Press 1 and 2 on the WiiRemote
3. press enter
4. leave this terminal open and open Kodi


====WiiRemote====
You should see Kodi recognize the WiiRemote. You can press the power button on the WiiRemote to save battery. To reconnect press the 1 and 2 again. As long as you leave the terminal window with xbmc-wiiremote open you will be able to do this, even if you exit/open Kodi.


The executable depends on libcwiid and libbluetooth and is compiled using # g++ WiiRemote.cpp -lcwiid -o WiiRemote
The executable depends on libcwiid and libbluetooth and is compiled using
# g++ WiiRemote.cpp -lcwiid -o WiiRemote


The WiiRemote will emulate mouse by default but can be disabled by running with --disable-mouseemulation
The WiiRemote will emulate the 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 is considered "dead", higher means more sensitive.
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 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


The WiiRemote is mappable with [[Keymap.xml|keymap.xml]] where button id's are the following:
;Nunchuck
 
:21 = Up (axis)
1 = Up
:22 = Dow (axis)
2 = Down
:23 = Left (axis)
3 = Left
:24 = Right (axis)
4 = Right
:25 = C
5 = A
:26 = Z
6 = B
7 = Minus
8 = Home
9 = Plus
10 = 1
11 = 2
 
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 but 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 Event Clients==
 
All clients are able to talk to any server on any O/S, still the clients are often O/S specific.


====Linux====
The name is by default WiiRemote, but this can be changed with the --joystick-name argument.


*PS3 Bluray Remote
=== J2ME (Java Phone Application) (no longer supported) ===
Support for J2ME client was removed in Kodi v17 via pull request https://github.com/xbmc/xbmc/pull/10049. If you absolutely must have it, revert the changes and follow the instructions to compile it.


*PS3 Sixaxis GamePad
The J2ME client requires the following:
* CLDC 1.0 and MIDP 1.0
* bluetooth connectivity
* client must be able to initialize the connection


*WiiRemote
For compiling the Java application, see Clients/J2ME and Client/README (precompiled versions exists in our forum).


*J2ME (CellPhone)
The Client can be mapped in the same manner as the PS3 controller in keymap.xml, but with the name J2ME:
    <joystick name="J2ME">


====Mac OSX====
The KeyIDs are generated in terminal using j2me_remote.py.


*PS3 Bluray Remote
== Known Working EventClients ==
All clients are able to talk to any server on any OS, but the client software is often OS specific.


*J2ME (CellPhone)
=== Kodi for Linux ===
* Sony PlayStation 3 (PS3) Blu-ray Remote
* PS3 Sixaxis GamePad
* Wii Remote
* J2ME (CellPhone)
* [https://github.com/xhaggi/kodi-eventclient-hama-mce Hama MCE Remote Control]


*AppleRemote
=== Kodi for Mac OS X ===
* Apple Remote
* Sony PlayStation 3 (PS3) Blu-ray Remote
* J2ME (CellPhone)


====Win32====
=== Kodi for Windows ===
* Sony PlayStation 3 (PS3) Blu-ray Remote
* Xbox 360 Controller
* J2ME (CellPhone)
* [http://forum.kodi.tv/showthread.php?t=38160 EventGhost]


*PS3 Bluray Remote
== 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.


*J2ME (CellPhone)


====Known caveats====
== Development of EventClients and the EventServer API ==


*Most of the clients are using python and PyBluez/Lightblue and both are needed to be installed.
=== Example demos of EventClients (open source code) ===
You can find several open source EventClient examples written in C++, Python, and Java in the Kodi Github. Look under [https://github.com/xbmc/xbmc/tree/master/tools/EventClients EventClients]. This directory contains seven event client sample programs that demonstrate Kodi's EventServer API. The different programs are in C++, Python, and Java. Kodi must be running to receive events. Please see README.txt for more information.


*PyBluez only works with broadcom chipsets on Win32.
[[Category:Add-on development]]
[[Category:Development]]

Latest revision as of 23:51, 29 August 2020

Home icon grey.png   ▶ Development ▶ EventServer
Cleanup.png This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.


EventServer is the part of Kodi that accepts remote device input on all platforms. EventServer API is used to program event clients and simplifies interfacing input devices with Kodi. EventServer accepts commands from event clients such as LIRC, joysticks, PDAs, and iPhones.

The Purpose of EventServer API in Kodi

The EventServer in Kodi 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 Kodi.

Event Clients and the EventServer

Kodi'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 Kodi, essentially as remote control addons.

To change the default Event Server port on Kodi, you must modify guisettings.xml under <services>, find this line "<esport>9777<esport/>", change the port number and save. The file is here: ~/.kodi/userdata/guisettings.xml (this has worked with Openelec for the Raspberry Pi).

v11 Eden options

In v11 (Eden), the event server is enabled through the "Allow programs on other systems to control Kodi" option. It runs by default on 9777, and can be confirmed by looking in the log at startup for "Starting UDP Event server on 0.0.0.0:9777"
To change the default port, you must modify advancedsettings.xml , but the exact setting is not known at this time.

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
  • 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 keyboard.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]. Or if you want to do it the gui way [2]

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. (This is not nessecary using the gui tool)

Using the PS3 Sixaxis Controller

There is xml configuration file for the ps3 controller under your keymaps folder. You need to change the name of the joystick in you xml configfile to containg the mac adress of your controller. "grep PLAYSTATION /proc/bus/input/devices" from a terminal will give you what you need.

WiiRemote

To use the WiiRemote: 1. Open a terminal window and type/paste xbmc-wiiremote (do not press enter yet) 2. Press 1 and 2 on the WiiRemote 3. press enter 4. leave this terminal open and open Kodi

You should see Kodi recognize the WiiRemote. You can press the power button on the WiiRemote to save battery. To reconnect press the 1 and 2 again. As long as you leave the terminal window with xbmc-wiiremote open you will be able to do this, even if you exit/open Kodi.

The executable depends on libcwiid and libbluetooth and is compiled using

  1. 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) (no longer supported)

Support for J2ME client was removed in Kodi v17 via pull request https://github.com/xbmc/xbmc/pull/10049. If you absolutely must have it, revert the changes and follow the instructions to compile it.

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.

Kodi for Linux

Kodi for Mac OS X

  • Apple Remote
  • Sony PlayStation 3 (PS3) Blu-ray Remote
  • J2ME (CellPhone)

Kodi for Windows

  • Sony PlayStation 3 (PS3) Blu-ray Remote
  • Xbox 360 Controller
  • J2ME (CellPhone)
  • EventGhost

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 Kodi Github. Look under EventClients. This directory contains seven event client sample programs that demonstrate Kodi's EventServer API. The different programs are in C++, Python, and Java. Kodi must be running to receive events. Please see README.txt for more information.

Retrieved from "https://kodi.wiki/index.php?title=EventServer&oldid=219805"