Setup instructions revisions

download_and_install/_ola_on_windows_wsl.md

@@ -0,0 +1,122 @@
+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:
+
+    $remoteport = wsl -d Debian ip addr `| grep -Ee 'inet.*eth0'
+    $found = $remoteport -match '\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}';
+
+    if( $found ){
+      $remoteport = $matches[0];
+    } else{
+      Write-Output "The Script Exited, the ip address of WSL 2 cannot be found";
+      exit;
+    }
+
+    #[Ports]
+
+    #All the ports you want to forward separated by comma
+    $ports=@(9090);
+
+
+    #[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 Exception Rules for inbound and outbound Rules
+    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=$remoteport";
+    }
+
+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       |
+| 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

download_and_install/compiling_from_source.md

@@ -0,0 +1,242 @@
+Compiling From Source
+=====================
+
+OLA source code lives on [GitHub](https://github.com/OpenLightingProject/ola).
+Stable releases are available from the [releases page](https://github.com/OpenLightingProject/ola/releases);
+for bleeding-edge development releases, run `git clone https://github.com/OpenLightingProject/ola.git`.
+
+Dependencies
+============
+
+You need a couple of libraries installed for everything to work correctly.
+
+First you’ll need at least the following:
+
+- [avahi](https://www.avahi.org) if you want to use network discovery.
+- [microhttpd](https://www.gnu.org/software/libmicrohttpd/) (if you want the web UI).
+- autoconf
+- automake
+- cppunit
+- ncurses
+- lex (or flex)
+- libftdi
+- liblo
+- libtool
+- libusb
+- pkg-config
+- [Protobuf](https://developers.google.com/protocol-buffers) (version 3.6 or later)
+- uuid or ossp uuid
+- yacc (or bison)
+- zlib
+
+The Python library also requires
+
+- Numpy
+- Protobuf for Python
+
+Debian/Ubuntu
+-------------
+
+Debian/Ubuntu users can install all dependencies with:
+
+    sudo apt-get install \
+        autoconf \
+        automake \
+        bison \
+        flex \
+        g++ \
+        libavahi-client-dev \
+        libcppunit-dev \
+        libftdi-dev \
+        liblo-dev \
+        libmicrohttpd-dev \
+        libncurses-dev \
+        libprotobuf-dev \
+        libprotoc-dev \
+        libtool \
+        libusb-1.0.0-dev \
+        make \
+        protobuf-compiler \
+        pkg-config \
+        uuid-dev \
+        zlib1g-dev
+
+CentOS/RHEL/Fedora
+------------------
+
+Distributions using RPM packages can install all dependencies with:
+
+    sudo dnf install \
+        autoconf \
+        automake \
+        avahi-devel \
+        bison \
+        cppunit-devel \
+        flex \
+        gcc-c++ \
+        libftdi-devel \
+        liblo-devel \
+        libmicrohttpd-devel \
+        libtool \
+        libusbx-devel \
+        make \
+        ncurses-devel \
+        protobuf-lite-devel \
+        uuid-devel \
+        zlib-devel
+
+macOS
+-----
+
+Dependencies are available from [MacPorts](https://www.macports.org/):
+
+    sudo port install \
+        autoconf \
+        automake \
+        bison \
+        cppunit \
+        flex \
+        libftdi1 \
+        liblo \
+        libmicrohttpd \
+        libtool \
+        libusb \
+        libuuid \
+        ncurses \
+        pkgconfig \
+        protobuf3-cpp \
+        zlib
+
+or [Homebrew](https://brew.sh/):
+
+    brew install \
+        autoconf \
+        automake \
+        bison \
+        cppunit \
+        flex \
+        libftdi \
+        liblo \
+        libmicrohttpd \
+        libtool \
+        libusb \
+        libuuid \
+        ncurses \
+        pkg-config \
+        protobuf \
+        zlib
+
+Python dependencies
+-------------------
+
+If you wish to build the Python library, additional libraries are required:
+
+    pip3 install --user \
+        numpy \
+        protobuf
+
+If the pip3 command does not exist, install python3-pip from your package manager and try again.
+
+Build
+=====
+
+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. The most popular option is `--enable-python-libs` to build the Python client module. If you want to
+use the RDM responder tests, add `--enable-rdm-tests`.
+
+Once you’ve decided on the options, it’s time to build OLA.
+
+    ./configure <your options>
+    make -j$(nproc)
+    make check
+    sudo make install
+
+Mac users should run use `make -j$(sysctl -n hw.logicalcpu)` instead of `make -j$(nproc)`.
+
+Finally, run `sudo ldconfig` to make new libraries available.
+
+Device drivers
+==============
+
+Note that, for some devices, it is necessary to install drivers for OLA to work with them. For example, the
+[Open DMX USB](http://opendmx.net/index.php/Open_DMX_USB "Open DMX USB") device needs an additional kernel module that
+could be built using the instructions on
+[LLA\_and\_Q\_Light\_Controller\_Ubuntu\_Tutorial](http://opendmx.net/index.php/LLA_and_Q_Light_Controller_Ubuntu_Tutorial)
+. For other devices, refer to the corresponding device page on the wiki.
+
+Known Issues
+============
+
+If you get an error like the following:
+
+    /bin/sh ./libtool --tag=CC   --mode=compile gcc -DHAVE_CONFIG_H -I.   -I/opt/local/var/macports/software/protobuf-cpp/2.0.3_0/opt/local/include/  -g -O2 -c -o ltdl.lo ltdl.c
+    ./libtool: line 464: CDPATH: command not found
+    /Users/simonn/lighting/lla/libltdl/libtool: line 464: CDPATH: command not found
+    /Users/simonn/lighting/lla/libltdl/libtool: line 1142: func_opt_split: command not found
+    libtool: Version mismatch error.  This is libtool 2.2.6, but the
+    libtool: definition of this LT_INIT comes from an older release.
+    libtool: You should recreate aclocal.m4 with macros from libtool 2.2.6
+    libtool: and run autoconf again.
+
+Your system uses a different version of libtool. Run:
+
+     libtoolize --ltdl -c -f
+
+and then start from the autoreconf step again.
+
+If you should get the following error try to fix it with one of
+[two available solutions](https://groups.google.com/group/open-lighting/msg/72060f6327d30df6):
+
+    Rpc.pb.cc: In copy constructor 'ola::rpc::RpcMessage::RpcMessage(const ola::rpc::RpcMessage&)': 
+    Rpc.pb.cc:143: error: base class 'class google::protobuf::Message' should be explicitly initialized in the copy constructor
+
+You should be able to prevent this
+by [editing `./src/Makefile.am`](https://groups.google.com/group/open-lighting/msg/c6d86d03dd74ed5b), removing `-Werror`
+and then start from the autoreconfig step again.
+
+If you get
+
+    In file included from ./common/rdm/PidStoreLoader.h:32:0,
+                     from common/rdm/PidStore.cpp:24:
+    ./common/rdm/Pids.pb.h:17:2: error: #error This file was generated by an older version of protoc which is
+     #error This file was generated by an older version of protoc which is
+      ^
+    ./common/rdm/Pids.pb.h:18:2: error: #error incompatible with your Protocol Buffer headers. Please
+     #error incompatible with your Protocol Buffer headers.  Please
+      ^
+    ./common/rdm/Pids.pb.h:19:2: error: #error regenerate this file with a newer version of protoc.
+     #error regenerate this file with a newer version of protoc.
+
+Then you should run
+
+    make clean
+
+to clean out the old protobuf files.
+
+Optional
+========
+
+Doxygen Documentation
+---------------------
+
+There is also an option to build the doxygen documentation! To do so, you will need to install
+[doxygen](http://www.doxygen.nl/manual/install.html) (available from package managers on all popular systems).
+
+Once you have installed Doxygen you may need to run `./configure` in your ola directory, so that it can generate the
+correct make file. To build the docs just use:
+
+     make doxygen-doc
+
+You’ll have to run a webserver to get the experience. A simple way to do this is to navigate to `open-lighting/html` and
+run:
+
+     python3 -m http.server 8000 --bind 127.0.0.1
+
+This starts a web server at http://127.0.0.1:8000.