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(const kodi::addon::IInstanceInfo& instance);
 
  void GetCapabilities(kodi::addon::PeripheralCapabilities& capabilities) override;
  ...
};
 
CMyPeripheralAddon::CMyPeripheralAddon(const kodi::addon::IInstanceInfo& instance)
  : CInstancePeripheral(instance)
{
  ...
}
 
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(const kodi::addon::IInstanceInfo& instance,
                              KODI_ADDON_INSTANCE_HDL& hdl) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(const kodi::addon::IInstanceInfo& instance,
                                      KODI_ADDON_INSTANCE_HDL& hdl)
{
  if (instance.IsType(ADDON_INSTANCE_PERIPHERAL))
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my peripheral addon");
    addonInstance = new CMyPeripheralAddon(instance);
    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.

Topics
	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 ( const IInstanceInfo & instance )

inlineexplicit

Peripheral addon class constructor used to support multiple instance types.

Parameters

[in]

instance

The instance value given to kodi::addon::CAddonBase::CreateInstance(...).

---

~CInstancePeripheral()

~CInstancePeripheral ( )

overridedefault

Destructor.