RDK

RDK Resources

RDK Preferred

Code Management Facility

Code Releases

RDK Forums

[RDK Conferences]

RDK Support

Archives

Papers & Presentations Archive

In the News!

Skip to end of metadata
Go to start of metadata


Versions

org.rdk.RDKShell.1

RDKShell controls the management of composition, layout, Z order, and key handling

Methods


moveToFront (v1)

Description:  moves the client to the front or top of the Z order

Arguments:

  • client - the name of the client to move to the front

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.moveToFront", "params":{ "client": "org.rdk.Netflix"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



moveToBack (v1)

Description:

Arguments:

  • client - the name of the client to move to the back or bottom of the Z order

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.moveToBack", "params":{ "client": "org.rdk.Netflix" }}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



moveBehind (v1)

Description:  Moves the client behind the specified target

Arguments:

  • client - the client to move
  • target - the target in which the client will move behind

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.moveBehind", "params":{ "client": "org.rdk.Netflix", "target": "org.rdk.RDKBrowser2"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


setFocus (v1)

Description:  Sets focus to the specified client

Arguments:

  • client - the client to move

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setFocus", "params":{ "client": "org.rdk.Netflix" }}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



kill (v1)

Description: Kills the client

Arguments:

  • client - name of the client to kill

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.kill", "params":{ "client": "org.rdk.Netflix" }}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



addKeyIntercept (v1)

Description:  Adds a key intercept to the client application specified.  The keys are specified by key code and a set of modifiers.  Regardless of the application that has focus, key presses that match the key code and modifiers will be sent to the client application

Arguments:

  • keyCode - the key code of the key to intercept
  • modifiers - list of modifiers that need to be present to intercept
  • client - the client to receive the key presses

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.addKeyIntercept", "params":{ 
              "keyCode": 10, 
              "modifiers": ["alt", "shift"], 
              "client": "org.rdk.Netflix" }}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



removeKeyIntercept (v1)

Description:  Removes the key intercept

Arguments:

  • keyCode - the key code of the key to intercept
  • modifiers - list of modifiers that need to be present to intercept
  • client - the client to receive the key presses

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.removeKeyIntercept", "params":{"keyCode": 10, "modifiers": ["alt", "shift"], "client": "org.rdk.Netflix"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



getScreenResolution (v1)

Description:  gets the screen resolution

Arguments:  none

Returns:

  • w - width
  • h - height
Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getScreenResolution", "params":{ }}

Response: {"jsonrpc":"2.0", "id":3, "result": {"w": 1920, "h": 1080} }



setScreenResolution (v1)

Description:  Sets the screen resolution

Arguments:

  • w - width
  • h - height

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setScreenResolution", "params":{ "w": 1920, "h": 1080 }}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



getClients (v1)

Description:  Gets a list of clients

Arguments:  none

Returns:

  • clients: array
Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getClients", "params":{ }}

Response: {"jsonrpc":"2.0", "id":3, "result": { "clients": ["org.rdk.Netflix", "org.rdk.RDKBrowser2"]} }



getZOrder (v1)

Description:  returns an array of clients in Z order, starting with the top most application client first

Arguments:  none

Returns:

  • clients:  array
Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getZOrder", "params":{ }}

Response: {"jsonrpc":"2.0", "id":3, "result": { "clients": ["org.rdk.Netflix", "org.rdk.RDKBrowser2"]} }



getBounds (v1)

Description:  gets the bounds of the specified client

Arguments: 

  • client

Returns:

  • x - the x location
  • y - the y location
  • w - width
  • h - height

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getBounds", "params":{ "client": "org.rdk.RDKBrowser2"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {
             "x": 0,
             "y": 0,
             "w": 600,
             "h": 400} }



setBounds (v1)

Description: sets the bounds of the specified client

Arguments:

  • client
  • x - the x location
  • y - the y location
  • w - width
  • h - height

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setBounds", "params":{ 
             "client": "org.rdk.RDKBrowser2",
             "x": 0,
             "y": 0,
             "w": 600,
             "h": 400
}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



