Hardware Deployment Guide

Operator Pre-requisites

Product Specifications

The first step is to get a fully functional product is to define the product features and see if they meet the standard requirements. For RDK-V (Reference Design Kit for video), the product features and Video Accelerator( the carrier grade , ready to deploy, RDK set top box devices ) specifications are available for operators to choose which features they want to integrate into their target platform. In addition to the standard RDK-V features, operators may want to define and add their own feature requirements ( for e.g. , the video streaming applications which they want to bring to their platform ) too . Furthermore, operators may also need to decide whether to use a pre-built User interface or develop their own, depending on their specific needs and preferences. Additional requirements that need to be defined by operators would include, but not limited to , deciding on the provisioning support as well as disaster recovery mechanisms. 

SoC and OEM selection

Once the product requirements are finalized, the operator can decide from an array of OEMs( preferably RDK certified ) who provide devices powered by SoC platforms that run on RDK-V. Depending on the requirements, the operator may select from a range of RDK Video device profiles from the simple IP STB to the advanced RDK Hybrid TV. Operators also need to consider the SoC platforms who have pre-certification available for some popular streaming apps like Amazon Prime, Netflix etc. so as to reduce time and effort for certifying those third-party apps. In order to support accelerated deployment to markets, RDKM also offers a wide array of Video accelerator devices – the carrier grade , ready to deploy, RDK set top box devices

RDK Architecture

A clear understanding of the RDK architecture, based on the target RDK device profile, is important for operators to understand the support available from RDK for each device type. By leveraging the pluggable architecture of RDK, a variety of target device profiles can be supported, ranging from a basic IP streaming-only STB to a full-fledged RDK TV. 

• RDK Video (RDK-V) IP provides a common method to manage video playback functions. The IP client device serves as an interface and receives video content from an in-home media gateway device or from an external media server. It will have only IP based data streaming without any display of its own Tuner capabilities.
• RDK-V Hybrid STB is an IP STB device along with capabilities such as tuning, conditional access, and stream management with which we can manage complex video functions .
• RDK-V IP TV is a smart TV profile powered by RDK Video stack that brings all your favorite apps, live channels, and On Demand contents together in one place.
• RDK Hybrid TV is a combination of RDK IP TV plus Hybrid capabilities such as tuning, conditional access etc.

RDK Architecture in detail:

The diagram below depicts the device profile-based detailed RDK architecture, focusing on the four main RDK device profiles: RDK IP STB, Hybrid STB, RDK IP TV and RDK Hybrid TV. 

Final Device Firmware

RDK provides the operators a better control of device upgrades thereby facilitating security updates and feature releases to the field in a quick and easy manner.  This is achieved by giving operators the opportunity to easily integrate their software modules and enhancements to the device firmware. RDK firmware builds are generated using the flexible Yocto build system which supports layered architecture thereby facilitating operators to easily and seamlessly plug their software layers to the existing RDK build from SI/OEM vendors.

Yocto Manifests

Yocto based RDK builds are flexible enough to easily accommodate SoC / OEM / Operator / third party changes. There would be a basic RDK build system on which SoC could add their Soc layer, OEM could add their OEM layer and finally Operator could add their Operator layer. The starting point for the Yocto build is a manifest file. The manifest file is an xml file that contains details of the different layers ( including their repository URL, target location where they need to be downloaded and any specific version – like branch or tag – which need to be used ) that needs to be fetched during initial stages of the builds. The manifest file will be usually used to download the repositories with details of meta layers and build configurations. Once the details are fetched, they are processed to set various generic settings/config related to builds post which the actual build generation – using bitbake command – will start. A set of sample manifests that can be used as a template for developing Operator specific manifests are given below ( along with sample manifest for SoC,OEM and third party )

Operator meta-layer creation

To match the layered structure of Yocto builds, an Operator specific layer is used to include Operator changes and additions. Use the yocto-layer create sub-command to create a new general layer.

$ yocto-layer create mylayer

There shall be separate device (machine) configuration file (.conf) for each device for the chip family for which the layer is intended for. The general naming terminology for Operator layer is meta-rdk-<soc name>-<oem name>-<device model>-<operator name>

