Peripheral

Detailed Description

Class: kodi::addon::CInstancePeripheral

Peripheral add-on instance

The peripheral add-ons provides access to many joystick and gamepad interfaces across various platforms. An input addon is used to map the buttons/axis on your physical input device, to the buttons/axis of your virtual system. This is necessary because different retro systems usually have different button layouts. A controller configuration utility is also in the works.

---

Here is an example of what the addon.xml.in would look like for an peripheral addon:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="peripheral.myspecialnamefor"
  version="1.0.0"
  name="My special peripheral addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="kodi.peripheral"
    provides_joysticks="true"
    provides_buttonmaps="true"
    library_@PLATFORM@="@LIBRARY_FILENAME@"/>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My peripheral addon</summary>
    <description lang="en_GB">My peripheral addon description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

Description to peripheral related addon.xml values:

Name	Description
provides_joysticks	Set to "true" if addon provides joystick support.
provides_buttonmaps	Set to "true" if button map is used and supported by addon.
point	Addon type specification At all addon types and for this kind always "kodi.peripheral".
library_@PLATFORM@	Sets the used library name, which is automatically set by cmake at addon build.

Remarks

For more detailed description of the addon.xml, see also https://kodi.wiki/view/Addon.xml.

---

Here is an example of how addon can be used as a single:

#include <kodi/addon-instance/Peripheral.h>
 
class CMyPeripheralAddon : public kodi::addon::CAddonBase,
                           public kodi::addon::CInstancePeripheral
{
public:
  CMyPeripheralAddon();
 
  void GetCapabilities(kodi::addon::PeripheralCapabilities& capabilities) override;
  ...
};
 
CMyPeripheralAddon::CMyPeripheralAddon()
{
  ...
}
 
void CMyPeripheralAddon::GetCapabilities(kodi::addon::PeripheralCapabilities& capabilities)
{
  capabilities.SetProvidesJoysticks(true);
  capabilities.SetProvidesButtonmaps(true);
  ...
}
 
ADDONCREATOR(CMyPeripheralAddon)

Note

It is imperative to use the necessary functions of this class in the addon.

---

Here is another example where the peripheral is used together with other instance types:

#include <kodi/addon-instance/Peripheral.h>
 
class CMyPeripheralAddon : public kodi::addon::CInstancePeripheral
{
public:
  CMyPeripheralAddon(KODI_HANDLE instance, const std::string& version);
 
  void GetCapabilities(kodi::addon::PeripheralCapabilities& capabilities) override;
  ...
};
 
CMyPeripheralAddon::CMyPeripheralAddon(KODI_HANDLE instance, const std::string& version)
  : CInstancePeripheral(instance, version)
{
  ...
}
 
void CMyPeripheralAddon::GetCapabilities(kodi::addon::PeripheralCapabilities& capabilities)
{
  capabilities.SetProvidesJoysticks(true);
  capabilities.SetProvidesButtonmaps(true);
  ...
}
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  ADDON_STATUS CreateInstance(int instanceType,
                              const std::string& instanceID,
                              KODI_HANDLE instance,
                              const std::string& version,
                              KODI_HANDLE& addonInstance) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  if (instanceType == ADDON_INSTANCE_PERIPHERAL)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my peripheral addon");
    addonInstance = new CMyPeripheralAddon(instance, version);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

The destruction of the example class CMyPeripheralAddon is called from Kodi's header. Manually deleting the add-on instance is not required.

Modules
	Peripheral system
	System description.
	Definitions, structures and enumerators
	Peripheral add-on general variables
	1. Peripheral operations
	Peripheral operations to handle control about.
	2. Joystick operations
	Joystick operations to handle control about.
	3. Callback functions
	Callback to Kodi functions.

Function Documentation

CInstancePeripheral() [1/2]

CInstancePeripheral ( )

inline

Peripheral class constructor.

Used by an add-on that only supports peripheral.

CInstancePeripheral() [2/2]

CInstancePeripheral ( KODI_HANDLE  instance, const std::string &  kodiVersion = ""  )

inlineexplicit

Peripheral addon class constructor used to support multiple instance types.

Parameters

[in]	instance	The instance value given to kodi::addon::CAddonBase::CreateInstance(...).
[in]	kodiVersion	[opt] Version used in Kodi for this instance, to allow compatibility to older Kodi versions.

Note

Recommended to set kodiVersion.

---

~CInstancePeripheral()

~CInstancePeripheral ( )

overridedefault

Destructor.