Khadas VIM3 initial config

Brief description

This GUIDE will show:

• How to flash a selected OS to the eMMc-storage of the VIM3.
• Show the initial boot
• Describe how to RE-flash the eMMc-storage for when another OS needs to be installed on the device.
• Costum OS-images
• Change username/password allong with ethernet settings using script
• How to install DOOM for fun

Original Khadas documentation

---

1 Install OS on to eMMC-storage

1. Dowload the USB-Upgrade Tool and extract it.

Description of the USB Upgrade Tool’s directory contents:

• The V2 and V3 folders hold the original burning tool files

---

1.1 Install OS on to eMMC-storage

• The burn tool folder stores burning tools and drivers for different boards
  Description of the burn tool directory contents:
  

• Driver-VIM1_2_3 Driver files for VIM1/VIM2/VIM3/VIM3L boards

• Driver-VIM4 Driver files for the VIM4 board

• VIM1_2_3.exe Burning tool for VIM1/VIM2/VIM3/VIM3L boards

• VIM4.exe Burning tool for the VIM4 board

---

2 Driver installation

1. Enter the Driver-VIM1_2_3 directory, and install dpscat.exe. The installation process is quick, and there’s is no GUI display.
2. Install dpinst64.exe. After the installation is successful, you can burn the firmware.

---

3 Download OS-image

Full link: https://dl.khadas.com/firmware/

• Download your image of choice
• Extract the image when downloaded

---

4 BURN-tool

• Make sure the drivers are all installed!
• Enter the burn tool directory, open VIM1_2_3.exe, click File–>Import Image, then choose an image for your board (the one downloaded from the firmware page).

---

4.1 Flash OS using BURN-tool

• Connect your board to your PC with a USB-C data cable (the board will power on automatically).

• Put your board into Upgrade Mode.

Recommended upgrade modes:

Option 1 - "Keys Mode"

1. Power on VIM3 (plug-in cable).
2. Long press the POWER key without releasing it.
3. Short press the ‘Reset’ key and release it.
4. Count for 2 to 3 seconds, then release the POWER key to enter into Upgrade Mode. You will see the sys-led turn ON when you’ve entered Upgrade Mode.

---

4.1 Flash OS using BURN-tool

Option 2 - "TST Mode" (recommended)

1. Power-on VIM3 (plug-in cable).
2. Quickly press the Function key 3 times in 2 seconds, then release the key.
3. You will see the Power-LED (Blue) blink for about 3 seconds. After the Power-LED (Blue) turns OFF, this indicates that the board is in Upgrade Mode (Maskrom Mode).
   

---

4.2 Flash the OS and detatch device

If you have performed all steps to put your device in Upgrade mode correctly, your PC/laptop will automatically discover the board as an attached USB-device.

Now you should see your device listed in the burn-tool.

To start flashing the OS, click Start button and wait for burning to complete.

4.2.1 Detatch

Once completed you can execute the following steps:

1. Disconnect device from PC/laptop
2. Click Stop in the BURN-tool
3. Close the BURN-tool

4.3 Flash fast (for recurring OS-flashing in short period)

When you need to change or set the OS-image for multiple devices in a short period or for 20 Khadas boards for example, this step will be faster in the long run.

1. First go to the firmware page for your device (VIM3 in this case).
   Select "oowow" and download the image.
   "Oowow" is comparable to a PC bios, from there you can configure some things quicker.

2. Once the image is downloaded flash this image to an SD-card using BalenaEtcher or Rufus and insert it into the underside of the VIM3 board.

3. Remove the SD-card from your PC and insert it again. Two drive letters will appear, one containing a folder "downloads".
   Add the RAW-image file downloaded from the fermware docs (image you want to install on to the eMMc storage).
   Contents of your "downloads" folder could look like this;
   

4. Remove the SD-card from your PC and insert it into the VIM3
   Supply power to the board (or press P button to boot) and wait for a screen looking like the following:
   

(Use arrows and enter to navigate the menu).
Here we want to write an image to eMMc-storage.
Press enter to say "okay" and go to the next screen.

Here we want to go to the downloads folder to select our image.

Select your image of choice to install.

Wait for installation to be done and follow further instructions shown on screen.

---

5 First boot

