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.

  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


    Figure 6. GamepadChecker application screen when rumble


    Figure 7. GamepadChecker application screen when connet two gamepads


FAQ

For the list of supported gamepads, refer to the Samsung TV E-manual from the Samsung Electronics retail website.

A maximum of 4 controllers can be connected to the TV simultaneously.

For detailed instructions on pairing your controller to the TV, go to Pair a Bluetooth controller or gamepad to your Samsung TV.