Tutorials

Interaction with the remote control

Introduction

This example will build on our Hello world example and will demonstrate the interaction of HbbTV applications with remote control. Remote control keys supported within applications are set within the ETSI TS 102 796 V1.1.1 standard document, chapter 10.2.2 User input:

Button (for conventional remote controls)Key eventStatus
4 colour buttons (red, green, yellow, blue)VK_RED, VK_GREEN, VK_YELLOW, VK_BLUEMandatory
4 arrow buttons (up, down, left, right)VK_UP, VK_DOWN, VK_LEFT, VK_RIGHTMandatory
ENTER or OK buttonVK_ENTERMandatory
BACK buttonVK_BACKMandatory
Number keysVK_0 to VK_9 inclusiveMandatory
Play, stop, pauseVK_STOP and either VK_PLAY and VK_PAUSE or VK_PLAY_PAUSEMandatory
Fast forward and fast rewindVK_FAST_FWD VK_REWINDMandatory
TEXT or TXT or comparable buttonNot available to applicationsMandatory
2 program selection buttons (e.g. P+ and P-)Not available to applicationsOptional
WEBTV or comparable buttonNot available to applicationsOptional
EXIT or comparable buttonNot available to applicationsOptional

Beware that the applications themselves define which key events they request to receive. This is done by setting the KeySet object to a bitwise mask constructed from the constants in the following table:

Constant nameNumeric ValueUse
RED0x1Used to identify the VK_RED key event.
GREEN0x2Used to identify the VK_GREEN key event.
YELLOW0x4Used to identify the VK_YELLOW key event.
BLUE0x8Used to identify the VK_BLUE key event.
NAVIGATION0x10Used to identify the VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT, VK_ENTER and VK_BACK key events.
VCR0x20Used to identify the VK_PLAY, VK_PAUSE, VK_STOP, VK_NEXT, VK_PREV, VK_FAST_FWD, VK_REWIND, VK_PLAY_PAUSE key events.
SCROLL0x40Used to identify the VK_PAGE_UP and VK_PAGE_DOWN key events.
INFO0x80Used to identify the VK_INFO key event.
NUMERIC0x100Used to identify the number events, 0 to 9.
ALPHA0x200Used to identify all alphabetic events.
OTHER0x400Used to indicate key events not included in one of the other constants in this class.

Implemented functionality

The example application, once started, shall demonstrate a typical red button scenario, when the application at first only reacts to the red button which, when pressed, invokes the full application that requests to receive more key events. To keep this example minimal, we will not use an image for the call-to-action banner:

In this state, the app receives only the red button event and reacts to it by showing the full application scene:

When full application scene is active, the app will react to all coloured RC buttons as follows:

  • RED BUTTON to hide the scene and go back to call-to-action scene
  • GREEN BUTTON to enable / disable reception of playback RC buttons (PLAY / PAUSE / STOP / FFWD / RWD) by the app
  • YELLOW BUTTON to enable / disable reception of numeric RC buttons (0 … 9) by the app
  • BLUE BUTTON to prevent reception of all RC buttons by the app for 10 seconds

When the full application scene is active, the app will also show the last RC button pressed on screen.

Source code

Full source code is available here: https://github.com/HbbTV-Association/Tutorials/tree/main/rc-interaction

The code consists of:

  • rc-interaction.html HTML document holding the application scene
  • rc-interaction.css CSS document holding the application scene styling
  • rc-buttons.js JavaScript file which defines global variables for RC button events and 2 utility functions
  • rc-interaction.js JavaScript file holding the application logic

rc-interaction.html

Application HTML document rc-interaction.html starts off as a “usual” HbbTV app (see Hello world example):

<!DOCTYPE html PUBLIC "-//HbbTV//1.1.1//EN" "http://www.hbbtv.org/dtd/HbbTV-1.1.1.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>RC interaction demo app</title>
    <meta http-equiv="Content-Type" content="application/vnd.hbbtv.xml+xhtml; utf-8" />
    <link rel="stylesheet" href="rc-interaction.css" />
    <script type="text/javascript" src="rc-buttons.js"></script>
    <script type="text/javascript" src="rc-interaction.js"></script>
</head>
<body onload="start();">
    <div>
        <object type="application/oipfApplicationManager" id="applicationManager"> </object>
    </div>

Observe that 2 JS documents are loaded:

  • rc-buttons.js which defines global variables for RC button events and 2 utility functions
  • rc-interaction.js which contains the application logic

The onload attribute of the body tag calls the app entry function start(). Document body also includes the  application/oipfApplicationManager embedded object which is used within application logic in order to acquire the Application object, as set by standard.

The rest of the rc-interaction.html document contains main application scene within the safe area as recommended by the standard and a separate div outside of safe area containing the red button call to action notification:

In order to keep this example as simple as possible the call-to-action banner (Press the red button on the RC to start!) is implemented as text.

rc-interaction.css

The rc-interaction.css starts with HbbTV specifics explained in the Hello world example.

The difference in this example is that initial visibility state of safe area (containing main application scene) is set to hidden since on application start only red button call-to-action notification is visible:

Red button call-to-action notification div and text style (contains nothing specific for HbbTV):

Main scene and bottom legend style concludes the CSS (contains nothing specific for HbbTV):

rc-buttons.js

The rc-buttons.js defines global variables for RC button events:

Key events for different RC buttons are defined in KeyEvent class, but we choose to define global variables, since we want to add support for key events on emulators running on computer browsers which receive input from a computer keyboard, which we do like so:

This approach ensures that we always have a global variable defined for every key event. The rest of rc-buttons.js defines 2 utility functions:

  • setKeyset(app, mask), which is used to set a KeySet mask (this is how applications define which key events they request to receive). This example application is built for maximum compatibility, so in order to support terminals implementing version 1.1.1 of the ETSI TS 102 796 standard the  setKeyset(app, mask) function has to compensate for a change in OIPF DAE Application class private property name change to privateData (OIPF DAE specification version 1.1 to version 1.2);
  • registerKeyEventListener(), which is used to invoke the callback function for processing RC button events (in our case it is the handleKeyCode(kc) function);

rc-interaction.js

The rc-interaction.js starts of with scene initialization implementation:

Followed by utility function used to show / hide main scene and retrieve the KeySet mask relevant for current state of main scene (numeric / playback RC buttons enabled or disabled):

Main application scene is rendered using the render() function:

When a user presses the BLUE RC button, all user input is disabled for 10 seconds. This is a demonstration of controlling the RC button events application will receive when setting the keyset value to different button masks. The waiting is implemented in timerTick() function like so:

RC button events handling is implemented in handleKeyCode(kc) function:

Observe that the key handler function code ends with returning true to suppress the default behaviour of the terminal for the pressed RC button.

The rc-interaction.js ends with app entry function:

This function tries to acquire the Application object and, when successful, initializes and shows it’s user interface (initial state set by CSS is app_area hidden, red button call-to-action banner visible).