If the OS is finally flashed on the device eMMc-storage you can connect an HDMi-cable to the device and power it up using the POE-extension board or just by pluging in a USB-C cable.

The Khadas logo and icon of your selected OS will appear.
Afterwards a login is required.

Default credentials are:
User: khadas
Password: khadas

---

6 Enable networking on the M2X-extension board

Change file "/boot/env.txt"
sudo vim /boot/env.txt and add the following to the overlays variable;
overlays=m2x-eth

Make sure the following files are also changed accordingly:

• Change hostname in /etc/hostname
• Add static-IP and hostname to /etc/hosts
• Add DNS-nameservers to /etc/resolv.conf
• Set the IP-address with the ifconfig command sudo ifconfig eth0 YourIPAddress netmask YourNetMask

(To quickly configure these files check step 7)

!Last but most importantly! make sure the /etc/network/interfaces has the following config inside:
(When the file does not exist create it).

auto eth0
iface eth0 inet static
address 172.16.0.4
gateway 172.16.0.126
netmask 255.255.255.128

(IP and netmask may differ for your setup).
The correct ethernet interface is most important as this will make sure the IP-address stays mapt to it on reboot.
When the wrong ehternet interface is defined the IP-address will erase itself on reboot, which requires you to reconfigure the IP on each reboot.

After all the files are correctly changed, reboot the device: sudo reboot

Warning: When using "sudo apt upgrade" This setting "m2x-eth" will disappear form the /boot/env.txt file which makes the port of the extension board inactive.
You will need to manually reset this setting (add to end of file).

To change username etc, follow these links;
https://askubuntu.com/questions/34074/how-do-i-change-my-username
https://www.cyberciti.biz/faq/ubuntu-change-hostname-command/
https://www.cyberciti.biz/faq/linux-set-change-password-how-to/

---

7 Change default settings on device using script

