== Introduction ==
This is a description of how to build an RDK hybrid image for the Raspberry Pi 3 Model B/B+ that includes the DTVKit ATSC 1.0 stack and related RDK modules. To use the resulting image a USB ATSC tuner will be needed, along with the appropriate firmware file, as this isn't provided in the RDK repositories. The firmware for many devices can be obtained from [[https://www.linuxtv.org/downloads/firmware|LinuxTV.org]].

== Build Environment ==
The build environment is based on a 64-bit Ubuntu 18.04 installation and should be set up as defined for a Yocto 3.1 (Dunfell) release on the [https://wiki.rdkcentral.com/display/RDK/How+to+Build|RDK wiki page]]. As a guide, a build on a PC with a 4th generation Intel Core i7 processor and 32GB RAM takes around 3 hours when building for the first time, and requires 80-100GB disk space.

== Building the image ==
You need to be an RDK member to access the build repositories. The image to be built uses the RDK-V **rdkv-2023q1-dunfell** release. RDK releases after this use the Raspberry Pi 4 which haven't been tried so may not work.

All commands to be run directly are shown in //italics//.

  - Create a directory for the build, into which the RDK recipes and source files will be downloaded. This will be referred to as <RDK_ROOT> from now on.
  - //cd <RDK_ROOT>//
  - Checkout the release to be built, where 'rdkv-2023q1-dunfell' is the name of the branch.
    * //repo init -u %%https://code.rdkcentral.com/r/manifests%% -b rdkv-2023q1-dunfell -m rdkv-nosrc.xml//
    * //repo sync %%--no-clone-bundle%%//
  - //git clone %%git@github.com:DTVKit/meta-dtvkit-rpi.git%%//
  - //git switch atsc_main//
  - //source meta-dtvkit-rpi/setup-environment//
  - Select the "meta-cmf-raspberrypi/conf/machine/raspberrypirdkhybriddtv.conf" configuration (option 22 at the time of writing).
  - //bitbake rdk-generic-hybrid-dtv-image//

== Flashing the image ==
When the build has completed, the following steps can be followed to install and run the image on the Pi. It's assumed this is being done from a Linux desktop, so the instructions will be different for other operating systems.

  - The image to be flashed will be found in <RDK_ROOT>/build-raspberrypirdkhybriddtv/tmp/deploy/images/raspberrypirdkhybriddtv. The actual name of the image to be used contains the build date and time and is of the form 'rdk-generic-hybrid-dtv-image_rdkv-2023q1-dunfell_<datetime>.rootfs.wic.bz2'.
  - The Pi's SD card needs to be inserted into a card reader on a PC that also has access to the above file.
  - If the SD card already contains partitions with valid filesystems then they will probably be mounted, so all partitions need to be unmounted, leaving the card still accessible at the device level.
  - Copy the image to the SD card using the following command, ensuring the correct device name is used in place of 'sdX' for the SD card:
    * //bzcat <IMAGE_NAME>.wic.bz2 | sudo dd of=/dev/sdX bs=4M iflag=fullblock oflag=direct conv=fsync//
  - When the copy is complete, the partitions on the SD card will probably be auto mounted. At this stage the firmware for the USB tuner can be copied to the SD card, or it can be done after the Pi has booted up. The firmware file(s) need to be copied to '/lib/firmware' in the Pi's root filesystem.
  - Select the option to eject the SD card from the Linux desktop, insert it into the Pi, connect it to a TV/monitor with an HDMI cable, connect the USB tuner and a USB keyboard, and power on the Pi.
  - If the USB tuner firmware wasn't installed above, then it can be done now, either by copying the firmware from a USB drive on the Pi, or by copying it across the network (assuming the Pi is connected to a wired network). Either way, you will need to find the IP address of the Pi by some means, probably from whatever is acting as a DHCP server on the network.
  - You can login to the Pi (no password) using 'ssh' to copy the file from a USB drive:
    * //ssh root@<Pi's IP ADDR>//
  - To copy the firmware file(s) over the network (no password), do:
    * //scp <firmware file(s)> root@<Pi's IP ADDR>:/lib/firmware//

== Running the image ==
Occasionally the DTV application doesn't launch on start-up, but this can be resolved by logging in to the Pi using 'ssh' again and typing the following:
    * //systemctl restart dtvapp//