# Renesas R-Car Starter Kit gen 3 (h3ulcb, m3ulcb) Hardware setup
Here is a non exhaustive list of hardware parts that could be used to setup the Starter Kit gen 3 board development environment:
* Starter Kit gen 3 board with its power supply
* mini USB-A cable for serial console
* USB 2.0 Hub
* Ethernet cable
* HDMI type D (Micro connector) cable and associated display
* micro-SD Card (at least 4GB)
* USB touch screen device like the GeChic 1502i

For more information and latest news, please check :
* For h3ulcb [Here][R-car h3ulcb]
* For m3ulcb [Here][R-car m3ulcb]

The following documents may also be helpful:
* Yocto-Gen3 on elinux [Link][R-car yocto]

# Building the AGL Demo Platform for R-Car Starter Kit gen 3
Before set up Build Environment you need to setup the proprietary drivers.
* Download Renesas graphics drivers with a "click through" license from Renesas website [Link][rcar demoboard]
 * Under the Target hardware: **R-Car H3/M3** section.

#### Note:
* That you have to register with a free account on MyRenesas and accept the license condition before downloading them.  
The operation is fast and simple but nevertheless mandatory to access evaluation of non open-source drivers for free.  
Once you registered, you can download two zip files.
* The files must be store into directory ~/Downloads (or $XDG_DOWNLOAD_DIR).  
Here after is an example of their names:
```
chmod a+r $XDG_DOWNLOAD_DIR/*.zip
ls -l $XDG_DOWNLOAD_DIR
total 8220
-rw-r--r-- 1 XXX XXX    4619114 14 sept. 05:02 R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-20160906.tar.gz
-rw-r--r-- 1 XXX XXX    4619796 10 oct.  23:23 R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-20160906.zip
```

### Set up Build Environment:
* To build AGL demo platform for R-Car Starter Kit gen 3 board feature **agl-demo** and :
 * for machine **h3ulcb** :
 ```
 export MACHINE=h3ulcb
 ```
 * for machine **m3ulcb** :
 ```
 export MACHINE=m3ulcb
 ```

* Now init your build environement:
```
cd $AGL_TOP
source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo agl-netboot agl-appfw-smack
```

#### Note:
* **IMPORTANT** read the log to be sure to have any error during your setup.  
In case graphical drivers were not found, you could notice an error message as follow:

```
[snip]
--- fragment /home/working/workspace_agl_master/meta-agl/templates/machine/h3ulcb/50_setup.sh
/home/working/workspace_agl_master /home/working/workspace_agl_master/build_gen3
The graphics and multimedia acceleration packages for the R-Car Gen3 board can be download from :
  <http://www.renesas.com/secret/r_car_download/rcar_demoboard.jsp>

These 2 files from there should be store in your'/home/ronan/Téléchargements' directory.
  R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-20160906.zip
  R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-20160906.zip
/home/working/workspace_agl_master/build_gen3
--- fragment /home/working/workspace_agl_master/meta-agl/templates/base/99_setup_EULAconf.sh
--- end of setup script
OK
Generating setup file: /home/working/workspace_agl_master/build_gen3/agl-init-build-env ... OK
------------ aglsetup.sh: Done
[snip]
```
* If you encounters this issue, or any other unwanted behavior, you can fix the error mentioned and then clean up by removing the “$AGL_TOP/build” directory then launch the procedure again.
* After this command, the working directory is changed to $AGL_TOP/build.
* Users may want to check that the board is correctly selected in the environment:

```
grep -w -e "^MACHINE =" $AGL_TOP/build/conf/local.conf
  MACHINE = "h3ulcb"
or
  MACHINE = "m3ulcb"
```
* Configure for Release or Development:  
Development images require extra tools for developer convenience, in particular:
 * a debugger (gdb)
 * some tweaks, including a disabled root password
 * a SFTP server
 * the TCF Agent for easier application deployment and remote debugging
 * ...  
 
We explicitely activate these Debug facilities by specifying the “agl-devel agl-netboot” feature.

