Document WSL and update ProxSpace instructions

CHANGELOG.md

@@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file.
 This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log...
 
 ## [unreleased][unreleased]
+ - Add documentation for usage of Proxmark3 under WSL (@doegox)
  - Change: replace ukbhit by kbd_enter_pressed, not requiring tcgetattr (@xianglin1998/@doegox)
  - Add config for RaspberryPi in JTAG tools (@doegox)
  - Add config for FTDI C232HM-DDHSL-0 in JTAG tools (@doegox)

doc/md/Installation_Instructions/Windows-Installation-Instructions.md

@@ -1,60 +1,149 @@
-# Building on Windows
+# Installing on Windows
-You will need to use the Gator96100 Proxspace package to assist in your windows installation.
+
-This can be downloaded from https://github.com/Gator96100/ProxSpace/
+There are two ways to install, build and use Proxmark3 on Windows:
+
+* Using Gator96100 **ProxSpace**, a package to assist in your Windows installation of MinGW
+* Using native **WSL**, if you're running a Windows 10 version recent enough (FCU 1709 or later)
 
 ---
-# Video Installation guide
+
+# Installing on Windows with ProxSpace
+
+## Video Installation guide
 [![Windows Installation tutorial](https://github.com/5w0rdfish/Proxmark3-RDV4-ParrotOS/blob/master/screenshot-www.youtube.com-2019.03.17-20-44-33.png)](https://youtu.be/zzF0NCMJnYU "Windows Installation Tutorial")
 
-## Manual Installation
+## Driver Installation
 
-### Driver Installation
+Install required drivers for your Windows installation. You may need admin privileges to do this.  
+Step by step guides are online such as [RiscCorps](https://store.ryscc.com/blogs/news/how-to-install-a-proxmark3-driver-on-windows-10).
 
-Install required drivers for your windows installation. You will may need admin privileges to do this. 
+## Download / clone ProxSpace repo
-(This is covered in the video) Step by step guides are online such as [RiscCorps](https://store.ryscc.com/blogs/news/how-to-install-a-proxmark3-driver-on-windows-10)
 
-### Install Github
+Download the Gator96100 ProxSpace package from https://github.com/Gator96100/ProxSpace/
 
-Install Github for Windows https://desktop.github.com/
+If you prefer, you can clone it, provided that you installed Github for Windows https://desktop.github.com/.
 
-### Download / clone Proxspace repo
+Extract 'ProxSpace' to a location path without spaces.  
-
-Download the required proxspace repo. https://github.com/Gator96100/ProxSpace/
-
-Extract 'ProxSpace' to a location on drive without spaces. 
 For example D:\OneDrive\Documents\GitHub is ok whereas C:\My Documents\My Projects\proxspace is not.
 
-### Clone the RRG/Iceman repository
+If you're running Windows in a Virtualbox guest, make sure not to install ProxSpace on a vbox shared drive. (It's ok later to move the `/pm3` subfolder to a shared drive and edit the `*.bat`)
 
-```sh
+## Launch ProxSpace
-git clone https://github.com/RfidResearchGroup/proxmark3.git
-```
-
-### Copy files to Proxspace
-
-Copy all the contents from the `proxmark3` folder into the proxspace `pm3` folder
-
-### Run the .bat
 
 Run `runme.bat` or `runme64.bat` depending on your Windows architecture.
 
-Please note you will need to use `/` as you are using BASH.
+You'll get a Bash prompt and your home directory should become the ProxSpace `pm3` sub-directory.
 
-### Compile and use the project
+Please note you will need to use `/` in paths as you are using Bash.
+
+## Clone the RRG/Iceman repository
+
+```sh
+cd
+git clone https://github.com/RfidResearchGroup/proxmark3.git
+cd proxmark3
+```
+
+## Compile and use the project
 
 Now you're ready to follow the [compilation instructions](/doc/md/Use_of_Proxmark/0_Compilation-Instructions.md).
 
-The only differences are that executables end with `.exe` (e.g. `client/flasher.exe`) and that the Proxmark3 port is one of your `comX` ports where "X" is the com port number assigned to proxmark3 under Windows.
+To use the compiled client and flasher, the only differences are that executables end with `.exe` (e.g. `client/flasher.exe`) and that the Proxmark3 port is one of your `comX` ports where "X" is the com port number assigned to proxmark3 under Windows.
 
-So flashing will resemble
+To flash: In principle, the helper script `flash-all.sh` should auto-detect your COM port, so you can just try:
+
+```sh
+./flash-all.sh
+```
+
+If COM port detection failed, you'll have to call the flasher manually and specify the correct port:
 
 ```sh
 client/flasher.exe comX -b bootrom/obj/bootrom.elf armsrc/obj/fullimage.elf
 ```
 
-And running the client will resemble
+Similarly, to run the client, you may try:
 
 ```sh
-cd client
+./proxmark3.sh
-./proxmark3.exe comX
+```
+
+Or, by specifying the COM port manually:
+
+```sh
+client/proxmark3.exe comX
+```
+
+# Installing on Windows with WSL
+
+It requires to run a Windows 10 version 1709 or above. Previous versions didn't have support for COM ports.
+
+Install WSL with e.g. the standard Ubuntu.
+
+For WSL configuration, see [Manage and configure Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/wsl-config).
+
+## Driver Installation
+
+Install required drivers for your Windows installation. You may need admin privileges to do this.  
+Step by step guides are online such as [RiscCorps](https://store.ryscc.com/blogs/news/how-to-install-a-proxmark3-driver-on-windows-10).
+
+## X Server Installation
+
+If you want to run the graphical components of the Proxmark3 client, you need to install a X Server such as [VcXsrv](https://sourceforge.net/projects/vcxsrv/) or [Xming](https://sourceforge.net/projects/xming/).
+
+## Dependencies
+
+Enter WSL prompt (`wsl`) and from there, follow the [Linux Installation Instructions](/doc/md/Installation_Instructions/Linux-Installation-Instructions.md) for Ubuntu, summarized here below:
+
+```sh
+sudo apt-get update
+sudo apt-get install p7zip git ca-certificates build-essential libreadline5 libreadline-dev libusb-0.1-4 \
+libusb-dev perl pkg-config wget libncurses5-dev gcc-arm-none-eabi libstdc++-arm-none-eabi-newlib \
+libqt4-dev
+```
+
+If you don't need the graphical components of the Proxmark3 client, you can skip the installation of `libqt4-dev`.
+
+## Clone the RRG/Iceman repository
+
+```sh
+git clone https://github.com/RfidResearchGroup/proxmark3.git
+```
+
+## Compile and use the project
+
+Now you're ready to follow the [compilation instructions](/doc/md/Use_of_Proxmark/0_Compilation-Instructions.md).
+
+To use the compiled client and flasher, the only difference is that the Proxmark3 port is translated from your `comX` port where "X" is the com port number assigned to proxmark3 under Windows, to a `/dev/ttySX`.
+
+You will need to give permission to the current user to access `/dev/ttySX`: (change X to your port number)
+
+```sh
+sudo chmod 666 /dev/ttySX
+```
+
+Unfortunately the access rights of the port won't survive and will have to be fixed again next time.
+
+If you installed a X Server and compiled the Proxmark3 with QT4 support, you've to export the `DISPLAY` environment variable:
+
+```sh
+export DISPLAY=:0
+```
+
+and add it to your Bash profile for the next times:
+
+```sh
+echo "export DISPLAY=:0" >> ~/.bashrc
+```
+
+To flash, you've to call the flasher manually and specify the correct port:
+
+```sh
+client/flasher /dev/ttySX -b bootrom/obj/bootrom.elf armsrc/obj/fullimage.elf
+```
+
+Similarly, to run the client:
+
+```sh
+client/proxmark3 /dev/ttySX
 ```