The device (machine) configuration file shall include corresponding include (.inc) file to get machine configuration details.

Adding the Machine Configuration File for the new Operator

Each meta-* layer should have a conf folder containing the machine configuration we can select during ‘source setup-environment’ which is done usually before every bitbake build ( to set environment variables and configs ) . Optionally it can also have a class/classes folder for keeping information that is useful to share between metadata files.

To add a machine configuration, you need to add a .conf file with details of the device being added to the conf/machine/ file. In the machine conf file the basic machine configuration should be defined.

Once the conf files are in place, the layer details need to be added to the corresponding package group file. Based on platform( and also a recommended approach ), the package group file will be grouped into multiple files with one bitbake packagegroup main file and multiple append files. Operator can add the Operator layer details to required package group append files applicable to the target device build file to get the features added into the final generated build.

For additional details on how to add a layer in Yocto build systems, please refer Yocto manual on layer creation

Generic Apps in RDK

RDK supports a wide range of apps running on the RDK platforms, be it the Lightning based apps, the regular web apps, or the native apps. Operators could also integrate app stores to the RDK platform( for e.g. the Metrological app store ) so as to make available to their consumers a wide range of apps to choose with. While webapps and lightning apps are easier to integrate to the platforms, the native apps would require much more integration effort , considering their interfacing to RDK specific layers. Operators would also have to integrate the apps to their User Interface. Apps need to interact with the Firebolt/RDKServices/Thunder APIs to fetch or pass data to the RDK platform.

Native apps usually come with their own SDK ( which is commonly used across multiple platforms/devices/middleware ) . To ease the porting efforts of popular video streaming apps like Amazon Prime, Netflix etc. RDK already have a porting layer in place, which abstracts platform functions like graphics, DRM, cryptography etc. For more details on Native apps bring up in RDK, please refer Native Apps

Operator Specific Apps

Operators will be having a range of Operator specific applications from simple generic device information apps to Operator specific content applications. RDK’s Yocto based layered structure allows Operators to easily integrate, upgrade and maintain their apps in their RDK based devices. Operators need to integrate the app to the platform builds by referring to the firmware section above. Operators may also switch their apps to  Lightning based apps for better performance in RDK platforms. If the Operator apps are not webapps, they would have to integrate the apps to the RDK platform via Firebolt layer.

Operator Specific User Interface

RDK supports usage of different User Interfaces in the RDK devices. Operators can either choose from among the open-source User Interfaces that are already available with RDK or develop & use their own User Interface

The RDK Accelerator Home UI version 3 is the latest version of the RDK reference UI, based on Lightning framework, which provides a full featured UI with a modern minimalistic design using a dark theme. This single UI currently supports IP-STB, Hybrid-STB and TV profile RDK stacks. The UI uses Lightning SDK Plugins such as Language, Router, Storage and supports Premium streaming applications such as Amazon, YouTube, Xumo along with a selection of Lightning apps from the Metrological App Store.  It also includes a wide section of settings which allow a user to take full advantage of the device features such as Audio, Video, Network, Language and more.

Instructions to use default RDK User Interface

This section details about how to customize the current UI source code and develop further.

Follow the commands to run the application on the server.

• Install Lightning CLI

• Type lng to confirm the installation. You will see the below output.

  $ npm install -g @lightningjs/cli
  $ lng
  Usage: index lightning-cli <command> [options]
   
  Options:
    -V, --version   output the version number
    -h, --help      display help for command
   
  Commands:
    create - Create a new Lightning App
    build - Build a local development version of the Lightning App
    serve - Start a local webserver and run a built Lightning App in a web browser
    watch - Watch for file changes and automatically rebuild the App
    dev - Build a local Lightning App, start a local webserver, run a built Lightning App in a web browser and watch for changes
    docs - Open the Lightning-SDK documentation
    dist [options] - Create a standalone distributable version of the Lightning App
    upload - Upload the Lightning App to the Metrological Back Office to be published in an App Store
    update - Update the Lightning-CLI to the latest version
    help [command] - display help for command