### Build your image:
The process to build an image is simple:
```
bitbake agl-demo-platform
```
Once done, what may take up to few hours, you should get the end result in the directory:
```
ls -l $AGL_TOP/build/tmp/deploy/images/$MACHINE
```
#### Note:
* In case of failure of the build it is safe to first check that the Linux distribution chosen for your host has been validated for version 2.1 of Yocto.

# Booting AGL Demo Platform on R-Car Starter Kit gen 3 using a micro-SD card
To boot the board using a micro-SD card, there are two operations that should be done prior to first initial boot:
* Create a SD-card with one ext3 partition,
* Set up the board to boot on the SD-card.

Then for each build, the SD-card is merely rewritten and used to boot the configured board.
## Deployment

### Format the SD-card on the host

* Plug microSD card and get its associated device by either running *dmesg | tail -15* or *lsblk*, for example:

```
dmesg | tail -15

  [ 1971.462160] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00
  [ 1971.462277] sd 6:0:0:0: [sdc] No Caching mode page found
  [ 1971.462278] sd 6:0:0:0: [sdc] Assuming drive cache: write through
  [ 1971.463870]  sdc: sdc1 sdc2
```
Here, the SD-card is attached to the device sdc.

```
lsblk

  NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
  sda      8:0    0 167,7G  0 disk
  ├─sda1   8:1    0   512M  0 part /boot/efi
  ├─sda2   8:2    0 159,3G  0 part /
  └─sda3   8:3    0   7,9G  0 part [SWAP]
  sdb      8:16   0 931,5G  0 disk
  └─sdb1   8:17   0 931,5G  0 part /media/storage
  sdc      8:32   1  14,9G  0 disk
  ├─sdc1   8:33   1    40M  0 part
  └─sdc2   8:34   1   788M  0 part
```
#### Note:
* **WARNING** This is a critical operation, each computer is different and device can change during time, so do this operation each time you incert the microSD card.
* In the **example** above, we see the first SATA drive as 'sda'.
* In the **example** above, 'sdc' corresponds to the microSD card.*

### Format the SD-card
* Create EXT3 partition on the SD-card using fdisk and set the MBR.
 * For **example**, if the microSD card is */dev/sdc*:

```
sudo fdisk /dev/sdc

  Welcome to fdisk (util-linux 2.27.1).
  Changes will remain in memory only, until you decide to write them.
  Be careful before using the write command.


  Command (m for help): o
  Created a new DOS disklabel with disk identifier 0x96e5850d.

  Command (m for help): n
  Partition type
     p   primary (0 primary, 0 extended, 4 free)
     e   extended (container for logical partitions)
  Select (default p):

  Using default response p.
  Partition number (1-4, default 1):
  First sector (2048-31291391, default 2048):
  Last sector, +sectors or +size{K,M,G,T,P} (2048-31291391, default 31291391):

  Created a new partition 1 of type 'Linux' and of size 14,9 GiB.

  Command (m for help): w
  The partition table has been altered.
  Calling ioctl() to re-read partition table.
  Syncing disks.
```
* Initialize the ext3 partition using “mke2fs”:
 *  for **example** if the microSD card is associated with *sdc*:

```
sudo mke2fs -t ext3 /dev/sdc1

  mke2fs 1.42.13 (17-May-2015)
  Creating filesystem with 3911168 4k blocks and 979200 inodes
  Filesystem UUID: 690804b9-6c7d-4bbb-b1c1-e9357efabc52
  Superblock backups stored on blocks:
  	32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208

  Allocating group tables: done
  Writing inode tables: done
  Creating journal (32768 blocks): done
  Writing superblocks and filesystem accounting information: done
```

### Copying the built image to the SD-card
Insert the SD-card into your build host:
* Your desktop system may probably offer a choice to mount the SD-card automatically in some directory.
* In the next sample code, we'll suppose that the SD-card mount directory is stored in the variable $SDCARD.
* For example **example** the microSD card is associated with device *sdc*:

```
export SDCARD=/tmp/agl
mkdir -p $SDCARD
sudo mount /dev/sdc1 $SDCARD
```

Go to your build directory:

```
cd $AGL_TOP/build/tmp/deploy/images/$MACHINE
```

