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:
- The application detects the event through the Gamepad API.
- The Gamepad API requests information about the event from the "gamepad-service" process through the GDBus.
- 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.
- 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:
-
Download the userwidget.zip file to your computer.
-
Extract the ZIP file content to a folder named "userwidget" on a USB flash drive.
-
Connect the USB flash drive to the TV.
The GamepadChecker application installs automatically.
Figure 3. GamepadChecker application installed -
Connect your USB or Bluetooth gamepad to the TV.
NoteIf your gamepad connects through Bluetooth, you must first pair it to the TV. -
To launch the GamepadChecker application, on the TV, go to "Apps > Downloaded App".
Figure 4. GamepadChecker application icon -
Test your gamepad keys in the GamepadChecker application.
Figure 5. GamepadChecker application screenNoteIf 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 rumbleNoteTV 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
- If any keys generate unexpected behavior, check that your firmware, key mapping, and driver codes are implemented correctly.
- You can also test the gamepad behavior in the Samsung TV Internet application, on any website of your choice.
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.