# Introduction
This guide demonstrates how to quickly start Linux on the AM64x Starter Kit (SK), log in to
the wireless Access Point (AP) and run out-of-box demos. This can be done from any PC platform
(Windows, Linux or macOS).
Please refer to [AM64x Starter Kit](https://www.ti.com/tool/SK-AM64B) for detailed information
about the Starter Kit.
# Hardware Setup
In addition to the Starter Kit (SK) itself, the following hardware is needed:
* USB-C 5V 3A power supply or USB-C to USB-C cable for powering from PC
* USB SD card writer
* Micro-SD card **(16GB or larger)**
* USB Micro-B cable for UART serial communication
* Ethernet cable (optional)
The figure below shows the basic hardware setup required to start Linux on the SK.
The simplest way to run Linux on the Starter Kit is through an SD card. For that, the SK will need to be
configured for SD card boot. Refer to [AM64x SK User's Guide](https://www.ti.com/lit/spruj64) for
detailed information about boot mode configurations. For quick reference, the figure below shows the
boot mode switches setting for SD card boot.
# Software Setup
To boot Linux on AM64x SK through an SD card, a Linux bootable SD card needs to be created. In order
to do that, an AM64x Linux WIC image and an image writing utility are needed.
### Getting the AM64x Linux WIC Image
Go to [Processor-SDK download page](https://www.ti.com/tool/PROCESSOR-SDK-AM64X). Click "Downloads" and
then choose either PROCESSOR-SDK-LINUX-AM64X or PROCESSOR-SDK-LINUX-RT-AM64X. Click "Download options"
and then find and download the WIC image tisdk-default-image-am64xx-evm.wic.xz.
The WIC image is also available inside the SDK which can be downloaded from the same page.
After SDK is installed, tisdk-default-image-am64xx-evm.wic.xz is located at
processor-sdk-install-folder/filesystem.
### Writing the WIC Image to SD Card
An image writing utility is needed to write the WIC image to an SD card. An open source project,
[balenaEtcher](https://www.balena.io/etcher/), is recommended for this purpose, which works with
Windows, macOS and Linux.
After balenaEtcher is installed, insert a micro SD card into the USB SD card writer and start balenaEtcher.
Choose the compressed WIC image obtained in previous step, choose the USB SD card writer as the
target, and then click "Flash". Etcher will decompress the image and write it to the SD card,
as shown below.
[[b! Additional Steps for AM64x SR1.0
A few additional steps are needed for SR1.0 boards, after flashing the Linux image to an SD card. Please refer to
<a href="javascript:void(0)" onclick="window.parent.jumpToTirexNode('A__AIPGKdkKPa-dZtlGjPW0rw__AM64-ACADEMY__WI1KRXP__LATEST')">AM64x Academy</a>,
Evaluating Linux -> Create a Linux Bootable SD Card.
]]
# Establishing a Serial Connection with the SK
Connect the USB Micro-B cable to the USB Micro-B debug console on the SK, which is right next to the
USB-C connector. Open a serial port console on the host PC, according to procedures described below
for Linux, Windows or macOS. When the serial console opens, it will be blank until the SK powers up.
### Connecting with Linux
1. Determine the device name associated with the SK by running the following command on your Linux PC:
```
dmesg | grep ttyUSB
```
You should see results similar to this:
```
[353309.273191] usb 2-1.5: cp210x converter now attached to ttyUSB0
[353309.275906] usb 2-1.5: cp210x converter now attached to ttyUSB1
```
This means the SK has two serial ports and the second one should be used for serial communication.
2. Use the following command to open a serial port console:
```
screen /dev/ttyUSB1 115200
```
### Connecting with Windows
1. If your Windows PC doesn't recognize the device, download and install the driver from
[here](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
2. Open Windows Device Manager and it should show 2 COM ports associated with the SK, as shown below:
3. Use a serial terminal emulator such as TeraTerm to connect to the second port. Configure the
serial port setting to 115200 baud rate, 8 bit, no parity, 1 stop bit, no flow control, as shown below:
### Connecting with MacOS
1. If macOS doesn't recognize the device, download and install the driver from
[here](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
2. Verify the driver is working by running this command:
```
ls /dev/cu*
```
You should see /dev/cu.SLAB_USBtoUART listed.
3. Use the following command to open a serial port console:
```
screen /dev/cu.SLAB_USBtoUART 115200
```
# Running Linux and Demos on the SK
### Booting Linux
Assuming you have made a Micro-SD card with AM64x Linux image and connected to the SK's serial
port, you can boot the SK to Linux now:
1. Insert the Micro-SD card to the SK (the side of the card with contacts should face upward).
2. Make sure the boot mode switches are set properly for SD card boot as described earlier.
3. Connect one end of the USB-C cable to the SK and plug in the other end to the power adapter or PC.
4. The SK should boot and the booting progress should display in the serial console output. At the end
of booting, the Arago login prompt will appear. Just enter "root" to log in, as shown below:
You are in Linux on your AM64x Starter Kit now and can proceed to run the out-of-box demos next.
### Connecting to SK's WiFi Access Point
This step can be skipped if the SK is connected to a router or switch through an Ethernet cable. Follow
the steps listed below to connect and log in to the WiFi AP on the SK:
* Scan for WiFi network on your phone or PC. The Access Point running on SK is named "AM64xSK-AP".
* Log in to AM64xSK-AP using password "**tiwilink8**".
* The serial terminal console will display "WPA: pairwise key handshake completed" if logging in succeeds.
### Running Matrix GUI
* Open a web browser on phone or PC and type the proper URL depending on the connection method:
* On phone or PC connected to the WiFi AP, use "http://192.168.43.1" as the URL.
* On PC connected to the same Ethernet as the SK, find the IP address of the SK using command
"ifconfig" and enter it to the browser address bar.
* Click "OK" and it will bring up the Matrix GUI as shown below. Next few steps show how to run
a Matrix application of lmbench on DDR data movement.
* Click icon "ARM" to go to the ARM benchmarking suites. Then click "DDR Bandwidth" to run the
lmbench benchmarks on DDR data movement.
* Click "RUN" to run the benchmarking.
* The benchmarking will run and display results after it finishes.
### Running Benchmark Demo
* In the web browser address bar of previous step, enter ":8081" at the end of the URL, i.e.
* **192.168.43.1:8081** for WiFi connection.
* **SK-ip-address:8081** for Ethernet connection.
* Then click "Benchmark Demo" and it will bring up the benchmark demo as shown below.
# Next Steps
After booting the AM64x Starter Kit to Linux, users are encouraged to explore more through the
<a href="javascript:void(0)" onclick="window.parent.jumpToTirexNode('A__AIPGKdkKPa-dZtlGjPW0rw__AM64-ACADEMY__WI1KRXP__LATEST')">AM64x Academy</a>.
# Troubleshooting
Here we list some common problems which may happen during this exercise and the corresponding solutions.
1. **The Starter Kit doesn't power up and no LEDs are illuminated after connecting the USB-C cable.**
This is usually caused by not having the right power supply. Please make sure a USB-C power adapter
or a USB-C to USB-C cable is used. A USB to USB-C cable will not work.
2. **SK is connected to the PC, but the PC doesn't recognize the device.**
This may be caused by connecting to the wrong port on the SK. Please make sure you connect to the
USB Micro-B connector right next to the USB-C connector.
This problem can also happen if the host PC doesn't have the CP210x USB to UART Bridge driver.
Please download the driver from [here](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
3. **The SK doesn't boot and the serial console doesn't display anything.**
First, make sure the Micro-SD card is flashed with the right WIC image.
Then double check the SK boot mode setting and it must be configured for SD card boot.
4. **The SK boots but it doesn't end up with the login prompt.**
This is likely caused by having a Micro-SD card with size less than 16GB. Please use a card with
16GB or larger capacity.
5. **The EVM boot stops in U-Boot or the kernel log has failure messages related to mmc1.**
This could be caused by Issue #7 mentioned in the [AM64x SK User's Guide](https://www.ti.com/lit/spruj64),
Section 5.7 "Issue 7 - uSD Card Boot Not Working". Please use a different brand of SD card or fix the
EVM according to the SK User's Guide.
If you encounter any other issues not listed here, please go to
[E2E Processor Forum](https://e2e.ti.com/support/processors-group/processors/f/processors-forum) for help.
<div align="center" style="margin-top: 4em; font-size: smaller;">
<a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="./web_support/cc_license_icon.png" /></a><br />This work is licensed under a <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/">Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License</a>.</div>