1. First insert a USB containing the script in to the device.
2. Next login as root user.
3. Create a folder to mount USB contents to e.g; "usb-device" (mkdir ~/usb-device)
4. Check path of USB-device (lsblk)
5. Mount USB-device to just created folder (sudo mount /dev/**yourUSBEndpoint** ~/usb-device)
6. Execute script (./scriptName.sh) and follow instructions.

The following script can be used to quickly configure the Khadas Vim 3.

#!/bin/bash
echo "Script to update your (1) password, (2) username, (3) system configuration updates (Executes as user !root!)"



UpdateDefaultPassword(){
echo "(1) Please enter username to change password (root or khadas):"
read username
echo "(1) Please enter the NEW password:"
read -s password1
echo "(1) Please REPEAT the NEW password:"
read -s password2

# Check both passwords match
if [ $password1 == $password2 ]; then
    echo "Changing password..."
     echo  "$username:$password2" | chpasswd
else
    echo "Passwords do not match"
    exit
fi
#echo -e "(1) $password1n$password1" | passwd $username
}


#Change current username to "delaware" allong with home folder...
#echo "(2) Please enter your the username u want to update:"

UpdateDefaultUser(){
echo "(2) Please enter your NEW username:"
read newUsername
echo "(2) Please enter your Old username (root or khadas):"
read oldUsername
usermod -l $newUsername $oldUsername
echo "(2) Updating group name..."
groupmod -n $newUsername $oldUsername
echo "(2) Updating home folder..."
usermod -d /home/$newUsername -m $newUsername
}




#UpdateFiles(){
#echo "Enter a hostname u want to use for the device:"
#read hostname
#if [-f "/etc/network/interfaces"]
#then
#    sed -i 's/Khadas/GSI-BE-KOR-SV04/' /etc/hostname #"-i 's/search_string/replace_string/'  " =>    '-i' means that if the string exists in the file it will be replaced, 's' means "substitute"
#else
#    echo "File does not exist, creating now..."
#    touch /etc/network/interfaces
#    cat $hostname >> /etc/network/interfaces
#fi
#}


UpdateFiles(){
echo "(3) Before updating system files we need some configuration information (type ctrl+c if you do not want to proceed)"
echo "(3) Enter the host IP-address:"
read ipAddress
echo "(3) Enter the gateway IP:"
read gateway
echo "(3) Enter the netmask:"
read netmask
echo "(3) Enter the hostname (make sure it is correct before proceeding)!"
read hostname

arrayOfFilesToUpdate=("/etc/hostname" "/etc/hosts" "/etc/network/interfaces" "/etc/resolv.conf" "/boot/env.txt")
ethernetPort="eth0"
#ipAddress="172.16.12.4"
#gateway="172.16.12.126"
#netmask="255.255.255.128"
#hostname="GSI-BE-GEN-SV04"

nameserver1="172.19.12.4"
nameserver2="172.19.12.5"
nameserver3="1.1.1.1"
nameserver4="1.0.0.1"

for file in "${arrayOfFilesToUpdate[@]}"; do
	case $file in
  	/etc/hostname)
		  echo "(3.0) Updating hostname file"
    	sed -i ''"s/Khadas/${hostname}/"'' /etc/hostname;; #"-i 's/search_string/replace_string/'  " =>    '-i' means that if the string exists in the file it will be replaced, 's' means "substitute"
	
    	
  	/etc/hosts)
	  echo "(3.1) Updating hosts file"
    	sed -i ''"s/127.0.0.1/${ipAddress}/"'' /etc/hosts
    	sed -i ''"s/Khadas/${hostname}/"'' /etc/hosts ;;
   
  	/etc/network/interfaces)
	  echo "(3.2) Updating interface settings"
   	 > /etc/network/interfaces #Clear file of any contents
 	echo ''"auto ${ethernetPort}"'
'"iface ${ethernetPort} inet static"'
'"address ${ipAddress}"'
'"gateway ${gateway}"'
'"netmask ${netmask}"'' > /etc/network/interfaces ;;

  	/etc/resolv.conf)
	  echo "(3.3) Updating DNS name servers"
    	> /etc/resolv.conf #Clear file of any contents
    	echo ''"nameserver ${nameserver1}"' 
'"nameserver ${nameserver2}"'
'"nameserver ${nameserver3}"'
'"nameserver ${nameserver4}"'' > /etc/resolv.conf ;;
  
  	/boot/env.txt)
	  echo "(3.4) Updating boot file"
    	#Append to end of file
	sed '${s/$/ m2x-eth/}' /boot/env.txt;;
	#echo " m2x-eth" >> /boot/env.txt;;
	*)
		echo -n "File changes failed... (could already be set to expected values)!"
    	;;
	esac
done
}

echo " "
echo "You are about to configure the default password."
read -p "Do you want to proceed? Y/n " -n 1 -r
echo    # (optional) move to a new line
if [[ $REPLY =~ ^[Yy]$ ]]
then
UpdateDefaultPassword
fi

echo " "
echo "You are about to change/update the username."
read -p "Do you want to proceed? Y/n " -n 1 -r
echo    # (optional) move to a new line
if [[ $REPLY =~ ^[Yy]$ ]]
then
UpdateDefaultUser
fi

echo " "
echo "You are about to make significant configuration changes to the system."
read -p "Do you want to proceed? Y/n " -n 1 -r
echo    # (optional) move to a new line
if [[ $REPLY =~ ^[Yy]$ ]]
then
UpdateFiles
echo "Configuration updated, remove the USB-device, before reboot please check if "m2x-eth" is defined in "/boot/env.txt" otherwise the extension board will not be used and the device will not get an IP.
fi

Warning: When using "sudo apt upgrade" This setting "m2x-eth" will disappear form the /boot/env.txt file which makes the port of the extension board inactive.
You will need to manually reset this setting (add to end of file).

---

8 RE-flash eMMc-storage

If u want to change the OS that is burnt on the devices eMMc-storage, you can do so by going back to step 4 and 4.1 in this GUIDE.
To RE-flash it is required (recommended) to use TST Mode, otherwise the PC/laptop will not detect the board and the device will boot in the OS that is already on the device.

Warning: This will fully wipe the eMMc-storage, a backup is recommended when working with critical data on the device!

---

9 Costum OS-images

Specific images may not be available on the Khadas site itself. For example; (at time of writing) we wanted to upgrade to Ubuntu 22.04 for eMMc storage. But that image whas not provided by default in the Khadas documentation. Therefore you could create your own images with the khadas spices added.

Documentation to create an costum image.

Khadas repo for costum image creation.

---

Install DOOM for fun

Follow this guide:
https://www.makeuseof.com/tag/run-doom-raspberry-pi/