• Clone repo

  $ git clone "https://code.rdkcentral.com/r/components/opensource/RDK_apps"
  $ cd RDK_apps
  $ git checkout rdk-next
  $ cd accelerator-home-ui
  Note: if you are not able to launch offline UI, add .env file inside accelerator-home-ui/ and add 'LNG_BUNDLER=esbuild' to force the bundler. Make sure you have esbuild dependency (npm install esbuild)
  $ npm install

• Build and Host

  $ lng build
  $ lng serve

• App will be hosted on http://127.0.0.1:8080

Instructions to deploy default RDK User Interface( either as such or with minimal changes )

1. ( Optional ): Create an offline and online version of the UI.
   1. Offline can have minimal things ( like pair the remote, settings to connect to WiFi etc ) which is available even if device is not connected to Internet.
   2. Online will be the full-fledged UI and will be fetched from a server with latest version
2. Host their UI in their own production server and make RDK use it. For this , operator need to change the URL in this line https://code.rdkcentral.com/r/plugins/gitiles/rdk/components/generic/appmanager/+/refs/heads/rdk-next/residentapp/residentApp.sh#165

Instructions to deploy operator specific User Interface

Operator can develop their own UI either using Html or Lightning. Below section stall describe how a Lightning UI can be deployed.

1. ResidentApp service serves the offline pages from DOCROOT of webserver(lighttpd) running on device. Operator need to install the UI assets in the DOCROOT and that will be launched by the https://code.rdkcentral.com/r/plugins/gitiles/rdk/components/generic/appmanager/+/refs/heads/rdk-next/residentapp/residentApp.sh#166 when the device starts up.
2. To make the device start always with offline UI pages; remove or comment out https://code.rdkcentral.com/r/plugins/gitiles/rdk/components/generic/appmanager/+/refs/heads/rdk-next/residentapp/residentApp.sh#230.

For further details, please refer to RDK Accelerator Home UI version 3 User Interface documentation.

Factory Test App

The Factory Test App is a special standalone application used for production line testing at the TV assembly factory of the CE manufacturers. It is embedded directly in the final production firmware image that gets flashed onto the boards on the TV production line.

The factory test app is generally provided by both OEM/CE and SoC vendors. SoC vendors will give a basic test which is good enough for engineering purposes, but when it comes to producing huge number of devices, the special factory test software is required ( along with special production line hardware to supplement the factory test software ). This is a specific requirement for the CE manufacturers and is not part of the default RDK.

Provisioning Support

Operator needs to add provisioning support in device so that Device provisioning can be done once deployed at customer premise. The steps for this vary based on platform as well as Operator type. In general, provisioning including attaching a device to a particular user account . 

Disaster Recovery

Disaster recovery is an inevitable part of the CPE life cycle. Operator, based on their disaster recovery strategy, could add support for this in the device. . Operators could easily add their business logic to RDK as part of Operator firmware engineering as described in above “Final Device Firmware” section. While there are some generic guidelines followed across industry, there is no single step that works for all. RDK has laid out some generic guidelines to follow for Disaster recovery implementation for better security and functionality at Bootloader/DRI/MemMap

Test & Certification of devices

Once the device engineering is completed from Operator side, the device can be test and verified easily by the Certification support provided by RDKM. Details of coverage as well as major cases are explained here (only for RDK licensee). For third party certification needs ( for e.g., compliance to a streaming app like Amazon prime or Netflix, compliance to an advanced audio technology like Dolby support ) operators has to directly work with the third-party vendors

Summary

In short, to get an RDK based device to field, Operators need to get

• RDK license
• Project agreement with OEM’s/ SoC
• Third-party licenses for applications ( Netflix, Amazon Prime etc. ) as well as technologies ( Dobly , Alexa etc. )

What Operators get from RDK/SoC/OEM:

• RDK Certified SoC/OEM platform
• Mostly ,pre-certified SoC platform for third-party apps
• RDK open-source User Interface

What Operators need to do:

• Integrate additional apps, including Operator specific apps, as required.
• Integrate and certify third party apps, if required.
• Integrate Operator specific User Interface
• Customization of stack to suite compliance requirements ( for e.g. power specifications of device to meet compliance requirements )
• Implement disaster recovery mechanisms.
• Implement provisioning logic.
• Any software changes related to Operator branding ( for e.g. logo during device boot up )
• Certification of the device