RDKShell Configuration

Created on June 21, 2022

The complexity of the configuration of RDKShell is increasing. Perhaps the time has come to consider a configuration file. This page suggests a possible format for one and how it would work alongside the current environment variables approach.

Environment Variables

Currently RDKShell is configured by a series of environment variables.

Name

Type

Default

Description

RDKSHELL_CRITICALLY_LOW_MEMORY_THRESHOLD

integer
The number of Mb of free memory below which to send a critical notification to clients.

RDKSHELL_ENABLE_IPC

Boolean (“0” or “1”)false

RDKSHELL_ENABLE_WS_IPC

Boolean (“0” or “1”)

false

RDKSHELL_EASTER_EGG_FILE

file path

RDKSHELL_EXTENDED_INPUT_ENABLEDBooleanfalseWhether the Westeros “rdkshell_extended_input” plugin is loaded.
RDKSHELL_FRAMERATEinteger
Desired framerate.
RDKSHELL_INPUT_DEVICES_CONFIGfile path
A JSON file containing input device configuration.

RDKSHELL_KEY_INITIAL_DELAY

integer500Initial delay before repeating key in milliseconds.

RDKSHELL_KEY_REPEAT_INTERVAL

integer100Interval at which key repeats.
RDKSHELL_KEYMAP_FILEfile path

RDKSHELL_LOG_LEVEL

“debug”,

“info”,

“warn”,

“error”,

“fatal”


Set the logging level to use.
RDKSHELL_LOW_MEMORY_THRESHOLDinteger
The number of Mb of free memory below which to send a notification to clients.

RDKSHELL_SERVER_ADDRESS

network address“localhost”

RDKSHELL_SERVER_PORT

integer9996

Proposed Configuration File

Since JSON has been used for other configuration files in RDKShell then I would suggest JSON again.

Currently all fields will be optional since RDKShell does not require any environment variables to be set.

The top-level JSON object has fields:

Field

Description

loggingRelated to logging
resource_usageRelated to the resource usage of RDKShell
inputRelated to inputs handled by RDKShell
commsRelated to communication with RDKShell

where the values associated with all fields are JSON objects.

Logging

The logging JSON object would initially only have the following field:

Field

Type

Description

Environment Variable

level

“debug”,

“info”,

“warn”,

“error”,

“fatal”

The level of logging to use.RDKSHELL_LOG_LEVEL

Resource Usage

The resource usage JSON object would initially have a single field “memory” with an associated JSON object. This JSON object would have the following fields:

Field

Type

Description

Environment Variable

critical_low_thresholdintegerSend client critical notifications if this threshold is breached.RDKSHELL_CRITICALLY_LOW_MEMORY_THRESHOLD
low_thresholdintegerSend clients notifications if this threshold is breached.RDKSHELL_LOW_MEMORY_THRESHOLD

So the path would be ‘config["resource_usage"]["memory"]["low_threshold"]‘.

Input

The input JSON object has the following fields.

Field

Type

Description

Environment Variable

keyobjectConfiguration related to keys.
device_configfile pathA file containing configuration for the device.RDKSHELL_INPUT_DEVICES_CONFIG
easter_egg_filefile path
RDKSHELL_EASTER_EGG_FILE
pluginfilenameAn external Westeros plugin to support custom input events.~ RDKSHELL_EXTENDED_INPUT_ENABLED

where the key JSON object has the following fields.

Field

Type

Description

Environment Variable

initial_delayintegerInitial delay before repeating key in milliseconds.RDKSHELL_KEY_INITIAL_DELAY
repeat intervalintegerInterval at which key repeats in milliseconds.RDKSHELL_KEY_REPEAT_INTERVAL
map_filefile path
RDKSHELL_KEYMAP_FILE

Comms

The communications JSON object would have the following fields:

Field

Type

Description

Environment Variable

enable_ipcboolean
RDKSHELL_ENABLE_IPC
enable_ws_ipcboolean
RDKSHELL_ENABLE_WS_IPC
server_addressnetwork address
RDKSHELL_SERVER_ADDRESS
server_portinteger
RDKSHELL_SERVER_PORT

Example

An example configuration file could be:

{
    "logging": {
        "level": "debug"
    },
    "resource_usage": {
        "memory": {
            "low_threshold": 100
        }
    },
    "input" : {
        "key" : {
            "repeat_interval": 150,
            "map_file": "/etc/rdkshell/custom_mapping.conf"
        },
        "device_config": "/etc/rdkshell/xi1_inputdevices.conf",
        "plugin": "libwesteros_plugin_rdkshell_extended_input.so"
    }
}

Location

A default location for the configuration file could be a build-time parameter with default locations per OS e.g. “/etc/rdkshell/config.json” for UNIX flavour. Absence of the configuration file implies defaults are used.

Precedence: Environment Variables vs Configuration File

To ensure backwards compatibility supporting both seems sensible. A standard approach is for environment variables to have precedence over the configuration file. Having the configuration printed to log when RDKShell starts will make it easier to see the configuration.


Go To Top