diff --git a/README.md b/README.md
index 7403d8b15573cfaf5509e1458149ae8d2e3be503..202882b82e38a7f32e329559342826f1b45139f3 100644
--- a/README.md
+++ b/README.md
@@ -2,55 +2,40 @@
## Description
-This is a virtual machine configurator to set up Ubuntu version 20.04 with Quartus Prime Lite edition. The intended audience for this repository is for students of [ELEN20006](https://handbook.unimelb.edu.au/subjects/elen20006/eligibility-and-requirements).
+This is a virtual machine configurator to set up Ubuntu version 20.04 with Quartus Prime Lite edition. The intended audience for this repository is for students of [ELEN20006](https://handbook.unimelb.edu.au/subjects/elen20006).
This will provide an environment with:
-* Quartus Prime Lite edition (Version 20.1.1)
+* Quartus Prime Lite edition (Version 20.1)
* Modelsim Starter Edition
-* [DESim](https://github.com/fpgacademy/DESim)
+* TODO: [DESim](https://github.com/fpgacademy/DESim)
-If you wish to use your own machine for this class, it is recommended that you use the virtual machine. This makes it easier for the demonstrators to help you as there is unlikely to be any issues with the installation of Quartus.
-
-Successfully setting up this virtual machine will allow the demonstrators to help you more e
+If you wish to use your own machine for this class, it is recommended that you use the virtual machine (Quartus does not run on OS X). This makes it easier for the demonstrators to help you as there is unlikely to be any issues with the installation of Quartus.
## Tested working on
Operating System | CPU | Memory
---------|----------|---------
-Windows 10 | Intel i5 | 16GB DDR3 RAM
-macOS Big Sur | Intel i5 | 8GB LPDDR3 RAM
-Arch Linux | AMD Ryzen | 32GB DDR4 RAM
+Windows 10 | Intel i5 (4 cores, 4 threads) | 16GB DDR3 RAM
+macOS Big Sur | Intel i5 (2 cores, 4 threads) | 8GB LPDDR3 RAM
+Arch Linux | AMD Ryzen (32 cores, 64 threads) | 32GB DDR4 RAM
## Prerequisites
-
-
* [VirtualBox (with extensions)](https://www.virtualbox.org/wiki/Downloads "VirtualBox Download Page")
* [Vagrant](https://www.vagrantup.com/downloads "Vagrant Download Page")
* [Git](https://git-scm.com/downloads "Git Download Page")
-* Memory: 8GB or more recommended (if you have less see step 6 in instructions)
-* Hard Drive Space: At least 40GB free space (final intalled size is <span>≅</span> 30GB)
-
-
-
+* Memory: 4GB (8GB or more recommended, see step 6 in instructions)
+* Hard Drive Space: At least 40GB free space (final installed size is <span>≅</span> 30GB)
## Usage
-Simply run the respective run script for your operating system:
-
-Windows (PowerShell): `.\run_windows`
-
-Linux (bash): `./run_linux.sh`
-
-Mac (terminal): `./run_unix`
-
-Note: This will likely take 1-2 hours (depending on your internet speed).
+Once installed, simply type `vagrant reload` in the cloned repository folder in a shell to bring up the virtual machine.
# Complete Installation Steps (Windows and Mac)
-1. Installing [Virtualbox](https://www.virtualbox.org/wiki/Downloads "VirtualBox Download Page")
+1. Install [Virtualbox](https://www.virtualbox.org/wiki/Downloads "VirtualBox Download Page")
- VirtualBox will be used to run the Ubuntu virtual machine for this.
+ VirtualBox will be used to run the Ubuntu virtual machine for this.
- Download and install the hosts package for your personal machine (OS X for Mac, etc)
+ Download and install the hosts package for your personal machine (OS X for Mac, etc)
**Windows**
@@ -58,32 +43,33 @@ Note: This will likely take 1-2 hours (depending on your internet speed).
**Mac**
- Download and install the OS X hosts package. OS X will ask for a file permission change. This will require a file extension permission:
+ Download and install the OS X hosts package. OS X will ask for a file permission change. Allow this to happen as this is required for the next step.
-2. Installing [VirtualBox Extensions](https://www.virtualbox.org/wiki/Downloads "VirtualBox Download Page")
+2. Install [VirtualBox Extensions](https://www.virtualbox.org/wiki/Downloads "VirtualBox Download Page")
- Virtualbox extensions will allow us to pass through USB 2.0 devices. This is required for programming the FPGA Development Boards (DE1-SoCs)
- The VirtualBox Extension Pack is also found on the downloads page for VirtualBox. Once VirtualBox is installed, simply double click the package to install.
+ Virtualbox extensions will allow us to pass through USB 2.0 devices. This is required for programming the FPGA Development Boards (DE1-SoCs)
-3. Installing [Vagrant](https://www.vagrantup.com/downloads "Vagrant Download Page")
+ The VirtualBox Extension Pack is also found on the downloads page for VirtualBox. Once VirtualBox is installed, simply double click the package to install.
+
+3. Install [Vagrant](https://www.vagrantup.com/downloads "Vagrant Download Page")
* Vagrant is used to create and configure our virtual machine.
* Download and install Vagrant.
-4. Installing [Git](https://git-scm.com/downloads "Git Download Page")
+4. Install [Git](https://git-scm.com/downloads "Git Download Page")
This repository contains the necessary scripts and configurations Vagrant requires to build up the virtual machine.
**Windows**
- Download and install git from the webpage.
+ Download and install git from the webpage.
**Mac**
- In spotlight search, type in terminal. Open the terminal, type in git and hit enter. A prompt will appear to install xcode, click yes.
+ In spotlight search, type in terminal. Open the terminal, type in git and hit enter. A prompt will appear to install xcode, click yes.
5. Downloading this repository
@@ -94,22 +80,23 @@ Note: This will likely take 1-2 hours (depending on your internet speed).
1. Create the folder where you want to store this repository. On Windows I use C:\workspace\
If you are unsure what to do here. Type PowerShell into your search bar and open powershell. Inside of Powershell type: `mkdir C:\workspace`
+
+ 2. Shift+Right Click in the folder that you wish to clone to and click "Open PowerShell window here".
+ 
- 2. . Shift+Right Click in the folder that you wish to clone to and click "Open PowerShell window here".
- 
+ 3. Copy and paste `git clone https://gitlab.eng.unimelb.edu.au/david_lynch/vagrant-with-quartus.git` into powershell and then hit enter (don't close PowerShell).
- 3. . Copy and paste `git clone https://gitlab.eng.unimelb.edu.au/david_lynch/vagrant-with-quartus.git` into powershell and then hit enter (don't close PowerShell).
- 
+ 
**Mac**
1. Create the folder where you want to store this repository. On Mac (and Linux) I use ~/workspace/
- If you are unsure what to do here. Type terminal into your search bar and open a terminal. Inside of the terminal type: `mkdir ~/workspace/`
+ * If you are unsure what to do here. Type terminal into your search bar and open a terminal. Inside of the terminal type: `mkdir ~/workspace/`
- **Note**: ~/ corresponds the the home folder in Linux and Mac operating systems. For example, on a Mac if your username was John then ~/Desktop/ = /Users/John/Desktop/
+ * **Note**: ~/ corresponds the the home folder in Linux and Mac operating systems. For example, on a Mac if your username was John then ~/Desktop/ = /Users/John/Desktop/
- 2. Open a terminal again from spotlight. You will need to know the path of the folder you created. Assuming you created it in ~/workspace/ - type cd ~
+ 2. Open a terminal again from spotlight. You will need to know the path of the folder you created. Assuming you created it in ~/workspace/ - type `cd ~/workspace` and hit enter.
3. Copy and paste `git clone https://gitlab.eng.unimelb.edu.au/david_lynch/vagrant-with-quartus.git` into the terminal and then hit enter (don't close the terminal).
@@ -119,13 +106,55 @@ Note: This will likely take 1-2 hours (depending on your internet speed).
* This is an attempt to cater for all students.
* If you have <span>≥</span>16GB of memory and <span>≥</span> 4 CPU cores, this is where you have the option of increasing the virtual machines allocation. Increasing the amount of memory is recommended if you can. Increasing the number of CPU cores may help but in my experience 2 is fine for Quartus Lite.
- Inside of the downloaded folder, there is a file called _Vagrantfile_
+ Inside of the downloaded folder, there is a file called _Vagrantfile_.
+
+ 1. Open the Vagrantfile
+ 2. There is a line `vb.memory = "4096"` that controls the amount of memory allocated. If you have <span>≥</span>16GB of memory, set this to 8192. If you have 4GB of memory set this to 2048
+ 3. There is a line `vb.cpus = "2"` that controls the number of CPUs allocated. If you have more than 4 cores / 4 threads then feel free to increase this. I would recommend not going above 4 for stability reasons.
7. Creating the virtual machine
- **NOTE**: THIS NEXT STEP WILL DOWNLOAD 30GB OF FILES, ENSURE YOU HAVE ENOUGH SPACE ON YOUR COMPUTER
+ **NOTE**: THIS NEXT STEP WILL DOWNLOAD 30GB TO 40GB OF FILES, ENSURE YOU HAVE ENOUGH SPACE ON YOUR COMPUTER
+ 1. In the shell/terminal you have been using, type `cd vagrant-with-quartus` and hit enter. If you had closed the terminal/shell then you will have to `cd` into this directory.
+
+ 2. In Windows type `.\run_windows.bat`. In Mac type `./run_unix.sh`. This will begin the virtual machine creation.
+
+ 3. Wait. This will likely take hours to build and install all the required software.
+
+8. Once the install process has finished, you should see the following screen in the VirtualBox window:
+
+ 
+ * The password is _vagrant_
+
+9. Check that the system is working.
+
+ * Try opening Quartus. In the bottom left corner of the virtual machine click on the KDE logo. In the search bar type Quartus and open it if it shows up.
+ * Try opening Modelsim. Repeat above with Modelsim.
+ * Dolphin is the default file explorer in KDE. Open an instance of Dolphin and check if the fpga_gui folder is present. Open it and double click `run.sh`. Did it open the simulator?
+
+
+## Troubleshooting
+
+I ran the installer but the login screen is just text screen saying _login:_
+* The installer wasn't able to complete.
+ * First, where you ran `run_windows.bat` or `run_unix.sh`, run `vagrant destroy` and confirm. Second, you may have to delete an additional folder. In Windows this folder will be 'C:\Users\\{USERNAME}\VirtualBox VMs\Quartus_Ubuntu'. On Mac this will be '~/VirtualBox VMs/Quartus_Ubuntu'. Go back to step 7 of the installation and try again. Please ensure a stable internet connection.
+
+The Quartus Programmer isn't detecting the DE1-SoC
+
+* There could be multiple causes for this.
+
+ * Make sure the USB cable is not plugged into a USB hub. Plug it directly into your computer. I had this issue multiple times whilst testing this.
+ * Try opening and closing hardware setup in the Quartus Programmer a 2-3 times. This often works.
+
+ 
+
+ * Check that the USB filter in virtual box is showing up. It should appear as below. If it is not there, you may have opened the virtual machine from VirtualBox. Ensure that the virtual machine is opened through using the command `vagrant reload`
+
+ 
+
+
## Contribution
diff --git a/Vagrantfile b/Vagrantfile
index 2fa7d179392bc656d7676f88c02e5223ed32936f..2a2582b5a68966077abf6563bf1dbb909ccc0c91 100644
--- a/Vagrantfile
+++ b/Vagrantfile
@@ -9,7 +9,8 @@ Vagrant.configure("2") do |config|
focal.vm.provider "virtualbox" do |vb|
vb.gui = true
vb.name = "Quartus_Ubuntu"
- vb.memory = "8192"
+ vb.cpus = "2"
+ vb.memory = "4096"
vb.customize ["modifyvm", :id, "--vram", "128"]
vb.customize ["modifyvm", :id, "--graphicscontroller", "vmsvga"]
vb.customize ["modifyvm", :id, "--accelerate3d", "on"]
diff --git a/images/login_screen.PNG b/images/login_screen.PNG
new file mode 100644
index 0000000000000000000000000000000000000000..52f1a0de53b1dda60166d52b34c36b544845b666
Binary files /dev/null and b/images/login_screen.PNG differ
diff --git a/images/opening_a_shell.png b/images/opening_a_shell.png
index 573b8e605ef07b7c09a2563aed54ca700114c8c1..5a062eabb85229c5f39ad95e0cb199d8d0856a54 100644
Binary files a/images/opening_a_shell.png and b/images/opening_a_shell.png differ
diff --git a/images/quartus_programmer.PNG b/images/quartus_programmer.PNG
new file mode 100644
index 0000000000000000000000000000000000000000..b33709d5f1589167dcca381e236db5015ccceeb3
Binary files /dev/null and b/images/quartus_programmer.PNG differ
diff --git a/images/usb_filter.PNG b/images/usb_filter.PNG
new file mode 100644
index 0000000000000000000000000000000000000000..77220c86db61966acdea20b57f1eb2b42af1bebd
Binary files /dev/null and b/images/usb_filter.PNG differ
diff --git a/run_unix.sh b/run_unix.sh
new file mode 100644
index 0000000000000000000000000000000000000000..8d0aa8254a8f655c07032b6d708682012f89cf10
--- /dev/null
+++ b/run_unix.sh
@@ -0,0 +1,7 @@
+ #!/bin/bash
+set -x
+
+script_dir=$(cd $(dirname ${BASH_SOURCE[0]}) && pwd)
+
+vagrant up
+vagrant reload