Setup instructions revisions

download_and_install/_ola_on_windows_msys2.md

@@ -0,0 +1,105 @@
+OLA on Windows
+==============
+
+TODO: This doesn't compile
+
+OLA is partially available on Windows using MSYS2. Please note that not all plugins are functional on Windows - only the
+following are available:
+
+- ArtNet
+- Dummy
+- ESP Net
+- FTDI
+- KiNet
+- OSC
+- Pathport
+- SandNet
+- Strand Shownet
+- USB DMX
+
+For other uses, consider using a Linux system, such as a [Raspberry Pi](ola_on_raspberry_pi).
+
+These instructions are generally similar to [compiling from source](compiling_from_source) on a Linux system, but are
+adapted slightly to the peculiarities of Windows. The troubleshooting advice there is applicable here as well.
+
+Setup
+=====
+
+Start by downloading and installing [MSYS2](https://www.msys2.org/). *Be sure to follow their instructions all the way
+through, including performing updates.*
+
+MSYS2 installs a subsystem on your machine. This means it functions a bit differently than the standard Windows command
+prompt. In particular:
+
+- Copy is Ctrl + Insert.
+- Paste is Shift + Insert.
+- The directory separator is a forward slash (`/`).
+- Directories appear differently than they do in Windows. The root is `/`; all directories descend from `/`.
+  See [here](https://www.msys2.org/wiki/MSYS2-introduction/#file-system) for how MSYS2 maps your Windows drives
+  and directories into this hierarchy. Your Windows "Documents" folder, unless you've moved it inside Windows, is likely
+  at `/c/Users/<your username>/Documents`.
+
+To install dependencies, launch "MSYS2 MSYS" from the Start Menu (it may have opened automatically after installation):
+
+    pacman -S \
+        base-devel \
+        git \
+        libutil-linux-devel \
+        mingw-w64-x86_64-cppunit \
+        mingw-w64-x86_64-libftdi \
+        mingw-w64-x86_64-liblo \
+        mingw-w64-x86_64-libmicrohttpd \
+        mingw-w64-x86_64-libusb \
+        mingw-w64-x86_64-protobuf \
+        mingw-w64-x86_64-python \
+        mingw-w64-x86_64-python-numpy \
+        mingw-w64-x86_64-python-protobuf \
+        mingw-w64-x86_64-toolchain
+
+When asked which members to install, press enter to install all. This process will take quite some time.
+
+If you're using USB devices, use [Zadig](https://zadig.akeo.ie/) to install the libusbK for each FTDI device.
+
+Run the below command to tell the build system where to find the newly-installed packages:
+
+     echo "export PKG_CONFIG_PATH=/usr/lib/pkgconfig:${PKG_CONFIG_PATH}" >> ~/.bashrc
+
+Now close the MSYS2 window.
+
+Build
+=====
+
+From the Start Menu, launch "MSYS2 MinGW 64-bit".
+
+Navigate to the directory you wish to use to build OLA.
+Run `git clone https://github.com/OpenLightingProject/ola.git && cd ola`.
+
+If this is the first time compiling with this download, generate the build system:
+
+    autoreconf -i
+
+OLA uses autotools for building. Run `./configure --help` to see all options.
+
+To install with all available Windows plugins, run:
+
+    ./configure \
+        --enable-python-libs \
+        --disable-all-plugins \
+        --enable-artnet \
+        --enable-dummy \
+        --enable-espnet \
+        --enable-ftdidmx \
+        --enable-kinet \
+        --enable-osc \
+        --enable-pathport \
+        --enable-sandnet \
+        --enable-shownet \
+        --enable-usbdmx
+
+To build OLA after configuring, run:
+
+    make -j$(nproc)
+    make check
+    make install
+
+TODO: Usage

download_and_install/_ola_on_windows_wsl.md

@@ -0,0 +1,120 @@
+OLA on Windows
+==============
+
+OLA is not presently available directly on Windows. However, it can be used with a shim. Note these installations are
+not well-tested and may encounter problems. In particular, non-network plugins (e.g. USB DMX) will fail to function. For
+show-critical uses, consider using a Linux system, such as a [Raspberry Pi](ola_on_raspberry_pi).
+
+Windows Subsystem for Linux (WSL) allows running programs written for Linux (such as OLA) on Windows. WSL requires
+Windows 10 version 1903 or newer. See Microsoft's notes on Windows
+versions [here](https://docs.microsoft.com/en-us/windows/wsl/install-win10#step-2---check-requirements-for-running-wsl-2).
+
+Setup
+=====
+
+1. Begin by installing WSL using the
+   [installation instructions](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Be sure to follow the
+   instructions for WSL2, not WSL1
+2. WSL supports several distributions, but OLA is best supported with Debian. Install the
+   [Debian WSL distribution](https://www.microsoft.com/en-us/p/debian/9msvkqc78pk6) from the Microsoft Store.
+3. From the Start Menu, launch Debian. Create a UNIX username and password when prompted.
+4. Once the system is installed, run `sudo apt-get update` and `sudo apt-get upgrade` to keep the system updated.
+5. Install OLA with `sudo apt-get install ola`.
+
+Networking
+==========
+
+TODO: This doesn't forward UDP ports, a function required for nearly everything interesting you can do with OLA.
+
+WSL uses a virtual network adapter internally. This means connections to OLA from your LAN will initially fail. There is
+some work being done in this area [here](https://github.com/microsoft/WSL/issues/4150). The following instructions are
+adapted from a [workaround](https://github.com/microsoft/WSL/issues/4150#issuecomment-504209723) in that issue.
+
+Create a PowerShell script somewhere on your system with these contents:
+
+    $remoteip = wsl -d Debian ip addr `| grep -Ee 'inet.*eth0'
+    $found = $remoteip -match '\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}';
+
+    if( $found ){
+      $remoteip = $matches[0];
+    } else{
+      Write-Output "The Script Exited, the ip address of WSL 2 cannot be found";
+      exit;
+    }
+
+    #[Ports]
+    # ADD PORTS HERE: all the ports you want to forward separated by comma
+    $ports=@(9090, 9099);
+
+    #[Static ip]
+    # You can change the addr to your ip config to listen to a specific address
+    $addr='0.0.0.0';
+    $ports_a = $ports -join ",";
+
+    # Remove Firewall Exception Rules
+    Invoke-Expression "Remove-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (TCP)'";
+    Invoke-Expression "Remove-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (UDP)'";
+
+    # Adding exceptions for inbound and outbound traffic
+    Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (TCP)' -Direction Outbound -LocalPort $ports_a -Action Allow -Protocol TCP";
+    Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (UDP)' -Direction Outbound -LocalPort $ports_a -Action Allow -Protocol UDP";
+    Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (TCP)' -Direction Inbound -LocalPort $ports_a -Action Allow -Protocol TCP";
+    Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (UDP)' -Direction Inbound -LocalPort $ports_a -Action Allow -Protocol UDP";
+
+    for( $i = 0; $i -lt $ports.length; $i++ ){
+      $port = $ports[$i];
+      Invoke-Expression "netsh interface portproxy delete v4tov4 listenport=$port listenaddress=$addr";
+      Invoke-Expression "netsh interface portproxy add v4tov4 listenport=$port listenaddress=$addr connectport=$port connectaddress=$remoteip";
+    }
+
+Add additional ports, if needed, separated by a comma below `# ADD PORTS HERE`.
+
+Next, open the Task Scheduler. Create a new task:
+
+![](images/wsl_networking_1.png)
+
+Configure the task like so:
+
+![](images/wsl_networking_2.png)
+
+In the triggers tab, add a new trigger:
+
+![](images/wsl_networking_3.png)
+
+In the actions tab, add a new action:
+
+![](images/wsl_networking_4.png)
+
+The arguments should be:
+
+    -ExecutionPolicy Bypass <PATH TO YOUR SCRIPT> 
+
+Save the action, then select it and choose `Run` from the right sidebar.
+
+Here are some common standard ports:
+
+| Plugin            | Port       |
+|-------------------|------------|
+| OLA Web interface | 9090       |
+| OLA RDM tests     | 9099       |
+| ArtNet            | 6454       |
+| E1.31 (sACN)      | 5568-5569  |
+| Enttec ESP Net    | 3333       |
+| KiNet             | 6038       |
+| Pathport          | 3792       |
+| Strand ShowNet    | 2501       |
+
+Start/Stop OLA
+==============
+
+When you wish to use OLA, open Debian from the Start Menu and run:
+
+    sudo service rsyslog start
+    sudo service dbus start
+    sudo service olad start
+
+OLA will continue to run in the background, regardless of whether the Debian command prompt is open or not.
+
+To stop, run:
+
+    sudo service olad stop