Hardware Porting Guide
Pre-requisites
The first step to get a functional device/platform is to define the product features and 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 vendors to choose which features they want to integrate into their target platform. In addition to the standard RDK-V features, vendors could define and add their own feature requirements ( for e.g. , the video streaming applications which they want to bring to their platform ) too as well as the strategy to be followed for various vendor specific items like the platform security hardening or the memory map of the device
SoC Pre-requisites
The below pre-requisites are expected from a SoC vendor before they start the porting efforts of RDK to their SoC platform
- A SoC target platform with required hardware capabilities to meet the RDK product/feature requirements
- Required drivers for associated hardware
- A Linux Kernel with required hardening and enhancements done for target platform
- A Secure boot mechanism along with image validation mechanism
OEM Pre-requisites
OEM should have
- A SoC platform with a successful RDK port( preferebly with RDK certification )
- Required third party drivers and support for peripherals
- Verified boot mechanisms and disaster recovery
- OTA upgrade support
- Flash banks defined
RDK Architecture
A clear understanding of the RDK architecture, based on the target RDK device profile, is important for SoC vendors to begin the process of porting RDK onto their target platform. 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 TV plus Hybrid capabilities such as tuning, conditional access etc.
Hardware Porting – Overview
A quick flow of how RDK can be implemented in a platform is given below in a step by step format. Additional details of how to achieve RDK/SoC/OEM specific features are mentioned in following sections. The below steps doesnt consider the specific differences in different RDK device profiles and is considering only the generic steps involved
SoC
Given SoC is meeting the pre-requisites mentioned in above section, SoC may follow the below steps to achieve porting. While the steps are mentioned in very high level, details of some of the steps are given later in this document
1 . Build Environment:
As a first step, SoC is recommended to migrate their platform builds to Yocto. RDK already provides a reference build in the form of the generic Raspberry Pi platform. SoC should create a layer for the SOC changes ( or could opt in for a generic SoC layer – with all the changes that is common for all platform models from the SoC – as well as a platform model specific SoC layer – with all the changes that is specific to this particular model ) which then can be used to replace the SoC( and device) specific layer in the Raspberry Pi build system. The vendor should also remove the RDKM specific layers as well as any third party customizations that are unwanted. SoC could use the layers to integrate their kernel, BSP as well as platform changes to the Yocto build system. Additionally, SoC has to create their own config file with the specific configurations that should be used during the build. Recipes and configurations to build the final rootFS and flashable image ( *.bin or *.img or any other preferred format ). Once they have a working Yocto build, then the next steps could be taken care of ( refer “Final Device Firmware” section for more details )
2 . Compatibility:
Once the build system is up,SoC need to cross check the compatibility of the configurations with the platform ( this is applicable to both RDK specific platform compatibility as well as open source software compatibility). RDK Linux is built with particular build flags/features in target platform in consideration ( For example, RDK considers hardware floating point in platform where as some platforms are on software based floating point ). SoC vendor need to analyze such flags in RDK and then make a comparison with the existing SoC platform Linux to ensure compatibility or to understand the required modifications in RDK code so as to bring in the compatibility changes
Specific DISTRO_FEATURES can be added to support build time flag for specific platforms. For example : DISTRO_FEATURES_append = ” referencepltfm “
For open source version details, the layers meta-openembedded, openembedded-core, meta-rdk-ext, meta-rdk should be checked. If multiple recipes with different versions are available, then check for the value of PREFFERED_VERSION_<recipe name> set to know which is the set version. However, it is recommended to stick to the versions of open source software that comes as part of RDK releases ( or higher )
3 . HAL Implementation:
RDK provides a set of HAL APIs that will abstract the platform from RDK. Vendor need to implement the HAL APIs to meet the HAL Specifications as described in the HAL Documentation. Details of which HAL componenets need to be implemented for each device profile and their documentation are specified in the HAL table towards the end of this guide
4 . Third party software integration:
Once the HAL Implementation is completed, SoC could proceed with integration third party software stacks and apps. The third party software stacks could be either to provide additional functionality ( for e.g. DVB support ) or the SDK for some native apps like some video streaming apps like Amazon Prime and Netflix. Some of the very popular software stakcs are already integrated to RDK so SoC vendors just need to take care of the changes in SoC platform side. Additionally, the streaming apps would require a pre-certification from the app vendor so that SoC can publish they are pre-certified with the respective app.
5 . Test & Certification:
SoC could leverage the RDK certification suite to perform self certification and to un-earth the issues during RDK bring up. Once they are good with the results, the SoC platform could be submitted to RDKM where the certification will be repeated and once it is successfully completed, SoC could advertise the SoC platform as “RDK Certified”
OEM
Given OEM is meeting the pre-requisites mentioned in above section, OEM may follow the below steps to achieve porting. While the steps are mentioned in very high level, details of some of the steps are given later in this document
1 . OEM Software Customizations:
OEM may add their own customizations of RDK and SOC layer components to the stack. This would be either to bring in OEM specific changes on a specific component or to add additional security patches. Additionally OEM would have to optimize the memory footprint of the stack for better usage of resources. To achieve this, OEM should create a layer for the OEM changes ( or could opt in for a generic OEMlayer – with all the changes that is common for all device models from the OEM- as well as a model specific OEMlayer – with all the changes that is specific to this particular model ). OEM must create a machine config specific for the target device with all the configurations for the target device model. This could either override any SOC changes ( with additional changes in build to match these changes ) or can supplementing to the existing SoC machine config changes.
2 . OEM Component Integration:
OEM should integrate OEM specific components ( like like Firmware Upgrade, Secure Boot Loader, MFR libraries, Vendor Specific Information, NVRAM files and partition, Provisioning, OEM Specific drivers, STB Utilities, RDK Device-Specific Patches, Image Generation Utiities etc. ) to the build they receive from SOC vendor. In case OEM decides to use a third party component than the one that comes with SoC platform ( for e.g. a Bluetooth or WiFi chip ), the component driver integration also needs to be taken care by the OEM.
3 . Image Bootup and recovery:
OEM is responsible for ensuring a secure boot mechanism, image upgrades using secure methods and also a disaster recovery in case of a failure in bootup.
4 . Test & Certification:
SoC could leverage the RDK certification suite to perform self certification and to un-earth the issues during RDK bring up. Once they are good with the results, the SoC platform could be submitted to RDKM where the certification will be repeated and once it is successfully completed, SoC could advertise the SoC platform as “RDK Certified”
Final Device Firmware
RDK provides the vendors 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 vendors 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 vendors to easily and seamlessly plug their software layers to the existing RDK builds
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 vendor specific manifests are given below ( along with sample manifest for SoC,OEM,and third party )
|
# |
File |
Remarks |
|---|---|---|
|
1 |
This is the starting point of the build and is specific to a device/board . If the SoC/OEM has only one target device /board, still it is recommended to maintain a different manifest for SoC/OEM for keeping it future-proof. Usually it contains references to other manifest files which will be having specific set of repos |
|
|
2 |
This manifest contains meta layer details of SoC and , optionally, some SoC specific repos |
|
| 3 | OEM Manifest |
This manifest contains meta layer details of OEM and , optionally, some OEM specific repos |
|
4 |
This manifest has details of the basic Yocto Open Embedded layers |
|
|
5 |
This manifest can contain meta layers specific to RDK & RDK-V and , for EXTERNALSRC cases, the RDK & RDK-V component repo details too. It might be supplemented with a conf file too |
|
|
6 |
Third party Apps manifest |
This manifest can contain meta layers related to premium streaming applications which are chosen by Operator |
Vendor meta-layer creation
To match the layered structure of Yocto builds, a SoC/OEM specific layer is used to include changes from the vendor 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 SOC generic layer is meta-rdk-<soc name> and for OEM generic layer is meta-rdk-<soc name>-<oem name>. Additionally, the platform model name or the device model name also can be included if there are changes specific to target model are present ( which are not part of the vendor’s generic layer ) which would be then present in folder meta-rdk-<soc name>-<soc platform name>-<oem name>-<oem device model name>
The device (machine) configuration file shall include corresponding include (.inc) file to get machine configuration details.
Adding the Machine Configuration File for the vendor
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. Vendor can add the Vendor/Device 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. While webapps and lightning apps are easier to integrate to the platforms and is usually of interest for the Operators, 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.
Most of the native apps would require the platform to be providing enough support to required security and AV functionalities. 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.
To integrate the streaming app to the platform along with leveraging the RDK Porting layer, some of the mandatory integrations that are expected to be inplace are
- RDKServices porting completion
- HAL porting ( especially IARM and Device settings )
- OCDM Integration ( to get DRM Encrypted content playback )
- SoC alignment with the Gstreamer integration to meet RDK requirements on gstreamer
Once the RDK Porting along with above 4 points are completed, then different features like Graphics,Westeros,Security, AV will be up so vendor can proceed with integration of native streaming app SDK. Now, vendor could add the meta layer for the streaming app to the yocto build structure and proceed with integration . For more details on Native apps bring up in RDK, please refer Native Apps
For more details on Apps in RDK, please refer app.rdkcentral.com
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.
While the default UI is good enough for the regular use, in case SOC or OEM vendor would like to customize the UI to suite their requirements, this is also supported
Instructions to use default RDK User Interface
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 )
-
( Optional ): Create an offline and online version of the UI.
- 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.
- Online will be the full-fledged UI and will be fetched from a server with latest version
- 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.
- 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.
- 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.
Conditional Access ( CAS )
For the RDK Hybrid devices ( that supports both IP and Tuner based streaming ), the Conditional Access Systems ( CAS ) are a must for the Operators to control content access for users. In RDK, the Conditional access is used only by the RDK Media Framework ( RMF ) components. While RDK doesnt have any recommended CAS systems, it is up to the SoC to work with their choice of CAS vendor and get CAS integrated to the platform. Currently,RDKM doesnt advocate any valid test suites for the CAS functionality confirmation so it is up to the SoC to decide on if they can go ahead with the custom validation methods of CAS vendor or need to define on their own Acceptance criteria. Usually, the final CAS testing is done by Operators
Third-party software
RDK supports integration of third party software stack to RDK to achieve extended functionalities using the RDK-V platforms.
The widely popular Amazon Voice as well as Alexa Video Skill kit is already integrated to RDK and available for demo in Raspberry Pi. All the details of how to perform the integration , along with license details and customization are available at RDK Alexa integration
A popular DVB stack, DTVKit, is already integrated to RDK-V and any vendor who has a license agreement with DTVKit can use their software stack. In order to complete ingration of DTVKit to the vendor platform, the HAL layer of the DTV software stack needs to be implemented by SoC post which the DVB support will be functional. The RDKServices component corresponding to DTVKit services is available here . As a reference, DTVKit is available integrated to the Raspberry Pi port of RDK-V for free evaluation by community members.
Another popular DVB stack, Mediarite, is currently being integrated to RDK stack and is expected to be available to community soon
Peripheral devices
While most of the changes related to RDK implementation as software specific, SoC and OEM would need to add support for additional peripheral devices like Front Panel LED, Remote controls units etc. to the platform.
There are already a set of Remote control devices available that supports RDK platforms out of the box. However, SoC/OEM might also want to integrate remote control devices of their own choice for business reasons. To get details of already supported Remote control devices as well as how to add support for a new Remote control device in RDK, please refer to Remote control documentation
Bootloader Security
The device bootloader is the entry point of the device firmware and hence an important component with security aspects related to it. It is the responsibility of the vendor to adhere to the best practices of a secure boot practice – be it an encrypted bootloader ,firmware validation before bootloader launches the main image or other related security practices. The recommended guidelines from RDKM on Bootloader is available at Bootloader/DRI/MemMap and vendors are highly encouraged to follow these practices. A detailed security specifications on Secure boot is expected to be available to community by Q3 2023
Image Upgrade
SoC and OEM vendors need to provide a mechanism to perform image upgrade in their platform. While SoC platforms can be supporting more generic methods to get image upgrade done ( being engineering platforms ), OEMs would have to implement standard secure methods to perform Over The Air (OTA) image upgrades which would be required for actual field deployments once Operators adopt the devices. The recommended method for image upgrade by RDKM is by using the XConf server ( please refer XConf Server on how to setup an XConf server and how to perform image upgrade using XConf server ). RDK also supports upgrade of firmware via the System plugin in RDK Services. Vendor need to implement the API for firmware upgrade as mentioned in the RDK Service documentation
Decisions on how to perform the actual image upgrade, the number of flash banks to be used ( for alternate image in case of image upgrade failure ), sample flash bank layout etc. are open to the vendor. However, the recommendations from RDKM on Memory map for image storage as well as behaviour of Bootloader during image upgrade are available at Bootloader/DRI/MemMap
Test & Certification of devices
RDK Certification program facilitates vendors to get their product certified as RDK Compliant device. It is mandatory to go through this program in order to brand user’s platform as RDK compliant product. The RDK Certification process includes vendor self certifying their platform using the RDK Certification suite followed by the same process repeated by RDKM. Once the device engineering is completed from vendor side, the device can be used for self certification. 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
For more details on the test support for RDK devices, please refer tools.rdkcentral.com[TODO]
HAL implementation
The table below lists all the HALs, their doxygen documentation, source code license type, implementation owner, and applicability to different device profiles. It also includes the corresponding HAL certification page.
Doxygen based HAL documentation for all components is available at HAL Components index page
Generic HAL:
| HAL Documentation | Source code | License type | HAL implementation owner | Device Profile Applicability | HAL certification page | |
|---|---|---|---|---|---|---|
| Bluetooth | Click Here | Open Source | OEM&SOC |
IP STB Hybrid STB TV |
||
| Closed Caption | Click Here | Licensed | SOC |
IP STB Hybrid STB TV |
|
|
| Deepsleep Manager | Open Source | SOC |
IP STB Hybrid STB TV |
|||
| Device Settings | Click Here | Open Source | OEM&SOC |
IP STB Hybrid STB TV |
||
| DVR Manager | Licensed | SOC |
Hybrid STB |
|||
| Open Source | SOC |
IP STB Hybrid STB TV |
||||
| IR Manager | Click Here | Open Source | SOC |
IP STB Hybrid STB TV |
||
| MFRLibs | Open Source | OEM |
IP STB Hybrid STB TV |
|||
| MoCA | Click Here | Open Source | SOC |
Hybrid STB |
||
| Motiondetector | Coming Soon |
|
OEM&SOC |
TV |
||
| Power Manager | Open Source | SOC |
IP STB Hybrid STB TV |
|||
| RDK-V RMF AudioCapture | Open Source | SOC |
IP STB Hybrid STB TV |
|||
| Section-Filter | Open Source | SOC |
Hybrid STB TV |
|||
| Sysint | Coming Soon | Open Source | OEM |
IP STB Hybrid STB TV |
||
| TV Settings | Coming Soon |
Open Source | SOC |
TV |
||
| Wi-Fi | Open Source | OEM&SOC |
IP STB Hybrid STB TV |
|||
| libdrm | Coming Soon | Open Source | SOC |
IP STB Hybrid STB TV |
||
| Front End | New HAL. To be implemented | Hybrid STB TV |
||||
| Demux | New HAL. To be implemented | Hybrid STB TV |
OEM&SOC : This indicates corresponding HAL needs to be implemented by both OEM&SOC
SOC : This indicates corresponding HAL needs to be implemented by SOC
OEM : This indicates corresponding HAL needs to be implemented by OEM