Make sure the filesystem is empty:

```
sudo rm -rf ${SDCARD:-bad_dir}/*
```
*** IMPORTANT ***
Verify that **tar** version is 1.28 or newer:

```
tar --version
tar (GNU tar) 1.28
[snip]
```
If your distribution is up to date on this dependency, you can use the host tool directly.  
Let's define a variable for the following steps:
```
TAR=$(which tar)
```
Otherwise, a native up-to-date version of tar is also generated while building AGL distribution:
```
TAR=$AGL_TOP/build/tmp/sysroots/x86_64-linux/usr/bin/tar-native/tar
$TAR --version
tar (GNU tar) 1.28
[snip]
```
Copy Automotive Grade Linux (AGL) files onto the mircoSD card by extracting the root file system archive:

```
sudo $TAR --extract --numeric-owner --preserve-permissions --preserve-order --totals \
           --xattrs-include='*' --directory=$SDCARD --file=agl-demo-platform-h3ulcb.tar.bz2
```

Copy Kernel Image and Device Tree Blob file into the **boot** directory:
* For machine h3ulcb:
```
sudo cp Image-r8a7795-h3ulcb.dtb /tmp/agl/boot/
```

* For machine m3ulcb:
```
sudo cp Image-r8a7796-m3ulcb.dtb /tmp/agl/boot/
```

Ensure the changes have been written to the disk:

```
sync
```
 Unmount the micrSD card:

```
sudo umount $SDCARD
```
### Configure U-boot on the board
* Turn the board on using the power switch.
* Hit any key to stop autoboot (warning you have only few seconds).
* Check if you have correct parameters for booting your board:
 * For machine m3ulcb:
```
=> print
	baudrate=115200
	bootargs=console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait rw rootfstype=ext3
	bootcmd=run load_ker; run load_dtb; booti 0x48080000 - 0x48000000
	bootdelay=3
	fdt_high=0xffffffffffffffff
	initrd_high=0xffffffffffffffff
	load_dtb=ext4load mmc 0:1 0x48000000 /boot/Image-r8a7795-h3ulcb.dtb
	load_ker=ext4load mmc 0:1 0x48080000 /boot/Image
	stderr=serial
	stdin=serial
	stdout=serial
	ver=U-Boot 2015.04 (Jun 09 2016 - 19:21:52)

	Environment size: 648/131068 bytes
```

 * For machine h3ulcb:
```
=> printenv
	baudrate=115200
	bootargs=console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait rw rootfstype=ext3
	bootcmd=run load_ker; run load_dtb; booti 0x48080000 - 0x48000000
	bootdelay=3
	fdt_high=0xffffffffffffffff
	filesize=cdeb
	initrd_high=0xffffffffffffffff
	load_dtb=ext4load mmc 0:1 0x48000000 /boot/Image-r8a7796-m3ulcb.dtb
	load_ker=ext4load mmc 0:1 0x48080000 /boot/Image
	stderr=serial
	stdin=serial
	stdout=serial
	ver=U-Boot 2015.04 (Nov 30 2016 - 18:25:18)

	Environment size: 557/131068 bytes
```

* If not copy line by line:

```
setenv bootargs console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait rw rootfstype=ext3
setenv bootcmd run load_ker\; run load_dtb\; booti 0x48080000 - 0x48000000
setenv load_ker ext4load mmc 0:1 0x48080000 /boot/Image
saveenv
```
 * For machine h3ulcb:
```
setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/Image-r8a7795-h3ulcb.dtb
```
 * For machine m3ulcb:
```
setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/Image-r8a7796-m3ulcb.dtb
```

* Now you can boot:

```
run bootcmd
```

### Booting the board
* Turn the board off using the power switch.  
* Insert the microSD-card.  
* Verify that you have plugged in, at least, the following:
 * External monitor on HDMI port
 * Input device (keyboard, mouse, touchscreen...) on USB port.

* Turn the board on using the power switch.  
After a few seconds, you'll see the AGL splash screen on the display and you'll be able to log in on the console terminal.  
(login is 'root', no password)

* For machine h3ulcb:

```
Automotive Grade Linux 3.0.0+snapshot-20161201 h3ulcb ttySC0

h3ulcb login: root
```

* For machine m3ulcb:

```
Automotive Grade Linux 3.0.0+snapshot-20161201 m3ulcb ttySC0

m3ulcb login: root
```

### To access the shell (serial)
* Install a serial client on your computer.  
This can be “screen”, “picocom”, “minicom”.  
The lighter of the 3 is “picocom” (it has less dependencies).  
* Plug a USB cable from your computer to the serial CP2102 USB port (mini USB-A).  
With “dmesg” you can check the device created for the serial link.  
To get it, you must switch the board on.  
For example:
```
dmesg | tail
[2097783.287091] usb 2-1.5.3: new full-speed USB device number 24 using ehci-pci
[2097783.385857] usb 2-1.5.3: New USB device found, idVendor=0403, idProduct=6001
[2097783.385862] usb 2-1.5.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[2097783.385864] usb 2-1.5.3: Product: FT232R USB UART
[2097783.385866] usb 2-1.5.3: Manufacturer: FTDI
[2097783.385867] usb 2-1.5.3: SerialNumber: AK04WWCE
[2097783.388288] ftdi_sio 2-1.5.3:1.0: FTDI USB Serial Device converter detected
[2097783.388330] usb 2-1.5.3: Detected FT232RL
[2097783.388658] usb 2-1.5.3: FTDI USB Serial Device converter now attached to ttyUSB0
```
The link is attached to the device /dev/ttyUSB0.  
It is time to launch your serial client.  
Example:
```
picocom -b 38400 /dev/ttyUSB0
```
or
```
minicom -b 38400 -D /dev/ttyUSB0
```
or
```
screen /dev/ttyUSB0 38400
```

Power on the board to see a shell on the console
* For machine h3ulcb:  

```
NOTICE:  BL2: R-Car Gen3 Initial Program Loader(CA57) Rev.1.0.7
NOTICE:  BL2: PRR is R-Car H3 ES1.1
NOTICE:  BL2: LCM state is CM
NOTICE:  BL2: DDR1600(rev.0.15)
NOTICE:  BL2: DRAM Split is 4ch
NOTICE:  BL2: QoS is Gfx Oriented(rev.0.30)
NOTICE:  BL2: AVS setting succeeded. DVFS_SetVID=0x52
NOTICE:  BL2: Lossy Decomp areas
NOTICE:       Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570
NOTICE:       Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0
NOTICE:       Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0
NOTICE:  BL2: v1.1(release):41099f4
NOTICE:  BL2: Built : 19:20:52, Jun  9 2016
NOTICE:  BL2: Normal boot
NOTICE:  BL2: dst=0xe63150c8 src=0x8180000 len=36(0x24)
NOTICE:  BL2: dst=0x43f00000 src=0x8180400 len=3072(0xc00)
NOTICE:  BL2: dst=0x44000000 src=0x81c0000 len=65536(0x10000)
NOTICE:  BL2: dst=0x44100000 src=0x8200000 len=524288(0x80000)
NOTICE:  BL2: dst=0x49000000 src=0x8640000 len=1048576(0x100000)


U-Boot 2015.04 (Jun 09 2016 - 19:21:52)

CPU: Renesas Electronics R8A7795 rev 1.1
Board: H3ULCB
I2C:   ready
DRAM:  3.9 GiB
MMC:   sh-sdhi: 0, sh-sdhi: 1
In:    serial
Out:   serial
Err:   serial
Net:   Board Net Initialization Failed
No ethernet found.
Hit any key to stop autoboot:  0
=>
```
* For machine m3ulcb:

