# GUIDE TO BUILDING AND INSTALLING UBUNTU 24.04 FOR ONEKIWI RZ/V2H SOM (SDK 6.2 - Styhead)

This document provides step-by-step instructions from initial setup through flashing the memory card and successfully running Ubuntu 24.04 on the OneKiwi RZ/V2H SOM board (8GB) using the SDK 6.2 (Styhead) environment.

> [!IMPORTANT]
> **Required preparation environment:**
> * **Operating system:** **Ubuntu 24.04** is recommended. You can use a physical machine/server or WSL2 on Windows.
> * **Source code:** Yocto source code, the `linux-rz` kernel, and the `rz-build-scripts` packaging scripts. These have been fixed for SDK 6.2.

---

## STEP 1: INSTALL THE REQUIRED ENVIRONMENT AND LIBRARIES

Before starting, open Terminal on Ubuntu and run the following commands to install the required build libraries:

```bash
sudo apt update
sudo apt install -y gcc-aarch64-linux-gnu build-essential bc bison flex libssl-dev git jq qemu-user-static zstd dos2unix
```

---

## STEP 2: BUILD THE YOCTO BSP (Create the Base Rootfs)

*Purpose: Yocto will automatically download Renesas proprietary hardware drivers (Mali GPU, Codec, VSPM) and create the root file system (rootfs).*