getVisibility (v1)

Description: gets the visibility of the specified client

Arguments:

  • client

Returns:

  • visible
Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getVisibility", "params":{ "client": "org.rdk.Netflix" }}

Response: {"jsonrpc":"2.0", "id":3, "result": {"visible": true} }



setVisibility (v1)

Description:

Arguments:

  • client
  • visible

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setVisibility", "params":{ "client": "org.rdk.Netflix", "visible": true }}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



getOpacity (v1)

Description:  gets the opacity of the specified client

Arguments:

  • client

Returns:

  • opacity
Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getOpacity", "params":{ "client": "org.rdk.Netflix"}}

Response: {"jsonrpc":"2.0", "id":3, "result": { "opacity" : 100} }



setOpacity (v1)

Description: Sets the opacity of the given client

Arguments:

  • client
  • opacity

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setOpacity", "params":{ "client": "org.rdk.Netflix", "opacity": 100}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }

enableInactivityReporting (v1)

Description: Enables or disables inactivity reporting and events

Arguments:

  • enable - enables/disables inactivity reporting (boolean)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.enableInactivityReporting", "params":{ "enable": true}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }

setInactivityInterval (v1)

Description: Sets the inactivity notification interval

Arguments:

  • interval - the inactivity event interval in minutes (integer)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setInactivityInterval", "params":{ "interval": 15}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


addKeyListener (v2)

Description: Adds a key listener to an app.  The keys are bubbled up based on their z-order


Arguments:

  • keyCode - the key code of the key to intercept (integer)
  • modifiers - list of modifiers that need to be present to intercept
  • client - the client to receive the key presses (string)
  • activate - activate app on key event.  default is false (boolean)
  • propagate - propagate to the next app in the z-order.  default is true (boolean)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.addKeyListener", "params":{
              "keys": [{
              "keyCode": 49,
              "modifiers": [],
             "activate":false,
             "propagate":true
              }, {
              "keyCode": 50,
              "modifiers": [],
             "activate":false,
             "propagate":true
              }],
              "client": "org.rdk.Netflix" }}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



removeKeyListener (v2)

Description: Removes a key listener for an app


Arguments:

  • keyCode - the key code of the key to intercept (integer)
  • modifiers - list of modifiers that need to be present to intercept
  • client - the client to receive the key presses (string)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.removeKeyListener", "params":{"keys": [{
              "keyCode": 49,
              "modifiers": []
              }, {
              "keyCode": 50,
              "modifiers": []
              }],
              "client": "org.rdk.Netflix" }}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


addAnimation (v2)

Description: Performs a set of animations


Arguments:

  • animations - list of animations to perform
  • client - the of the client to animate (in list) (string)
  • x - the x location
  • y - the y location
  • w - width
  • h – height
  • sx - x scale factor (double)
  • sy - y scale factor (double)
  • a - alpha/opacity level to animate to (between 0 and 100)
  • duration - duration of animation in seconds (double)
  • tween - the animation tween type.  supported tweens are: linear, exp1, exp2, exp3, inquad, incubic, inback, inelastic, outelastic, outbounce.  the default is linear (string)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.addAnimation", "params":{"animations": [{
         "client": "HtmlApp",
         "x":0, "y":0, "w":1920, "h":1080, "duration":"3"
         }, 
		 {
           "client": "ResidentApp",
           "x":0, "y":0, "w":0, "h":0, "sx":0.5, "sy":0.5, "duration":"2"
		 }
         ]}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


setScale (v2)

Description: Scale an application


Arguments:

  • client - the client to scale (string)
  • sx - x scale factor (double)
  • sy - y scale factor (double)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.setScale", "params":{"client": "ResidentApp", "sx":1.5, "sy":1.5}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


getScale (v2)

Description: Scale an application


Arguments:

  • client - the client to scale (string)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getScale", "params":{"client": "ResidentApp"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {"sx":1.5, "sy":1.5} }



