XBMC will be renamed to Kodi for v14. Read here for more details

Archive:HOW-TO:Gyration USB remote in Ubuntu for XBMC using Lirc, Add-on development

From Kodi
(Difference between pages)
Jump to: navigation, search
 
 
Line 1: Line 1:
This is a configuration for using a Gyration USB media remote reviewed at [http://reviews.cnet.com/keyboards/gyration-media-center-pc/4505-3134_7-32331445.html]
+
{{XBMC faq toc}}
This method uses two instances of lircd that are manually configured to start using /etc/rc.local.  The files that are affected are:
+
This page summarizes the new addons system introduced in the Dharma release (v10) of XBMC.
/etc/lirc/lircd.conf
+
/etc/rc.local
+
~usernamerunningxbmc/.xbmc/userdata/Keymap.xml
+
~usernamerunningxbmc/.xbmc/userdata/Lircmap.xml
+
  
Credit goes to the random anonymous bits and pieces I've found on the Interwebs along with my own experimentation using hexcump -C to look at the character device files while pressing buttons.
+
XBMC has introduced an addons system.  This allows 3rd party developed enhancements to XBMC to be distributed to XBMC users direct from inside the XBMC interface.
  
First, install the lirc package.
+
The addons system is based on the plugin library [http://www.c-pluff.org c-pluff].
<source lang="bash">sudo apt-get install lirc</source>
+
  
We do not want to use Ubuntu's init scripts and config files, therefore we need to tell it not to start up automatically.  Here is the command which changes the symbolic link in /etc/rc2.d/:
+
You can find a more detailed Addon Developers Document at [http://code.google.com/p/xbmc-gpodder-integration/downloads/list XBMC Addon Developers Guide]  It builds on information found on this page and elsewhere.  The document is delivered as a PDF.
<source lang="bash">sudo update-rc.d lirc disable 2</source>
+
  
Back up your old files that we are about to overwrite:
 
<source lang="bash">mkdir ~/backupfiles
 
for a in /etc/rc.local /etc/lirc/lircd.conf  ~/.xbmc/userdata/Lircmap.xml ~/.xbmc/userdata/Keymap.xml ; do cp $a ~/backupfiles/; done</source>
 
  
Put these lines in /etc/rc.local:
+
==Structure of an Add-on==
<source lang="bash">/usr/sbin/lircd --driver=devinput --device=/dev/input/by-id/usb-Gyration_Gyration_RF_Technology_Receiver-event-mouse --output=/dev/lircd1 --pidfile=/var/run/lircd1.pid --listen
+
/usr/sbin/lircd --driver=devinput --device=/dev/input/by-id/usb-Gyration_Gyration_RF_Technology_Receiver-event-kbd --output=/dev/lircd --pidfile=/var/run/lircd.pid --connect=localhost:8765</source>
+
  
Here is /etc/lirc/lircd.conf
+
Each add-on is kept in it's own folder, and is described via an XML file named addon.xml.  In addition, some other files can also come with the add-on, namely icon.png, changelog.txt, and fanart.jpg.  These are all optional, though we encourage you to at least have icon.png.  All of these reside in the "root" of the folder that contains the add-on.  Additional data may be contained within a resources/ subfolder, such as language translations and descriptions of settings.
<source lang="bash">#This configuration has been automatically generated via
+
#the Ubuntu LIRC package maintainer scripts.
+
#
+
#It includes the default configuration for the remote and/or
+
#transmitter that you have selected during package installation.
+
#
+
#Feel free to add any custom remotes to the configuration
+
#via additional include directives or below the existing
+
#Ubuntu include directives from your selected remote and/or
+
#transmitter.
+
  
#
+
==Guidelines for images==
# lircd.conf
+
Each add-on has 2 images associated with it: An icon (icon.png) and an optional fanart image (fanart.jpg). If you want a high quality icon or fanart image made for your add-on, then feel free to ask freezy at xbmc.org or the community on the XBMC forums - there are many talented designers who are more than happy to do up artwork for your add-ons.
#    for Gyration MCE remote(s).  Could almost certainly be expanded to work for their keyboard as well.
+
#
+
# Composed by Marc Randolph based upon
+
#    initial lircd.conf by Modulok (https://bugs.launchpad.net/mythbuntu/+bug/156494/comments/6)
+
#    with help from the Linux MCE wiki (http://wiki.linuxmce.org/index.php/Gyration-GYR3101US-codes)
+
#
+
# Notes:
+
#    Star and Hash keys produce two key sequences: 0x002A followed by either 8 for star, or 3 for hash
+
#
+
# Revision history
+
#    2.3 - Marc Randolph - Renamed camera to pictures and video to videos. Added alternative mappings
+
#    2.2 - Marc Randolph - Added untested DVDMenu entry
+
#    2.1 - Marc Randolph - StarHash comment was wrong
+
#    2.0 - Marc Randolph - Special codes should be correct, or at least, very close to correct
+
#    1.0 - Marc Randolph - added missing codes and changed names to match up the mceusb remote
+
#                        -   Some of the more special codes have not been verified (Pictures, LiveTV,  etc)
+
#    0.1 - Modulok      - Initial revision
+
#
+
#
+
begin remote
+
  
name    gyration
+
===icon.png===
bits          16
+
In order to keep a coherent look and give the skinner a good idea how the icons of the add-ons look, we have defined the following rules:
eps            30
+
aeps          100
+
  
one             0    0
+
* The icon size must be 256x256 pixels.
zero            0    0
+
* File format is PNG.
pre_data_bits  16
+
* Background must be 100% solid. That doesn't mean one color, it also can be a gradient or a low contrast texture. Just make sure there is no transparency.
pre_data      0x8001
+
* Keep the logo as simple a possible, no exaggerated 3D effects or high contrast textures.
gap          135997
+
* Use a padding of at least 25px for your logo (not the background!). Excepted are large text logos (see icon for themoviedb.org).
toggle_bit_mask 0x0
+
* Keep text to a minimum. However, a text logo along with the graphical logo is recommended in order to easily recognize the addon.
 +
* Don't mix logos with XBMC's logo, it's obvious that we're talking about XBMC here.
 +
* Don't add borders or any overlays, that's the skinner's job. However, if borders are an element of your logo, make sure there is enough padding.
  
      begin codes
+
===fanart.jpg===
        Home                    0x0066 # AKA "Windows button"
+
We recommend that fanart.png be a 16:9 JPG image. Some simple guidelines:
        Up                      0x0067
+
* It is intended for the background, so should be simple and without text where reasonable.
        Left                    0x0069
+
* We recommend a 1280x720 JPG image. It should certainly be no larger than 1920x1080.
        Right                    0x006A
+
* We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.
        Down                    0x006C
+
        Mute                    0x0071
+
        VolDown                  0x0072
+
        VolUp                    0x0073
+
        Power                    0x008e
+
        Pause                    0x0077
+
        More                    0x0082 # AKA "Info" or Help
+
        Back                    0x009E
+
        Skip                    0x00A3
+
        Replay                  0x00A5
+
        Stop                    0x00A6
+
        RecTV                    0x00A7  #Not "recorded TV", but "record current show on TV"
+
        Rewind                  0x00A8
+
        Play                    0x00CF
+
        Forward                  0x00D0
+
        Pictures                0x00D4 # not on Dell remote
+
        RecordedTV              0x00E2 # aka KEY_MEDIA
+
        Guide                    0x016A
+
        LiveTV                  0x016E  # aka KEY_PVR
+
        DVD                      0x0185
+
        Music                    0x0187  # not on Dell remote  # aka KEY_MP3
+
        Videos                  0x0189  # not on Dell remote
+
        ChanUp                  0x0192
+
        ChanDown                0x0193
+
        DVDMenu                  0x019A  # untested. not on Dell remote
+
        Clear                    0x0001
+
        One                      0x0002
+
        Two                      0x0003
+
        Three                    0x0004
+
        Four                    0x0005
+
        Five                    0x0006
+
        Six                      0x0007
+
        Seven                    0x0008
+
        Eight                    0x0009
+
        Nine                    0x000A
+
        Zero                    0x000B
+
        Enter                    0x001C
+
        StarHash                0x002A  # Star=0x2a and 0x08; Hash = 0x2a and 0x03
+
        a                      0x001E
+
    end codes
+
  
end remote
+
==addon.xml==
# Alternative mappings to try if some of the above don't work
+
 
# (please report any findings back to http://www.mythtv.org/wiki/Gyration-based_MCE_Remotes)
+
The addon.xml file is the most important file, as it tells XBMC what the addon provides (i.e. what type of extensions this add-on offers) and also what the add-on relies on (minimal versions of interfaces in XBMC that interact with the add-on.
#            Up  0x0062
+
 
#          Left  0x0064
+
An example addon.xml file is as follows:
#        Right  0x0066
+
 
#          Down  0x0068
+
<source lang="xml">
#        Pause  0x0075
+
<?xml version="1.0" encoding="UTF-8"?>
#        Power  0x008E
+
<addon
#          Halt  0x019C
+
  id="skin.confluence"
#        Lights  0x0111
+
  version="1.1.0"
#        Clear  0x0016
+
  name="Confluence"
#        Enter  0x0024
+
  provider-name="Jezz_X, Team XBMC">
#      DVDMenu  0x0029
+
  <requires>
 +
    <import addon="xbmc.gui" version="2.11"/>
 +
  </requires>
 +
  <extension
 +
    point="xbmc.gui.skin"
 +
    defaultresolution="720p"
 +
    defaultresolutionwide="720p"
 +
    defaultthemename="textures.xbt"
 +
    effectslowdown="0.75"
 +
    debugging="false"/>
 +
  <extension point="xbmc.addon.metadata">
 +
    <summary>Confluence skin by Jezz_X. (XBMC's default skin)</summary>
 +
    <summary lang="nl">Confluence skin door Jezz_X</summary>
 +
    <summary lang="zh">Jezz_X开发的Confluence皮肤</summary>
 +
    <description>Confluence is the default skin for XBMC 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time XBMC users to understand and use.</description>
 +
    <description lang="nl">Confluence is de standaard skin voor XBMC 9.11 en hoger. Het combineert de concepten van andere populaire skins, waarbij het tracht hun goede ideëen te integreren in een skin die gemakkelijk in gebruik is.</description>
 +
    <description lang="zh">在XBMC 9.11之后的版本中Confluence是默认皮肤。它集合了许多流行皮肤的创意,力求把这些优点融合到一个皮肤中,使得首次使用XBMC的用户能更容易上手。</description>
 +
    <disclaimer>Confluence is the default skin for XBMC, removing it may cause issues</disclaimer>
 +
    <disclaimer lang="nl">Confluence is de standaard XMBC skin, het verwijderen van Confluence kan leiden tot problemen.</disclaimer>
 +
    <disclaimer lang="zh">Confluence是XMBC的默认皮肤,删除它可能导致故障。</disclaimer>
 +
    <platform>all</platform>
 +
  </extension>
 +
</addon>
 
</source>
 
</source>
 +
 +
There are a few things to notice:
 +
* The <addon> element must be present, and is used to present the data about the addon package as a whole.
 +
* Inside the <addon> element is a <requires> element, listing the requirements that this addon needs in order to function.
 +
* Then there is one or more <extension> elements, each of which describes which part of XBMC the addon extends.
 +
* Finally, there is a specific <extension> element which describes the addon for the user.
 +
 +
===The <addon> element===
 +
 +
The addon element has 4 attributes: id, version, name, and provider-name.
 +
* The id attribute is the unique identifier used for this add-on.  It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers.  This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like <type>.<uniquename>.
 +
* The version attribute is used by XBMC to determine whether updates are available.  You should use something like 1.0.3 for this.
 +
* The name attribute is the name of the add-on as it appears in the UI.  This should be in English where it makes sense for it to be so, and is not translateable.
 +
* The provider-name attribute is used as the author field.  This could be a team of authors or a single author.
 +
 +
===The <requires> element===
 +
 +
The requires element contains one or more <import> elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires.  These add-ons may be part of XBMC itself, or may (in the future) be parts of other 3rd party add-ons.  XBMC will only allow the add-on to be run if versions of the add-ons on which this add-on depends are installed.  When a user installs your add-on from an online repository via XBMC's add-on manager, XBMC attempts to resolve these dependencies, and install anything that your add-on relies on first.
 +
 +
===The <extension> elements===
 +
 +
The extension element describes the technical aspects of this add-on.  It will have at least a point attribute which will give the part of XBMC that the add-on extends.  For instance, the addon.xml file for the Confluence skin above extends the "xbmc.gui.skin" part of XBMC.  Other extension points are given below.
 +
 +
===The xbmc.addon.metadata extension===
 +
 +
This special extension point must be provided by all add-ons, and is the way that your add-on is described to users of the XBMC add-on manager.  There are 4 elements that this should contain, though only the first is compulsory:
 +
* One or more summary elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages, whereby each has a lang="ch" attribute. No lang attribute indicates English.
 +
* One or more description elements provide a more detailed summary of what the add-on does.  Again, these can be translated.
 +
* One or more disclaimer elements that indicate what (if any) things the user should know about the add-on.  There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here.
 +
* A platform tag which specifies which platforms (operating systems, hardware) this add-on runs on.  Many add-ons will run on all platforms, so "all" is an option, as are "linux", "osx", "windx" and "wingl".  If the platform tag is missing, we assume the add-on runs on all platforms.
 +
 +
==Types of Extension==
 +
 +
The various extension points that XBMC provides are given in the list below.
 +
 +
* [[Add-ons_for_XBMC_(Developement)#addon.xml|xbmc.gui.skin]]
 +
* [[Add-ons_for_XBMC_(Developement)#Repository_Add-on|xbmc.addon.repository]]
 +
* [[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]
 +
* xbmc.metadata.scraper.albums
 +
* xbmc.metadata.scraper.artists
 +
* xbmc.metadata.scraper.movies
 +
* xbmc.metadata.scraper.musicvideos
 +
* xbmc.metadata.scraper.tvshows
 +
* xbmc.metadata.scraper.library
 +
* xbmc.ui.screensaver
 +
* xbmc.player.musicviz
 +
* [[Plugin_Sources#What_XBMC_requires_for_your_add-on|xbmc.python.pluginsource]]
 +
* [[Script_Sources#What_XBMC_requires_for_your_add-on|xbmc.python.script]]
 +
* xbmc.python.weather
 +
* [[Script_Subtitles#What_XBMC_requires_for_your_add-on|xbmc.python.subtitles]]
 +
* [[Script_Lyrics#What_XBMC_requires_for_your_add-on|xbmc.python.lyrics]]
 +
* [[Script_Library#What_XBMC_requires_for_your_add-on|xbmc.python.library]]
 +
 +
[[category:Add-ons]]

Revision as of 20:04, 2 December 2011

Home icon grey.png   ▶ Add-on development

This page summarizes the new addons system introduced in the Dharma release (v10) of XBMC.

XBMC has introduced an addons system. This allows 3rd party developed enhancements to XBMC to be distributed to XBMC users direct from inside the XBMC interface.

The addons system is based on the plugin library c-pluff.

You can find a more detailed Addon Developers Document at XBMC Addon Developers Guide It builds on information found on this page and elsewhere. The document is delivered as a PDF.


Contents

1 Structure of an Add-on

Each add-on is kept in it's own folder, and is described via an XML file named addon.xml. In addition, some other files can also come with the add-on, namely icon.png, changelog.txt, and fanart.jpg. These are all optional, though we encourage you to at least have icon.png. All of these reside in the "root" of the folder that contains the add-on. Additional data may be contained within a resources/ subfolder, such as language translations and descriptions of settings.

2 Guidelines for images

Each add-on has 2 images associated with it: An icon (icon.png) and an optional fanart image (fanart.jpg). If you want a high quality icon or fanart image made for your add-on, then feel free to ask freezy at xbmc.org or the community on the XBMC forums - there are many talented designers who are more than happy to do up artwork for your add-ons.

2.1 icon.png

In order to keep a coherent look and give the skinner a good idea how the icons of the add-ons look, we have defined the following rules:

  • The icon size must be 256x256 pixels.
  • File format is PNG.
  • Background must be 100% solid. That doesn't mean one color, it also can be a gradient or a low contrast texture. Just make sure there is no transparency.
  • Keep the logo as simple a possible, no exaggerated 3D effects or high contrast textures.
  • Use a padding of at least 25px for your logo (not the background!). Excepted are large text logos (see icon for themoviedb.org).
  • Keep text to a minimum. However, a text logo along with the graphical logo is recommended in order to easily recognize the addon.
  • Don't mix logos with XBMC's logo, it's obvious that we're talking about XBMC here.
  • Don't add borders or any overlays, that's the skinner's job. However, if borders are an element of your logo, make sure there is enough padding.

2.2 fanart.jpg

We recommend that fanart.png be a 16:9 JPG image. Some simple guidelines:

  • It is intended for the background, so should be simple and without text where reasonable.
  • We recommend a 1280x720 JPG image. It should certainly be no larger than 1920x1080.
  • We recommend keeping it as small as is reasonable with respect to file-size. Remember that hundreds of thousands of users are going to be downloading this.

3 addon.xml

The addon.xml file is the most important file, as it tells XBMC what the addon provides (i.e. what type of extensions this add-on offers) and also what the add-on relies on (minimal versions of interfaces in XBMC that interact with the add-on.

An example addon.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="skin.confluence"
  version="1.1.0"
  name="Confluence"
  provider-name="Jezz_X, Team XBMC">
  <requires>
    <import addon="xbmc.gui" version="2.11"/>
  </requires>
  <extension 
    point="xbmc.gui.skin"
    defaultresolution="720p" 
    defaultresolutionwide="720p"
    defaultthemename="textures.xbt" 
    effectslowdown="0.75"
    debugging="false"/>
  <extension point="xbmc.addon.metadata">
    <summary>Confluence skin by Jezz_X. (XBMC's default skin)</summary>
    <summary lang="nl">Confluence skin door Jezz_X</summary>
    <summary lang="zh">Jezz_X开发的Confluence皮肤</summary>
    <description>Confluence is the default skin for XBMC 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time XBMC users to understand and use.</description>
    <description lang="nl">Confluence is de standaard skin voor XBMC 9.11 en hoger. Het combineert de concepten van andere populaire skins, waarbij het tracht hun goede ideëen te integreren in een skin die gemakkelijk in gebruik is.</description>
    <description lang="zh">在XBMC 9.11之后的版本中Confluence是默认皮肤。它集合了许多流行皮肤的创意,力求把这些优点融合到一个皮肤中,使得首次使用XBMC的用户能更容易上手。</description>
    <disclaimer>Confluence is the default skin for XBMC, removing it may cause issues</disclaimer>
    <disclaimer lang="nl">Confluence is de standaard XMBC skin, het verwijderen van Confluence kan leiden tot problemen.</disclaimer>
    <disclaimer lang="zh">Confluence是XMBC的默认皮肤,删除它可能导致故障。</disclaimer>
    <platform>all</platform>
  </extension>
</addon>

There are a few things to notice:

  • The <addon> element must be present, and is used to present the data about the addon package as a whole.
  • Inside the <addon> element is a <requires> element, listing the requirements that this addon needs in order to function.
  • Then there is one or more <extension> elements, each of which describes which part of XBMC the addon extends.
  • Finally, there is a specific <extension> element which describes the addon for the user.

3.1 The <addon> element

The addon element has 4 attributes: id, version, name, and provider-name.

  • The id attribute is the unique identifier used for this add-on. It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers. This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like <type>.<uniquename>.
  • The version attribute is used by XBMC to determine whether updates are available. You should use something like 1.0.3 for this.
  • The name attribute is the name of the add-on as it appears in the UI. This should be in English where it makes sense for it to be so, and is not translateable.
  • The provider-name attribute is used as the author field. This could be a team of authors or a single author.

3.2 The <requires> element

The requires element contains one or more <import> elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires. These add-ons may be part of XBMC itself, or may (in the future) be parts of other 3rd party add-ons. XBMC will only allow the add-on to be run if versions of the add-ons on which this add-on depends are installed. When a user installs your add-on from an online repository via XBMC's add-on manager, XBMC attempts to resolve these dependencies, and install anything that your add-on relies on first.

3.3 The <extension> elements

The extension element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of XBMC that the add-on extends. For instance, the addon.xml file for the Confluence skin above extends the "xbmc.gui.skin" part of XBMC. Other extension points are given below.

3.4 The xbmc.addon.metadata extension

This special extension point must be provided by all add-ons, and is the way that your add-on is described to users of the XBMC add-on manager. There are 4 elements that this should contain, though only the first is compulsory:

  • One or more summary elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages, whereby each has a lang="ch" attribute. No lang attribute indicates English.
  • One or more description elements provide a more detailed summary of what the add-on does. Again, these can be translated.
  • One or more disclaimer elements that indicate what (if any) things the user should know about the add-on. There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here.
  • A platform tag which specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so "all" is an option, as are "linux", "osx", "windx" and "wingl". If the platform tag is missing, we assume the add-on runs on all platforms.

4 Types of Extension

The various extension points that XBMC provides are given in the list below.

Personal tools
Namespaces

Variants
Actions
Navigation
Wiki help
Toolbox