To build Yocto, follow the detailed instructions at the link below:
👉 [Yocto Build Guide for SOM V2H SDK 6.2](https://ontech-com-vn.gitbook.io/product/som-rz-v2h)

**Extremely important notes for SDK 6.2:**
1. During the Yocto source code setup process, you **must replace the default `meta-renesas` folder with OneKiwi's `meta-renesas` folder** configured for the 8GB board. You can download OneKiwi's `meta-renesas` folder from the link below:
   👉 [Download meta-renesas here](https://linuxbsp.onekiwi.com.vn/SOM_V2H/images/ubuntu/)
2. After copying OneKiwi's `meta-renesas` into place, you **MUST** run the following command to force Yocto compatibility with Styhead (SDK 6.2):
   ```bash
   sudo find /path/to/yocto_folder/meta-renesas -name "layer.conf" -exec sed -i 's/scarthgap/styhead/g' {} +
   ```

After the Yocto build is complete, you will obtain the Rootfs source file (`.tar.bz2`) in your Yocto path. It is usually located at:

`build/tmp/deploy/images/onekiwi-rzv2h-8gb/core-image-weston-onekiwi-rzv2h-8gb.rootfs.tar.bz2`

---

## STEP 3: BUILD THE KERNEL (Enable USB 3.0 & UVC Camera Support)

*Purpose: Configure the Linux kernel core (`Image` file) to enable the USB 3.0 port driver and USB Camera support.*

1. Clone the Linux RZ source code from GitHub:
   ```bash
   git clone -b ubuntu/rz-v2h-rdk https://github.com/Renesas-SST/linux-rz.git
   cd linux-rz
   ```
2. Set up the cross-compiler for the ARM64 chip:
   ```bash
   export ARCH=arm64
   export CROSS_COMPILE=aarch64-linux-gnu-
   ```
3. Remove the old configuration and load the standard Renesas configuration:
   ```bash
   make clean
   make renesas_defconfig
   ```
4. **Enable the required modules for USB and Camera:**
   ```bash
   scripts/config --enable CONFIG_RESET_RZV2H_USBPHY_CTRL  # Enable power for the USB 3.0 port
   scripts/config --enable CONFIG_USB_VIDEO_CLASS           # Detect Webcam/Camera devices (UVC)
   scripts/config --module CONFIG_SND_USB_AUDIO             # Support audio capture via USB
   make olddefconfig
   ```
5. Start compiling the Kernel:
   ```bash
   make -j$(nproc) Image modules
   ```
6. **Build output:**
   The Kernel file with integrated USB drivers will be generated at:

   `arch/arm64/boot/Image`

---

## STEP 4: PACKAGE THE UBUNTU OPERATING SYSTEM (.WIC File)

*Purpose: Embed Ubuntu 24.04 and integrate OpenCV and Codec drivers into a single image file for flashing to the memory card.*

1. **Download and extract the Ubuntu packaging script package:**
   Download OneKiwi's packaging script package (`rz-build-scripts`) from the link below:
   👉 [Download rz-build-scripts here](https://linuxbsp.onekiwi.com.vn/SOM_V2H/images/ubuntu/)

   After downloading and extracting it on your Ubuntu computer, move into the script directory:
   ```bash
   cd rz-build-scripts/rz-cmn-srp
   ```
2. **Copy the Rootfs file from Step 2 here and rename it (REQUIRED):**
   ```bash
   cp /path/to/yocto_folder/build/tmp/deploy/images/onekiwi-rzv2h-8gb/core-image-weston-onekiwi-rzv2h-8gb.rootfs.tar.bz2 ./renesas-ubuntu.tar.bz2
   ```
3. **Add the OneKiwi board configuration to the packaging system:**
   Copy OneKiwi's `meta-renesas` folder downloaded in Step 2 into the script workspace:
   ```bash
   mkdir -p yocto_rzcmn_board
   cp -r /path/to/yocto_folder/meta-renesas ./yocto_rzcmn_board/
   ```
4. **Download the vendor's proprietary Video Codec library (REQUIRED):**
   You must provide the vendor Codec file so that the script can integrate the Video driver.
   * Visit the Renesas official website and download the file: `RTK0EF0045Z15001ZJ-v1.1.0_EN.zip`
   * Copy this `.zip` file directly into the `rz-cmn-srp` directory.
5. **Fix permission and Windows format (CRLF) issues:**
   To avoid unclear Yocto build failures caused by unwanted Windows CRLF characters, run the cleanup commands below:
   ```bash
   # Convert all source files to Unix format
   sudo find .. -type f -print0 | sudo xargs -0 dos2unix

   chmod +x rz_builder.sh
   chmod +x jq-linux-amd64
   ```
6. **Start the Ubuntu image generation process:**
   ```bash
   sudo MACHINE=onekiwi-rzv2h-8gb IMAGE=ubuntu-core ./rz_builder.sh build
   ```

> [!TIP]
> **Normal messages/events while the script is running:**
> * **Layer is missing & Cloning:** You will see the script automatically run `git clone` to download layers such as `meta-arm`. This is an intelligent feature of the script.
> * **chmod error (Cosmetic Error):** If you see a yellow/red message such as `chmod: cannot access...`, you can **safely ignore it**.

7. **Build output:**
   When the terminal shows `Deploying ubuntu build artifacts`, the final operating system image will be exported to:

   `yocto_rzcmn_board/build/tmp/deploy/images/onekiwi-rzv2h-8gb/target/images/ubuntu-core-image.wic`

   or as a `.wic.gz` file.

---

## STEP 5: FLASH THE OPERATING SYSTEM FILE (.WIC) TO THE MEMORY CARD

Perform this step on your Windows computer.

1. **Copy the file from the Server:** Download the `ubuntu-core-image.wic` file, or the `.wic.gz` file, generated in Step 4 from the Server to your Windows computer.
2. **Flash the image:** Use **Rufus** or **BalenaEtcher** to flash this `.wic` file to the MicroSD card.

---

## STEP 6: OVERWRITE THE NEW KERNEL (IMAGE) ONTO THE MEMORY CARD (IMPORTANT)

> [!WARNING]
> If you skip this step, the memory card will boot using the default Kernel and **will NOT detect the USB Camera**. You must overwrite it with the customized Kernel built in Step 3.

1. After flashing the memory card in Step 5, **do not remove it immediately**. Remove it and plug it back into the Windows computer.
2. Windows will detect a small memory-card partition named **`boot`**. It is usually a few dozen MB in size.
3. Return to the Server and get the `Image` file generated in **Step 3**, located at `arch/arm64/boot/Image`.
4. **Copy and overwrite** this `Image` file directly into the root directory of the **`boot`** drive on the memory card.

*(Note: The `.dtb` file has already been correctly packaged into the memory card by Yocto. You do not need to touch or overwrite the `.dtb` file.)*

---

## STEP 7: TEST ON THE BOARD

After overwriting the `Image` file, remove the memory card and insert it into the OneKiwi RZ/V2H board. Make sure the DIP Switch is configured correctly to boot from the memory card. Connect the Serial cable, plug the USB Camera into the USB 3.0 port, and power on the board.

Check the Camera connection using the following commands in the Board terminal:

```bash
# Check whether the USB port has power and whether the hardware has been detected
dmesg | grep usb
lsusb

# Check whether the Video Camera has been detected successfully
ls /dev/video*
```

If `/dev/video0` appears, congratulations. You have successfully completed the installation process!