generateKey (v2)

Description: Triggers key events (key press and release)


Arguments:

  • keys - list of keys to simulate
  • keyCode - the key code of the key to intercept (integer)
  • modifiers - list of modifiers (as strings) that need to be present to intercept ("ctrl", "alt", and "shift" are supported)
  • delay – the amount of time to wait (in seconds) before sending the key event (double)
  • callsign - the app to send the key event to (optional)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.generateKey", "params":{
   "keys":[ {
               "keyCode": 49,
               "modifiers": [],
               "delay":1.0,
               "callsign":"appName"
             },
             {
               "keyCode": 50,
               "modifiers": [],
               "delay":2.0
             }
          ]
}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



launch

Description: Launches an application


Arguments:

  • type – the id of the runtime package or the callsign of the plugin desired to be clone (string). Required for create
  • version – version of the package. Default to latest version
  • uri: uri of app to launch
  • x, y, w, h – positioning (integers). Defaults to 0, 0, screen width, screen height
  • suspend – suspend the app on launch (boolean). Default is false
  • visible – visible on launch (boolean). Default is true. This will be false if launch to suspended is true
  • focused – app is focused on launched (boolean). Default is true. The app cannot be focused if visible is false
  • configuration – json object specifying the plugin configuration overrides. Empty by default
  • behind – client to put behind (string). Default to top of z-order
  • displayName – name of the display to create

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.launch", "params":{"callsign": "app1", "type":"HtmlApp", "uri":"https://www.example.com", "x":0, "y":0, "w":1920, "h":1080}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


suspend (v2)

Description: Suspend an application


Arguments:

  • callsign - the client to suspend (string)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.suspend", "params":{"callsign": "Cobalt"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }


destroy (v2)

Description: destroys an application


Arguments:

  • client - the client to destroy (string)

Returns: none

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.destroy", "params":{"callsign": "Cobalt"}}

Response: {"jsonrpc":"2.0", "id":3, "result": {} }



getAvailableTypes (v2)

Description: returns the list of application types available on the firmware.


Arguments: none

Returns: list of available application types

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getAvailableTypes", "params":{}}

Response: {"jsonrpc":"2.0", "id":<number>, "result": {”types":[
"LightningBrowser", "HtmlBrowser", "Cobalt", "Netflix"], "success" : true} }


getState (v2)

Description: returns the list of application types available on the firmware.


Arguments: none

Returns:

  • state – state of the runtime (e.g. ["resumed", "suspended"]) (string)
  • callsign – callsign of the runtime (string) uri – the uri/url the package is set to (string)

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getState", "params":{}}

Response:  {"jsonrpc":"2.0", "id":<number>, "result": {"runtimes":[

{"callsign":"netflix1", "state":"suspended", "uri":"https://…. "},

{"callsign":"cobalt1", "state":"resumed", "uri":"https://…. "}
], "success": true} }


getSystemResourceInfo (v2)

Description: returns the list of application types available on the firmware.


Arguments: none

Returns:

  • callsign – callsign of the runtime (string)
  • ram – the amount of memory the runtime is consuming in kB (integer)
  • vram – the amount of graphics memory runtime is using in kB (integer) (if supported)

Request : {"jsonrpc":"2.0", "id":3, "method":"org.rdk.RDKShell.1.getSystemResourceInfo", "params":{}}