```
NOTICE:  BL2: R-Car Gen3 Initial Program Loader(CA57) Rev.1.0.8
NOTICE:  BL2: PRR is R-Car M3 ES1.0
NOTICE:  BL2: LCM state is CM
NOTICE:  BL2: DDR1600(rev.0.15)
NOTICE:  BL2: DRAM Split is 2ch
NOTICE:  BL2: QoS is default setting(rev.0.14)
NOTICE:  BL2: AVS setting succeeded. DVFS_SetVID=0x52
NOTICE:  BL2: Lossy Decomp areas
NOTICE:       Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570
NOTICE:       Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0
NOTICE:       Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0
NOTICE:  BL2: v1.1(release):41099f4
NOTICE:  BL2: Built : 09:24:53, Nov 24 2016
NOTICE:  BL2: Normal boot
NOTICE:  BL2: dst=0xe630f068 src=0x8180000 len=36(0x24)
NOTICE:  BL2: dst=0x43f00000 src=0x8180400 len=3072(0xc00)
NOTICE:  BL2: dst=0x44000000 src=0x81c0000 len=65536(0x10000)
NOTICE:  BL2: dst=0x44100000 src=0x8200000 len=524288(0x80000)
NOTICE:  BL2: dst=0x49000000 src=0x8640000 len=1048576(0x100000)


U-Boot 2015.04 (Nov 30 2016 - 18:25:18)

CPU: Renesas Electronics R8A7796 rev 1.0
Board: M3ULCB
I2C:   ready
DRAM:  1.9 GiB
MMC:   sh-sdhi: 0, sh-sdhi: 1
In:    serial
Out:   serial
Err:   serial
Net:   Board Net Initialization Failed
No ethernet found.
Hit any key to stop autoboot:  0
=>
```

### U-Boot screen configurations

Follow the steps below to configure boot from microSD card and to set screen resolution:

* Power up the board and, using your preferred terminal emulator.
* Type a character to abort the boot and enter the U-boot menu.
* Type **print** to check the environment:

```
print
```

* Verify that the ethaddr environment variable is set to the same MAC address value shown on the label on top of the RJ45 Ethernet connector.
* If not please set it using the following command:

```
setenv ethaddr <MAC address>
```

For example:

```
setenv ethaddr 2e:09:0a:00:75:b5
```

* Set the follow environment variables:

```
setenv bootargs_console 'console=ttySC6,38400 ignore_loglevel'
setenv bootargs_video 'vmalloc=384M video=HDMI-A-1:1920x1080-32@60'
setenv bootargs_root 'root=/dev/mmcblk0p1 rootdelay=3 rw rootfstype=ext3 rootwait'
setenv bootmmc '1:1'
setenv bootcmd_sd 'ext4load mmc ${bootmmc} 0x40007fc0 boot/uImage+dtb'
setenv bootcmd 'setenv bootargs ${bootargs_console} ${bootargs_video} ${bootargs_root}; run bootcmd_sd; bootm 0x40007fc0'
```
**WARNINGS:**
* If no display shows up when booting, e.g. for a non-full HD screen, replace  **1920x1080** value in the **bootargs_video** variable with lower screen resolution such as **1024x768**.  
  Unfortunately for the moment there are no universally supported setting.

For Renesas h3ulcb use screen resolution **1024x768** and set **bootmmc** to **2:1**.

* Save the environment variables:

```
saveenv
  Saving Environment to SPI Flash...
  SF: Detected S25FL512S with page size 256 KiB, total 64 MiB
  Erasing SPI flash...Writing to SPI flash...done
```

* Reboot:

```
reset
```

### More Documentation
Detailed guide on how to build AGL for Renesas boards and using AGL SDK inside a ready-to-use Docker container.
* [AGL-Devkit-Build-your-1st-AGL-Application.pdf][Iot.bzh AGL-Devkit-Build-your-1st-AGL-Application]
Generic guide on how to build various application types (HTML5, native, Qt, QML, …) for AGL.
* [AGL-Devkit-HowTo_bake_a_service.pdf][Iot.bzh AGL_Phase2-Devkit-HowTo_bake_a_service]
Generic guide on how to add a new service in the BSP.

[R-car m3ulcb]: http://elinux.org/R-Car/Boards/M3SK
[R-car h3ulcb]: http://elinux.org/R-Car/Boards/H3SK
[R-car yocto]: http://elinux.org/R-Car/Boards/Yocto-Gen3
[rcar demoboard]: https://www.renesas.com/en-eu/solutions/automotive/rcar-demoboard.html