= UART =

The board features makes both JTAG and UART available over a micro USB connector. It appears as two separate devices in Linux (/dev/ttyUSB0, /dev/ttyUSB1). The second ttyUSB device represents the UART. The baudrate is 57600 for the Boot ROM but 115200 for U-Boot and Linux.

You can use the package picocom to access the serial console:

{{{
sudo apt-get install picocom
sudo picocom -b 115200 /dev/ttyUSB1
}}}


== Boot device selection ==

Set jumpers to boot from the microSD by setting MSEL=1011 (MSEL2 to the outside of the board, the rest to the inside).

== Using the server install image ==

=== Copying Ubuntu onto the SD-card ===

Download the Ubuntu live install server image and flash it on your sdcard using:

{{{
zcat ubuntu-22.04.2-live-server-riscv64.img.gz | sudo dd of=/dev/sdX bs=1M conv=fsync
}}}

You will have to replace ''/dev/sdX'' by the actual device name of your SD card.
Please, be especially cautious not to overwrite the wrong drive as this cannot be undone.

=== Installation ===

Establish a serial console connection to the Unmatched board.

{{{
sudo picocom -b 115200 /dev/ttyUSB1
}}}

Insert the SD card and power up the system.

If no prior operating system installation exists, U-Boot will start up GRUB on the SD card.

Otherwise press the enter key when seeing the ''Hit any key to stop autoboot:'' message and execute:

{{{
pci enum
nvme scan
load mmc 0:1 $fdt_addr_r dtb/sifive/hifive-unmatched-a00.dtb
load mmc 0:1 $kernel_addr_r EFI/boot/bootriscv64.efi
bootefi $kernel_addr_r $fdt_addr_r
}}}

In the GRUB menu select ''Try or Install Ubuntu Server''.

Reading from the SD card is very slow. Loading the installer takes several minutes. Once it is loaded follow the installation steps in https://ubuntu.com/tutorials/install-ubuntu-server.

When the installation is finished reboot the board without removing the SD card.

U-Boot does not allow the operating system to write UEFI variables. We have to do this manually. While rebooting press the enter key when seeing the Hit any key to stop autoboot: message. The following commands set up the installation on the NVMe drive as UEFI boot option 0001.

{{{
pci enum
nvme scan
efidebug boot add -b 0001 'Ubuntu Jammy' nvme 0:1 /EFI/ubuntu/grubriscv64.efi
efidebug boot order 0001
}}}

To boot into your fresh installation you can use:

{{{
bootefi bootmgr
}}}

On the next boot U-Boot will automatically start into GRUB.

=== Installing the Gnome desktop ===

If you have a graphics card installed, you may want to use a graphical desktop.
The Gnome desktop can be installed with

{{{
sudo apt-get update
sudo apt-get install ubuntu-desktop
sudo systemctl start gdm3
}}}


== Using the preinstalled server image ==

=== Copying Ubuntu onto the SD-card ===

Download the Ubuntu preinstalled server image and flash it on your sdcard using:

{{{
xzcat lunar-preinstalled-server-riscv64+unmatched.img.xz | sudo dd bs=1M conv=fsync of=/dev/sdX
}}}

You will have to replace ''/dev/sdX'' by the actual device name of your SD card.
Please, be especially cautious not to overwrite the wrong drive as this cannot be undone.

=== First boot ===

Establish a serial console connection to the Unmatched board.

{{{
sudo picocom -b 115200 /dev/ttyUSB1
}}}

Insert the SD card and power on the board.

When booting the first time wait until you see an output line confirming that cloud-init has finished. Cloud init is responsible for generating the SSH keys and setting the default password. Cloud init itself will also need a few minutes. The line to wait for will look similar to
{{{
[  150.053340] cloud-init[1274]: Cloud-init v. 23.1.1-0ubuntu2 finished at Mon, 03 Apr 2023 11:14:35 +0000. Datasource DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net].  Up 150.00 seconds
}}}

Now you can login with user ''ubuntu'' and the default password ''ubuntu'' and will be asked to choose a new password.

=== cloud-init integration ===

The image has a fallback cloud-init datasource that configures sudo user `ubuntu` with password `ubuntu` and DHCP networking. You will be asked to change the password on first login.

The image has `CIDATA` partition which can be used as a valid datasource to adjust cloud-config metadata. If you wish to customize user password, networking information, add ssh keys, etc. Please mount `CIDATA` partition rename `meta-data` and `user-data` files and adjust them to taste. You can use network-info to configure networking if something more sophisticated than just DHCP is desired.

For example ssh keys, disabling interactive login, and so on. See https://cloudinit.readthedocs.io/en/latest.