Response:   {"jsonrpc":"2.0", "id":<number>, "result": {"runtimes":[
{"callsign":"netflix1", "ram":123, "vram":50},
{"callsign":"html1", "ram":123, "vram":50},
{"callsign":”cobalt1", "ram":123, "vram":50}], "success": true} }


Events

onUserInactivity (v1)

Description: An event that is broadcasted when a device has been inactive for a period of time.  This event is broadcasted at the frequency specified by setInactivityInterval if the device is not active.  The default frequency is 15 minutes.

Parameters:

  • minutes - The number of minutes that the device has been inactive (double)

onLaunched (v1)

Description: An event that is broadcasted when an runtime is launched

Parameters:

  • client - the callsign of the plugin/runtime that was launched
  • launchType - create, activate, suspend, or resume

onSuspended (v1)

Description: An event that is broadcasted when an runtime is suspended

Parameters:

  • client - the callsign of the plugin/runtime that was suspended

onDestroyed (v1)

Description: An event that is broadcasted when an runtime is destroyed

Parameters:

  • client - the callsign of the plugin/runtime that was destroyed
  • No labels

16 Comments

  1. Z-bing.jiang

    keys miss “” in addKeyListener and removeKeyListener

    1. Ganesh Sahu

      Z-bing.jiang Can you please provide more details on the issue, the device on which this issue is observed and how to reproduce it?

      1. Arkadiusz Radoń

        It is:

        "params":{
          keys: [{
            "keyCode": 49,

        And should be:

        "params":{
          "keys": [{
            "keyCode": 49,


        In the examples here on the wiki in sections mentioned by bing.jiang

        1. Ganesh Sahu

          corrected the pointed errors.

  2. bkskoti

    Hi ,

    I enabled RDKShell in STB and able to run above commands, when I tried getclients command, getting getClients as empty.

    is there any steps how to create/integrate simple html/third-party app into rdkshell and test?

    1. Steve Ford

      If you launch something using RDKShell then it should be listed as a client, e.g. (I'm running these commands from a PC):

      > curl --data-binary '{"jsonrpc":"2.0","id":1,"method":"org.rdk.RDKShell.1.launch","params":{"callsign":"Cobalt"}}' http://<ipaddr>:9998/jsonrpc
      {"jsonrpc":"2.0","id":1,"result":{"launchType":"activate","success":true}}

      > curl --data-binary '{"jsonrpc":"2.0","id":2,"method":"org.rdk.RDKShell.1.getClients"}' http://<ipaddr>:9998/jsonrpc
      {"jsonrpc":"2.0","id":2,"result":{"clients":["cobalt"],"success":true}}


      1. bkskoti

        When i tried above commands for simple app i was getting below error and webkit was crashing/killing

        2021 Jan 11 11:29:10.129453 mediabox WPEFramework[8774]: 1610364550127: ERROR: ../git/drm/westeros-gl/westeros-gl.c:4993 westeros-gl: wstGLInit: unable to resolve eglGetDisplay.



        1. Michael Fiess

          It sounds like we may need to debug this issue to get to the bottom of this problem you're seeing.  Please feel free to reach out to me, and we'll find a time that is convenient for you to debug this issue together.

          1. bkskoti

            Hi Fiess,

            I tried solving above issue. But got some other issue when  tried to run the rdkshell

            ./rdkshell
            initializing rdk shell
            Ignored file read due to keyMap env not set
            Ignored file read due to input devices environment variable not set
            key initial delay: 500 repeat interval: 100
            Essos Info: westeros (essos) version 1.01.19
            Essos Info: westeros (essos) config supports: direct 1 wayland 1
            1613628651578: ERROR: ../git/drm/westeros-gl/westeros-gl.c:4991 BKS start
            1613628651578: ERROR: ../git/drm/westeros-gl/westeros-gl.c:5024 BKS END
            1613628651578: INFO: ../git/drm/westeros-gl/westeros-gl.c:2895 opened /dev/dri/card0: master 0
            1613628651578: INFO: ../git/drm/westeros-gl/westeros-gl.c:3051 wstInitCtx: current mode 1280x720@60
            Essos Info: displaySizeCallback: display size 1280x720
            Essos Info: displaySizeCallback: display safe (64,36,1152,648)
            Essos error during initialization: Error. Unable to get EGL display: eglError 3000
            Essos Info: essResize 1280x720

            Can you tell me when and how we can connect?

            1. Deepthi Suseelan

              bkskoti

              Can you please post the contents of your wpeframework.service file. Also the platform which you are using.

              1. bkskoti

                Deepthi Suseelan 

                I am using realTek(arm) and wpeframework.service content is 


                [Unit]
                Description=wpeframework
                Before=xre-receiver.service
                After=lighttpd.service iarmbusd.service pwrmgr.service irmgr.service dsmgr.service sysmgr.service authservice.service

                [Service]
                PIDFile=/var/run/WPEFramework.pid
                EnvironmentFile=-/etc/wpeframework/WPEFramework.env
                Environment="WAYLAND_DISPLAY=wayland-0"
                Environment="XDG_RUNTIME_DIR=/tmp"
                Environment="XDG_DATA_HOME=/opt/QT/home"
                Environment="LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib:/usr/lib/realtek"
                Environment="LD_PRELOAD=/usr/lib/libwayland-client.so.0:/usr/lib/libwayland-egl.so.0:/usr/lib/realtek/libVOutWrapper.so:/usr/lib/realtek/libjpu.so:/usr/lib/realtek/libvpu.so:/usr/lib/libwesteros_gl.so.0"
                Environment="GST_PLUGIN_PATH=$GST_PLUGIN_PATH:/usr/lib/gstreamer-1.0"
                Environment="GST_DEBUG=2"
                ExecStart=-/usr/bin/WPEFramework -b
                #ExecStop=/bin/kill $MAINPID
                #Restart=always
                #KillMode=mixed
                Restart=no
                KillSignal=SIGKILL

                [Install]
                WantedBy=multi-user.target

                1. Deepthi Suseelan

                  bkskoti

                  The LD_PRELOAD requirement for any platform is based on whether there is a need to overload certain EGL methods. On some platforms, wayland EGL implementation is separate from the EGL implementation and hence the need to preload libwayland-egl.so.
                  On platforms using westeros drm backend (which I assume Realtek is), libwesteros-gl.so needs to overload some EGL methods and hence the need to preload libwesteros_gl.so

                  Can you please try removing the preload of libwayland-egl.

                  1. bkskoti

                    With your suggested change, During box bootup i am getting below error and WPEFramework is crashing.

                    initializing rdk shell
                     Ignored file read due to keyMap env not set
                     Ignored file read due to input devices environment variable not set
                    key initial delay: 500 repeat interval: 100
                    INFO [AbstractPlugin.h:67] AbstractPlugin:
                    INFO: ../git/drm/westeros-gl/westeros-gl.c:2895 opened /dev/dri/card0: master 0
                    INFO [SystemServices.cpp:253] SystemServices: first boot so setting mode to 'NORMAL' ('/tmp/system_service_temp.conf' does not contain("mode"))
                    WARN [SystemServices.cpp:694] setMode: request to switch to mode 'NORMAL' from mode '' with duration -1
                    INFO: ../git/drm/westeros-gl/westeros-gl.c:3051 wstInitCtx: current mode 1280x720@60
                    INFO: ../git/drm/westeros-gl/westeros-gl.c:5479 native window: wxh=1280x720
                    INFO: ../git/drm/westeros-gl/westeros-gl.c:3586 choosing output mode: 1280x720x60

                    1. Deepthi Suseelan

                      bkskoti 

                      Can you also please share the rdkshell "launch" command you used to launch the application. 

  3. Steve Ford

    Can you provide some more info for some of the APIs, such as what values are possible for the "type" argument for the "launch" command?

    Can a normal executable to started using RDKShell, such as the essos-sample demo app, and if so, how would this be done?

    1. Michael Fiess

      Hey Steve, you can run the RDKShell getAvailableTypes API to learn of the available types that are configured on your device. 

      RDKShell does provide a way to launch a normal executable as well.  This support was recently added.  We will update the documentation on new APIs available to accomplish this in a few days.

DISCLAIMER: Please note that the use of the RDK Wiki is subject to its Privacy Policy & Terms of Use. In addition, this Wiki may be accessed by all RDK licensees and their contractors.