Gamepad Accessory Development

Gamepad buttons can be used to control a Smart TV in the same way as a TV remote control. For gaming applications, you can also implement specific functionalities for each button.

This topic describes the Gamepad framework for Samsung Smart TVs. It lists the supported TVs, drivers, and gamepads, outlines the structure of the Gamepad framework, and lists the event types and codes for gamepad buttons. To ensure your gamepad functions correctly with Smart TVs, this topic also provides a testing application that you can use to test and debug your gamepad button implementation.

Specifications

The following table lists the Tizen platform and kernel version for the supported TV model years.

TV model year	Platform version	Kernel version
2023	Tizen 7.0	5.4.77
2022	Tizen 6.5	5.4.77
2021	Tizen 6.0	4.1.10

Table 1. Supported TV models, platform versions, and kernel versions

The Gamepad framework for Smart TV supports the following drivers:

• /drivers/hid/hid-amazon.c
• /drivers/hid/hid-generic.c
• /drivers/hid/hid-microsoft.c
• /drivers/hid/hid-nvidia.c
• /drivers/hid/hid-playstation.c
• /drivers/hid/hid-sony.c
• /drivers/input/joystick/xpad.c
• xpadneo

The Gamepad framework supports a range of gamepads. For the list of supported gamepads, refer to the Samsung TV E-manual from the Samsung Electronics retail website.

System Structure

The following figure is a simplified schematic of the gamepad system on Samsung Smart TVs.

Figure 1. Gamepad system structure

When a gamepad button is pressed:

1. The application detects the event through the Gamepad API.
2. The Gamepad API requests information about the event from the "gamepad-service" process through the GDBus.
3. The "gamepad-service" process retrieves from the device node the driver key code that was generated by the gamepad button press, and maps it to the corresponding Samsung TV Platform key code.
4. The "gamepad-service" process returns the Platform key code through the Gamepad API to be handled by the application.

Gamepad Service Modes

The "gamepad-service" process manages gamepad input. It operates in different modes depending on the active window on the TV screen:

• Menu mode
  The "gamepad-service" process starts in Menu mode when the TV is powered on. In Menu mode, the gamepad functions as a TV remote control for navigating TV menus, Smart Hub, and menus in non-gaming applications, such as Netflix or YouTube:
  • The D-pad buttons navigate Up, Down, Left, and Right.
  • The "A" button functions as the "Enter" key.
  • The "B" button functions as the "Return" key.
• Game mode
  When a game application is launched, the "gamepad-service" process switches to Game mode. In Game mode, the function of each gamepad button and stick is defined by the game application.

Key Code Mapping

The "gamepad-service" process maps each driver key code to its corresponding Samsung TV Platform key code. You must implement each key press event to generate the appropriate driver key code.

The following figure illustrates the various buttons on the gamepad.

Figure 2. Gamepad buttons

Key Events

The EV_KEY event type describes state changes of buttons, keyboards, and other key-like devices. On a gamepad, button press and release events are detected as EV_KEY events.

The following table lists the driver and platform code mappings for EV_KEY events. The labels correspond to those in Figure 2.

Label	Driver Code	Platform Code	Description
1	0x130	0x00	"A" button
2	0x131	0x01	"B" button
3	0x133	0x02	"X" button
4	0x134	0x03	"Y" button
5	0x136	0x04	Left bumper
6	0x137	0x05	Right bumper
7	0x13d	0x0a	Left stick button
8	0x13e	0x0b	Right stick button
9	0x13a	0x0c	"Select" button
10	0x13b	0x0d	"Start" button
11	0x13c	0x0e	"Home" button

Table 2. "EV_KEY" event driver and platform codes

Absolute Axis Events

The EV_ABS event type describes absolute axis value changes, such as coordinates or movement along the horizontal or vertical axis. On a gamepad, the thumb sticks, D-pad, and trigger buttons are detected as EV_ABS events.

The following table lists the driver and platform code mappings for EV_ABS events. The labels correspond to those in Figure 2.

Label	Driver Code	Platform Code	Description
7	0x00	0x00	Horizontal axis (Left stick)
7	0x01	0x01	Vertical axis (Left stick)
8	0x03	0x03	Horizontal axis (Right stick)
8	0x04	0x04	Vertical axis (Right stick)
12	0x10	0x10	Horizontal axis (D-pad)
12	0x11	0x11	Vertical axis (D-pad)
13	0x02	0x02	Left trigger button
14	0x05	0x05	Right trigger button

Table 3. "EV_ABS" event driver and platform codes

For more information on event types and codes, see the kernel documentation.

Testing Gamepad Functionality

To test the gamepad functionality of your application on a Samsung TV, use the GamepadChecker application:

1. Download the userwidget.zip file to your computer.

2. Extract the ZIP file content to a folder named "userwidget" on a USB flash drive.

3. Connect the USB flash drive to the TV.
   The GamepadChecker application installs automatically.

   
   Figure 3. GamepadChecker application installed

4. Connect your USB or Bluetooth gamepad to the TV.

   NoteIf your gamepad connects through Bluetooth, you must first pair it to the TV.

5. To launch the GamepadChecker application, on the TV, go to "Apps > Downloaded App".

   
   Figure 4. GamepadChecker application icon

6. Test your gamepad keys in the GamepadChecker application.

   
   Figure 5. GamepadChecker application screen

   NoteIf your gamepad support rumble, the gamepad will vibrate when you press the left trigger button or right trigger button (label 13 or label 14 in Figure 2)

   
   Figure 6. GamepadChecker application screen when rumble

   NoteTV supports multiple gamepads connection, max supported count is 4. When 2 gamepads are connected, applicaiton shows in this way:

   
   Figure 7. GamepadChecker application screen when connet two gamepads

FAQ